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
|
||||
|
|
|
|||
|
|
@ -321,7 +321,7 @@ number to move.
|
|||
**Server finding S2 (not fixed):** the escrow of an offer that expires or is cancelled after the POP's store filled up again is
|
||||
refunded only up to the Rack hall cap (`trade.refund`, decision R1). The harness books it: 36 refunds per 30-day run (all three seeds) lose
|
||||
12 to 15k Hardware and Capital in total (`arch-d30-s1`: 3.3k Hardware, 11.2k Capital in 36 events), invisibly to the player.
|
||||
DESIGN.md says nothing is lost in trade. Fix options: credit the clipped part back as a transport that waits, or let escrow refunds
|
||||
DESIGN.md used to say nothing is lost in trade (corrected to describe the cap). Fix options: credit the clipped part back as a transport that waits, or let escrow refunds
|
||||
exceed the cap the way the existing "stock above a lowered cap is kept" rule does for stock.
|
||||
|
||||
### Power binds early and then recedes
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ committed file is stale, which satisfies "updated in the same commit as any rout
|
|||
|
||||
## D8 — Resource fields are slot-keyed
|
||||
Buildings table key: `f1..f18` for resource fields (type fixed at founding, 4 per type + 2 wild), the building type for infrastructure.
|
||||
Build "slots": 1 concurrent build, 2 from Core router 10 (queue = pending `buildDone` events).
|
||||
Build "slots": 1 concurrent build, 2 from Core router 3 (was 10, changed by B1; queue = pending `buildDone` events).
|
||||
|
||||
## S5-1 — Alliance size cap is stored, only ever raised
|
||||
DESIGN says the Peering office level sets the size you can found. The cap is stored at founding (`10 + 2 * best level`). A lost or
|
||||
|
|
@ -111,7 +111,7 @@ arrival, before the POP changes hands. On transfer the old owner's pending train
|
|||
the new owner's user, and that POP's units standing elsewhere are re-homed to the old owner's capital. A captured POP keeps its footprint.
|
||||
|
||||
## S3-6 — Transport links
|
||||
`links` = Internet exchange level, each carries 500 (`D.TRANSPORT`). A link is busy while the transport is out and while its empty carriers
|
||||
`links` = Internet exchange level, each carries 1000 (`D.TRANSPORT`; 500 until B2). A link is busy while the transport is out and while its empty carriers
|
||||
drive back (a `return` movement with `extra.link`). Cargo above the receiver's Rack hall cap is lost (the notification says how much).
|
||||
`transport` movements keep arbitrary `extra` and `movements.hooks.transportArrived` is called on delivery, so the trade stage needs no
|
||||
change in the movement code.
|
||||
|
|
@ -190,8 +190,8 @@ alliance can ship; nothing here is balanced.
|
|||
## T1 — Trade: escrow, one link per side, reach by exchange level
|
||||
- Offers are escrowed in `trade_offers` and hold one transport link of the poster's POP while open (`movements.activeLinks` counts open
|
||||
offers), so accepting never fails for lack of a link on the poster's side and cannot exceed the exchange level.
|
||||
- Each side of an offer must fit ONE transport (<= 500); larger deals are several offers. The ratio band is count-based 1:2.
|
||||
- Escrow returns without the Rack hall cap (conservation beats the cap here); deliveries keep the existing cap rule (`cargoLost`).
|
||||
- Each side of an offer must fit ONE transport (<= 1000, was 500 until B2); larger deals are several offers. The ratio band is count-based 1:2.
|
||||
- Escrow returned WITHOUT the Rack hall cap at first (conservation beats the cap); review round 1 (R1) reversed that: refunds are capped like `cancelBuild` (stock already above the cap stays, the clipped part is lost silently, BALANCE.md S2). Deliveries keep the cap rule (`cargoLost`).
|
||||
- Reach: `10 tiles x exchange level` of the taker's POP, and the offer's own `maxDistance`; the poster's level only matters for the number of
|
||||
offers they can hold open.
|
||||
- A POP changing hands voids its open offers (`combat.transferTown` calls `trade.onTownTransferred`); the escrow stays in the POP.
|
||||
|
|
@ -221,7 +221,7 @@ no-referrer and a `connect-src` that allowed any `ws:`/`wss:` host (now `'self'`
|
|||
cache per world); weaker town-name sanitiser (now `text.cleanText`); rejected 429s pinned into the idempotency store (no longer);
|
||||
notifications never pruned (30 days); `units_offline` warning missing when units went offline through an arrival.
|
||||
Accepted for now, written down so nobody is surprised:
|
||||
- Escrowed trade stock is not lootable, so an unattractive offer is a hiding place for up to 250-500 of one resource per link (48 h
|
||||
- Escrowed trade stock is not lootable, so an unattractive offer is a hiding place for up to 1000 (500 before B2) of one resource per link (48 h
|
||||
offers, cancellable). Revisit if bots or players abuse it.
|
||||
- Leaving/being kicked from an alliance drops pact protection at once (pacts bind alliances, not people). Revisit: track `left_at`.
|
||||
- A battery above a lowered Battery bank cap is clamped immediately, while stock above a lowered Rack hall cap is kept. Intentional:
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# Deploying UPSTREAM
|
||||
|
||||
UPSTREAM is one Node process: it serves the static client from `public/`, the REST API under `/api/v1/` and (stage 6)
|
||||
a WebSocket at `/ws`. Unlike NETWALL it **keeps state**: one SQLite file, owned by that process. A restart loses
|
||||
UPSTREAM is one Node process: it serves the static client from `public/`, the REST API under `/api/v1/` and a
|
||||
WebSocket push channel at `/ws` (docs/PROTOCOL.md). Unlike NETWALL it **keeps state**: one SQLite file, owned by that process. A restart loses
|
||||
nothing: overdue events are caught up in order before the server accepts traffic.
|
||||
|
||||
```
|
||||
|
|
@ -17,6 +17,10 @@ layer. The differences are the Node version (`node:sqlite` needs 22.13+), a stat
|
|||
|
||||
* **Run:** `systemd-analyze verify` on the three unit files (syntax and directives only), the CLI `tools/admin.js`
|
||||
and its tests on a dev machine (Node 24.21), a backup, verify and prune cycle, `sh -n` on `deploy/upstream-admin`.
|
||||
Re-checked on 2026-10-11 with the code as it is now (Node 24.21, scratch directory, no systemd): first boot with `DB_PATH`/`PORT`/`HOST`
|
||||
(migrations 001-004 applied, `created world 1`), `/healthz`, `/` headers, signup + build over the API, `admin.js` status / worlds / users /
|
||||
operators / inspect-town / events / replay-events / backup / verify-backup / ban / unban / grant / end-world (refusal without `--yes`),
|
||||
SIGTERM and restart (state, queue and password kept, no migrations re-applied; tokens revoked by `ban` stay revoked), SIGKILL then restart after a build fell due (`caught up 1 overdue event(s)`, the build level was applied), and a restore by copying a snapshot to a fresh `DB_PATH` and starting on it (section 7: it logged `caught up 1 overdue event(s)`).
|
||||
* **Taken from NETWALL's docs, not re-run for UPSTREAM:** everything about nginx Proxy Manager (labels, header
|
||||
behaviour, "Client addresses"). NETWALL's guide records what was observed against NPM v2.16.0.
|
||||
* **Never run:** a Proxmox LXC, a started unit under systemd, the timer firing on its own, a Node install from the
|
||||
|
|
@ -163,8 +167,8 @@ line, no `export`) or in a `systemctl edit upstream` override, then `systemctl r
|
|||
| `DB_PATH` | `/var/lib/upstream/game.db` | SQLite file. The code default is `./data/game.db`; the unit overrides it. Its directory is created if missing, it must be writable by the service user. `-wal` and `-shm` files appear next to it: always copy via a snapshot (section 7), never with `cp` while running. |
|
||||
| `TRUST_PROXY` | `auto` | `auto`: believe `X-Forwarded-For` / `X-Forwarded-Host` only from loopback / private-range peers. `1`: always (then firewall the port). `0`: never. Used for the per-IP rate limits and the log. |
|
||||
| `TRUSTED_PROXIES` | empty | Extra IPs / CIDRs `auto` believes: needed when the proxy reaches the LXC from a global IPv6, Tailscale / CGNAT `100.64.0.0/10` or another routable address. |
|
||||
| `ALLOWED_ORIGINS` | empty | Extra origins for the WebSocket origin check (stage 6), comma separated, with the port when it is not 80/443. The REST API uses bearer tokens (no cookies) and does not check origins. |
|
||||
| `MAX_CONN_PER_IP` | `40` | Open connections per client address (WebSocket cap, stage 6). `0` disables. |
|
||||
| `ALLOWED_ORIGINS` | empty | Extra origins for the WebSocket origin check, comma separated, with the port when it is not 80/443. The REST API uses bearer tokens (no cookies) and does not check origins. |
|
||||
| `MAX_CONN_PER_IP` | `40` | Open WebSockets per client address (HTTP connections are not capped). `0` disables. |
|
||||
| `WORLD_SPEED` | unset (1) | World speed multiplier, **first boot only**, when the database has no world yet. |
|
||||
| `WORLD_RADIUS` | unset (50) | Map radius in tiles (coordinates `-R..R`, so 50 = 101 x 101), **first boot only**. |
|
||||
| `WORLD_NAME` | unset (`World 1`) | Name of the first world, **first boot only**. |
|
||||
|
|
@ -193,7 +197,7 @@ In NPM: **Hosts > Proxy Hosts > Add Proxy Host**.
|
|||
| Details: Forward Port | `8080` |
|
||||
| Details: Cache Assets | **off** (static files are `no-cache` and revalidated by ETag; the game must see new versions) |
|
||||
| Details: Block Common Exploits | optional |
|
||||
| Details: **Websockets Support** | **on.** The REST game works without it, but stage 6 adds `/ws` and it fails with HTTP 426 when this is off. Switch it on now so you do not forget. |
|
||||
| Details: **Websockets Support** | **on.** The REST game works without it, but `/ws` (live push) fails with HTTP 426 when this is off. |
|
||||
| Custom Locations | none needed |
|
||||
| SSL | Request a new Let's Encrypt certificate, **Force SSL**, **HTTP/2** (HSTS optional) |
|
||||
| Advanced (gear) | nothing required; optional gzip below |
|
||||
|
|
@ -214,9 +218,9 @@ Notes carried over from NETWALL's setup (observed there against NPM v2.16.0, not
|
|||
shares one rate-limit budget and the log shows the proxy's address. Fix: `TRUSTED_PROXIES=<its address or CIDR>`.
|
||||
* Clients on your own LAN can pick their address through NPM's `real_ip` handling, so the per-IP limits protect against
|
||||
public abuse, not against LAN users.
|
||||
* **Heads-up for stage 6:** NPM's default `proxy_read_timeout` is 90 s. NETWALL never idles because it streams 20
|
||||
snapshots a second; UPSTREAM's socket will be quiet for long stretches. The WebSocket server must send a ping
|
||||
well under 90 s (NETWALL's pings every 25 s), or the proxy drops idle players.
|
||||
* **Idle timeout:** nginx's `proxy_read_timeout` is 60 s by default (NETWALL's notes say 90 s for NPM; not re-checked). NETWALL never
|
||||
idles because it streams 20 snapshots a second; UPSTREAM's socket is quiet for long stretches. `server/push.js` sends a protocol ping
|
||||
every 30 s (`wsPingMs`), below either value, which is reasoning, not a measurement behind a real NPM.
|
||||
|
||||
Firewall and dual stack: identical to NETWALL (`docs/DEPLOY.md` there, section 6): only the proxy needs to reach port
|
||||
8080. `curl -i http://127.0.0.1:8080/healthz` and `curl -gi 'http://[::1]:8080/healthz'` check both families.
|
||||
|
|
@ -233,7 +237,7 @@ upstream-admin help
|
|||
upstream-admin status # file, size, migrations, overdue events
|
||||
upstream-admin worlds
|
||||
upstream-admin create-world --name "Summer" --speed 2 --radius 60 --seed 1234 --end-in 90d
|
||||
upstream-admin end-world 1 --yes
|
||||
upstream-admin end-world 1 --yes # flag flip only, see below
|
||||
upstream-admin users [--banned] # no hashes or tokens are ever printed
|
||||
upstream-admin operators [--world 1]
|
||||
upstream-admin ban mallory # sets banned, revokes all tokens: old tokens give 401, login 403
|
||||
|
|
@ -259,6 +263,9 @@ Safety rules the CLI follows:
|
|||
* Destructive or test-only commands refuse without a flag: `end-world` and `grant` need `--yes`; `reset-world`
|
||||
needs `--yes-destroy` (without it, it prints what it would delete and exits 2). `ban`, `unban`, `revoke-tokens` are
|
||||
reversible and need none.
|
||||
* `end-world` just sets the world's status to `ended` (and `end_at` to now): signup and join stop and every game command answers
|
||||
`world_ended`, but it writes no ranking snapshot (`GET /worlds/:id/results` stays `available: false`), cancels no pending event and
|
||||
closes no trade offer. The natural end (a backbone winner, then the `worldEnd` event two world days later) does all of that.
|
||||
* `reset-world` deletes the world's game rows (everything with a `world_id`, plus tables pointing at them: towns,
|
||||
buildings, events, operators, alliances, messages, ... discovered from the schema, so tables added by later stages
|
||||
are covered) and **keeps accounts and tokens**; players must join the world again. It resets `start_at`, clears
|
||||
|
|
@ -394,4 +401,4 @@ A healthy server has **no overdue events** in `status`: the timer processes even
|
|||
| `upstream-backup.service` failed | `journalctl -u upstream-backup`. Typical: disk full, or the integrity check of the new snapshot failed (then nothing was kept and nothing pruned; check the disk and the `game.db` itself). |
|
||||
| Backups not appearing | `systemctl list-timers upstream-backup.timer`; the timer must be **enabled** (`systemctl enable --now upstream-backup.timer`), not just installed. |
|
||||
| World reset by mistake | Restore the snapshot taken before (section 7), or the one `reset-world --backup` wrote. |
|
||||
| (stage 6) WebSocket upgrade answered 426 / 403 / 429 | 426: **Websockets Support** off in NPM. 403: origin check, see `ALLOWED_ORIGINS` and the notes in section 5. 429: more than `MAX_CONN_PER_IP` sockets from one address. |
|
||||
| WebSocket upgrade answered 426 / 403 / 429 | 426: **Websockets Support** off in NPM. 403: origin check, see `ALLOWED_ORIGINS` and the notes in section 5. 429: more than `MAX_CONN_PER_IP` sockets from one address. |
|
||||
|
|
|
|||
|
|
@ -25,7 +25,7 @@ Mid game adds more POPs, alliances and trade. Late game is the backbone race.
|
|||
|
||||
## World
|
||||
|
||||
- Square tile map, default 301 x 301 (coordinates -150..150), one tile = one site. World config sets size,
|
||||
- Square tile map, default 101 x 101 (radius 50, coordinates -50..50; `WORLD_DEFAULTS.mapRadius`, DECISIONS D6), one tile = one site. World config sets size,
|
||||
speed (1x, 2x, 3x), start time and a planned end.
|
||||
- Tile types: empty land, **rural area** (bonus tile), **incumbent site** (NPC), **backbone landing site**
|
||||
(appears late, see End game), player POP.
|
||||
|
|
@ -63,7 +63,7 @@ Current amount is always computed, never stored as "now": `amount = min(cap, sto
|
|||
|
||||
## Buildings
|
||||
|
||||
One build queue per POP. The **Core router** level shortens all build times. Level cap 20 for most buildings.
|
||||
One build slot per POP, a second from Core router 3 (`FORMULAS.secondQueueCoreLevel`, BALANCE.md B1). The **Core router** level shortens all build times. Level cap 20 for most buildings.
|
||||
|
||||
| Building | Role |
|
||||
| --------------- | --------------------------------------------------------------------------------------------- |
|
||||
|
|
@ -166,7 +166,8 @@ pump-feeding. Accepting an offer spawns two transport movements. Direct transpor
|
|||
an Internet exchange. Each side must fit ONE transport link (1..1000) and the two amounts differ by at most 1:2:
|
||||
`give <= 2 x want` and `want <= 2 x give` (count-based, the resources are not weighted). The resources must differ.
|
||||
- The offered amount is **escrowed**: it leaves the POP when the offer is posted. Cancelling or expiry (48 h / world speed) credits it back
|
||||
to the POP without the Rack hall cap (an amount above the cap is kept, it only stops growing), so nothing is created or lost.
|
||||
to the POP **capped by the Rack hall** (`trade.refund`, review fix R1: stock already above the cap stays, a refund never lifts it further). If
|
||||
the POP's store filled up meanwhile, the clipped part is destroyed without a notice (BALANCE.md S2, open); otherwise nothing is created or lost.
|
||||
- **Reach:** a POP sees and takes offers of other operators within `min(offer.maxDistance, 10 x Internet exchange level)` tiles. The poster
|
||||
cannot take their own offer.
|
||||
- **Links:** an open offer holds one transport link of the poster's POP in reserve (open offers + running transports + returning carriers
|
||||
|
|
@ -260,4 +261,4 @@ computed from `serverTime`.
|
|||
- Research as a tree or a flat list of upgrades?
|
||||
- Should rural areas be contested (takeable from each other) or just held?
|
||||
- Night protection and holiday mode.
|
||||
- World size vs expected players (301² tiles is a lot for 50 players; shrink for the first world).
|
||||
- World size vs expected players (the default is already 101², radius 50; is that right for 50 players? untested with real players).
|
||||
|
|
|
|||
61
docs/NEXT.md
61
docs/NEXT.md
|
|
@ -2,6 +2,41 @@
|
|||
|
||||
Honest status, updated at the end of every stage.
|
||||
|
||||
## Status at a glance (checked 2026-10-11, Node 24.21)
|
||||
Where it stands: stages 0-6 are built on the server and in the web client (economy, world, military, expansion, social, trade, end game,
|
||||
WebSocket push); stage 7 is partly done (bot harness + first balance pass, admin CLI, deploy files). **The game is not balanced, not
|
||||
playtested by humans, and has never run on the real target (Debian LXC + systemd + nginx Proxy Manager).**
|
||||
|
||||
Runnable and checked just now:
|
||||
- `npm test`: 207 tests pass in about 7 s (rules as pure functions, commands/events/scheduler with a fake clock, REST over HTTP with every
|
||||
response checked against its schema, push with a real `ws` client, client logic, bot harness, admin CLI). `npm run openapi` leaves
|
||||
`docs/openapi.json` unchanged (it is in sync with the route table: 68 paths).
|
||||
- `node tools/bot.js --players 50 --days 14 --speed 1`: about 3 s, `INVARIANTS OK`. `node tools/admin.js help` works.
|
||||
- The deploy path from DEPLOY.md in a scratch directory, without systemd: first boot (migrations, world), `/healthz`, signup, a build,
|
||||
`admin.js` status/worlds/users/inspect/events/replay/backup/verify-backup/ban/grant, SIGTERM + restart (state kept), SIGKILL + restart
|
||||
after a build fell due (caught up in order), restore of a snapshot into a fresh `DB_PATH`.
|
||||
- `npm run e2e` (`e2e/run.js`, Playwright): see the e2e section of this file, if present; not re-run for this status.
|
||||
|
||||
Never run: real devices, Safari/iOS, a Proxmox LXC, a unit under systemd, the backup timer firing, nginx Proxy Manager (WebSocket upgrade,
|
||||
idle timeouts, real client IPs), Let's Encrypt, a restore on the real box, load with many real sockets, any human player. Node 22.13 (the
|
||||
stated minimum) was not run, only 24.21.
|
||||
|
||||
Known gaps, consolidated (the sections below have the detail and the reasoning):
|
||||
- **Balance:** nothing is tuned beyond B1/B2 (BALANCE.md). Open: a 3x world's end game is as long as a 1x world's; after the opening days
|
||||
nobody can contest a built-up landing site (no garrisons, E1); raid loot is split evenly and destroyed on overflow (S4); trade escrow
|
||||
refunds are clipped at the Rack hall cap without a notice (S2); the capital runs out of things to build long before the backbone opens;
|
||||
the bots are not humans.
|
||||
- **Game rules not built:** cancelling training, sitters, night protection, a command to choose a new capital, power draw for units in
|
||||
transit, alliance rename/description, trade order book / price history / counter-offers, multi-link trade deals.
|
||||
- **Server:** no `backbone_open` push (sites are created lazily, E2); no `incoming` for confederates and no `town` hint for reinforcing
|
||||
owners; token revocation reaches an open socket only at the next 30 s ping; tokens never expire and there is no change-password route; no APNs/FCM
|
||||
sender; `reports.id` can be reused after a full cleanup (S3, low); no recovery sweeper if an `arrive`/`return` handler ever throws (R1);
|
||||
HTTP connections per IP are not capped; admin `end-world` is a flag flip without ranking snapshot (DEPLOY.md section 6).
|
||||
- **Client:** no service worker (no offline mode), no light theme, no unit icons or battle simulator, no sound/system notifications; a few
|
||||
one-tap destructive actions without confirmation; unread-badge state is partly in localStorage; ended-world locking is a DOM sweep.
|
||||
- **Docs:** `docs/workflows/` (planned stage workflows, CLAUDE.md layout) is empty: no stage workflow was ever written there.
|
||||
- **Not run in a browser:** takeover/capture flows, the confederation `alliedIncoming` view, real devices (see the client sections).
|
||||
|
||||
## Done
|
||||
- Stage 0 skeleton: db + migrations, clock, scheduler with catch-up, router, auth/tokens, error envelope, openapi generation, static server.
|
||||
- Stage 1 economy (server): lazy resources, buildings, build queue, storage caps, power battery.
|
||||
|
|
@ -22,8 +57,8 @@ Not done:
|
|||
is enforced by the military stage (`pactBlocks`).
|
||||
- Web client: see the client sections below; WebSocket push (stage 6) exists server-side and in the client.
|
||||
- Message retention/cleanup of old rows, alliance rename/description, mass-mail abuse reporting, sitter accounts.
|
||||
- Rankings are not cached; battle rankings stay empty until the military stage writes `operator_stats`.
|
||||
- Not run: Playwright, load, or any bot balance run; the social numbers in `SOCIAL` (limits, TTLs, role table) are first guesses.
|
||||
- Rankings: the footprint part has a 5 s per-world cache (review R1); battle rankings are filled from `operator_stats` now that the military stage writes it.
|
||||
- Not run: Playwright, load; the social numbers in `SOCIAL` (limits, TTLs, role table) are first guesses (the bot runs only exercised alliances/NAP/confederation lightly).
|
||||
|
||||
## Stage 3/4: military and expansion (server only)
|
||||
Built (migration `002_military.sql`: `town_units`, `stationed`, `town_research`, `town_power`, `movements`, `reports`, `report_recipients`,
|
||||
|
|
@ -55,13 +90,13 @@ Built: `public/` vanilla JS, no build step, strict-CSP friendly (no inline scrip
|
|||
map (`js/render.js` canvas: pan, pinch, wheel, keyboard, culling; chunked `GET /map` cache; tile info sheet), alerts
|
||||
(`GET /notifications`), settings (language, device tokens + revoke, logout).
|
||||
- `js/api.js`: bearer token, serverTime offset, retry/backoff (network, 429 + Retry-After, 502-504), `Idempotency-Key` per intent,
|
||||
`ApiError.code`, event emitter with a reserved `push` event (no WebSocket client yet).
|
||||
`ApiError.code`, event emitter with a `push` event (the WebSocket client `ws.js` came with the military client, below).
|
||||
- `js/i18n.js`: en + nb, all player-facing names; `PWA`: manifest + icons (no service worker, so no offline mode).
|
||||
- Tests: `test/client-i18n.test.js` (key parity, names, error codes, formatting), `test/client-api.test.js` (retry, idempotency, offset).
|
||||
- Looked at with headless Chromium screenshots (phone portrait, phone landscape, desktop) and one scripted signup/build/cancel/map-tap
|
||||
flow on a phone profile. Not run: real devices, Safari/iOS, Playwright suite.
|
||||
Gaps: the unread badge is stored in localStorage (no "mark read" route); `/me` exposes the world seed which the client ignores;
|
||||
no push, no service worker, canvas has no inertia/fling, no light theme.
|
||||
no service worker (push was added later, see the WebSocket section), canvas has no inertia/fling, no light theme.
|
||||
|
||||
## Client: social (alliance, messages, rankings)
|
||||
Built (all in the nav "More" group, `navGroup: 'more'`): `screens/alliance.js` (found with Peering office gate and translated server
|
||||
|
|
@ -162,7 +197,7 @@ Built (More group; strings in `strings/{trade,world,alerts}.js`, en + nb):
|
|||
minute. Confederate Carol gets no push for `alliedIncoming` (known server gap): it shows when the Moves screen is opened or the poll runs, and never in her badge.
|
||||
Found and fixed in the client: `report` pushes now also refetch movements (the incoming banner used to linger up to a few seconds after the arrival).
|
||||
Not done / not claimed:
|
||||
- Not run: real devices, Safari, a socket behind nginx Proxy Manager, throttled networks, the Playwright suite (`e2e/` is still empty), long lists (offers > 25 per
|
||||
- Not run: real devices, Safari, a socket behind nginx Proxy Manager, throttled networks, the full Playwright suite (only the smoke e2e exists), long lists (offers > 25 per
|
||||
filter paged only up to what the sweep seeded).
|
||||
- Ended-world locking is a DOM sweep, not per-button wiring: a new primary/danger button that is NOT a game command must carry `data-keep`. Messages, ranking and
|
||||
settings screens are exempt by selector. Open send/trade sheets that were opened before the end stay usable until the next DOM change or a refused command.
|
||||
|
|
@ -187,7 +222,7 @@ one tick are merged. Small edits outside the new files: `scheduler.js` (outbox,
|
|||
Tests: `test/push-ws.test.js` (auth ok/bad/timeout, origin, path, per-IP cap and its release, rate limit, bad budget, oversize frame, dead
|
||||
socket, revoked token, banned user, shutdown, REST with no socket) and `test/push-game.test.js` (build/train done, incoming only to the
|
||||
defender, report/message/alliance invite hints, recall, coalescing, rollback). Real `ws` client, fake clock, port 0. `npm test`: 113 pass
|
||||
(run after the push work, with the other agents' changes in the tree at that moment).
|
||||
when this was written (207 on 2026-10-11, whole suite).
|
||||
Not done / not claimed:
|
||||
- The client now exists (`public/js/ws.js`, see "Client: military, expansion, WebSocket") and was run against this server in a headless browser; not through a proxy.
|
||||
- Revocation closes the socket at the next ping tick (default 30 s), not instantly: `POST /auth/logout` and token deletion do not call push.
|
||||
|
|
@ -220,8 +255,8 @@ Not done / not claimed:
|
|||
- No `backbone_open` push at the moment the sites appear unless something touches a site first (E2); clients see the phase by polling status.
|
||||
- Trade: no multi-link deals (each side <= 500), no price history or order book, no counter-offers, no notification when a new offer appears
|
||||
in reach, offers are not hidden from enemies, the escrow of a taken-over POP goes to the conqueror.
|
||||
- Ended worlds: movements still `out` and queued builds are left as they were (events cancelled, E3); there is no admin "end world now" or
|
||||
"reset" yet (stage 7 world lifecycle: the `worldEnd` event can be enqueued by hand); several winners are impossible by design.
|
||||
- Ended worlds: movements still `out` and queued builds are left as they were (events cancelled, E3); `tools/admin.js end-world` only flips the status (no snapshot, no event cancellation) and `reset-world`
|
||||
wipes a world's rows; neither runs the real `worldEnd` event (see DEPLOY.md section 6); several winners are impossible by design.
|
||||
- The ranking snapshot is the same numbers as `/rankings`, computed once; `/rankings/*` after the end still compute live from the frozen state.
|
||||
- Client for all of this: see "Client: trade, end game, alerts" above.
|
||||
|
||||
|
|
@ -243,5 +278,13 @@ reading the constant); trade escrow refunds are clipped at the Rack hall cap sil
|
|||
the capital runs out of things to build ~50 days before the backbone opens at 4 sittings a day; a built-up landing site is out of reach of any
|
||||
single-POP army (no garrisons, E1), so there is no fight for a site after the first days.
|
||||
|
||||
## Stage 7 (ops part): admin CLI, deploy files
|
||||
Built: `tools/admin.js` (status, migrate, worlds, create-world, end-world, users, operators, ban/unban/revoke-tokens, inspect-operator/-town, events,
|
||||
replay-events [--simulate], backup/verify-backup (VACUUM INTO, verified, pruned), reset-world, grant), `deploy/` (service, backup service + timer,
|
||||
`upstream-admin` wrapper), `docs/DEPLOY.md`. Tests: `test/admin-cli.test.js`. Run by hand on 2026-10-11 in a scratch directory: see "Status at a glance".
|
||||
Not done / not claimed: nothing of it has run under systemd or on Debian 13 (DEPLOY.md lists what was and was not run); no load test with real sockets;
|
||||
world lifecycle through the CLI is partial (above); no scheduled "create next world".
|
||||
|
||||
## Not done
|
||||
- Everything else. See CLAUDE.md "Working in stages".
|
||||
- Stage 7 remainder: balance passes beyond B1/B2 with the open items above, a real world lifecycle (start, natural end, reset) driven from the CLI,
|
||||
load test over HTTP/WebSocket, the full e2e suite and a human playtest. Everything else in CLAUDE.md "Working in stages" is built.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue