macula_peering (macula v4.7.1)

View Source

Macula peering — connection state machine API.

Each peer connection is one macula_peering_conn gen_statem under the macula_peering_conn_sup simple_one_for_one supervisor.

Two entry points:

  • connect/1 — outbound dial; worker drives the QUIC connect.
  • accept/2 — inbound; caller transfers ownership of an already-established macula_quic connection (a reference()) to a new worker.

The caller passes a controlling_pid in opts; that pid receives peering events as messages:

  • {macula_peering, connected, ConnPid, PeerNodeId}
  • {macula_peering, frame, ConnPid, Frame} (post-handshake)
  • {macula_peering, disconnected, ConnPid, Reason}

An optional accept_owner pid in opts receives a single {macula_peering, handshake_complete, ConnPid, PeerNodeId} message the moment the worker transitions from handshaking to connected. Used by accept-side listeners that (a) cap concurrent handshaking workers separately from healthy connected peers, and (b) dedupe duplicate dials from the same peer identity by closing prior workers for the same PeerNodeId.

Summary

Types

opts/0

Functions

accept(Conn, Opts)

Inbound accept. Caller currently owns Conn (e.g. it's the listener owner that just received {quic, new_conn, Conn, _}). The transfer of ownership and the handshake start are sequenced atomically.

close(Pid)

Initiate a graceful close (sends GOODBYE, drains 5s, terminates).

close(Pid, Reason)
connect(Opts)

Outbound connect. Spawns a worker that opens a QUIC connection to target and runs the CONNECT/HELLO handshake.

peer_capabilities(Pid)

Read the peer's capabilities bitmask as observed in their CONNECT/HELLO frame. Returns {ok, NegotiatedCaps} once the handshake has completed and {error, not_connected} otherwise.

send_frame(Pid, Frame)

Send a frame through the peer connection. Signs the frame with the local identity if it isn't already signed. Fire-and-forget.

Types

opts/0

-type opts() :: macula_peering_conn:opts().

Functions

accept(Conn, Opts)

-spec accept(reference(), opts()) -> {ok, pid()} | {error, term()}.

Inbound accept. Caller currently owns Conn (e.g. it's the listener owner that just received {quic, new_conn, Conn, _}). The transfer of ownership and the handshake start are sequenced atomically.

close(Pid)

-spec close(pid()) -> ok.

Initiate a graceful close (sends GOODBYE, drains 5s, terminates).

close(Pid, Reason)

-spec close(pid(), atom()) -> ok.

connect(Opts)

-spec connect(opts()) -> {ok, pid()} | {error, term()}.

Outbound connect. Spawns a worker that opens a QUIC connection to target and runs the CONNECT/HELLO handshake.

peer_capabilities(Pid)

-spec peer_capabilities(pid()) -> {ok, non_neg_integer()} | {error, not_connected}.

Read the peer's capabilities bitmask as observed in their CONNECT/HELLO frame. Returns {ok, NegotiatedCaps} once the handshake has completed and {error, not_connected} otherwise.

Used by relays to tell direct daemon ADVERTISEs from station-to- station gossip relays at frame-dispatch time (see ?CAP_STATION). Daemons send 0; relay stations OR-in ?CAP_STATION. Pre-version peers that don't set the bit are treated as daemons by callers, which matches their actual role.

send_frame(Pid, Frame)

-spec send_frame(pid(), macula_frame:frame()) -> ok.

Send a frame through the peer connection. Signs the frame with the local identity if it isn't already signed. Fire-and-forget.