macula_relay_node (macula v0.20.5)

View Source

Peer Relay Node.

Provides relay functionality for peers that cannot establish direct connections due to NAT restrictions. A relay node:

- Accepts connections from peers behind restrictive NATs - Forwards traffic between connected peers - Manages relay sessions with bandwidth limits - Auto-registers with relay registry when capable

Relay Protocol: 1. Peer A connects to relay with RELAY_REQUEST(target_id) 2. Relay checks if target is reachable and accepts 3. Relay establishes/reuses connection to target 4. Relay forwards bidirectional traffic 5. Either peer can close the relay session

Resource Limits: - Max concurrent relay sessions (default: 100) - Per-session bandwidth limit (default: 1 MB/s) - Session timeout (default: 30 minutes)

Summary

Types

relay_session/0
relay_stats/0

Functions

close_relay(SessionId)

Close a relay session.

disable()

Disable relay functionality.

enable()

Enable relay functionality on this node.

enable(Opts)

Enable relay with options. Options: node_id - This node's ID endpoint - This node's endpoint for relay registry capacity - Max concurrent sessions

get_sessions()

Get active relay sessions.

get_stats()

Get relay statistics.

handle_call(Request, From, State)
handle_cast(Msg, State)
handle_info(Info, State)
init(Opts)
is_enabled()

Check if relay is enabled.

request_relay(InitiatorId, TargetId)

Request a relay session to target. Returns session ID on success.

start_link(Opts)

Start the relay node server.

terminate(Reason, State)

Types

relay_session/0

-type relay_session() ::
          #{session_id := binary(),
            initiator_id := binary(),
            target_id := binary(),
            initiator_conn => term(),
            target_conn => term(),
            started_at := integer(),
            bytes_relayed := non_neg_integer(),
            last_activity := integer()}.

relay_stats/0

-type relay_stats() ::
          #{enabled := boolean(),
            max_sessions := pos_integer(),
            active_sessions := non_neg_integer(),
            total_bytes_relayed := non_neg_integer(),
            total_sessions_created := non_neg_integer()}.

Functions

close_relay(SessionId)

-spec close_relay(binary()) -> ok.

Close a relay session.

disable()

-spec disable() -> ok.

Disable relay functionality.

enable()

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

Enable relay functionality on this node.

enable(Opts)

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

Enable relay with options. Options: node_id - This node's ID endpoint - This node's endpoint for relay registry capacity - Max concurrent sessions

get_sessions()

-spec get_sessions() -> [relay_session()].

Get active relay sessions.

get_stats()

-spec get_stats() -> relay_stats().

Get relay statistics.

handle_call(Request, From, State)

handle_cast(Msg, State)

handle_info(Info, State)

init(Opts)

is_enabled()

-spec is_enabled() -> boolean().

Check if relay is enabled.

request_relay(InitiatorId, TargetId)

-spec request_relay(binary(), binary()) -> {ok, binary()} | {error, term()}.

Request a relay session to target. Returns session ID on success.

start_link(Opts)

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

Start the relay node server.

terminate(Reason, State)