57 lines
2.4 KiB
Markdown
57 lines
2.4 KiB
Markdown
# 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:
|
||
|
||
```json
|
||
{"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.
|