macula_relay_registry (macula v0.20.5)

View Source

Distributed Relay Registry.

Tracks peers that can serve as relay nodes for NAT traversal. Peers with public IPs or NATs that allow incoming connections can register as relay-capable.

Relay Selection Criteria: - Peer must have public IP or full-cone NAT - Lower latency to requesting peer preferred - Load balancing across available relays - Geographic proximity (via RTT estimation)

Registry Storage: - Local ETS for fast lookup - DHT for distributed discovery - TTL-based cleanup for stale entries

Usage: register(NodeId, Endpoint) to register as relay-capable, find_relay(TargetNodeId) to find best relay for a target.

Summary

Types

find_opts/0
relay_info/0

Functions

find_relay(TargetNodeId)

Find best relay for connecting to a target.

find_relay(TargetNodeId, Opts)

Find relay with options.

get_relay_count()

Get count of available relays.

get_relays()

Get all registered relays.

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

Check if a node is registered as relay.

register(NodeId, Endpoint)

Register current node as relay-capable.

register(NodeId, Endpoint, Opts)

Register as relay with options. Options: capacity - Maximum concurrent relay connections (default: 100)

start_link(Opts)

Start the relay registry server.

terminate(Reason, State)
unregister(NodeId)

Unregister as relay.

Types

find_opts/0

-type find_opts() ::
          #{max_results => pos_integer(), exclude => [binary()], max_latency_ms => non_neg_integer()}.

relay_info/0

-type relay_info() ::
          #{node_id := binary(),
            endpoint := {binary() | string(), inet:port_number()},
            capacity := non_neg_integer(),
            current_load := non_neg_integer(),
            latency_ms => non_neg_integer(),
            registered_at := integer(),
            expires_at := integer()}.

Functions

find_relay(TargetNodeId)

-spec find_relay(binary()) -> {ok, relay_info()} | {error, no_relays_available}.

Find best relay for connecting to a target.

find_relay(TargetNodeId, Opts)

-spec find_relay(binary(), find_opts()) -> {ok, relay_info()} | {error, no_relays_available}.

Find relay with options.

get_relay_count()

-spec get_relay_count() -> non_neg_integer().

Get count of available relays.

get_relays()

-spec get_relays() -> [relay_info()].

Get all registered relays.

handle_call(Request, From, State)

handle_cast(Msg, State)

handle_info(Info, State)

init(Opts)

is_relay(NodeId)

-spec is_relay(binary()) -> boolean().

Check if a node is registered as relay.

register(NodeId, Endpoint)

-spec register(binary(), {binary() | string(), inet:port_number()}) -> ok | {error, term()}.

Register current node as relay-capable.

register(NodeId, Endpoint, Opts)

-spec register(binary(), {binary() | string(), inet:port_number()}, map()) -> ok | {error, term()}.

Register as relay with options. Options: capacity - Maximum concurrent relay connections (default: 100)

start_link(Opts)

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

Start the relay registry server.

terminate(Reason, State)

unregister(NodeId)

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

Unregister as relay.