macula_mesh_client (macula v1.4.25)

View Source

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

Functions

advertise(Pid, Procedure, Handler)

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

call(Pid, Procedure, Args, Timeout)

-spec call(pid(), binary(), map(), timeout()) -> {ok, term()} | {error, term()}.

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

-spec call(pid(), binary(), map(), timeout(), map()) -> {ok, term()} | {error, term()}.

handle_call(Request, From, State)

handle_cast(Msg, State)

handle_info(Info, State)

init(Opts)

is_connected(Pid)

-spec is_connected(pid()) -> boolean().

publish(Pid, Topic, Payload)

-spec publish(pid(), binary(), binary() | map()) -> ok.

start_link(Opts)

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

stop(Pid)

-spec stop(pid()) -> ok.

subscribe(Pid, Topic, Callback)

-spec subscribe(pid(), binary(), fun((map()) -> ok)) -> {ok, reference()}.

terminate(Reason, State)

unadvertise(Pid, Procedure)

-spec unadvertise(pid(), binary()) -> ok.

unsubscribe(Pid, Ref)

-spec unsubscribe(pid(), reference()) -> ok.