houserules/packages/server/PROTOCOL.md

Chess Server WebSocket Protocol v1

Overview

All WebSocket messages are JSON. Every message includes:

• v: 1 — protocol version; mismatch triggers hard disconnect
• seq: number — monotonic sequence number (client and server maintain separate counters; client acks server seq)
• ts: number — unix milliseconds timestamp of message creation

Maximum message size: 64KB. Exceeding this limit causes hard disconnect with error code MSG_TOO_LARGE.

The server is AUTHORITATIVE. Clients send INTENTS (what they want to do). The server validates, applies the intent to the engine session, and broadcasts FACTS (what changed) to all room members.

Connection

WebSocket upgrade URL: ws://{host}:{port}/ws

Required query params on upgrade: none (auth happens via first message after connect).

Origin allow-list: Configurable via ALLOWED_ORIGINS env var (comma-separated). Requests from unlisted origins receive HTTP 403 before upgrade. Default: http://localhost:5173 (dev).

Message Envelope

Every message has this wrapper:

{
  "v": 1,
  "seq": 42,
  "ts": 1745000000000,
  "type": "room.create",
  "token": "optional-room-token",
  "payload": {}
}

token is required on all messages AFTER the first room.create or room.join. The first message from a client need not include token.

Auth & Rooms

• Room codes: 6 characters, uppercase [A-Z0-9], randomly generated
• Room token: UUID v4, returned on room.create, required on subsequent messages
• Rooms are in-memory only (lost on server restart)
• Maximum 2 players per room
• 60-second reconnection grace window after disconnect

Message: room.create

Direction: Client → Server Purpose: Create a new game room. Server responds with room code and auth token.

Request payload:

{
  "rulesetIds": ["pawns-move-backward", "piece-hp"],
  "layout": { "kind": "premade", "id": "dunsany" }
}

• rulesetIds: optional array of preset rule IDs to activate for this game
• layout: optional starting-layout selector. Discriminated union:
  • { "kind": "premade", "id": "dunsany" } — look up by registered id (classic, dunsany, monster, pawns-only, horde, knightmate, chess960, empty).
  • { "kind": "fen", "fen": "rnbqkbnr/...", "name": "optional" } — parse the piece-placement field of a FEN string. Extra FEN fields (side-to-move, castling, en-passant, clocks) are ignored.
  • { "kind": "custom", "pieces": [...], "name": "optional" } — direct placements; each piece is { type, color, square, hasMoved? }. square is 0..63. Capped at 128 pieces.
• When layout is omitted, the server uses the Classic (FIDE) layout.

Response (Server → Client, type room.created):

{
  "v": 1, "seq": 1, "ts": 1745000000000,
  "type": "room.created",
  "payload": {
    "code": "ABC123",
    "token": "550e8400-e29b-41d4-a716-446655440000",
    "color": "white",
    "layout": {
      "id": "dunsany",
      "name": "Dunsany's Chess",
      "pieces": [{ "type": "pawn", "color": "white", "square": 0 }, ...]
    }
  }
}

• layout: resolved starting layout echoed back. Present on all room.created and room.joined responses from new servers; may be absent on legacy (pre-layouts) servers.
• profile: resolved modifier profile echoed back. Same shape as the request-side profile field. Omitted when the room was created without a profile, or when the server is pre-modifiers.

Error cases:

• Server at capacity (too many rooms): error code SERVER_FULL
• Layout fails validation (bad king count, duplicate squares, unknown premade id, malformed FEN): error code LAYOUT_INVALID. Message field carries the human-readable reason.
• Modifier profile fails validation: error code MODIFIER_PROFILE_INVALID (schema / descriptor value-schema failure) or one of the three carved-out invariants: MODIFIER_PROFILE_NO_KING, MODIFIER_PROFILE_INVULN_KING, MODIFIER_PROFILE_DEADLOCK. The message field carries a human-readable reason; clients may use the code for targeted UI hints (e.g. "Your profile leaves white with no king — please adjust the setup").

Message: room.join

Direction: Client → Server Purpose: Join an existing room as the second player.

Request payload:

{
  "code": "ABC123"
}

Response (Server → Client, type room.joined):

{
  "v": 1, "seq": 1, "ts": 1745000000000,
  "type": "room.joined",
  "payload": {
    "code": "ABC123",
    "token": "661f9500-f30c-52e5-b827-557766550111",
    "color": "black",
    "activeRules": ["pawns-move-backward"],
    "layout": {
      "id": "dunsany",
      "name": "Dunsany's Chess",
      "pieces": [{ "type": "pawn", "color": "white", "square": 0 }, ...]
    }
  }
}

