Halit Aksoy b94c9336dd 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

2.7 KiB

Raw Blame History

Mancala Backend

This is the backend code for the Mancala project, written in Express.js.

Getting Started

Install Packages

yarn install

Start in Development Mode

yarn dev

Start in Release Mode

yarn build
yarn start

Development Dependencies

This package links the local packages @mancala/core and mancala.js. Build them first with yarn build:packages in the repo root.

Authentication

Clients log in with Keycloak (see apps/keycloak), either as a guest or with an account, and send the access token over the WebSocket right after connecting:

{ "channel": "auth", "message": { "token": "<Keycloak access token>" } }

The server answers on on_auth with the user ({ id, name, isGuest }) or on on_auth_error and closes the socket with code 4001. Other messages are ignored until the socket is authenticated, and connections that do not authenticate within 5 seconds are closed. Send auth again with the new token after refreshing it. User ids of Keycloak users are the token subject prefixed with kc:.

Variable	Default	Purpose
`KEYCLOAK_ISSUER`	`http://localhost:8080/realms/mancala`	Token issuer; must match the `iss` claim exactly
`KEYCLOAK_JWKS_URL`	issuer + `/protocol/openid-connect/certs`	Where to fetch signing keys, if the backend reaches Keycloak at a different address
`KEYCLOAK_CLIENT_IDS`	`mancala-web`	Comma-separated clients whose tokens are accepted
`LEGACY_USERKEY_AUTH`	`true`	Also accept old clients that connect with `?userKey=<uuid>` and the `/register` endpoint. Turn off once no released client uses it, because a userKey is not a secret the server can check

Saved games and live games

Finished games are saved in Postgres; live games are copied to Valkey after every change and restored when the backend starts, so a restart or deploy does not end them. The design is in docs/specs/game-history.

Variable	Default	Purpose
`DATABASE_URL`	`postgres://mancala:mancala@localhost:5433/mancala`	Saved games; migrations run on startup
`VALKEY_URL`	`redis://localhost:6379`	Live game state and short-lived caches

The backend keeps running when either is down: games are still played, finished games are saved once Postgres is back, and lists are served without the missing data.

Route	Auth	Response
`GET /game/:id`	–	A live game, or `{ status: "finished", record }`
`GET /games/popular?limit=5`	–	`{ kind: "live" \| "finished", games }`
`GET /games/me/active`	Bearer token	`{ game }` or `{ game: null }`
`GET /games/me?limit=3`	Bearer token	`{ games }`, newest first

Tests use Docker (testcontainers) for Postgres and Valkey.

2.7 KiB Raw Blame History Unescape Escape