Search documentation of macula

# macula_gateway_mesh (macula v0.44.2)

View Source

Mesh Connection Manager GenServer - manages peer-to-peer QUIC connections.

Responsibilities: - Pool QUIC connections to remote peers by node_id (BOUNDED POOL) - Enforce max_connections limit with LRU eviction - Check connection liveness before reuse - Open new streams on pooled connections - Monitor connection processes for automatic cleanup - Cache connection metadata with timestamps

Pattern: Bounded connection pooling with LRU eviction - Cache connections by node_id (max: max_mesh_connections, default 1000) - Evict least recently used when pool is full - Verify liveness before reuse (open new stream) - Remove dead connections and recreate on demand

Configuration: - max_mesh_connections: Maximum pooled connections (default: 1000)

Extracted from macula_gateway.erl (Phase 9)

# Summary

## Types

connection_info/0

## Functions

get_connection_info(Pid, NodeId)

Get connection metadata for a node.

get_or_create_connection(Pid, NodeId, Address)

Get existing connection or create new one. Returns opened stream ready for use.

handle_call(Request, From, State)
handle_cast(Msg, State)

Handle async send request - spawns process for connection + send. Fire-and-forget pattern - does not block the gen_server.

handle_info(Info, State)
init(Opts)
list_connections(Pid)

List all cached connections.

remove_connection(Pid, NodeId)

Explicitly remove connection from cache.

send_async(Pid, NodeId, Address, EncodedMessage)

Send message asynchronously (fire-and-forget). Connection creation and sending happens in a spawned process. Does NOT block the caller - returns immediately with 'ok'. Use this for pubsub_route and other non-critical messages.

start_link(Opts)

Start the mesh connection manager with options. Options: - cert_file: Path to TLS certificate - key_file: Path to TLS private key Registers as 'macula_gateway_mesh' for discovery by pubsub module.

stop(Pid)

Stop the mesh connection manager.

terminate(Reason, State)

# Types

# connection_info/0

    -type connection_info() ::
              #{connection => pid() | reference() | undefined,
                stream => pid() | reference() | undefined,
                address => {inet:ip_address(), inet:port_number()},
                last_used => integer()}.

# Functions

# get_connection_info(Pid, NodeId)

    -spec get_connection_info(pid(), binary()) -> {ok, connection_info()} | not_found.

Get connection metadata for a node.

# get_or_create_connection(Pid, NodeId, Address)

    -spec get_or_create_connection(pid(), binary(), {inet:ip_address(), inet:port_number()}) ->
                                      {ok, pid()} | {error, term()}.

Get existing connection or create new one. Returns opened stream ready for use.

# handle_call(Request, From, State)

# handle_cast(Msg, State)

Handle async send request - spawns process for connection + send. Fire-and-forget pattern - does not block the gen_server.

# handle_info(Info, State)

# init(Opts)

# list_connections(Pid)

    -spec list_connections(pid()) -> {ok, [{binary(), connection_info()}]}.

List all cached connections.

# remove_connection(Pid, NodeId)

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

Explicitly remove connection from cache.

# send_async(Pid, NodeId, Address, EncodedMessage)

    -spec send_async(pid(), binary(), binary() | {inet:ip_address(), inet:port_number()}, binary()) -> ok.

Send message asynchronously (fire-and-forget). Connection creation and sending happens in a spawned process. Does NOT block the caller - returns immediately with 'ok'. Use this for pubsub_route and other non-critical messages.

# start_link(Opts)

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

Start the mesh connection manager with options. Options: - cert_file: Path to TLS certificate - key_file: Path to TLS private key Registers as 'macula_gateway_mesh' for discovery by pubsub module.

# stop(Pid)

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

Stop the mesh connection manager.

# terminate(Reason, State)