-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 child_spec(term(), [macula_client:seed()], macula_client:opts()) -> supervisor:child_spec().

OTP child spec to drop a V2 pool into a caller's supervision tree.

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

Stop a V2 pool. Every subscriber receives a final {macula_event_gone, SubRef, pool_closed} message.

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

Half-close the write side; recv still drains.

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

Close a V1 stream (both sides). Renamed from close/1 in 3.11.0 because close/1 now refers to the V2 pool surface.

-spec connect([macula_client:seed()], macula_client:opts()) -> {ok, pool()} | {error, term()}.

Connect to the Macula relay mesh and return a pool handle.

Seeds is a list of relay endpoints (URL binaries/strings or #{host, port} maps). The pool spawns one peering link per seed and routes ops with replication, replay, and event dedup. Returns immediately; link handshakes complete asynchronously.

See macula_client for the canonical pool implementation and macula_pubsub for the slice module.

**Breaking change since 3.11.0**: this function previously returned a macula_mesh_client single-connection client. V1 callers must now call macula_mesh_client:start_link/1 directly to retain V1 semantics. See CHANGELOG.md / migration guide.

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

Disconnect a V1 macula_mesh_client client. **Legacy** — V2 pools use close/1.

-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.

V1 publish — single-connection client, no realm. **Legacy**. V2 callers use publish/4 or publish/5.

-spec publish(pool(), realm(), topic(), term()) -> ok | {error, term()}.

Publish to (Realm, Topic) on Pool. Equivalent to publish/5 with empty opts.

**Breaking change since 3.11.0**: this signature previously was publish(Client, Topic, Data, Opts) (V1). V1 callers using the 4-arg form must call macula_mesh_client:publish/3 directly to retain V1 semantics.

-spec publish(pool(), realm(), topic(), term(), map()) -> ok | {error, term()}.

Publish to (Realm, Topic) on Pool with options. See macula_pubsub:publish/5 for honored opts.

-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()}.

V1 subscribe — single-connection client, no realm. **Legacy**. V2 callers use subscribe/4 or subscribe/5.

-spec subscribe(pool(), realm(), topic(), pid()) -> {ok, reference()}.

Subscribe Subscriber to (Realm, Topic) on Pool. Equivalent to subscribe/5 with empty opts.

-spec subscribe(pool(), realm(), topic(), pid(), map()) -> {ok, reference()}.

Subscribe Subscriber to (Realm, Topic) on Pool with options. See macula_pubsub:subscribe/5.

-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(pool(), reference()) -> ok.

Drop a V2 pool subscription. Idempotent.

**Breaking change since 3.11.0**: this routes to the V2 pool (macula_client:unsubscribe/2). V1 callers must call macula_mesh_client:unsubscribe/2 directly to drop a V1 sub.

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

Cancel a subscribe_records/3 subscription.