macula_quic (macula v4.1.1)
View SourceMacula QUIC transport — Quinn-based Rust NIF.
Provides QUIC listener, connection, and stream operations backed by Quinn (Rust) instead of MsQuic. Key improvement: listeners actually 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 (compat with quicer flags).
Async shutdown stream (compat with quicer flags).
Generic close — tries stream, then connection, then listener.
Close a connection.
Close a listener.
Close a stream.
Connect to a remote QUIC server.
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).
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 (compat with quicer flags).
Async shutdown stream (compat with quicer flags).
-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(Target, inet:port_number(), list(), timeout()) -> {ok, reference()} | {error, term()} when Target :: binary() | string() | {pubkey, binary()}.
Connect to a remote QUIC server.
Target forms:
Host :: binary() | string()— the existing hostname / IP-string path. Validation depends onverify/verify_pubkeyopts.{pubkey, Pubkey :: binary()}— sovereign-overlay path. The 32-byte Ed25519 pubkey is the identity. The Yggdrasil IPv6 is derived from it; the leaf cert is validated by SPKI pin against the same pubkey. No DNS, no CA. See PLAN_SOVEREIGN_OVERLAY_PHASE1 §4.4.
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).
Used by macula_yggdrasil:cert_for/1 for the sovereign-overlay listener path — the cert wraps the identity's macula pubkey, no CA chain required. See PLAN_SOVEREIGN_OVERLAY_PHASE1 §4.3.
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.