WebSocket wire reference

Handshake & close codes

wss://engine.example.com/ws
Sec-WebSocket-Protocol: inachess.v2, <sessionToken>

# One socket per login session. The token travels in the subprotocol list —
# never in the URL — and is validated BEFORE the upgrade: a bad/expired token
# is refused at the handshake, never as a message.
# Close codes: 4001 token expired (re-mint, don't retry) · 4002 replaced by the
# user's own newer socket (don't retry).

Server → client

WS game_state

full snapshot of one room — replaces the client's whole view. Sent on own-game push (match start / reconnect), on subscribe, and re-broadcast on every gate accept. Seat-relative: you / youAccepted differ per recipient. Also carries the match identity (variant, timeControl, players — the exact seat shape of match_found), so a client that reconnects after a page reload or device switch, or a spectator who never got a match_found, can still render the players.

WS move

broadcast to the room after a move is validated.

WS match_found

pushed when the player is seated in a new game (matchmaking pair, bot fallback, tournament round), always before that room's first game_state. matchId is the room id to route to. The same identity (variant, timeControl, players) repeats in every game_state, so losing this message — page reload, device switch — loses nothing.

WS game_over

the room finished — terminal for that room only, the session socket stays open.

WS draw_offer

the opponent proposed a draw.

WS draw_declined

your draw offer was declined.

WS error

a rejected command, sent only to the offending client. Branch on code — message is human text and may change.

WS ping

lag probe + periodic clock resync (~5s per room). The SDK answers automatically with a pong echoing t.

Client → engine

// Game intents carry NO room — the engine resolves it from the player:
{ "type": "move", "uci": "e2e4" }
{ "type": "resign" }
{ "type": "offer_draw" } · { "type": "accept_draw" } · { "type": "decline_draw" }
{ "type": "claim_draw" } · { "type": "abort" } · { "type": "accept" }
{ "type": "pong", "t": 1720000000 }

// Session-scoped intents (lobby-level — they address no room):
{ "type": "queue", "variant": "standard", "timeControl": "blitz_3_2", "rated": true, "autoBot": true }
{ "type": "queue_cancel" }
{ "type": "subscribe",   "room": "match_abc" }   // omit room to re-attach to your own game
{ "type": "unsubscribe", "room": "match_abc" }
{ "type": "play_bot", "level": 5, "color": "white", "timeControl": "blitz_3_2" }

Game intents

They carry no room — one active game per user, so the engine resolves the game from the player:

Session intents

queue — never carries a rating (the engine pulls it); rate-limited per session; double enqueue → already_queued. queue_cancel takes no params.

subscribe / unsubscribe — spectate is delayed by spectatorDelaySec and capped per game (spectator_limit):

play_bot — no Stockfish available → bots_unavailable:

Delivery guarantees on the socket

• Game frames are never shed. A saturated spectator stream is dropped first — a lost move frame would silently desync the board, so it never happens.
• Reconnect restores your own game only. The pushed game_state carries the full match identity (variant, timeControl, players) — no state from the original match_found is needed. Spectate subscriptions and queue entries are not restored — re-request them on open.
• Every rejection is an error with a stable code. Full list + handling: Errors & codes.