Search documentation of macula

# macula_peering (macula v4.4.9)

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.