Smoke e2e, docs consistency pass, status summary
Built: e2e/run.js + lib.js (playwright-core, in-process server, temp DB): desktop flow, phone touch portrait/landscape, layout matrix on 5 viewports x pop/map/trade/world (overflow + console errors), WebSocket push incoming-banner without reload. 61/61 checks, ~54 s, identical over 4 runs; the push and overflow checks were shown to fail when the behaviour is removed. Docs: fixed stale numbers/claims in DESIGN, DECISIONS, BALANCE, API (undocumented routes, rate limits, notification types), DEPLOY, NEXT (status-at-a-glance on top). Deploy path exercised in a scratch dir: migrations, healthz, signup/build, admin CLI, SIGKILL catch-up, backup restore. Tested: npm test 207/207, npm run e2e 61/61, bot run 50x14d INVARIANTS OK. NOT tested: Chromium only; no systemd/nginx Proxy Manager/Node 22.13 run; e2e does not cover units, alliances, messages, trade or end-game flows beyond empty-state rendering; no nb, PWA or polling-fallback e2e; docs/workflows/ still empty. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
This commit is contained in:
parent
931f59e11e
commit
cc0524de5e
8 changed files with 533 additions and 38 deletions
24
docs/API.md
24
docs/API.md
|
|
@ -9,25 +9,30 @@ REST JSON under `/api/v1/`. The machine-readable contract is `docs/openapi.json`
|
|||
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`;
|
||||
- Mutating POSTs accept `Idempotency-Key` (8-64 chars `A-Za-z0-9_.:-`); a replay returns the stored response with `Idempotent-Replay: true` (keys are kept 24 h);
|
||||
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`.
|
||||
- Rate limits (token buckets, `server/http.js`): per client address 30 requests/s sustained, burst 90 (IPv6 clients share one bucket per /64); per
|
||||
token 15/s, burst 45; login and signup per address about 1 per 10 s, burst 8, plus a per-username login throttle. `429 rate_limited` with
|
||||
`Retry-After` / `details.retryAfter`. Request bodies are capped at 32 KB. Message and WebSocket limits are separate (below, PROTOCOL.md).
|
||||
- The client never sends computed amounts, only intents. The server recomputes everything with `public/js/rules.js`.
|
||||
|
||||
## Resources (stage 0-2)
|
||||
## Accounts, POPs, map (stage 0-2)
|
||||
|
||||
| Route | Purpose |
|
||||
| ----- | ------- |
|
||||
| `POST /auth/signup`, `POST /auth/login` | account + token (signup also founds the capital POP) |
|
||||
| `POST /auth/signup {username, password, invite?, worldId?, device?}` | account + token (201); founds the capital POP; `invite` is required only when the server has `SIGNUP_CODE` set (`signup_closed` otherwise) |
|
||||
| `POST /auth/login` | token for another device (`invalid_credentials`, `forbidden` when banned) |
|
||||
| `GET /auth/tokens`, `DELETE /auth/tokens/:tokenId`, `POST /auth/logout` | list this account's active device tokens, revoke one, revoke the current one |
|
||||
| `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 |
|
||||
| `POST /towns/:id/rename {name}` | rename a POP (2-40 chars) |
|
||||
| `GET /map?x&y&r` | rural areas, incumbent sites, POPs in the viewport |
|
||||
| `GET /notifications?after&limit` | durable notification feed (build done, ...) |
|
||||
| `GET /notifications?after&limit` | durable notification feed (build done, ...), pruned after 30 days |
|
||||
|
||||
## Social (stage 5, no marketplace/transport yet)
|
||||
## Social (stage 5)
|
||||
|
||||
`worldId` is optional everywhere a caller's operator is needed (default: their oldest operator). Most commands are
|
||||
idempotent where that makes sense and answer `{ changed: false }` when there was nothing to do (leaving twice, kicking someone
|
||||
|
|
@ -91,8 +96,9 @@ Units are plain `{ unitId: count }` objects with the generic ids of `data.UNITS`
|
|||
now carries `town.military`: units at home (`online` flag, `offlineSince`), reinforcements standing here and away, the training queue,
|
||||
what can be trained (cost, time, missing requirements), research levels and queue, transport links, and this POP's outgoing/incoming
|
||||
movements. Nothing resolves when you send it: combat, loot and arrival happen in the event queue at the arrival time, and reports and
|
||||
notifications (`incoming`, `report`, `train_done`, `research_done`, `movement_returned`, `transport_arrived`, `units_offline`,
|
||||
`units_decommissioned`, `town_lost`, `town_gained`) tell you afterwards.
|
||||
notifications (`incoming`, `report`, `train_done`, `research_done`, `movement_returned`, `movement_lost`, `transport_arrived`,
|
||||
`transport_delivered`, `reinforcements_sent_home`, `units_offline`, `units_decommissioned`, `town_lost`, `town_gained`; `build_done` for
|
||||
buildings) tell you afterwards.
|
||||
|
||||
| Route | Purpose |
|
||||
| ----- | ------- |
|
||||
|
|
@ -131,7 +137,7 @@ offer you have (older ones follow). `status`: `open`, `accepted`, `completed`, `
|
|||
| `GET /trade/offers?worldId&townId&give&want&after&limit` | open offers of others that one of your POPs (or `townId`) can take: within `min(maxDistance, 10 x exchange level)`. Each carries `acceptableFrom: [{townId, distance}]`; `exchangeLevels` lists your exchanges and their reach |
|
||||
| `GET /trade/offers/mine?worldId&status&after&limit` | offers you posted or accepted, any status, with `role` |
|
||||
| `GET /trade/offers/:id` | one offer: open ones to every operator of the world, closed ones to the two parties (`not_found` otherwise) |
|
||||
| `DELETE /trade/offers/:id` | cancel your open offer; the escrow returns to the POP (`offer_closed` when it is not open) |
|
||||
| `DELETE /trade/offers/:id` | cancel your open offer; the escrow returns to the POP, capped by its Rack hall (stock already above the cap stays; a refund never lifts it further, and the clipped part is lost without a notice: BALANCE.md S2). `offer_closed` when it is not open |
|
||||
| `POST /trade/offers/:id/accept {townId}` | take it with one of your POPs (201): two transports leave at once (your payment, their goods); `own_offer`, `offer_closed`, `trade_out_of_range`, `no_transport_link`, `not_enough_resources`; all or nothing |
|
||||
|
||||
Notifications: `trade_accepted` (poster), `trade_completed` (both, when both transports arrived), `trade_expired`, `trade_void` (the POP
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue