macula_mesh_client (macula v3.13.0)

Macula Mesh Client — connects a node to the relay mesh via QUIC.

Single gen_server managing ONE persistent QUIC connection to a relay with automatic failover across multiple relays. On disconnect, cycles to the next relay in the list with exponential backoff + jitter. Replays all subscriptions and procedure registrations on reconnect.

This is the SDK client module. It speaks the node role only — it cannot identify as a relay, cannot subscribe to _swim/_dht/_relay.*, and has no loop-prevention concerns. For relay-to-relay peering connections, see macula_peer_client in the macula-relay repository.

Usage:

   {ok, Client} = macula_mesh_client:start_link(#{
       relays => [<<"quic://boot.macula.io:443">>],
       realm => <<"io.macula">>
   }).

Summary

Types

stream_handler/0

stream_mode/0

Functions

advertise(Pid, Procedure, Handler)

advertise_stream(Pid, Procedure, Handler)

Advertise a streaming procedure (default mode: server_stream). Registers locally in this client's stream_procedures map AND sends a register_procedure frame upstream so the relay routes incoming STREAM_OPEN frames for Procedure back to this client.

advertise_stream(Pid, Procedure, Mode, Handler)

call(Pid, Procedure, Args, Timeout)

call(Pid, Procedure, Args, Timeout, Opts)

call_stream(Pid, Procedure, Args, Opts)

Open a server-stream call against a connected mesh client.

call_stream(Pid, Procedure, Args, Opts, Timeout)

handle_call(Request, From, State)

handle_cast(Msg, State)

handle_info(Info, State)

init(Opts)

is_connected(Pid)

open_stream(Pid, Procedure, Args, Opts)

Open a client-stream or bidi call (mode from opts; default bidi).

open_stream(Pid, Procedure, Args, Opts, Timeout)

publish(Pid, Topic, Payload)

send_stream_frame(Pid, Type, Msg)

Send a STREAM_* frame out the QUIC stream (called by macula_stream_v1 processes when their peer shape is {remote, ...}).

start_link(Opts)

stop(Pid)

subscribe(Pid, Topic, Callback)

terminate(Reason, State)

unadvertise(Pid, Procedure)

unsubscribe(Pid, Ref)