macula_connection (macula v0.20.3)

Macula Connection - QUIC Transport Layer (v0.7.0+).

This module manages the low-level QUIC connection lifecycle and message transport for mesh participants.

Responsibilities: - Establish and maintain QUIC connection - Send messages via QUIC stream - Receive and route incoming messages to handlers - Handle connection errors and reconnection - Message encoding/decoding and buffering

Renamed from macula_connection in v0.7.0 for clarity: - macula_connection = QUIC transport (this module - low-level) - macula_peer = mesh participant (high-level API)

Summary

Functions

call(Pid, Procedure, Args, Opts)

Make an RPC-style call over a connection. Sends a call message and waits for a reply. Uses the underlying send_message API with type 'bridge_rpc'.

close(Pid)

Close a connection gracefully. Stops the gen_server which triggers proper QUIC cleanup in terminate/2. Uses catch expression to handle race conditions where process may already be dead.

connect(Host, Port, Opts)

Connect to a remote endpoint. Creates a new QUIC connection to the specified host:port.

decode_messages(Buffer, Acc)

Decode all complete messages from buffer.

default_config()

get_status(Pid)

handle_call(Request, From, State)

handle_cast(Msg, State)

Handle async send message - fire and forget. Sends if connected, logs warning and drops if not.

handle_info(Info, State)

init(_)

send(Pid, Message)

Send a message over a connection asynchronously. Fire-and-forget delivery - returns immediately.

send_message(Pid, Type, Msg)

send_message_async(Pid, Type, Msg)

Send message asynchronously (fire-and-forget). Use for operations where blocking is unacceptable and failures can be tolerated. The message will be sent if connected, silently dropped if not.

start_keepalive_timer(State)

Start keep-alive timer if enabled in options.

start_link(Url, Opts)

terminate(Reason, State)

Functions

call(Pid, Procedure, Args, Opts)

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

Make an RPC-style call over a connection. Sends a call message and waits for a reply. Uses the underlying send_message API with type 'bridge_rpc'.

close(Pid)

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

Close a connection gracefully. Stops the gen_server which triggers proper QUIC cleanup in terminate/2. Uses catch expression to handle race conditions where process may already be dead.

connect(Host, Port, Opts)

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

Connect to a remote endpoint. Creates a new QUIC connection to the specified host:port.

decode_messages(Buffer, Acc)

-spec decode_messages(binary(), list()) -> {list(), binary()}.

Decode all complete messages from buffer.

default_config()

-spec default_config() -> map().

get_status(Pid)

-spec get_status(pid()) -> connecting | connected | disconnected | error.

handle_call(Request, From, State)

handle_cast(Msg, State)

Handle async send message - fire and forget. Sends if connected, logs warning and drops if not.

handle_info(Info, State)

init(_)

send(Pid, Message)

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

Send a message over a connection asynchronously. Fire-and-forget delivery - returns immediately.

send_message(Pid, Type, Msg)

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

send_message_async(Pid, Type, Msg)

-spec send_message_async(pid(), atom(), map()) -> ok.

Send message asynchronously (fire-and-forget). Use for operations where blocking is unacceptable and failures can be tolerated. The message will be sent if connected, silently dropped if not.

start_keepalive_timer(State)

-spec start_keepalive_timer(#state{url :: binary(),
                                   opts :: map(),
                                   node_id :: binary(),
                                   realm :: binary(),
                                   peer_id :: integer(),
                                   connection :: pid() | undefined,
                                   stream :: pid() | undefined,
                                   status :: connecting | connected | disconnected | error,
                                   recv_buffer :: binary(),
                                   keepalive_timer :: reference() | undefined}) ->
                               #state{url :: binary(),
                                      opts :: map(),
                                      node_id :: binary(),
                                      realm :: binary(),
                                      peer_id :: integer(),
                                      connection :: pid() | undefined,
                                      stream :: pid() | undefined,
                                      status :: connecting | connected | disconnected | error,
                                      recv_buffer :: binary(),
                                      keepalive_timer :: reference() | undefined}.

Start keep-alive timer if enabled in options.

start_link(Url, Opts)

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

terminate(Reason, State)