tavolo/server/README.md

# tavolo (backend)

The backend for a multiplayer card-game platform, built on the
[kaya](../kaya) framework. It is a monorepo of three distributions
sharing the `tavolo` namespace (see
[`packages/tavolo-platform/README.md`](packages/tavolo-platform/README.md)
and [`packages/tavolo-scopone/README.md`](packages/tavolo-scopone/README.md)):

- **`tavolo-platform`** (`packages/tavolo-platform/`) — everything
  game-independent: the lobby API, the live-game store, the WebSocket
  endpoint, the deadline scheduler, match persistence and the Elo
  leaderboards, plus the `GameEngine` contract games implement.
- **`tavolo-scopone`** (`packages/tavolo-scopone/`) — scopone
  scientifico, the four-player, fixed-partnership variant of the classic
  Italian card game: pure rules plus the platform adapter.
- **`tavolo-app`** (`src/tavolo/`, this `pyproject.toml`) — the
  composition root wiring the platform to the scopone game, with the
  environment-driven settings and the SPA shell.

Players authenticate with the configured **OIDC** provider. Live game
state is kept in **Redis** (with real-time play over WebSocket), and
completed matches — every participant and the game-specific result — are
persisted to **Postgres** for history and leaderboard statistics.

## Quick start (Docker Compose)

```sh
# From the repository root (docker-compose.yml lives there):
docker compose up --build
```

The stack starts Postgres, Redis, a mock OIDC provider
(navikt/mock-oauth2-server) with four ready-made players
(`alice`, `bob`, `carol`, `dave`), a one-shot database migration service,
and the app itself on `http://127.0.0.1:8080`. The same container also
serves the Sycamore/WASM frontend (built from `../web/` by the Docker
image), so the UI is available at that address.

Because the browser and the app both talk to the OIDC issuer at
`http://mockoauth:8180/tavolo`, add a host entry once:

```sh
echo "127.0.0.1 mockoauth" | sudo tee -a /etc/hosts
```

Then log in: `GET http://localhost:8080/auth/login`, type any username
(e.g. `alice`) in the interactive login, and you are redirected back with a
session cookie. That cookie authenticates both the REST API and the
WebSocket endpoint.

OpenAPI documentation is served at `/api/docs` (`/api/openapi.json`).

## Configuration

All configuration comes from environment variables (see `.env.example`):

| Variable | Default | Description |
|---|---|---|
| `DATABASE_ENGINE` | `postgres` | Database DSN scheme/driver |
| `DATABASE_HOST` | `localhost` | Postgres host |
| `DATABASE_PORT` | unset | Postgres port; omitted from the DSN when empty (driver default, 5432 for Postgres) |
| `DATABASE_NAME` | `tavolo` | Postgres database name |
| `DATABASE_USER` | `tavolo` | Postgres user |
| `DATABASE_PASSWORD` | `password` | Postgres password |
| `DATABASE_OPTIONS` | unset | Extra DSN query parameters, e.g. `ssl=require` |
| `DATABASE_URL` | unset | Full-DSN override; when set, the `DATABASE_*` parts above are ignored (used for sqlite in tests and for managed-DB URLs) |
| `REDIS_URL` | unset | Redis DSN for sessions + live games. Unset falls back to in-memory stores |
| `OIDC_ISSUER` | `http://localhost:8180/tavolo` | OIDC issuer URL |
| `OIDC_CLIENT_ID` | `tavolo` | OIDC client id |
| `OIDC_CLIENT_SECRET` | unset | OIDC client secret |
| `OIDC_REDIRECT_URI` | `http://localhost:8080/auth/callback` | Login callback URL |
| `GAME_TTL_SECONDS` | `86400` | Sliding TTL of a live game in Redis |
| `HAND_ACK_TIMEOUT_SECONDS` | `30` | Seconds the scopone between-hands scoring summary waits for acknowledgements (wired into the `ScoponeEngine`) |
| `TURN_TIMEOUT_SECONDS` | `30` | Seconds a scopone player has to play before the server plays a random legal card for them (wired into the `ScoponeEngine`) |
| `DEADLINE_HEARTBEAT_MS` | `1000` | Upper bound on the deadline consumer's poll interval (locally enqueued deadlines fire on time regardless) |
| `LOGGING_CONFIG` | unset | Path to a YAML logging configuration file (see below). Unset logs DEBUG to the console |
| `CORS_ALLOW_ORIGINS` | unset | Comma-separated origins allowed for cross-origin requests, or `*` for any. CORS is disabled unless this or `CORS_ALLOW_ORIGIN_REGEX` is set |
| `CORS_ALLOW_ORIGIN_REGEX` | unset | Regex (fullmatch) additionally matched against request origins, e.g. `https://tavolo-[a-z0-9-]+\.vercel\.app` |
| `CORS_ALLOW_METHODS` | `GET` | Comma-separated methods allowed for cross-origin requests, or `*` for all |
| `CORS_ALLOW_HEADERS` | unset | Comma-separated request headers allowed in cross-origin requests, or `*` to mirror back the requested ones. The CORS-safelisted headers are always allowed |
| `CORS_ALLOW_CREDENTIALS` | `false` | `1`/`true`/`yes`/`on` allow cookies/credentials on cross-origin requests |
| `CORS_EXPOSE_HEADERS` | unset | Comma-separated response headers exposed to the browser |
| `CORS_MAX_AGE` | `600` | Seconds browsers may cache the preflight response |
| `OTEL_ENABLED` | `false` | `1`/`true`/`yes`/`on` enable OpenTelemetry traces and metrics (requires the `otel` extra, i.e. `pip install tavolo-app[otel]`) |
| `OTEL_SERVICE_NAME` | `tavolo` | `service.name` resource attribute of the exported telemetry |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | unset | Base URL of an OTLP/HTTP collector (e.g. `http://localhost:4318`); unset uses the exporter default |
| `OTEL_EXPORTER_OTLP_HEADERS` | unset | Comma-separated `key=value` headers sent to the collector (e.g. authentication) |
| `OTEL_EXCLUDED_PATHS` | `/api/health` | Comma-separated paths excluded from tracing and metrics (exact matches) |
| `APP_HOST` / `APP_PORT` | `0.0.0.0` / `8080` | Bind address |

