Search documentation of macula

# macula_net_transport_quic (macula v4.4.9)

View Source

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 `connect`ed 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 `connect`ed 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 `&lt;&lt;"::"&gt;&gt;`)
- `alpn` — ALPN protocol id binary (default `&lt;&lt;"macula-net"&gt;&gt;`)

# stop()

    -spec stop() -> ok.

# terminate(Reason, State)