macula_peering (macula v4.3.0)

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.

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.

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.