macula_host_attach_controller (macula v4.3.0)
View SourceHost-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:
- attach_v1 dispatch — On a
macula_attach_v1frame, parse + validate the daemon's signed delegation, then call the configuredattach_fnwith the originating StreamRef as theattach_conn. Owning the StreamRef at attach time is what lets the host send replies on the same bidi stream the daemon dialed in on. - hosted-data forwarding — On a
dataframe whosedstis in the host_identity table, look up the stored StreamRef and re-send the original CBOR on it viaattach_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. - fallback — Anything else (non-data envelopes, data for non-hosted dst, malformed CBOR) is handed to
fallback_fn, typicallymacula_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
Functions
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.
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.
Types
-type attach_fn() :: fun((<<_:128>>, <<_:256>>, macula_record:host_delegation(), stream_ref()) -> ok | {error, term()}).
-type attach_send_fn() :: fun((stream_ref(), iodata()) -> ok | {error, term()}).
-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()}.
-type lookup_fn() :: fun((<<_:128>>) -> {ok, stream_ref()} | not_found).
-type stream_ref() :: macula_net_transport:stream_ref().
Functions
-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.
-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.
-spec stop() -> ok.