• layout: resolved layout used when the room was created. Late joiners render the board from this. Optional for backward compat.

When second player joins, server broadcasts game.state to BOTH players (initial board state).

Error cases:

• Room not found: error code ROOM_NOT_FOUND
• Room full (2 players already): error code ROOM_FULL
• Wrong protocol version: disconnect + error code VERSION_MISMATCH

Message: room.leave

Direction: Client → Server Purpose: Voluntarily leave a room / concede.

Request payload: {}

Server broadcasts game.end with reason: "player_left" to remaining player.

Message: game.move

Direction: Client → Server Purpose: Express a move intent. Server validates and applies if legal.

Request payload:

{
  "from": "e2",
  "to": "e4",
  "promoteTo": "queen"
}

• from, to: algebraic square notation (a1–h8)
• promoteTo: optional, only relevant for pawn promotion; one of "queen", "rook", "bishop", "knight"

On valid move: Server applies to engine, broadcasts game.delta to both players. On invalid move: Server sends error (code ILLEGAL_MOVE) to mover only; no broadcast.

Error cases:

• Not your turn: error code NOT_YOUR_TURN
• Illegal move: error code ILLEGAL_MOVE
• Game already over: error code GAME_OVER

Message: game.state

Direction: Server → Client Purpose: Full board state snapshot. Sent on room join and on reconnect.

Payload:

{
  "fen": "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1",
  "facts": [
    { "id": 1, "attr": "PieceType", "value": "pawn" },
    { "id": 1, "attr": "Color", "value": "white" },
    { "id": 1, "attr": "Position", "value": 12 }
  ],
  "activeRules": ["pawns-move-backward"],
  "turn": "black",
  "lastSeq": 42,
  "moveHistory": ["e2-e4"]
}

• fen: standard FEN string for UI rendering convenience
• facts: all non-derived working-memory facts
• lastSeq: highest server seq the client should ack from (used for reconnect delta)

Message: game.delta

Direction: Server → Client Purpose: Incremental fact changes after each move. Sent to BOTH players after valid move.

Payload:

{
  "inserted": [
    { "id": 1, "attr": "Position", "value": 28 }
  ],
  "retracted": [
    { "id": 1, "attr": "Position", "value": 12 }
  ],
  "moveNotation": "e2e4",
  "turn": "black",
  "gameOver": null
}

• inserted: facts added to working memory this tick
• retracted: facts removed this tick (identified by id+attr)
• gameOver: null if game continues; { winner: "white"|"black"|"draw", reason: "checkmate"|"stalemate"|"50-move"|"threefold"|"insufficient"|"player_left" } when game ends

Message: game.end

Direction: Server → Client Purpose: Explicit game-over notification (also included in game.delta gameOver field, but sent separately for clarity).

Payload:

{
  "winner": "white",
  "reason": "checkmate",
  "finalFen": "rnb1kbnr/pppp1ppp/8/4p3/6Pq/5P2/PPPPP2P/RNBQKBNR w KQkq - 0 3"
}

Message: modifier-profile.update

Direction: Client → Server Purpose: Replace the room's active modifier profile. Applied by the server at the NEXT TURN BOUNDARY — never mid-move.

Request payload:

{
  "type": "modifier-profile.update",
  "roomCode": "ABC123",
  "newProfile": {
    "id": "buff-rooks",
    "name": "Rook Reach",
    "description": "All rooks get +1 range.",
    "layoutId": "classic",
    "perType": [
      { "kind": "range-bonus", "pieceType": "rook", "color": "both", "value": 1 }
    ],
    "perInstance": [],
    "version": 1,
    "source": "custom"
  },
  "version": 3
}

• roomCode: the code of the room whose profile is being swapped.
• newProfile: the full replacement ModifierProfile (same shape as the profile field on room.create). Partial updates are not supported — the server treats the incoming profile as authoritative.
• version: the PROFILE version the client last observed (starts at 0 before any update and is incremented by the server on each successful apply). Submitting a stale version triggers an error with code MODIFIER_PROFILE_INVALID so concurrent edits from both players never silently overwrite.

On successful apply, the server broadcasts modifier-profile.updated to both players (see below), followed by the usual game.state / game.delta reflecting any piece-attribute changes.

Error cases:

