macula_net_transport_quic (macula v4.2.3)

QUIC transport plugin for macula-net.

Implements macula_net_transport using the SDK's existing macula_quic primitives (Quinn-based Rust NIF). One bidi stream per outbound connection carries length-prefixed CBOR envelopes:

     <<Len:32/big, Cbor:Len/binary>>

Phase 1 simplifications

These will be addressed in Phase 4 hardening (PLAN_MACULA_NET.md §13):

Self-signed throwaway TLS cert generated at startup. Identity authentication happens at the macula-net envelope layer (sigs on control messages), NOT at the TLS layer. Phase 4 swaps to raw-pubkey TLS bound to the macula identity.
One outbound connection per peer; no connection pooling.
On disconnect, no automatic reconnect.
No backpressure beyond the QUIC flow-control window.

Summary

Functions

code_change(OldVsn, State, Extra)

connect(StationId, Host, Port)

Open an outbound QUIC connection + bidi stream to a peer station.

connection_count()

Active outbound-connection count. Used by macula_metrics's gauge poller (see PLAN_MACULA_NET_PHASE4_1_OBSERVABILITY.md).

disconnect(StationId)

handle_call(Other, From, State)

handle_cast(Msg, State)

handle_info(Other, State)

init(_)

peer_path_mtu(StationId)

Path MTU as currently tracked by Quinn for the connection to StationId. Phase 4.2 — see PLAN_MACULA_NET_PHASE4_2_MTU_PMTUD.md.

send(StationId, Cbor)

Send a CBOR envelope to a known station (must be connected first).

set_handler(Handler)

Register the inbound handler. Called for every received envelope.

start_link(Opts)

Start the QUIC listener.

stop()

terminate(Reason, State)

Functions

code_change(OldVsn, State, Extra)

connect(StationId, Host, Port)

-spec connect(StationId :: macula_net_transport:station_id(),
              Host :: binary() | string(),
              Port :: inet:port_number()) ->
                 ok | {error, term()}.

Open an outbound QUIC connection + bidi stream to a peer station.

connection_count()

-spec connection_count() -> non_neg_integer().

Active outbound-connection count. Used by macula_metrics's gauge poller (see PLAN_MACULA_NET_PHASE4_1_OBSERVABILITY.md).

disconnect(StationId)

-spec disconnect(macula_net_transport:station_id()) -> ok.

handle_call(Other, From, State)

handle_cast(Msg, State)

handle_info(Other, State)

init(_)

peer_path_mtu(StationId)

-spec peer_path_mtu(macula_net_transport:station_id()) ->
                       {ok, pos_integer()} | {error, not_connected | term()}.

Path MTU as currently tracked by Quinn for the connection to StationId. Phase 4.2 — see PLAN_MACULA_NET_PHASE4_2_MTU_PMTUD.md.

send(StationId, Cbor)

-spec send(macula_net_transport:station_id(), macula_net_transport:cbor_envelope()) ->
              ok | {error, term()}.

Send a CBOR envelope to a known station (must be connected first).

set_handler(Handler)

-spec set_handler(macula_net_transport:handler()) -> ok.

Register the inbound handler. Called for every received envelope.

The handler is invoked as Handler(Cbor, StreamRef) where StreamRef is the bidi-stream reference the frame arrived on. Non-host handlers can ignore StreamRef; the host_attach_controller (Phase 3.5) uses it to forward replies on the same stream a daemon dialed in on.

start_link(Opts)

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

Start the QUIC listener.

Opts map keys:

port — UDP port for the QUIC listener (mandatory)
bind — bind address binary (default <<"::">>)
alpn — ALPN protocol id binary (default <<"macula-net">>)

stop()

-spec stop() -> ok.

terminate(Reason, State)