Search documentation of macula

# macula_dist_relay (macula v0.44.2)

View Source

Relay-routed Erlang distribution.

When MACULA_DIST_MODE=relay, Erlang distribution connections are tunneled through the Macula relay mesh instead of direct QUIC. This enables distribution across firewalls and NATs — nodes only need outbound connectivity to a relay.

The tunnel works by: 1. Node A requests a tunnel via mesh RPC (_dist.tunnel.{node}) 2. Node B creates a gen_tcp loopback pair bridged to relay pub/sub 3. Node A creates its own loopback pair bridged to the tunnel 4. dist_util handshake flows through the relay tunnel 5. Post-handshake: tick keepalive + distribution traffic via bridge

Bridge processes are supervised by `macula_dist_bridge_sup` (simple_one_for_one under `macula_dist_system`).

Tunnel bytes are encrypted with AES-256-GCM derived from the Erlang distribution cookie. The relay cannot read ETF content.

### Recommended net_ticktime

Relay adds WAN latency to every tick. Increase net_ticktime to avoid false disconnects: -kernel net_ticktime 120 The default 60s may cause spurious node-DOWN on high-latency relays.

# Summary

## Functions

advertise_dist_accept()

Advertise this node as accepting distribution connections via relay.

connect(NodeStr, Host, Port)

Connect to a remote node via relay mesh.

extract_payload(P)
get_mesh_client()
get_tunnel_metrics()

Get metrics for all active tunnels.

get_tunnel_metrics(TunnelId)

Get metrics for a specific tunnel.

is_relay_mode()

Check if relay distribution mode is enabled.

register_mesh_client(Pid)

Register a mesh relay client for distribution tunneling.

# Functions

# advertise_dist_accept()

    -spec advertise_dist_accept() -> ok.

Advertise this node as accepting distribution connections via relay.

# connect(NodeStr, Host, Port)

    -spec connect(string(), string(), integer()) -> {ok, port(), port()} | {error, term()}.

Connect to a remote node via relay mesh.

# extract_payload(P)

# get_mesh_client()

    -spec get_mesh_client() -> pid() | undefined.

# get_tunnel_metrics()

    -spec get_tunnel_metrics() -> [{binary(), map()}].

Get metrics for all active tunnels.

# get_tunnel_metrics(TunnelId)

    -spec get_tunnel_metrics(binary()) -> map() | undefined.

Get metrics for a specific tunnel.

# is_relay_mode()

    -spec is_relay_mode() -> boolean().

Check if relay distribution mode is enabled.

# register_mesh_client(Pid)

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

Register a mesh relay client for distribution tunneling.