mancala/apps/backend/README.md

# Mancala Backend

The game server: matchmaking, live games over a WebSocket, saved games and a small HTTP API. Java 25 and Quarkus 3.40,
built with Maven. The design and the reasons for it are in `docs/specs/quarkus-backend`.

## Getting started

You need a JDK 25 (e.g. Temurin); Maven comes with the wrapper. Postgres, Valkey and Keycloak run with Docker Compose,
see the README in the repo root.

```sh
./mvnw quarkus:dev            # http://localhost:5005; a debugger can attach on 5006
./mvnw test                   # needs Docker: Postgres and Valkey run with Quarkus Dev Services
./mvnw package                # target/quarkus-app/quarkus-run.jar
java -jar target/quarkus-app/quarkus-run.jar
```

The Docker image is built from the repo root: `docker build -f apps/backend/Dockerfile .`. It listens on port 6000.

## Code

| Package | What |
|---|---|
| `engine` | The game rules, a port of `packages/mancala.js`; `Position`, a compact board for searching moves |
| `bot` | The bot: levels, strength, the search and `BotPlayer`, which plays its turns in live games |
| `model` | The JSON sent to clients and stored, and the shared `ObjectMapper` |
| `loop` | `GameLoop`, the single thread that owns all live game state |
| `auth` | Keycloak token verification |
| `rtmt` | The WebSocket protocol (`RtmtServer`) and the Quarkus endpoint |
| `game` | Games, matchmaking, the clock, live previews, snapshots and saving finished games |
| `history` | Saved games in Postgres, migrations, the lists for the API |
| `live` | Valkey: live game snapshots, games waiting to be saved, the cache |
| `http` | The HTTP API |
| `Backend` | Wiring and startup |

All live state (games, matchmaking, sockets) is only touched on the game loop, like on the Node backend's event loop.
Blocking work never runs there: Postgres writes run on the recorder's thread, Valkey writes on their own ordered
thread, token checks on virtual threads, HTTP requests on Quarkus' workers (which read live games through
`GameLoop.call`).

The clients use the TypeScript engine, the server the Java one; they must play exactly alike.
`EngineParityTest` replays games recorded with the TypeScript engine. After changing the rules in both, record them
again:

```sh
yarn --cwd ../../packages/mancala.js build && node scripts/record-engine-games.js
```

## 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:

```json
{ "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 |
| `PORT` | `5005` (`6000` in the image) | HTTP and WebSocket port |

## 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_JDBC_URL` | `jdbc:postgresql://localhost:5433/mancala` | Saved games; migrations run on startup |
| `DATABASE_USERNAME`, `DATABASE_PASSWORD` | `mancala`, `mancala` | |
| `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. The tables, the `schema_migrations` table and the Valkey keys
are the Node backend's, so the two can replace each other in either direction.

## Game clock

Each player has a clock for the whole game; only the clock of the player whose turn it is runs, also while they are
offline. A move that arrives after the mover's time has run out is refused, and `GameClockScheduler` ends games whose
running clock reaches zero once a second, so the opponent wins on time even if nobody is connected. Time while the
backend is down is not charged. The design is in `docs/specs/game-clock`.

| Variable | Default | Purpose |
|---|---|---|
| `GAME_CLOCK_MS` | `300000` | Time each player has for a game; a short value such as `40000` helps when testing by hand |

## Bot

Players can play against a bot at four levels (`new_bot_game` with `{ level }`); the lobby offers it after 10 seconds
without an opponent. Each level is a range of strengths, and the bot draws one per game, so games at the same level
differ. It plays as `bot:<level>` through the same game logic as players, with the clock, saving and spectators, and
waits for the previous move's animation and a thinking time before moving. Its moves are worked out with alpha-beta
search on `Position` on a thread pool of their own, never on the game loop. The design is in `docs/specs/game-bot`.

| Variable | Default | Purpose |
|---|---|---|
| `BOT_SEARCH_THREADS` | half the processors | Threads working out the bot's moves |

After changing the search or the strength table, check that every level still beats the one below:

```sh
./mvnw test -Dtest=BotTournamentTest -Dgroups=calibration -DexcludedGroups=none
```

| 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 |

Requests are logged to `access.log`, and a move that fails writes the game to `crashes/`, both in the working
directory.