Search documentation of macula

# macula_host_attach_controller (macula v4.4.9)

View Source

Host-side controller for the macula-net attach plane.

PLAN_MACULA_NET_PHASE3_5_TRANSPORT_SEAM.md §5. When a station hosts daemons, this slice is the transport's inbound handler. It owns three responsibilities:

1. attach_v1 dispatch — On a `macula_attach_v1` frame, parse + validate the daemon's signed delegation, then call the configured `attach_fn` with the originating StreamRef as the `attach_conn`. Owning the StreamRef at attach time is what lets the host send replies on the same bidi stream the daemon dialed in on.
2. hosted-data forwarding — On a `data` frame whose `dst` is in the host_identity table, look up the stored StreamRef and re-send the original CBOR on it via `attach_send_fn`. The dst is checked by ETS membership lookup, not by trusting the daemon's claim — the address-binding-by-construction discipline from the resolver applies here too.
3. fallback — Anything else (non-data envelopes, data for non-hosted dst, malformed CBOR) is handed to `fallback_fn`, typically `macula_deliver_packet:handle_envelope/1`.

Every external coupling is a callback in the config; production wiring lives in `macula_net` (host-mode boot path), tests pass capture functions to a process mailbox.

# Summary

## Types

attach_fn/0
attach_send_fn/0
config/0
fallback_fn/0
forward_fn/0
lookup_fn/0
stream_ref/0

## Functions

code_change(OldVsn, State, Extra)
delegation_from_wire(_)

Convert the wire-shape (single-letter keys) delegation map into the in-process atom-keyed form that `macula_record:verify_host_delegation/1` expects. Exported for test reuse.

handle(Cbor, StreamRef)

Transport handler entry point. Suitable for direct use as the argument to `macula_net_transport_quic:set_handler/1` when the station is configured in host mode.

handle_call(Other, From, State)
handle_cast(Msg, State)
handle_info(Msg, State)
init(Config)
start_link(Config)
stop()
terminate(Reason, State)

# Types

# attach_fn/0

    -type attach_fn() ::
              fun((<<_:128>>, <<_:256>>, macula_record:host_delegation(), stream_ref()) ->
                      ok | {error, term()}).

# attach_send_fn/0

    -type attach_send_fn() :: fun((stream_ref(), iodata()) -> ok | {error, term()}).

# config/0

    -type config() ::
              #{realm_pubkey := <<_:256>>,
                host_pubkey := <<_:256>>,
                attach_send_fn := attach_send_fn(),
                lookup_fn := lookup_fn(),
                attach_fn := attach_fn(),
                fallback_fn := fallback_fn(),
                forward_fn => forward_fn()}.

# fallback_fn/0

    -type fallback_fn() :: fun((binary()) -> any()).

# forward_fn/0

    -type forward_fn() :: fun((Cbor :: binary(), Dst :: <<_:128>>) -> {ok, term()} | {error, term()}).

# lookup_fn/0

    -type lookup_fn() :: fun((<<_:128>>) -> {ok, stream_ref()} | not_found).

# stream_ref/0

    -type stream_ref() :: macula_net_transport:stream_ref().

# Functions

# code_change(OldVsn, State, Extra)

# delegation_from_wire(_)

    -spec delegation_from_wire(map()) -> macula_record:host_delegation() | error.

Convert the wire-shape (single-letter keys) delegation map into the in-process atom-keyed form that `macula_record:verify_host_delegation/1` expects. Exported for test reuse.

# handle(Cbor, StreamRef)

    -spec handle(binary(), stream_ref()) -> ok.

Transport handler entry point. Suitable for direct use as the argument to `macula_net_transport_quic:set_handler/1` when the station is configured in host mode.

# handle_call(Other, From, State)

# handle_cast(Msg, State)

# handle_info(Msg, State)

# init(Config)

# start_link(Config)

    -spec start_link(config()) -> {ok, pid()} | {error, term()}.

# stop()

    -spec stop() -> ok.

# terminate(Reason, State)