Message reference#

PacketRelay parses exactly one message per connection: the hello. Everything after it is forwarded as opaque text, so the wire vocabulary is small and closed — five hellos a client may send, twelve responses the relay may return, and nothing else. This page enumerates every envelope field by field, gives the JSON shape of each, and states the framing rules that decide which WebSocket frames the relay looks at in the first place.

Both tables are in source order — the order the variants are declared in src/protocol.rs — not alphabetical order. Source order groups the bridge, broadcast and room families together, which alphabetical order would scatter.

Client hellos#

Five hello variants, discriminated by a type tag (protocol.rs:77, protocol.rs:80). Every field on every hello is required: no field is an Option, so a missing field fails deserialisation and the connection is dropped without an error frame — connection.rs:491-546.

Both session_id and member_id are validated after parsing: non-empty, at most --max-id-bytes, charset [A-Za-z0-9._-] — connection.rs:41-50, connection.rs:472-478. A bad session_id yields {"type":"error","message":"invalid session ID"}; a bad member_id yields "invalid member ID" — connection.rs:54-65.

Hello envelopes#

The four unauthenticated hellos carry one field each. Possession of the session_id plus self-selection of a role is the whole admission boundary for them — nothing in these four envelopes is verified against anything.

{"type":"desktop_hello","session_id":"demo-session"}

{"type":"mobile_hello","session_id":"demo-session"}

{"type":"host_hello","session_id":"demo-session"}

{"type":"spectator_hello","session_id":"demo-session"}

The room_hello below uses the field values of the golden signing vector at room_auth.rs:804-812, so it lines up with the payload documented on Room authentication. The pubkey there is the literal test string pk, not a real SPKI DER key, and sig is shown elided because the vector pins the payload rather than a signature.

{
  "type": "room_hello",
  "session_id": "sid",
  "member_id": "m1",
  "pubkey": "pk",
  "nonce": 42,
  "sig": "<base64 P1363 r||s>"
}

Unknown fields are ignored#

No hello variant carries #[serde(deny_unknown_fields)] — protocol.rs:76-80. Extra keys in a hello are silently dropped during deserialisation, so a client that sends a client_version or user_id alongside session_id is admitted exactly as though it had not, and receives no indication that the field went nowhere.

Relay responses#

Twelve response variants, also tagged by type (protocol.rs:114-115). Every one is emitted as a WebSocket text frame; the relay never sends a binary frame.

Response envelopes#

session_ready and room_ready are quoted from the shared fixtures in testdata/, which the wire-conformance tests assert against the serialised enum — protocol.rs:172-191. The member_joined, member_left and member_count samples use the exact values pinned at protocol.rs:193-213.

{"type":"session_ready","session_id":"test-sid"}

{"type":"peer_connected"}

{"type":"peer_disconnected"}

{"type":"host_connected"}

{"type":"host_disconnected"}

{"type":"viewer_count","count":3}

{"type":"room_ready","session_id":"test-sid"}

{"type":"member_joined","member_id":"m1"}

{"type":"member_left","member_id":"m1"}

{"type":"member_count","count":3}

{"type":"member_frame","member_id":"m1","payload":"{\"kind\":\"chat\"}"}

{"type":"error","message":"invalid session ID"}

A field-less variant serialises to an object carrying only type — that is what #[serde(tag = "type")] does to a unit variant, and it is why peer_connected is a well-formed object rather than a bare string.

Frame handling is narrower than WebSocket#

The relay reads six WebSocket message kinds and acts on two of them. The table is exhaustive: any frame not listed does not exist in tokio-tungstenite 0.26's message enum.

Three consequences follow, and all three surprise clients.

The first frame must be text. A client that opens with a binary hello — a MessagePack or CBOR encoding, say — is closed without an error frame, because the refusal happens before any parsing that could produce a message to send.

Discarded frames cost nothing. Binary, Pong and raw Frame are dropped before the budget is touched, so a peer can flood the relay with binary frames and never trip "message rate exceeded". The connection-admission limiter and the tungstenite max_frame_size ceiling are the only things standing in the way — see Limits & capacity.

The relay never initiates a keepalive. It echoes Ping as Pong and sends no Ping of its own — connection.rs:397-399. There is also no post-hello idle timeout (connection.rs:333-409), so an idle connection is held open indefinitely by the relay and torn down only by the client or the network path.

Keepalive recognition is exact, not heuristic#

The relay recognises one application-level keepalive envelope and drops it rather than forwarding it. is_relay_keepalive_ping requires all four conditions — connection.rs:480-488:

1. The frame is shorter than 64 bytes.
2. It parses as JSON.
3. The parsed value is an object with exactly one key.
4. That key is "type" and its value is the string "ping".

{"type":"ping"}

Anything else is an ordinary application frame and is forwarded. A keepalive with a second key — {"type":"ping","t":1756512000000} — fails condition 3 and is relayed to the peer as normal traffic. This is deliberate: the test at connection.rs:584 pins the exact envelope so that widening the rule is a visible change rather than an accident.

The relay never sends a Close frame#

Every refusal path — invalid session id, invalid member id, session kind mismatch, capacity, a failed room signature, a breached message budget — sends an error text frame and then returns from the handler, dropping the sink. No WebSocket Close frame with a status code is ever sent.

A client therefore cannot distinguish refusal reasons from the close code, because there is no close code. The error frame is the only signal, and on the paths that precede it — hello timeout, close before hello, unparseable hello JSON, connection-rate breach — there is no signal at all: the socket simply goes away. Troubleshooting maps the silent failures to their causes.

Related#

• Room authentication — the canonical signing payload, nonce window and TOFU pinning behind room_hello.
• Core concepts — sessions, roles and session kinds, and which hello selects which.
• Bridge sessions — the message order a desktop and mobile pair actually observe.
• Broadcast sessions — host fan-out, viewer counts, and the ordering quirk spectators see.
• Limits & capacity — what the message budget charges, and what it does not.
• Troubleshooting — the silent drops, and how to tell them apart.