• Profile fails schema / value-schema validation: MODIFIER_PROFILE_INVALID
• Profile would leave a side with no king: MODIFIER_PROFILE_NO_KING
• Profile would make a king invulnerable (damage-resistance ≥ 1.0): MODIFIER_PROFILE_INVULN_KING
• Profile's combined effects make the current position a legal-move deadlock (neither side has any move): MODIFIER_PROFILE_DEADLOCK
• Room not found / client not a member: ROOM_NOT_FOUND

Message: modifier-profile.updated

Direction: Server → Client Purpose: Broadcast to both players after a successful modifier-profile.update. Clients apply the new profile to their local engine at the next turn boundary.

Payload:

{
  "type": "modifier-profile.updated",
  "profile": {
    "id": "buff-rooks",
    "name": "Rook Reach",
    "description": "All rooks get +1 range.",
    "layoutId": "classic",
    "perType": [
      { "kind": "range-bonus", "pieceType": "rook", "color": "both", "value": 1 }
    ],
    "perInstance": [],
    "version": 1,
    "source": "custom"
  },
  "version": 4,
  "appliedAt": "turn-boundary"
}

• profile: the newly-active modifier profile (same shape as room.create.profile).
• version: the monotonically-incremented profile version. Clients echo this on subsequent modifier-profile.update requests.
• appliedAt: always "turn-boundary" in v1. Reserved for future policies (e.g. "immediate" for settings that apply mid-move).

Message: error

Direction: Server → Client Purpose: Report validation failures, protocol errors, rate limit violations.

Payload:

{
  "code": "ILLEGAL_MOVE",
  "message": "Move e2-e5 is not legal for white pawn on e2",
  "fatal": false
}

• fatal: true means the connection will be closed immediately after this message (e.g., rate limit, version mismatch, bad auth)
• fatal: false means the connection stays open; client may retry

Reconnection Flow

1. Client disconnects (network drop, tab sleep, etc.)
2. Server starts a 60-second grace timer for that client's slot in the room
3. During grace period: other player continues playing (server holds their moves but doesn't process if no opponent — or processes against a "ghost" state)
4. Client reconnects: sends room.join with same code and original token
5. Server validates token matches the disconnected slot
6. Server sends game.state (full snapshot) followed by all game.delta messages since the client's last acked seq
7. Client reconciles local state with the snapshot
8. After 60 seconds: server broadcasts game.end with reason: "player_left" to the remaining player; room is destroyed

Reconnect message flow:

Client                          Server
  |-- room.join (code, token) -->|
  |<-- game.state (full snap) ---|
  |<-- game.delta (seq 43..50) --|  (missed deltas since last ack)
  |  [game resumes]              |

Rate Limiting

Token-bucket algorithm per WebSocket connection:

• Capacity: 20 messages (burst)
• Refill rate: 100 messages per second
• When bucket is empty: connection is closed with error code RATE_LIMIT, fatal: true

Messages counted: all messages from client including heartbeats.

Security

• Origin: Only connections from ALLOWED_ORIGINS (env var) are accepted
• Message size: Max 64KB; exceeded → disconnect + error code MSG_TOO_LARGE
• JSON validation: Every message validated against Zod schema; malformed JSON → disconnect
• Token: Room tokens are UUID v4; expire when room is destroyed; not reusable across rooms
• No user auth: v1 has no accounts; rooms are ephemeral; tokens are room-scoped only
• No server-side persistence: Game state lives in-memory; server restart destroys all rooms

Error Codes

Code	Fatal	Description
ILLEGAL_MOVE	No	Move not in legal move set
NOT_YOUR_TURN	No	Move attempted when it's opponent's turn
GAME_OVER	No	Move attempted after game ended
ROOM_NOT_FOUND	No	Room code doesn't exist or expired
ROOM_FULL	No	Room already has 2 players
SERVER_FULL	No	Server at maximum room capacity
VERSION_MISMATCH	Yes	v field doesn't match server's protocol version
RATE_LIMIT	Yes	Message rate exceeded 100/sec
MSG_TOO_LARGE	Yes	Message exceeds 64KB
BAD_TOKEN	Yes	Token missing or invalid for room
INVALID_MESSAGE	Yes	JSON parse failure or schema validation failure
LAYOUT_INVALID	No	Starting layout failed validation
MODIFIER_PROFILE_INVALID	No	Modifier profile failed schema / descriptor validation, or stale version on an update
MODIFIER_PROFILE_NO_KING	No	Profile would leave a side without a king
MODIFIER_PROFILE_INVULN_KING	No	Profile would make a king invulnerable
MODIFIER_PROFILE_DEADLOCK	No	Profile would make the current position an unplayable deadlock