macula_quic (macula v4.2.0)
View SourceMacula 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 with options and timeout (for macula_dist).
Start accepting connections on a listener. Delivers {quic, new_conn, ConnRef, Info} to the calling process.
Start accepting streams on a connection. Delivers {quic, new_stream, StreamRef, #{conn => ConnRef}} to the owning process.
Send data asynchronously.
Async shutdown connection.
Async shutdown stream.
Generic close — tries stream, then connection, then listener.
Close a connection.
Close a listener.
Close a stream.
Connect to a remote QUIC server. Host is a hostname or IP-string; validation depends on verify / verify_pubkey opts.
Transfer ownership of a handle to another process. Works with both stream and connection handles.
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.
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).
Hand off a stream to another process (for macula_dist).
Complete TLS handshake. With Quinn, handshake completes during accept — this is a no-op for compat.
Listen on a port or {Address, Port} tuple.
Listen on a specific bind address and port. BindAddr is a binary: "0.0.0.0", "192.168.1.1", "2600:3c0e::100", etc.
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 a new bidirectional stream.
Open stream with options map (for macula_dist).
Get remote address of a connection.
Send data on a stream (blocking).
Set active mode on a stream handle.
Functions
Accept stream with options and timeout (for macula_dist).
Start accepting connections on a listener. Delivers {quic, new_conn, ConnRef, Info} to the calling process.
Start accepting streams on a connection. Delivers {quic, new_stream, StreamRef, #{conn => ConnRef}} to the owning process.
Send data asynchronously.
Async shutdown connection.
Async shutdown stream.
-spec close(reference()) -> ok.
Generic close — tries stream, then connection, then listener.
-spec close_connection(reference()) -> ok.
Close a connection.
-spec close_listener(reference()) -> ok.
Close a listener.
-spec close_stream(reference()) -> ok.
Close a stream.
-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.
Transfer ownership of a handle to another process. Works with both stream and connection handles.
-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.
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).
Hand off a stream to another process (for macula_dist).
Complete TLS handshake. With Quinn, handshake completes during accept — this is a no-op for compat.
-spec listen(inet:port_number() | {string() | binary(), inet:port_number()}, list()) -> {ok, reference()} | {error, term()}.
Listen on a port or {Address, Port} tuple.
-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.
-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 a new bidirectional stream.
Open stream with options map (for macula_dist).
-spec peername(reference()) -> {ok, {string(), inet:port_number()}} | {error, term()}.
Get remote address of a connection.
Send data on a stream (blocking).
Set active mode on a stream handle.