macula_peering (macula v3.13.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}

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.