-spec abort(stream(), binary(), binary()) -> ok.

Abort the stream with an error frame.

-spec advertise(client(), procedure(), fun()) -> {ok, reference()} | {error, term()}.

Advertise an RPC procedure handler.

-spec advertise(client(), procedure(), fun(), map()) -> {ok, reference()} | {error, term()}.

Advertise with options.

-spec advertise_stream(procedure(), stream_handler()) -> ok | {error, term()}.

Advertise a streaming procedure (default: server_stream). LOCAL dispatch only — see advertise_stream/3,4 for the Client form.

-spec advertise_stream(procedure() | client(), stream_mode() | procedure(), stream_handler()) ->
                          ok | {error, term()}.

Advertise a streaming procedure.

Two shapes: advertise_stream(Procedure, Mode, Handler) — LOCAL dispatch advertise_stream(Client, Procedure, Handler) — REMOTE, default mode server_stream

-spec advertise_stream(procedure() | client(),
                       stream_mode() | procedure(),
                       stream_handler() | stream_mode(),
                       map() | stream_handler()) ->
                          ok | {error, term()}.

Advertise with explicit mode / options.

Two shapes: advertise_stream(Procedure, Mode, Handler, Opts) — LOCAL advertise_stream(Client, Procedure, Mode, Handler) — REMOTE

-spec await_reply(stream()) -> {ok, term()} | {error, term()}.

Wait for the terminal reply (client-stream / bidi).

-spec call(client(), procedure(), term()) -> {ok, term()} | {error, term()}.

Call a remote procedure (default 5s timeout).

-spec call(client(), procedure(), term(), pos_integer()) -> {ok, term()} | {error, term()}.

Call a remote procedure with timeout.

-spec call_node(client(), binary(), procedure(), term()) -> {ok, term()} | {error, term()}.

Call a remote procedure on a specific target node (default 5s timeout).

Target can be a mesh name, site_id, or node_id (all binaries). The relay resolves the target and routes the CALL directly to that node.

-spec call_node(client(), binary(), procedure(), term(), pos_integer()) ->
                   {ok, term()} | {error, term()}.

Call a remote procedure on a specific target node with timeout.

-spec call_stream(procedure(), term()) -> {ok, stream()} | {error, term()}.

Open a server-stream call (default mode).

Phase 1 shortcut — dispatches in-process via the local registry. For cross-node streaming use the (Client, Procedure, Args) form.

-spec call_stream(procedure() | client(), procedure() | term(), term() | map()) ->
                     {ok, stream()} | {error, term()}.

Open a server-stream call with options.

Two shapes: call_stream(Procedure, Args, Opts) — LOCAL dispatch only call_stream(Client, Procedure, Args) — REMOTE via mesh client

-spec call_stream(client(), procedure(), term(), map()) -> {ok, stream()} | {error, term()}.

Open a remote server-stream call against a mesh client, with opts.

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

Close the stream (both sides).

-spec close_send(stream()) -> ok.

Half-close the write side; recv still drains.

-spec connect(binary() | [binary()], map()) -> {ok, client()} | {error, term()}.

Connect to a Macula relay.

Returns a client PID (macula_mesh_client gen_server) that you pass to all other API functions. Accepts a single URL binary or a list.

-spec disconnect(client()) -> ok.

Disconnect from the relay.

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

Ensure this node is running in distributed mode.

-spec find_record(client(), record_key()) -> {ok, record()} | {error, not_found | term()}.

Fetch a record by its macula_record:storage_key/1.

Returns {error, not_found} when no record exists at the key. The returned record's signature should be verified via macula_record:verify/1 before its payload is trusted.

-spec find_records_by_type(client(), record_type()) -> {ok, [record()]} | {error, term()}.

Return every record of a given type currently visible from the connected relay.

Coverage depends on the relay's view of the DHT — a single relay sees its local replicas plus whatever its peers have gossiped. Aggregating across the full mesh requires querying multiple relays and deduplicating by record key.

-spec get_cookie() -> atom().

Get the Erlang cluster cookie.

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

Enable Erlang distribution over a dedicated dist relay (macula-io/macula-dist-relay).

