Client for the Macula dist relay (macula-io/macula-dist-relay).

Maintains a persistent QUIC connection to a dedicated dist relay and exposes a simple API for establishing point-to-point tunnels between Erlang nodes. Each tunnel is backed by a raw QUIC stream — no framing, no pub/sub, no application-level encryption.

This replaces the pub/sub bridge approach in macula_dist_pool (the SDK's previous dist-over-mesh implementation) which forced dist bytes through the station's MessagePack/handler pipeline.

Protocol

Control frames on stream 0 (length-prefixed MessagePack):

     node → relay    identify{node_name}
     relay → node    identified{status}
     node → relay    tunnel_request{target}
     relay → node    tunnel_ok{tunnel_id} | tunnel_error{reason}
     relay → node    tunnel_notify{tunnel_id, source}
     node → relay    tunnel_close{tunnel_id}

Tunnel data streams (stream 1+) carry the raw dist wire bytes after a 32-byte tunnel_id prefix (written by the relay on stream open) that lets the client match new_stream events to pending tunnels.

Lifecycle

1. start_link(RelayUrl, NodeName) connects + sends identify 2. Await identified reply 3. request_tunnel(TargetNode) blocks until tunnel_ok + tunnel stream arrive; returns {ok, ConnRef, StreamRef, Received} for use as the dist Socket in macula_dist, where Received holds the tunnel's bytes the client read before handing the stream over 4. Incoming tunnels: tunnel_notify arrives on control, then a new_stream event; client reads 32-byte prefix, matches to the notified tunnel, hands the stream to net_kernel via the standard {accept, _, Socket, Family, Driver} protocol, and the tunnel's bytes read before the handoff reach the dist controller in its controller-ok message.

Tunnel bytes at a handoff

A tunnel stream changes owner once or twice: to the caller of request_tunnel/2, or to a setup process and then the dist controller. The bytes an owner read before the handoff, including those that arrive while a tunnel waits for tunnel_ok or tunnel_notify, travel inside the handoff message, so the new owner has them before anything the stream delivers to it directly.

Tunnel end

The client monitors the process that holds each tunnel stream after the handoff: the caller of request_tunnel/2 for an outbound tunnel, and for an inbound tunnel the setup process until it names the dist controller, then the controller. When that process ends, however it ends, the client drops the tunnel and sends tunnel_close for it once.

Control stream

Control frames reach the relay in the order the client sends them. While the relay takes no data on the control stream, the client holds them and keeps serving tunnel requests, inbound tunnels and status/1, which reports how many it holds as held_control_frames.

Not yet implemented (Phase 2 MVP)

- net_kernel handoff for incoming tunnels (needs macula_dist integration on the accept side) - automatic reconnect on relay disconnect - multiple relay failover