Search documentation of macula

# macula_quic (macula v4.4.1)

View Source

Macula QUIC transport — Quinn-based Rust NIF.

Provides QUIC listener, connection, and stream operations backed by Quinn (Rust). Listeners bind to specific IP addresses, enabling per-identity IPv6 binding for virtual relay identities.

Active-mode messages delivered to owning process: {quic, Data, StreamRef, Flags} — stream data {quic, new_conn, ConnRef, Info} — new connection accepted {quic, new_stream, StreamRef, Props} — new stream accepted {quic, peer_send_shutdown, StreamRef, undefined} {quic, stream_closed, StreamRef, Flags} {quic, shutdown, Handle, Reason}

# Summary

## Functions

accept_stream(Conn, Opts, Timeout)

Accept stream with options and timeout (for macula_dist).

async_accept(Listener)

Start accepting connections on a listener. Delivers {quic, new_conn, ConnRef, Info} to the calling process.

async_accept(Listener, Opts)
async_accept_stream(Conn)

Start accepting streams on a connection. Delivers {quic, new_stream, StreamRef, #{conn => ConnRef}} to the owning process.

async_accept_stream(Conn, Opts)
async_send(Stream, Data)

Send data asynchronously.

async_shutdown_connection(Conn, Flag, Code)

Async shutdown connection.

async_shutdown_stream(Stream, Flag, Code)

Async shutdown stream.

close(Ref)

Generic close — tries stream, then connection, then listener.

close_connection(Conn)

Close a connection.

close_listener(Listener)

Close a listener.

close_stream(Stream)

Close a stream.

connect(Host, Port, Opts, Timeout)

Connect to a remote QUIC server. `Host` is a hostname or IP-string; validation depends on `verify` / `verify_pubkey` opts.

controlling_process(Handle, Pid)

Transfer ownership of a handle to another process. Works with both stream and connection handles.

generate_self_signed_cert(Pubkey, Privkey, Sans)

Generate a self-signed X.509 cert from an Ed25519 keypair. Returns `{ok, {CertPem, KeyPem}}` as PEM-encoded binaries suitable for handing to `macula_quic:listen/3` via `cert` / `key` opts (after writing to disk). The cert wraps the identity's macula pubkey; no CA chain required. Used by station listeners running pubkey-anchored peering and by `macula-net` transport bring-up.

getstat(Conn, Stats)

Get connection stats. Currently returns zeros for all requested counters — Quinn exposes per-connection stats but the NIF binding hasn't surfaced them yet. Used by macula_dist for telemetry; zeroed values are harmless (dist_util only uses these for liveness signals).

handoff_stream(Stream, NewOwner, Opts)

Hand off a stream to another process (for macula_dist).

handshake(Conn)

Complete TLS handshake. With Quinn, handshake completes during accept — this is a no-op for compat.

listen(Port, Opts)

Listen on a port or {Address, Port} tuple.

listen(BindAddr, Port, Opts)

Listen on a specific bind address and port. BindAddr is a binary: "0.0.0.0", "192.168.1.1", "2600:3c0e::100", etc.

max_datagram_size(Conn)

Path MTU as discovered by Quinn's DPLPMTUD on this connection. Returns `{ok, Bytes}` once the path MTU has been established; `{error, no_path_mtu}` early in the connection lifecycle (before the first probe lands) or if the peer disabled datagrams. Phase 4.2.

open_stream(Conn)

Open a new bidirectional stream.

open_stream(Conn, Opts)

Open stream with options map (for macula_dist).

peername(Conn)

Get remote address of a connection.

send(Stream, Data)

Send data on a stream (blocking).

setopt(Stream, _, Value)

Set active mode on a stream handle.

# Functions

# accept_stream(Conn, Opts, Timeout)

    -spec accept_stream(reference(), map(), timeout()) -> {ok, reference()} | {error, term()}.

Accept stream with options and timeout (for macula_dist).

# async_accept(Listener)

    -spec async_accept(reference()) -> ok | {error, term()}.

Start accepting connections on a listener. Delivers {quic, new_conn, ConnRef, Info} to the calling process.

# async_accept(Listener, Opts)

    -spec async_accept(reference(), map()) -> ok | {error, term()}.

# async_accept_stream(Conn)

    -spec async_accept_stream(reference()) -> ok | {error, term()}.

Start accepting streams on a connection. Delivers {quic, new_stream, StreamRef, #{conn => ConnRef}} to the owning process.

# async_accept_stream(Conn, Opts)

    -spec async_accept_stream(reference(), map()) -> ok | {error, term()}.

# async_send(Stream, Data)

    -spec async_send(reference(), iodata()) -> ok | {error, term()}.

Send data asynchronously.

# async_shutdown_connection(Conn, Flag, Code)

    -spec async_shutdown_connection(reference(), integer(), integer()) -> ok.

Async shutdown connection.

# async_shutdown_stream(Stream, Flag, Code)

    -spec async_shutdown_stream(reference(), integer(), integer()) -> ok.

Async shutdown stream.

# close(Ref)

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

Generic close — tries stream, then connection, then listener.

# close_connection(Conn)

    -spec close_connection(reference()) -> ok.

Close a connection.

# close_listener(Listener)

    -spec close_listener(reference()) -> ok.

Close a listener.

# close_stream(Stream)

    -spec close_stream(reference()) -> ok.

Close a stream.

# connect(Host, Port, Opts, Timeout)

    -spec connect(Host, inet:port_number(), list(), timeout()) -> {ok, reference()} | {error, term()}
                     when Host :: binary() | string().

Connect to a remote QUIC server. `Host` is a hostname or IP-string; validation depends on `verify` / `verify_pubkey` opts.

# controlling_process(Handle, Pid)

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

Transfer ownership of a handle to another process. Works with both stream and connection handles.

# generate_self_signed_cert(Pubkey, Privkey, Sans)

    -spec generate_self_signed_cert(Pubkey :: binary(), Privkey :: binary(), Sans :: [binary() | string()]) ->
                                       {ok, {CertPem :: binary(), KeyPem :: binary()}} | {error, term()}.

Generate a self-signed X.509 cert from an Ed25519 keypair. Returns `{ok, {CertPem, KeyPem}}` as PEM-encoded binaries suitable for handing to `macula_quic:listen/3` via `cert` / `key` opts (after writing to disk). The cert wraps the identity's macula pubkey; no CA chain required. Used by station listeners running pubkey-anchored peering and by `macula-net` transport bring-up.

# getstat(Conn, Stats)

    -spec getstat(reference(), [atom()]) -> {ok, [{atom(), integer()}]} | {error, term()}.

Get connection stats. Currently returns zeros for all requested counters — Quinn exposes per-connection stats but the NIF binding hasn't surfaced them yet. Used by macula_dist for telemetry; zeroed values are harmless (dist_util only uses these for liveness signals).

# handoff_stream(Stream, NewOwner, Opts)

    -spec handoff_stream(reference(), pid(), map()) -> ok | {error, term()}.

Hand off a stream to another process (for macula_dist).

# handshake(Conn)

    -spec handshake(reference()) -> ok | {ok, reference()} | {error, term()}.

Complete TLS handshake. With Quinn, handshake completes during accept — this is a no-op for compat.

# listen(Port, Opts)

    -spec listen(inet:port_number() | {string() | binary(), inet:port_number()}, list()) ->
                    {ok, reference()} | {error, term()}.

Listen on a port or {Address, Port} tuple.

# listen(BindAddr, Port, Opts)

    -spec listen(binary() | string(), inet:port_number(), list()) -> {ok, reference()} | {error, term()}.

Listen on a specific bind address and port. BindAddr is a binary: "0.0.0.0", "192.168.1.1", "2600:3c0e::100", etc.

# max_datagram_size(Conn)

    -spec max_datagram_size(reference()) -> {ok, pos_integer()} | {error, term()}.

Path MTU as discovered by Quinn's DPLPMTUD on this connection. Returns `{ok, Bytes}` once the path MTU has been established; `{error, no_path_mtu}` early in the connection lifecycle (before the first probe lands) or if the peer disabled datagrams. Phase 4.2.

# open_stream(Conn)

    -spec open_stream(reference()) -> {ok, reference()} | {error, term()}.

Open a new bidirectional stream.

# open_stream(Conn, Opts)

    -spec open_stream(reference(), map()) -> {ok, reference()} | {error, term()}.

Open stream with options map (for macula_dist).

# peername(Conn)

    -spec peername(reference()) -> {ok, {string(), inet:port_number()}} | {error, term()}.

Get remote address of a connection.

# send(Stream, Data)

    -spec send(reference(), iodata()) -> ok | {error, term()}.

Send data on a stream (blocking).

# setopt(Stream, _, Value)

    -spec setopt(reference(), active, boolean()) -> ok | {error, term()}.

Set active mode on a stream handle.