woggioni
e98d43e59a
CI / Build and push docker image (push) Successful in 6m2s
kaya-openapi 0.0.8 supports named component schemas, so the routes' description-only responses become $refs: schemas for the core payloads (auth providers, lobby, game view, ongoing games, match history, leaderboard, ratings) live in tavolo.platform.openapi and are registered through the mixin's components. Engine-defined parts (options echo, game views, match results) stay open objects on purpose. Error responses now carry the error envelope schema, and a new suite sweeps the document to keep every /api response typed.
69 lines
3.4 KiB
Markdown
69 lines
3.4 KiB
Markdown
# tavolo-platform
|
|
|
|
The game-independent half of tavolo: lobby, live play, match history and
|
|
leaderboards. Everything here works for any game that implements the
|
|
[`GameEngine`](src/tavolo/platform/engine.py) contract; the package
|
|
itself ships no game.
|
|
|
|
## Contents
|
|
|
|
- `engine.py` — the platform↔game contract: `GameEngine` (ABC),
|
|
`GameSession` (the platform-owned envelope with an opaque `state` blob),
|
|
`Seat`, `Deadline` (kind + due time + revalidation token) and the
|
|
`MatchResult`/`PlayerResult` outcome types.
|
|
- `registry.py` — `GameRegistry`: game id → engine lookup, single source
|
|
of truth for which games exist.
|
|
- `mixin.py` — `Platform` (registry + store + scheduler + OIDC, the
|
|
collaborators every endpoint needs) and `PlatformMixin`, the kaya mixin
|
|
that registers all routes and the websocket endpoint on an app.
|
|
- `routes/` — `health` (`GET /api/health`), `me` (`GET /api/me`), `games`
|
|
(lobby: `GET /api/game-types`, `POST /api/games`, `POST /api/games/join`,
|
|
`GET /api/games/{id}`) and `stats` (`GET /api/me/matches`,
|
|
`GET /api/leaderboard`, `GET /api/me/ratings`).
|
|
- `ws.py` — the live-play websocket (`/ws/games/{id}`): connection
|
|
lifecycle, the message envelope and the publish/subscribe fan-out.
|
|
Game-specific actions are dispatched to the session's engine.
|
|
- `store.py` — live-session persistence: `RedisGameStore` (production)
|
|
and `InMemoryGameStore` (tests/dev) over a JSON envelope plus the
|
|
engine's opaque state blob, with per-game locks, change signals and the
|
|
shared deadline queue.
|
|
- `deadlines.py` — `DeadlineScheduler`: enqueue the deadline an engine
|
|
declares after each mutation; a per-loop consumer fires due entries
|
|
through `engine.fire_deadline` under the per-game lock. Engines
|
|
revalidate the token, so stale or duplicate deliveries are harmless.
|
|
- `models.py` — `Match` (`game_type`, timestamps, game-specific JSON
|
|
`result`), `MatchPlayer` (seat, team, won, points, Elo delta, JSON
|
|
`details`) and `PlayerRating` (Elo and leaderboard aggregates per
|
|
`(user_sub, game_type)`).
|
|
- `stats.py` — `save_match_result` (engine `MatchResult` → Postgres,
|
|
transactionally, with Elo and the leaderboard aggregates) and
|
|
`apply_match_stats`.
|
|
- `elo.py` — chess-style Elo math generalized to two-team matches.
|
|
- `backfill_elo.py` — rebuild every rating and aggregate from the match
|
|
history: `python -m tavolo.platform.backfill_elo --database-url postgres://…`.
|
|
- `auth.py`, `http.py`, `pagination.py`, `openapi.py`,
|
|
`tortoise_mixin.py` — OIDC helpers, JSON helpers, keyset and
|
|
page-number pagination, shared OpenAPI fragments and response schemas,
|
|
the TortoiseORM lifecycle mixin.
|
|
|
|
## Adding a game
|
|
|
|
Implement `GameEngine` (see `engine.py` for the full contract), register
|
|
it in a `GameRegistry`, and mount `PlatformMixin(Platform(...))` on a
|
|
`KayaApp` — see the composition root in `tavolo.app`. The canonical
|
|
examples are [`tavolo-scopone`](../tavolo-scopone/README.md),
|
|
[`tavolo-scopa`](../tavolo-scopa/README.md) and
|
|
[`tavolo-briscola`](../tavolo-briscola/README.md).
|
|
|
|
## Development (from `server/`)
|
|
|
|
```sh
|
|
.venv/bin/python -m unittest discover -s packages/tavolo-platform/tests
|
|
.venv/bin/python -m mypy -p tavolo.platform
|
|
```
|
|
|
|
Tests run fully in-process against a `DummyEngine` (a two-player toy game
|
|
in `tests/helpers.py`): in-memory sqlite, in-memory stores, a patched
|
|
OIDC user and `httpx` / `httpx-ws` ASGI transports. No test in this
|
|
package may import a real game.
|