Search documentation of macula

# macula_relay_node (macula v0.44.2)

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)