feat(api): viewer read-only API — epic E4 (TASK-33…40) #4

Merged

geekiot merged 9 commits from feat/api into main

2026-08-09 18:12:24 +05:00

geekiot commented

2026-08-09 18:11:56 +05:00

Owner

What

Complete viewer REST API per docs/spec/05-api/viewer-api.md and the OpenAPI
contract docs/contracts/api/viewer-api.openapi.yaml — 8 endpoints, read-only
(CON-002, NFR-031, D-18): metadata from PostgreSQL, events from JSONL journals
in the named volume (D-62). No game logic, no calls into game-core.

Endpoints (base path `/api/v1`, D-72)

GET /health — liveness probe;
GET /sessions/current — active session or next_scheduled_at from
SessionScheduled.planned_at (FR-040, D-84);
GET /sessions — finished sessions, offset pagination, newest first;
GET /sessions/{id} — metadata, roster with roles (D-43), events_count;
GET /sessions/{id}/events — event page via after/limit cursor,
last_seq, session_status (polling stop signal, D-73); single mechanism
for live and replay (FR-031, ADR-004), no visibility filtering (D-43);
GET /players, GET /players/{id} — catalog-consistent attributes (FR-020),
public memory (D-52), stats history (D-66);
GET /stats/overview — six D-20 metrics (draft D-74, TODO in code);
GET /sessions/test — journal fixture data/fixtures/test-session.jsonl
under the /sessions/{id}/events contract (FR-044, D-63, D-75).

Key decisions

JournalReader (TASK-34): cursor paging with seq > after, parsing only via
domain JournalLine.from_json (CON-003), tolerant of a live file being
appended (broken tail line skipped, D-62); reused by /sessions/test
unchanged (D-75).
Repositories are SELECT-only over schema 0001/0002; OpenAPI contract
serialization happens in the route layer.
Errors unified with admin-api: {"error": {code, message}} — 400 (invalid
parameters), 404 (not found), 500 without internals plus an ERROR log entry
(NFR-040); request metrics middleware (method/path/status/latency_ms) in
structured JSON logs (D-82).

Tests and checks

61 new tests (391 → 452 passed, 1 skipped): contract tests for all
endpoints, error-code table, p95 reader benchmark (NFR-012 ≤ 500 ms),
fixture coverage of every event type.
ruff check, ruff format --check, ty check, uv run pytest,
nix flake check — all green.

Traceability

FR-030, FR-031, FR-040, FR-043, FR-044; D-16, D-43, D-51, D-52, D-53, D-62,
D-63, D-66, D-72, D-73, D-75; NFR-012, NFR-031, NFR-040; ADR-004.

Open notes: TODO(D-74) in StatsRepository (the /stats/overview field
composition is finalized together with the frontend epic E5 / TASK-48).

## What Complete viewer REST API per `docs/spec/05-api/viewer-api.md` and the OpenAPI contract `docs/contracts/api/viewer-api.openapi.yaml` — 8 endpoints, read-only (CON-002, NFR-031, D-18): metadata from PostgreSQL, events from JSONL journals in the named volume (D-62). No game logic, no calls into game-core. ## Endpoints (base path `/api/v1`, D-72) - `GET /health` — liveness probe; - `GET /sessions/current` — active session or `next_scheduled_at` from SessionScheduled.planned_at (FR-040, D-84); - `GET /sessions` — finished sessions, offset pagination, newest first; - `GET /sessions/{id}` — metadata, roster with roles (D-43), `events_count`; - `GET /sessions/{id}/events` — event page via `after`/`limit` cursor, `last_seq`, `session_status` (polling stop signal, D-73); single mechanism for live and replay (FR-031, ADR-004), no visibility filtering (D-43); - `GET /players`, `GET /players/{id}` — catalog-consistent attributes (FR-020), public memory (D-52), stats history (D-66); - `GET /stats/overview` — six D-20 metrics (draft D-74, TODO in code); - `GET /sessions/test` — journal fixture `data/fixtures/test-session.jsonl` under the `/sessions/{id}/events` contract (FR-044, D-63, D-75). ## Key decisions - `JournalReader` (TASK-34): cursor paging with `seq > after`, parsing only via domain `JournalLine.from_json` (CON-003), tolerant of a live file being appended (broken tail line skipped, D-62); reused by `/sessions/test` unchanged (D-75). - Repositories are SELECT-only over schema 0001/0002; OpenAPI contract serialization happens in the route layer. - Errors unified with admin-api: `{"error": {code, message}}` — 400 (invalid parameters), 404 (not found), 500 without internals plus an ERROR log entry (NFR-040); request metrics middleware (method/path/status/latency_ms) in structured JSON logs (D-82). ## Tests and checks - 61 new tests (391 → 452 passed, 1 skipped): contract tests for all endpoints, error-code table, p95 reader benchmark (NFR-012 ≤ 500 ms), fixture coverage of every event type. - `ruff check`, `ruff format --check`, `ty check`, `uv run pytest`, `nix flake check` — all green. ## Traceability FR-030, FR-031, FR-040, FR-043, FR-044; D-16, D-43, D-51, D-52, D-53, D-62, D-63, D-66, D-72, D-73, D-75; NFR-012, NFR-031, NFR-040; ADR-004. Open notes: `TODO(D-74)` in `StatsRepository` (the `/stats/overview` field composition is finalized together with the frontend epic E5 / TASK-48).

geekiot added 9 commits

2026-08-09 18:11:56 +05:00

feat(api): app skeleton and read-only DB repositories (TASK-33, FR-030, NFR-031) 1bc66b8a50

feat(api): JSONL journal reader with cursor paging (TASK-34, D-51, D-62, FR-011) 6e40560c1a

feat(api): session endpoints /sessions/current, /sessions, /sessions/{id} (TASK-35, FR-030, FR-040) 90a17e4b3a

feat(api): events endpoint /sessions/{id}/events (TASK-36, FR-031, D-16, D-73) 127c931238

feat(api): player endpoints /players, /players/{id} (TASK-37, FR-020, FR-043, D-52, D-66) e3ad885b13

feat(api): stats overview endpoint (TASK-38, D-20, FR-043, draft D-74) ae71ec6b03

feat(api): test session endpoint /sessions/test from journal fixture (TASK-39, FR-044, D-63, D-75) f8a810bc89

feat(api): unified error handling and request observability (TASK-40, NFR-040, D-82) 19732d67b8

docs: mark E4 (viewer api) as completed in root README 030c94c575