Stage 0-2 server spine: db, scheduler, REST, auth, economy, map

Built: SQLite (node:sqlite) via server/db.js with checksummed migrations, injectable clock, persistent event
scheduler with catch-up, tiny REST router (error envelope, idempotency keys, rate limits, bearer tokens with scrypt
passwords), lazy-resource economy in public/js/rules.js + data.js, build/cancel/rename commands, seeded map +
spawn ring, generated docs/openapi.json. NETWALL net.js/static.js reused.
Tested: manual smoke run only (signup, town view, build, map). No unit tests or e2e yet.
NOT done: military, expansion, social, client, push, deploy docs, bots/admin.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
This commit is contained in:
jvanvik 2026-10-11 18:07:42 +02:00
parent 9fa76d53a8
commit b56b13880e
39 changed files with 4450 additions and 0 deletions

30
docs/API.md Normal file
View file

@ -0,0 +1,30 @@
# API
REST JSON under `/api/v1/`. The machine-readable contract is `docs/openapi.json`, generated from the route table
(`npm run openapi`); this file covers conventions and per-resource notes.
## Conventions
- Auth: `Authorization: Bearer <token>` (opaque, one per device; `POST /auth/login` or `/auth/signup` issues one, `POST /auth/logout`
and `DELETE /auth/tokens/:id` revoke). No cookies.
- Every response is an object with `serverTime` (integer ms since epoch, server clock). Clients compute countdowns from the offset.
- Errors: `{ serverTime, error: { code, message, details } }`. Clients switch on `code`. All codes: `x-error-codes` in openapi.json.
- Mutating POSTs accept `Idempotency-Key` (8-64 chars `A-Za-z0-9_.:-`); a replay returns the stored response with `Idempotent-Replay: true`;
the same key with a different request is `idempotency_key_reuse`.
- Lists are cursor-paginated: `?after=<id>&limit=<n>`, response `next` is the cursor or `null`.
- Rate limits: per IP, per token, stricter on login/signup. `429 rate_limited` with `Retry-After`.
- The client never sends computed amounts, only intents. The server recomputes everything with `public/js/rules.js`.
## Resources (stage 0-2)
| Route | Purpose |
| ----- | ------- |
| `POST /auth/signup`, `POST /auth/login` | account + token (signup also founds the capital POP) |
| `GET /me` | user, operators (per world), POPs |
| `GET /towns/:id` | full POP state: resources `{amount, rate, cap}` at `serverTime`, power, buildings with the server's build plan, queue |
| `POST /towns/:id/build {key}` | build/upgrade one level of a field (`f1..f18`) or an infrastructure building |
| `DELETE /towns/:id/queue/:eventId` | cancel a running build, 80% refund |
| `GET /map?x&y&r` | rural areas, incumbent sites, POPs in the viewport |
| `GET /notifications?after&limit` | durable notification feed (build done, ...) |
Later stages append their routes here and to the route table.