PacketRelayDocs

Operate PacketRelay#

PacketRelay is a small in-memory router, but its process boundaries matter. Operate one replica per client population, terminate TLS before traffic reaches the relay, and set resource limits before exposing it publicly.

Before you start#

  • Complete Deploy.
  • Confirm which application and client versions use the relay.
  • Estimate concurrent connections, spectators, room members, and frame sizes.
  • Arrange process restart and log collection through the hosting platform.

Health checks#

Use /health or /healthz for liveness and /ready or /readyz for readiness. Point the platform readiness check at /ready and keep WebSocket traffic on a different path.

test -n "$PACKETRELAY_URL" || { echo "Set PACKETRELAY_URL to the deployed origin" >&2; exit 1; }
curl -fsS "$PACKETRELAY_URL/health"
curl -fsS "$PACKETRELAY_URL/ready"

Configure limits#

Review the built-in help before changing defaults:

packet-relay --help

The main controls limit total connections, sessions, spectators, room members, identifier length, frame size, hello time, and per-connection traffic. Start with conservative limits and raise them only after observing legitimate load.

PORT selects the listener port. RUST_LOG selects Rust log filtering. Other runtime behaviour is configured with command-line options.

Scaling and restarts#

State is not shared. Two replicas may accept the same session identifier while routing different clients, so ordinary round-robin scaling breaks pairing. Scale vertically or partition clients to a known relay instance.

A restart drops every WebSocket, session, room pin, and nonce high-water mark. Clients must reconnect, repeat admission, and restore application state.

Verify#

  1. Restart one test instance with the new limits.
  2. Confirm health and readiness.
  3. Complete a bridge round trip.
  4. Exercise the limit being changed with a controlled client.
  5. Confirm logs show the expected refusal without exposing application payloads.

If it does not work#

Symptom Check Recovery
Health passes but clients disconnect The close code the client received See Read the close code
Sessions drop at a regular interval Heartbeat timing against any proxy idle timeout See Diagnose heartbeat timeouts
A limit change has no effect Whether the process was restarted Limits are read at start
Scaling produced two relays instead of one Whether sessions are held in a single process Sessions are in-memory and per-process; a second replica is a second relay
Metrics cannot be scraped The token and the exact path See Metrics scrape problems