maze32/docs/PROTOCOL.md

maze32 WebSocket protocol v1

Limits and ordering

• Endpoint: /ws.
• At most six WebSocket connections are accepted: two players and four observers.
• A text frame is at most 512 bytes. Binary frames are rejected.
• Each connection may submit at most 20 messages in a one-second monotonic window.
• The gateway uses a fixed 12-entry outgoing queue with 768 bytes per entry.
• Client sequence numbers start above zero and strictly increase for the life of one WebSocket connection. Replayed or decreasing values are rejected.
• Server sequence numbers strictly increase until reboot. Clients discard stale server messages.

All messages use this envelope:

{"v":1,"type":"message_type","seq":1,"requestId":"optional","payload":{}}

Envelope keys may appear in any order except that type must precede payload. Unknown and duplicate keys are rejected. requestId is optional and is only echoed for correlation; it grants no authority.

Client messages

• join: {"role":"player","name":"..."} or {"role":"observer"}. Player names contain 1–32 UTF-8 bytes, have no control bytes or outer spaces, and are unique within the current lobby.
• restore: {"token":"32 lowercase hexadecimal characters"}.
• suggest_name: {}.
• start: {}. Only connected Player 1 may use it, and both player slots must be connected.
• heartbeat: {} after a session has been joined or restored.

No Milestone 005 maze or movement messages are implemented by this milestone.

Server messages

• session: the private role result containing role, slot, and temporary token. The token is never included in a shared snapshot.
• name_suggestion: an available humorous Russian player name.
• lobby: the authoritative phase, revision, readiness, public player slots, connected observer count, and limits.
• countdown: the single authoritative [3,2,1] event with common monotonic startedAtMs and activationAtMs values. It is sent to both players.
• active: the exact authoritative activation instant.
• ack: successful heartbeat correlation.
• error: a stable English code and Russian player-facing message.

An observer session can receive snapshots but cannot issue start. Player tokens reserve their original slot after disconnection so a refresh can restore it. A disconnected observer token may be restored until its bounded slot is reused by a new observer.