jhalitaksoy/mancala
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
mancala/docs/specs/game-history/tasks.md

26 lines
2.0 KiB
Markdown
Raw Permalink Normal View History

docs: add game history and live games spec
2026-10-16 00:03:32 +03:00
# Game history and live games: tasks
Work through the tasks in order; each ends with its tests passing and a commit. Tick a task when it is committed.
build: add shared Postgres and Valkey to compose - postgres replaces keycloak-db and holds a keycloak and a mancala database, each with its own user, created by apps/postgres/init - valkey with an append-only file for live game state and caches - backend gets DATABASE_URL and VALKEY_URL
2026-10-16 00:05:21 +03:00
- [x] 1. **Infrastructure**: `postgres` service with init script for the `keycloak` and `mancala` databases
docs: add game history and live games spec
2026-10-16 00:03:32 +03:00
(replacing `keycloak-db`), `valkey` service, backend `DATABASE_URL` / `VALKEY_URL`, `.env` variables, README.
feat(core): add game history types and move history helpers - PlayerSummary, MoveRecord, live and finished game summaries, GameRecord, timeout constants, startedAt/moveTimes on Game and offlineSince on UserConnectionInfo - Channels for live game previews and for rejecting a new game while one is in progress - getInitialBoard, getBoardAfterMove, describeMove and createGameAtMove, with tests against games played with the engine - English and Turkish strings for the new screens
2026-10-16 00:07:36 +03:00
- [x] 2. **Core types and history helpers**: `PlayerSummary`, `MoveRecord`, summaries, `GameRecord`,
docs: add game history and live games spec
2026-10-16 00:03:32 +03:00
`TURN_TIMEOUT_MS`, new channels, `offlineSince`; `getInitialBoard`, `getBoardAfterMove`, `describeMove`,
`createGameAtMove` with unit tests; localized strings.
fix(backend): clean up spectators and finished games - Spectators are removed from games when they disconnect; the lookup iterated an iterator with for...in and never found anything - Finished and left games are removed from memory, not only from the player mappings - The connection info is sent once when a game starts
2026-10-16 00:08:38 +03:00
- [x] 3. **Backend fixes**: remove spectators on disconnect, remove finished games from memory, send the connection
docs: add game history and live games spec
2026-10-16 00:03:32 +03:00
info once at game start.
feat(backend): save finished games in Postgres - Connection pool and a small migration runner (schema_migrations, one transaction per migration, advisory lock) - games and game_players tables with indexes for a user's games and for popular games - PostgresGameHistoryRepository: idempotent save, get, recent games of a user, popular games - Integration tests against a real Postgres via testcontainers; a custom Jest environment gives tests Node's web globals, which Jest 27 leaves out - GameRecord carries the number of distinct spectators
2026-10-16 00:11:12 +03:00
- [x] 4. **Postgres repository**: pool, migration runner, `games` and `game_players`, `PostgresGameHistoryRepository`
docs: add game history and live games spec
2026-10-16 00:03:32 +03:00
(save, get, recent for user, popular), integration tests.
feat(backend): keep live games and caches in Valkey - Valkey client that fails commands at once while Valkey is down instead of queueing them, and logs connection errors once - ValkeyLiveGameStore: live game snapshots and finished games waiting to be saved, loaded with SCAN on startup - ValkeyCache: JSON values with a TTL; errors count as cache misses - Integration tests against a real Valkey, including an unreachable one
2026-10-16 00:14:07 +03:00
- [x] 5. **Valkey store**: live game snapshots and restore, pending saves, cache; integration tests.
feat(backend): save every game and keep live games across restarts - Games record start and move times, spectator peak and distinct count - Games end as completed, left (the leaver loses), timeout (5 minutes offline on your turn while the opponent is online) or inactive (both offline for 30 minutes); everyone gets on_game_end - Connection info carries offlineSince for the countdown - A new game is rejected while the user has one in progress - Live games are written to Valkey after every change and restored on startup; finished games are saved to Postgres with public ids, and saves that fail are kept and retried every 30 seconds - Clients get a trimmed game without spectator ids - Startup waits for Valkey, restores games, then accepts connections; migrations are retried while Postgres is unreachable
2026-10-16 00:18:33 +03:00
- [x] 6. **Game lifecycle**: start and move times, spectator counters, outcomes (completed, left, timeout, inactive),
docs: add game history and live games spec
2026-10-16 00:03:32 +03:00
timeout watcher, `offlineSince`, rejecting a new game while playing, saving with retry, restore on startup;
unit tests.
feat(backend): add game history API and live game previews - GET /games/me/active and /games/me (Bearer token), /games/popular (live games, or the most spectated finished ones), and /game/:id now also returns saved records of finished games - Lists are cached in Valkey for 10 seconds, cleared when a game is saved, and empty instead of failing while the database is down - Live game previews over WebSocket: subscribers get the top 5 on subscribe and on change, at most once per second, without counting as spectators; ids are public ids - RTMT supports several connection listeners
2026-10-16 00:21:09 +03:00
- [x] 7. **API**: public ids, Bearer auth middleware, `/games/me/active`, `/games/me`, `/games/popular`,
docs: add game history and live games spec
2026-10-16 00:03:32 +03:00
`/game/:id` for finished games, live games channel with throttled push; tests.
feat(frontend): let the board render at any width Board components size themselves from a --board-unit CSS variable instead of vw. By default it is 1vw, so the game page looks the same; with the new width prop the same board renders small, e.g. in previews.
2026-10-16 00:21:53 +03:00
- [x] 8. **Board size**: `--board-unit` in `BoardView`, `PitView`, `StoreView`, `StoneView`; `width` prop.
feat(frontend): show ongoing, live, popular and recent games on the home page - Banner for the user's game in progress with a Continue button - Live games as cards with the real board, updated over WebSocket; the most watched finished games when nothing is live - The user's last 3 games, from their side of the board, with the result as they would say it - The lobby offers to continue the game in progress when a new one is refused - Spectators register once connected and identified, and again after a reconnect, so they are counted - The backend includes games that ended but are not saved yet in /game/:id and the lists
2026-10-16 00:27:06 +03:00
- [x] 9. **Home page**: `ActiveGameBanner`, `LiveGamesSection` with live updates, `RecentGamesSection`; lobby
docs: add game history and live games spec
2026-10-16 00:03:32 +03:00
rejection message.
feat(frontend): show the moves of a live game and let players look back - Move list under the board with player, pit and what happened (extra turn, capture, stones to the store, game over); collapsed on phones - Selecting a move or using the arrow keys shows that position with a banner and Back to live; pits are locked meanwhile and the banner says when it is your turn - Countdown while the opponent is offline on their turn - on_game_end is handled, so games that end by timeout or inactivity end on the page with the reason
2026-10-16 00:31:43 +03:00
- [x] 10. **Live game history**: `MoveList`, review mode with `ReviewBanner` and keyboard, timeout countdown.
feat(frontend): replay finished games move by move - Opening a finished game shows its final position, result, score, date and duration, with Watch from start - First / previous / play-pause / next / last, speed 1x, 2x, 4x, a timeline, the move list and arrow keys and space - Stepping forward animates the move like a live game; jumps show the position directly - ?move=n links to a move and follows the shown move - Players see the board from their own side - PitAnimator takes its step interval as a parameter
2026-10-16 00:34:49 +03:00
- [x] 11. **Replay**: `ReplayView` with controls, speed, timeline, `?move=`, own-side orientation, duration.
docs: document game history and update the TODO - Backend README: DATABASE_URL, VALKEY_URL, the new routes and how the backend behaves when Postgres or Valkey is down - TODO: drop the fixed spectator and memory bugs, add game history on mobile, a page with all games, single-instance limits, backups and the new .env variables - Spec marked as implemented, all tasks ticked
2026-10-16 00:36:48 +03:00
- [x] 12. **End to end and docs**: Chrome tests from `design.md`, README and `TODO.md` updates.
Reference in New Issue Copy Permalink