Add design doc for ecast shard monitor replacing Puppeteer audience approach
Replaces room-monitor.js (REST polling) and player-count-checker.js (Puppeteer/CDP audience join) with a single EcastShardClient that connects as a shard via direct WebSocket. Defines new event contract, integration points, error handling, and reconnection strategy. Made-with: Cursor
This commit is contained in:
cottongin
345
docs/plans/2026-03-20-shard-monitor-design.md
Normal file
345
docs/plans/2026-03-20-shard-monitor-design.md
Normal file
@@ -0,0 +1,345 @@
|
|||||||
|
# Ecast Shard Monitor — Design Document
|
||||||
|
|
||||||
|
**Date:** 2026-03-20
|
||||||
|
**Status:** Approved
|
||||||
|
**Replaces:** `room-monitor.js` (REST polling for lock) + `player-count-checker.js` (Puppeteer audience join)
|
||||||
|
|
||||||
|
## Problem
|
||||||
|
|
||||||
|
The current player count approach launches a headless Chrome instance via Puppeteer, navigates to `jackbox.tv`, joins as an audience member through the UI, and sniffs WebSocket frames via CDP. This is fragile, resource-heavy, and occupies an audience slot. The room monitor is a separate module that polls the REST API until the room locks, then hands off to the Puppeteer checker. Two modules, two connection strategies, a circular dependency workaround.
|
||||||
|
|
||||||
|
## Solution
|
||||||
|
|
||||||
|
Replace both modules with a single `EcastShardClient` that connects to the Jackbox ecast server as a **shard** via a direct Node.js WebSocket. The shard role:
|
||||||
|
|
||||||
|
- Gets the full `here` map (authoritative player list with names and roles)
|
||||||
|
- Receives real-time entity updates (room state, player joins, game end)
|
||||||
|
- Can query entities via `object/get`
|
||||||
|
- Does NOT count toward `maxPlayers` or trigger `full: true`
|
||||||
|
- Does NOT require a browser
|
||||||
|
|
||||||
|
One REST call upfront validates the room and retrieves the `host` field needed for the WebSocket URL. After that, the shard connection handles everything.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
### Lifecycle
|
||||||
|
|
||||||
|
```
|
||||||
|
Room code registered
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
REST: GET /rooms/{code} ──── 404 ──→ Mark failed, stop
|
||||||
|
│
|
||||||
|
│ (get host, maxPlayers, locked, appTag)
|
||||||
|
▼
|
||||||
|
WSS: Connect as shard
|
||||||
|
wss://{host}/api/v2/rooms/{code}/play?role=shard&name=GamePicker&userId=gamepicker-{sessionId}&format=json
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
client/welcome received
|
||||||
|
├── Parse `here` → initial player count (filter for `player` roles)
|
||||||
|
├── Parse `entities.room` → lobby state, gameCanStart, etc.
|
||||||
|
├── Store `secret` + `id` for reconnection
|
||||||
|
└── Broadcast initial state to our clients
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─── Event loop (listening for server messages) ───┐
|
||||||
|
│ │
|
||||||
|
│ `object` (key: textDescriptions) │
|
||||||
|
│ → Parse latestDescriptions for player joins │
|
||||||
|
│ → Broadcast `lobby.player-joined` to clients │
|
||||||
|
│ │
|
||||||
|
│ `object` (key: room) │
|
||||||
|
│ → Detect state transitions: │
|
||||||
|
│ lobbyState changes → broadcast lobby updates │
|
||||||
|
│ state: "Gameplay" → broadcast `game.started` │
|
||||||
|
│ gameFinished: true → broadcast `game.ended` │
|
||||||
|
│ gameResults → extract final player count │
|
||||||
|
│ │
|
||||||
|
│ `client/connected` (if delivered to shards) │
|
||||||
|
│ → Update here map, recount players │
|
||||||
|
│ │
|
||||||
|
│ WebSocket close/error │
|
||||||
|
│ → REST check: room exists? │
|
||||||
|
│ Yes → reconnect with secret/id │
|
||||||
|
│ No → game ended, finalize │
|
||||||
|
└────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### Internal State
|
||||||
|
|
||||||
|
| Field | Type | Source |
|
||||||
|
|-------|------|--------|
|
||||||
|
| `playerCount` | number | `here` map filtered for `player` roles |
|
||||||
|
| `playerNames` | string[] | `here` map player role `name` fields |
|
||||||
|
| `lobbyState` | string | `room` entity `lobbyState` |
|
||||||
|
| `gameState` | string | `room` entity `state` (`"Lobby"`, `"Gameplay"`) |
|
||||||
|
| `gameStarted` | boolean | Derived from `state === "Gameplay"` |
|
||||||
|
| `gameFinished` | boolean | `room` entity `gameFinished` |
|
||||||
|
| `maxPlayers` | number | REST response + `room` entity |
|
||||||
|
| `secret` / `id` | string/number | `client/welcome` for reconnection |
|
||||||
|
|
||||||
|
### Player Counting
|
||||||
|
|
||||||
|
The `here` map from `client/welcome` is the authoritative source. It lists all registered connections with their roles. Count entries where `roles` contains `player`. The shard itself is excluded (it has `roles: {shard: {}}`). The host (ID 1, `roles: {host: {}}`) is also excluded. Since Jackbox holds slots for disconnected players, `here` always reflects the true occupied slot count.
|
||||||
|
|
||||||
|
For subsequent joins after connect, `textDescriptions` entity updates provide join notifications. Since shards have `here` visibility, `client/connected` messages may also be delivered — both paths are handled, with `here` as source of truth.
|
||||||
|
|
||||||
|
## WebSocket Events (Game Picker → Connected Clients)
|
||||||
|
|
||||||
|
### `room.connected`
|
||||||
|
|
||||||
|
Shard successfully connected to the Jackbox room. Sent once on initial connect. Replaces the old `audience.joined` event.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "room.connected",
|
||||||
|
"timestamp": "...",
|
||||||
|
"data": {
|
||||||
|
"sessionId": 1,
|
||||||
|
"gameId": 5,
|
||||||
|
"roomCode": "LSBN",
|
||||||
|
"appTag": "drawful2international",
|
||||||
|
"maxPlayers": 8,
|
||||||
|
"playerCount": 2,
|
||||||
|
"players": ["Alice", "Bob"],
|
||||||
|
"lobbyState": "CanStart",
|
||||||
|
"gameState": "Lobby"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### `lobby.player-joined`
|
||||||
|
|
||||||
|
A new player joined the lobby.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "lobby.player-joined",
|
||||||
|
"timestamp": "...",
|
||||||
|
"data": {
|
||||||
|
"sessionId": 1,
|
||||||
|
"gameId": 5,
|
||||||
|
"roomCode": "LSBN",
|
||||||
|
"playerName": "Charlie",
|
||||||
|
"playerCount": 3,
|
||||||
|
"players": ["Alice", "Bob", "Charlie"],
|
||||||
|
"maxPlayers": 8
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### `lobby.updated`
|
||||||
|
|
||||||
|
Lobby state changed (enough players to start, countdown started, etc.).
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "lobby.updated",
|
||||||
|
"timestamp": "...",
|
||||||
|
"data": {
|
||||||
|
"sessionId": 1,
|
||||||
|
"gameId": 5,
|
||||||
|
"roomCode": "LSBN",
|
||||||
|
"lobbyState": "Countdown",
|
||||||
|
"gameCanStart": true,
|
||||||
|
"gameIsStarting": true,
|
||||||
|
"playerCount": 4
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### `game.started`
|
||||||
|
|
||||||
|
The game transitioned from Lobby to Gameplay.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "game.started",
|
||||||
|
"timestamp": "...",
|
||||||
|
"data": {
|
||||||
|
"sessionId": 1,
|
||||||
|
"gameId": 5,
|
||||||
|
"roomCode": "LSBN",
|
||||||
|
"playerCount": 4,
|
||||||
|
"players": ["Alice", "Bob", "Charlie", "Diana"],
|
||||||
|
"maxPlayers": 8
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### `game.ended`
|
||||||
|
|
||||||
|
The game finished.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "game.ended",
|
||||||
|
"timestamp": "...",
|
||||||
|
"data": {
|
||||||
|
"sessionId": 1,
|
||||||
|
"gameId": 5,
|
||||||
|
"roomCode": "LSBN",
|
||||||
|
"playerCount": 4,
|
||||||
|
"players": ["Alice", "Bob", "Charlie", "Diana"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### `room.disconnected`
|
||||||
|
|
||||||
|
Shard lost connection to the Jackbox room.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "room.disconnected",
|
||||||
|
"timestamp": "...",
|
||||||
|
"data": {
|
||||||
|
"sessionId": 1,
|
||||||
|
"gameId": 5,
|
||||||
|
"roomCode": "LSBN",
|
||||||
|
"reason": "room_closed",
|
||||||
|
"finalPlayerCount": 4
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Possible `reason` values: `room_closed`, `room_not_found`, `connection_failed`, `role_rejected`, `manually_stopped`.
|
||||||
|
|
||||||
|
### Dropped Events
|
||||||
|
|
||||||
|
| Old event | Replacement |
|
||||||
|
|-----------|-------------|
|
||||||
|
| `audience.joined` | `room.connected` (richer payload) |
|
||||||
|
| `player-count.updated` (automated) | `lobby.player-joined`, `game.started`, `game.ended` carry `playerCount` |
|
||||||
|
|
||||||
|
The manual `PATCH .../player-count` endpoint keeps broadcasting `player-count.updated` for its specific use case.
|
||||||
|
|
||||||
|
### DB Persistence
|
||||||
|
|
||||||
|
The `session_games` table columns `player_count` and `player_count_check_status` continue to be updated:
|
||||||
|
|
||||||
|
- `player_count` — updated on each join and at game end
|
||||||
|
- `player_count_check_status` — `'monitoring'` (shard connected), `'completed'` (game ended with count), `'failed'` (couldn't connect), `'stopped'` (manual stop)
|
||||||
|
|
||||||
|
The old `'checking'` status becomes `'monitoring'`.
|
||||||
|
|
||||||
|
## Integration Points
|
||||||
|
|
||||||
|
### Files Deleted
|
||||||
|
|
||||||
|
- `backend/utils/player-count-checker.js` — Puppeteer audience approach
|
||||||
|
- `backend/utils/room-monitor.js` — REST polling for lock state
|
||||||
|
|
||||||
|
### Files Created
|
||||||
|
|
||||||
|
- `backend/utils/ecast-shard-client.js` — `EcastShardClient` class + module exports: `startMonitor`, `stopMonitor`, `cleanupAllShards`
|
||||||
|
|
||||||
|
### Files Modified
|
||||||
|
|
||||||
|
**`backend/utils/jackbox-api.js`** — Add `getRoomInfo(roomCode)` returning the full room response including `host`, `appTag`, `audienceEnabled`.
|
||||||
|
|
||||||
|
**`backend/routes/sessions.js`** — Replace imports:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Old
|
||||||
|
const { stopPlayerCountCheck } = require('../utils/player-count-checker');
|
||||||
|
const { startRoomMonitor, stopRoomMonitor } = require('../utils/room-monitor');
|
||||||
|
|
||||||
|
// New
|
||||||
|
const { startMonitor, stopMonitor } = require('../utils/ecast-shard-client');
|
||||||
|
```
|
||||||
|
|
||||||
|
All call sites change from two-function calls to one:
|
||||||
|
|
||||||
|
| Route | Old | New |
|
||||||
|
|-------|-----|-----|
|
||||||
|
| `POST /:id/games` (with room_code) | `startRoomMonitor(...)` | `startMonitor(...)` |
|
||||||
|
| `PATCH .../status` (away from playing) | `stopRoomMonitor(...) + stopPlayerCountCheck(...)` | `stopMonitor(...)` |
|
||||||
|
| `DELETE .../games/:gameId` | `stopRoomMonitor(...) + stopPlayerCountCheck(...)` | `stopMonitor(...)` |
|
||||||
|
| `POST .../start-player-check` | `startRoomMonitor(...)` | `startMonitor(...)` |
|
||||||
|
| `POST .../stop-player-check` | `stopRoomMonitor(...) + stopPlayerCountCheck(...)` | `stopMonitor(...)` |
|
||||||
|
|
||||||
|
Endpoint paths stay the same for backwards compatibility.
|
||||||
|
|
||||||
|
**`backend/server.js`** — Wire `cleanupAllShards()` into `SIGTERM`/`SIGINT` handlers.
|
||||||
|
|
||||||
|
## Error Handling and Reconnection
|
||||||
|
|
||||||
|
### Connection Failures
|
||||||
|
|
||||||
|
1. **REST validation fails** (room not found, network error): Set status `'failed'`, broadcast `room.disconnected` with `reason: 'room_not_found'` or `'connection_failed'`. No automatic retry.
|
||||||
|
|
||||||
|
2. **Shard WebSocket fails to connect**: Retry up to 3 times with exponential backoff (2s, 4s, 8s). On exhaustion, set status `'failed'`, broadcast `room.disconnected` with `reason: 'connection_failed'`.
|
||||||
|
|
||||||
|
3. **Ecast rejects the shard role** (error opcode received): Set status `'failed'`, broadcast `room.disconnected` with `reason: 'role_rejected'`. No retry.
|
||||||
|
|
||||||
|
### Mid-Session Disconnections
|
||||||
|
|
||||||
|
4. **WebSocket closes unexpectedly**: REST check `GET /rooms/{code}`:
|
||||||
|
- Room exists → reconnect with stored `secret`/`id` (up to 3 attempts, exponential backoff). Transparent to clients on success.
|
||||||
|
- Room gone → finalize with last known count, status `'completed'`, broadcast `game.ended` + `room.disconnected`.
|
||||||
|
|
||||||
|
5. **Ecast error 2027 "room already closed"**: Same as room-gone path.
|
||||||
|
|
||||||
|
### Manual Stop
|
||||||
|
|
||||||
|
6. **`stop-player-check` called or game status changes**: Close WebSocket gracefully, set status `'stopped'` (unless already `'completed'`), broadcast `room.disconnected` with `reason: 'manually_stopped'`.
|
||||||
|
|
||||||
|
### Server Shutdown
|
||||||
|
|
||||||
|
7. **`SIGTERM`/`SIGINT`**: `cleanupAllShards()` closes all WebSocket connections. No DB updates on shutdown.
|
||||||
|
|
||||||
|
### State Machine
|
||||||
|
|
||||||
|
```
|
||||||
|
startMonitor()
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌───────────┐
|
||||||
|
┌────────│ not_started│
|
||||||
|
│ └───────────┘
|
||||||
|
│ │
|
||||||
|
REST fails REST succeeds
|
||||||
|
│ │
|
||||||
|
▼ ▼
|
||||||
|
┌────────┐ ┌────────────┐
|
||||||
|
│ failed │ │ monitoring │◄──── reconnect success
|
||||||
|
└────────┘ └─────┬──────┘
|
||||||
|
▲ │
|
||||||
|
│ ┌────┴─────┬──────────────┐
|
||||||
|
reconnect │ │ │
|
||||||
|
exhausted game ends WS drops manual stop
|
||||||
|
│ │ │ │
|
||||||
|
│ ▼ ▼ ▼
|
||||||
|
│ ┌──────────┐ REST check ┌─────────┐
|
||||||
|
│ │ completed │ │ │ stopped │
|
||||||
|
│ └──────────┘ │ └─────────┘
|
||||||
|
│ │
|
||||||
|
└──── room gone? ────┘
|
||||||
|
│
|
||||||
|
room exists?
|
||||||
|
│
|
||||||
|
reconnect...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Timeouts
|
||||||
|
|
||||||
|
| Concern | Value | Rationale |
|
||||||
|
|---------|-------|-----------|
|
||||||
|
| WebSocket connect timeout | 10s | Ecast servers respond fast |
|
||||||
|
| Reconnect backoff | 2s, 4s, 8s | Three attempts, ~14s total |
|
||||||
|
| Max reconnect attempts | 3 | Fail fast, user can retry manually |
|
||||||
|
| WebSocket inactivity timeout | None | Shard connections receive periodic `shard/sync` CRDT messages |
|
||||||
|
|
||||||
|
## Dependencies
|
||||||
|
|
||||||
|
**Added:** `ws` (Node.js WebSocket library) — already a dependency (used by `websocket-manager.js`).
|
||||||
|
|
||||||
|
**Removed:** `puppeteer` — no longer needed for room monitoring.
|
||||||
|
|
||||||
|
## Non-Goals
|
||||||
|
|
||||||
|
- Renaming REST endpoint paths (`start-player-check` / `stop-player-check`) — kept for backwards compatibility
|
||||||
|
- Auto-starting monitoring when room code is set via `PATCH .../room-code` — kept as manual trigger only
|
||||||
|
- Frontend `Picker.jsx` changes — tracked separately (existing bugs: `message.event` vs `message.type`, subscribe without auth, `'waiting'` status that's never set)
|
||||||
Reference in New Issue
Block a user