## Logging

The application logs through the Python stdlib `logging` module, one
`getLogger(__name__)` per module: lifecycle and business events at INFO
(game created/joined, websocket connections, match results, auto-plays),
per-move and store detail at DEBUG.

By default everything at DEBUG level goes to the console. Set
`LOGGING_CONFIG` to the path of a YAML file to take over the
configuration; the file follows the
[`logging.config.dictConfig`](https://docs.python.org/3/library/logging.config.html#logging-config-dictschema)
schema. Keep `disable_existing_loggers: false` — Granian configures its own
loggers before importing the app, and disabling them would silence the
server. Example for quieter production logs (WARNING for third parties,
INFO for the application):

```yaml
version: 1
disable_existing_loggers: false
formatters:
  default:
    format: "{asctime} [{levelname}] ({processName:s}/{threadName:s}) - {name} - {message}"
    style: "{"
handlers:
  console:
    class: logging.StreamHandler
    formatter: default
root:
  level: WARNING
  handlers: [console]
loggers:
  tavolo:
    level: INFO
```

## Data model

### Redis (live games)

- `tavolo:game:<uuid>` — the whole session as JSON: the platform-owned
  envelope (`id`, `game_type`, `join_code`, seats, timestamps) plus the
  game-specific `state` blob, which only the registered engine
  interprets. Sliding TTL (`GAME_TTL_SECONDS`).
- `tavolo:code:<JOINCODE>` — the 6-character join code → game id index.
- `tavolo:game:<uuid>:lock` — a short-lived lock serializing every mutation.
- `tavolo:game:<uuid>:events` — a pub/sub channel carrying "state changed"
  signals; every open WebSocket reloads the session and pushes the
  personalized view to its player.
- `tavolo:deadlines` — a sorted set (score = due timestamp) of pending
  timeouts (e.g. scopone's turn auto-plays and hand-end auto-continues).
  Every worker runs a consumer that fires due entries under the per-game
  lock by calling the engine's `fire_deadline`, so timeouts do not depend
  on any player being connected and survive the death of any worker
  (delivery is at-least-once; engines revalidate the entry's token
  against the live state before firing).

### Postgres (statistics, via Tortoise ORM + aerich migrations)

- `match` — one row per finished match: the game played (`game_type`, one
  of the ids from `GET /api/game-types`, indexed so statistics can be
  scoped per game), start/finish timestamps, and the game-specific outcome
  as reported by the engine (`result` JSON — for scopone: both teams'
  final scores, winner, target score, hands played and the per-hand
  audit).
- `match_player` — one row per participant: the OIDC `sub`, display name,
  seat, game-defined team label (nullable), whether they won, the points
  they scored, the Elo change the match produced (`elo_delta`) and
  game-specific extras (`details` JSON). Unique per `(match, user_sub)`.
- `player_rating` — current Elo rating per `(user_sub, game_type)`, with
  the number of rated matches played.

When a match ends, the engine's result is written transactionally to
Postgres (once, guarded by a flag on the session); the finished session
stays in Redis until its TTL expires so clients can still fetch the final
board.

### Elo ratings

Players carry a chess-style Elo rating per game type
(`tavolo.platform.elo`): everyone starts at 1500, a team's rating is the
mean of its members, and the standard formula
`E = 1 / (1 + 10 ** ((R_opp - R_team) / 400))` with `K = 32` decides how
many points the match result moves — the same delta for every member of
a team, zero-sum between the two teams. Ratings update in the same
transaction as the match result. To recompute every rating from the
recorded match history (e.g. to backfill matches recorded before ratings
existed):

```sh
.venv/bin/python -m tavolo.platform.backfill_elo \
  --database-url postgres://tavolo:tavolo@localhost:5432/tavolo
```

## REST API

All endpoints except `/api/health`, `/api/docs`, `/api/openapi.json`,
`/api/game-types` and `/api/leaderboard` require authentication.

| Method | Path | Description |
|---|---|---|
| `GET` | `/api/game-types` | The games the platform can host (for the creation dropdown), each with its `options_schema` |
| `POST` | `/api/games` | Create a lobby game. Optional body `{"game_type": "scopone_scientifico", "options": {"target_score": 11, "napola": true}}`. Returns the lobby (`{id, join_code, players, seats_open, ...}`) |
| `POST` | `/api/games/join` | Join with `{"code": "ABC123"}`. The last player triggers the start and gets the game view back |
| `GET` | `/api/games/{id}` | Personalized snapshot (only your own hand is visible) |
| `GET` | `/api/me/matches` | Cursor-paginated match history with the engine's `result` and per-player Elo deltas (`?limit=&cursor=&game_type=`) |
| `GET` | `/api/me/ratings` | The caller's Elo rating per game type |
| `GET` | `/api/leaderboard` | Elo rating, aggregated wins / matches / points per player, sorted by Elo (`?game_type=`) |

## WebSocket protocol

Connect to `/ws/games/{game_id}` with your session cookie. Only seated
players are accepted; unauthenticated, unknown-game and non-player
connections are closed with codes `4401`, `4404` and `4403` respectively.

Server → client messages are JSON objects with a `type`:

- `{"type": "state", "game": {...}}` — personalized game view. Your own
  hand is included; other players expose only their card counts.
  `your_turn: true` is present when it is your move.
- `{"type": "game_over", "scores": {"A": 11, "B": 7}, "winner": "A"}`
- `{"type": "error", "code": "illegal_move", "message": "..."}`

Client → server messages are JSON objects with an `action`. The
platform handles `state` (resend the snapshot) itself; every other action
is dispatched to the session's game engine with the rest of the message
as its payload. For scopone scientifico:

```json
{"action": "play", "card": "07D", "capture": ["02D", "05C"]}
{"action": "play", "card": "07D"}
{"action": "ack"}
{"action": "state"}
```

- `card` is the card you play, rendered as `RRSUIT` (`01A`..`10D`; suits
  `D` denari, `C` coppe, `S` spade, `B` bastoni — e.g. `07D` is the
  settebello).
- `capture` lists the table cards to take. When a capture is legal it is
  mandatory to provide one; when no capture exists it must be omitted.
- `ack` acknowledges the hand-end scoring summary (see below). The next
  hand is dealt once all four players have acknowledged, or automatically
  after `HAND_ACK_TIMEOUT_SECONDS`.
- `state` asks for a fresh snapshot.

After every accepted move the new state is broadcast to all four players.

### Turn timeout

The state carries a `turn_deadline` while a hand is being played. If the
player on turn does not move before it, the server plays a random legal
card for them (picking one of the legal captures at random when a capture
is required), so a disconnected or idle player cannot stall the match. The
timeout is `TURN_TIMEOUT_SECONDS` (default 30); the auto-played move is
broadcast like any other. Deadlines fire from the shared `tavolo:deadlines`
queue (see above), not from timers tied to client connections, so the
match keeps progressing even with every player disconnected.

### Hand-end summary

When a hand finishes but the match continues, the game enters the
`hand_end` phase instead of dealing immediately: the state carries
`last_hand` (a full scoring breakdown with an `award` map naming the team
that won each category), the `acknowledged` seats and a
`hand_end_deadline`. The frontend renders this as a screen every player
must dismiss. A play attempted in this phase is rejected with an
`illegal_move` error.

## Rules implemented

- 40-card Italian deck, ten cards per player, empty table at hand start.
- A card captures a **single card of equal rank** (mandatory when present)
  or a **combination of table cards whose ranks sum to its own**.
- Emptying the table scores a *scopa* (+1), except on the last play of a
  hand. Remaining table cards go to the last player who captured.
- Hand points: `carte` (most captured cards), `denara` (most diamonds),
  `settebello` (7♦), `primiera` (best 7/6/5/4 per suit, all four suits
  required), plus one point per scopa. Ties award nothing.
- Optional *napola* rule (per-game `napola` creation option, default on):
  the longest run of consecutive denari starting from the ace scores one
  point per card once it reaches three cards (A-2-3 = 3, A-2-3-4 = 4, …).
  A team that captures the whole denari suit (ace to king) wins the match
  instantly, regardless of the score.
- The match ends when a team reaches the target score (default 11,
  configurable per game via the `target_score` creation option) with a
  clear lead; a tie at or above the target is broken by another hand.

## Development

```sh
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e ./packages/tavolo-platform -e ./packages/tavolo-scopone -e '.[dev]'
# app integration suite:
.venv/bin/python -m unittest discover -s tests -t .
# per-package suites (each package is self-contained):
.venv/bin/python -m unittest discover -s packages/tavolo-platform/tests
.venv/bin/python -m unittest discover -s packages/tavolo-scopone/tests
# type checks:
.venv/bin/python -m mypy -p tavolo.platform
.venv/bin/python -m mypy -p tavolo.scopone
.venv/bin/python -m mypy --namespace-packages --explicit-package-bases \
  src/tavolo/app.py src/tavolo/config.py src/tavolo/static.py \
  src/tavolo/aerich_config.py src/tavolo/logging_config.py
```

Tests run fully in-process: in-memory sqlite for Postgres, in-memory stores
for Redis, a fake OIDC user patched onto the mixins, and `httpx` /
`httpx-ws` ASGI transports for HTTP and WebSocket coverage. The platform
suite additionally runs against a `DummyEngine` toy game, so the
game-independent machinery is covered without importing scopone.

### Migrations

The Postgres schema is owned by aerich migrations in `migrations/`. The
`db-migrate` compose service runs `aerich upgrade` before the app starts.
To add a migration after changing
`packages/tavolo-platform/src/tavolo/platform/models.py`:

```sh
DATABASE_URL=postgres://tavolo:tavolo@localhost:5432/tavolo .venv/bin/aerich migrate
DATABASE_URL=postgres://tavolo:tavolo@localhost:5432/tavolo .venv/bin/aerich upgrade
```

(`aerich init-db` produces sqlite-flavored DDL when pointed at sqlite;
adjust `UUID`/`TIMESTAMPTZ`/`BOOL`/`JSONB` for Postgres like the existing
baseline.)

## Layout

```
packages/tavolo-platform/     # game-independent platform (own pyproject + tests)
  src/tavolo/platform/
  ├── __init__.py             # public surface (GameEngine, GameSession, Platform, ...)
  ├── engine.py               # the platform<->game contract
  ├── registry.py             # game id -> engine lookup
  ├── mixin.py                # Platform + PlatformMixin (mounts everything on a kaya app)
  ├── errors.py               # shared GameError hierarchy
  ├── models.py               # Match / MatchPlayer / PlayerRating (Postgres)
  ├── elo.py                  # chess-style Elo math (1500 start, K=32)
  ├── stats.py                # MatchResult -> Postgres persistence + Elo update
  ├── backfill_elo.py         # recompute all ratings from the match history
  ├── store.py                # Redis / in-memory live-session store (+ deadline queue)
  ├── deadlines.py            # connection-independent timeout scheduler
  ├── ws.py                   # WebSocket live-play endpoint (generic envelope)
  ├── auth.py                 # auth helpers (HTTP + WebSocket)
  ├── http.py                 # JSON request/response helpers
  ├── pagination.py           # keyset (cursor) pagination
  ├── openapi.py              # shared OpenAPI parameter fragments
  ├── tortoise_mixin.py       # TortoiseORM lifecycle (HTTP + WebSocket)
  └── routes/
      ├── health.py           # GET /api/health
      ├── me.py               # GET /api/me
      ├── games.py            # lobby: game-types / create / join / snapshot
      └── stats.py            # match history + leaderboard + Elo ratings
packages/tavolo-scopone/      # scopone scientifico game (own pyproject + tests)
  src/tavolo/scopone/
  ├── state.py                # ScoponeState / PlayerState / Card, JSON (de)serialization
  ├── engine.py               # pure scopone scientifico rules
  ├── errors.py               # scopone-specific rule violations
  └── plugin.py               # ScoponeEngine: the GameEngine adapter
src/tavolo/                   # tavolo-app: composition root (this pyproject.toml)
├── app.py                    # session/OIDC/Tortoise/OpenAPI/Platform/DeadlineScheduler mixins
├── config.py                 # env -> frozen Settings
├── aerich_config.py          # aerich CLI configuration
├── logging_config.py         # logging setup
└── static.py                 # SPA shell hosting
migrations/                   # aerich migrations for the platform models
tests/                        # app integration suite (platform + scopone wired together)
```