Different from join_mesh/1: - Connects to a dist relay (port 4434, ALPN macula-dist), NOT the pub/sub station mesh - No mesh_client, no pub/sub subscriptions — only dist traffic - Uses raw QUIC stream routing with no MessagePack overhead

Options: - url (required): <<"quic://relay.example.com:4434">>

After this returns ok, standard OTP distribution (rpc:call/4, gen_server:call/3 across nodes, pg groups, etc.) works across firewalls via the dist relay.

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

Join the Macula relay mesh with Erlang distribution.

After calling this, standard OTP distribution works across firewalls. Options: relays (required list), realm, identity, site, tls_verify.

-spec list_nodes(client()) -> {ok, map()} | {error, term()}.

List all nodes connected to the relay (default 5s timeout).

-spec list_nodes(client(), map()) -> {ok, map()} | {error, term()}.

List all nodes connected to the relay with options.

-spec monitor_nodes() -> ok.

Subscribe to node up/down events.

-spec open_stream(procedure() | client(), procedure() | term(), term() | map()) ->
                     {ok, stream()} | {error, term()}.

Open a client-stream or bidi call.

Two shapes: open_stream(Procedure, Args, Opts) — LOCAL dispatch open_stream(Client, Procedure, Args) — REMOTE, default mode bidi

-spec open_stream(procedure() | client(), procedure() | term(), term() | map(), stream_mode() | map()) ->
                     {ok, stream()} | {error, term()}.

Open a stream with explicit mode.

Two shapes: open_stream(Procedure, Args, Opts, Mode) — LOCAL dispatch, explicit mode open_stream(Client, Procedure, Args, Opts) — REMOTE via mesh client

-spec publish(client(), topic(), term()) -> ok.

Publish an event to a topic (fire-and-forget).

-spec publish(client(), topic(), term(), map()) -> ok.

Publish an event with options.

-spec put_record(client(), record()) -> ok | {error, term()}.

Store a signed record in the mesh DHT.

Build the record via the typed constructors in macula_record (node_record/3,4, content_announcement/3,4, tombstone/3,4, realm_directory/3,4, procedure_advertisement/3,4, etc.) then sign it with macula_record:sign/2. The relay validates the signature on receipt; an invalid signature returns {error, bad_signature}. Successful stores propagate to the K-nearest peers in the DHT under the record's macula_record:storage_key/1.

-spec recv(stream()) -> {chunk, binary()} | {data, term()} | eof | {error, term()}.

Receive the next chunk (blocks).

-spec resolve(client(), binary()) -> {ok, map()} | {error, term()}.

Resolve a mesh name to node identity information.

Returns the node's identity including name, site_id, city, endpoint, and connected_at timestamp. Works for names, site_ids, or node_ids.

-spec send(stream(), binary()) -> ok | {error, term()}.

Send a binary chunk on the stream.

-spec send(stream(), binary() | term(), raw | msgpack) -> ok | {error, term()}.

Send a chunk with explicit encoding.

-spec set_cookie(atom() | binary()) -> ok.

Set the Erlang cluster cookie.

-spec set_reply(stream(), term()) -> ok.

Server-side: emit the terminal reply value.

-spec subscribe(client(), topic(), fun((term()) -> ok) | pid()) -> {ok, reference()} | {error, term()}.

Subscribe to a topic.

The callback receives the event payload (map or binary). Returns a subscription reference for unsubscribing.

-spec subscribe_records(client(), record_type(), fun((record()) -> any()) | pid()) ->
                           {ok, reference()} | {error, term()}.

Subscribe to live record-stored events filtered by type.

The callback (or pid) receives each newly-stored record of the given type as {record, Record} (pid form) or via direct invocation (fun form). Returns a subscription reference for unsubscribe_records/2. Topic shape is _dht.records.<type>.stored, rendered with the type tag as a decimal integer for log friendliness.

-spec unadvertise(client(), procedure()) -> ok | {error, term()}.

Stop advertising a procedure.

-spec unadvertise_stream(procedure()) -> ok.

Stop advertising a streaming procedure.

-spec unmonitor_nodes() -> ok.

Unsubscribe from node up/down events.

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

Unsubscribe from a topic.

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

Cancel a subscribe_records/3 subscription.