Search documentation of macula

# macula_connection (macula v0.44.2)

View Source

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

build_node_identity(Opts)

Build node identity from opts or environment variables. Opts key `identity` takes precedence. Falls back to HECATE_GEO_* and MACULA_GEO_* env vars (same pattern as relay identity).

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

# build_node_identity(Opts)

    -spec build_node_identity(map()) -> map().

Build node identity from opts or environment variables. Opts key `identity` takes precedence. Falls back to HECATE_GEO_* and MACULA_GEO_* env vars (same pattern as relay identity).

# 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,
                                       connect_in_flight :: boolean(),
                                       retry_delay_ms :: pos_integer()}) ->
                                   #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,
                                          connect_in_flight :: boolean(),
                                          retry_delay_ms :: pos_integer()}.

Start keep-alive timer if enabled in options.

# start_link(Url, Opts)

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

# terminate(Reason, State)