macula_dist_relay (macula v3.13.0)
View SourceRelay-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 this node as accepting distribution connections via relay.
Connect to a remote node via relay mesh.
Get metrics for all active tunnels.
Get metrics for a specific tunnel.
Check if relay distribution mode is enabled.
Register a mesh relay client for distribution tunneling.
Functions
-spec advertise_dist_accept() -> ok.
Advertise this node as accepting distribution connections via relay.
Connect to a remote node via relay mesh.
-spec get_mesh_client() -> pid() | undefined.
Get metrics for all active tunnels.
Get metrics for a specific tunnel.
-spec is_relay_mode() -> boolean().
Check if relay distribution mode is enabled.
-spec register_mesh_client(pid()) -> ok.
Register a mesh relay client for distribution tunneling.