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:
jvanvik 2026-10-11 20:34:35 +02:00
parent 931f59e11e
commit cc0524de5e
8 changed files with 533 additions and 38 deletions

View file

@ -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. 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. - 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. - 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`. 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`. - 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`. - 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 | | 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 /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 | | `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 | | `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 | | `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 /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 `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 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, 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 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 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`, notifications (`incoming`, `report`, `train_done`, `research_done`, `movement_returned`, `movement_lost`, `transport_arrived`,
`units_decommissioned`, `town_lost`, `town_gained`) tell you afterwards. `transport_delivered`, `reinforcements_sent_home`, `units_offline`, `units_decommissioned`, `town_lost`, `town_gained`; `build_done` for
buildings) tell you afterwards.
| Route | Purpose | | 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?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/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) | | `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 | | `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 Notifications: `trade_accepted` (poster), `trade_completed` (both, when both transports arrived), `trade_expired`, `trade_void` (the POP

View file

@ -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 **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 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. 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. exceed the cap the way the existing "stock above a lowered cap is kept" rule does for stock.
### Power binds early and then recedes ### Power binds early and then recedes

View file

@ -32,7 +32,7 @@ committed file is stale, which satisfies "updated in the same commit as any rout
## D8 — Resource fields are slot-keyed ## 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. 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 ## 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 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. 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 ## 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). 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 `transport` movements keep arbitrary `extra` and `movements.hooks.transportArrived` is called on delivery, so the trade stage needs no
change in the movement code. 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 ## 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 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. 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. - 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 returns without the Rack hall cap (conservation beats the cap here); deliveries keep the existing cap rule (`cargoLost`). - 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 - 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. offers they can hold open.
- A POP changing hands voids its open offers (`combat.transferTown` calls `trade.onTownTransferred`); the escrow stays in the POP. - 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); 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. 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: 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. 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`. - 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: - A battery above a lowered Battery bank cap is clamped immediately, while stock above a lowered Rack hall cap is kept. Intentional:

View file

@ -1,7 +1,7 @@
# Deploying UPSTREAM # Deploying UPSTREAM
UPSTREAM is one Node process: it serves the static client from `public/`, the REST API under `/api/v1/` and (stage 6) UPSTREAM is one Node process: it serves the static client from `public/`, the REST API under `/api/v1/` and a
a WebSocket at `/ws`. Unlike NETWALL it **keeps state**: one SQLite file, owned by that process. A restart loses 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. 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` * **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`. 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 * **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. 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 * **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. | | `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. | | `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. | | `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. | | `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 connections per client address (WebSocket cap, stage 6). `0` disables. | | `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_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_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**. | | `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: Forward Port | `8080` |
| Details: Cache Assets | **off** (static files are `no-cache` and revalidated by ETag; the game must see new versions) | | 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: 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 | | Custom Locations | none needed |
| SSL | Request a new Let's Encrypt certificate, **Force SSL**, **HTTP/2** (HSTS optional) | | SSL | Request a new Let's Encrypt certificate, **Force SSL**, **HTTP/2** (HSTS optional) |
| Advanced (gear) | nothing required; optional gzip below | | 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>`. 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 * 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. 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 * **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
snapshots a second; UPSTREAM's socket will be quiet for long stretches. The WebSocket server must send a ping idles because it streams 20 snapshots a second; UPSTREAM's socket is quiet for long stretches. `server/push.js` sends a protocol ping
well under 90 s (NETWALL's pings every 25 s), or the proxy drops idle players. 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 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. 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 status # file, size, migrations, overdue events
upstream-admin worlds upstream-admin worlds
upstream-admin create-world --name "Summer" --speed 2 --radius 60 --seed 1234 --end-in 90d 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 users [--banned] # no hashes or tokens are ever printed
upstream-admin operators [--world 1] upstream-admin operators [--world 1]
upstream-admin ban mallory # sets banned, revokes all tokens: old tokens give 401, login 403 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` * 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 needs `--yes-destroy` (without it, it prints what it would delete and exits 2). `ban`, `unban`, `revoke-tokens` are
reversible and need none. 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, * `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 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 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). | | `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. | | 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. | | 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. |

View file

@ -25,7 +25,7 @@ Mid game adds more POPs, alliances and trade. Late game is the backbone race.
## World ## 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. speed (1x, 2x, 3x), start time and a planned end.
- Tile types: empty land, **rural area** (bonus tile), **incumbent site** (NPC), **backbone landing site** - Tile types: empty land, **rural area** (bonus tile), **incumbent site** (NPC), **backbone landing site**
(appears late, see End game), player POP. (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 ## 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 | | 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: 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. `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 - 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 - **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. 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 - **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? - Research as a tree or a flat list of upgrades?
- Should rural areas be contested (takeable from each other) or just held? - Should rural areas be contested (takeable from each other) or just held?
- Night protection and holiday mode. - 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).

View file

@ -2,6 +2,41 @@
Honest status, updated at the end of every stage. 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 ## Done
- Stage 0 skeleton: db + migrations, clock, scheduler with catch-up, router, auth/tokens, error envelope, openapi generation, static server. - 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. - 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`). 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. - 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. - 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`. - 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, or any bot balance run; the social numbers in `SOCIAL` (limits, TTLs, role table) are first guesses. - 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) ## Stage 3/4: military and expansion (server only)
Built (migration `002_military.sql`: `town_units`, `stationed`, `town_research`, `town_power`, `movements`, `reports`, `report_recipients`, 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 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). (`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, - `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). - `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). - 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 - 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. 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; 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) ## 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 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. 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). 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 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). 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 - 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. 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 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 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 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: 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. - 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. - 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. - 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 - 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. 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 - 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`
"reset" yet (stage 7 world lifecycle: the `worldEnd` event can be enqueued by hand); several winners are impossible by design. 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. - 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. - 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 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. 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 ## 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.

158
e2e/lib.js Normal file
View file

@ -0,0 +1,158 @@
'use strict';
/*
* Shared plumbing for the smoke e2e: boots the real server in-process (real clock, temp SQLite file, high WORLD_SPEED so
* builds finish in seconds), creates users, opens pages with console/page-error capture, and a tiny pass/fail recorder.
* Self-contained: only depends on server/, public/js/rules.js and playwright-core.
*/
const fs = require('fs');
const os = require('os');
const path = require('path');
const { createServer } = require('../server');
const R = require('../public/js/rules.js');
const ROOT = path.join(__dirname, '..');
const PASSWORD = 'correct horse battery';
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
// ---------------------------------------------------------------- pass/fail recorder
const results = [];
let currentGroup = '';
function group(name) { currentGroup = name; console.log('\n== ' + name); }
function record(name, ok, detail) {
results.push({ group: currentGroup, name, ok: !!ok, detail });
console.log((ok ? ' PASS ' : ' FAIL ') + name + (!ok && detail ? '\n ' + String(detail).split('\n').join('\n ') : ''));
return !!ok;
}
// Run one named check; an exception is a failure, not a crash of the whole run.
async function check(name, fn) {
const t0 = Date.now();
try {
const r = await fn();
if (r === false) return record(name, false, 'returned false');
if (typeof r === 'string') return record(name, false, r); // a string is a failure message
return record(name, true);
} catch (e) {
return record(name, false, (e && e.message || String(e)).split('\n').slice(0, 6).join('\n') + ' [' + (Date.now() - t0) + ' ms]');
}
}
function summary() {
const failed = results.filter((r) => !r.ok);
console.log('\n' + '='.repeat(60));
console.log(results.length - failed.length + ' passed, ' + failed.length + ' failed, ' + results.length + ' checks');
for (const f of failed) console.log(' FAIL [' + f.group + '] ' + f.name);
return failed.length;
}
// ---------------------------------------------------------------- server
async function bootServer(o) {
o = o || {};
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'upstream-e2e-'));
const logs = [];
const srv = await createServer({
port: 0, host: '127.0.0.1', dbPath: path.join(dir, 'game.db'), log: (m) => { logs.push(m); },
// one machine plays many users: lift the per-IP / per-token / auth rate limits (they are covered by server tests)
ipRate: 1e6, ipBurst: 1e6, tokenRate: 1e6, tokenBurst: 1e6, authRate: 1e6, authBurst: 1e6,
signupCode: o.signupCode || '',
world: { speed: o.speed || 4000, mapRadius: o.mapRadius || 60, name: 'E2E' },
});
const world = srv.db.get('SELECT * FROM worlds LIMIT 1');
const base = 'http://127.0.0.1:' + srv.port;
async function api(p, method, body, token) {
const r = await fetch(base + '/api/v1' + p, { method: method || 'GET', headers: Object.assign({ 'content-type': 'application/json' }, token ? { authorization: 'Bearer ' + token } : {}), body: body === undefined ? undefined : JSON.stringify(body) });
const j = await r.json().catch(() => ({}));
if (r.status >= 300) throw new Error((method || 'GET') + ' ' + p + ' -> ' + r.status + ' ' + JSON.stringify(j));
return j;
}
async function signup(name) {
const r = await api('/auth/signup', 'POST', { username: name, password: PASSWORD, device: 'e2e' });
const op = r.operators[0];
return { name, token: r.token, userId: r.user.id, operatorId: op.id, townId: op.towns[0].id };
}
async function close() { await srv.close(); try { fs.rmSync(dir, { recursive: true, force: true }); } catch (e) { /* ignore */ } }
return { srv, db: srv.db, world, base, api, signup, close, logs, dir };
}
// ---------------------------------------------------------------- direct DB seeding (what a long game would have built up)
function landNear(S, x, y) {
for (let i = 0; i < 400; i++) {
const xx = x + i;
if (R.tileAt(S.world.seed, S.world.map_radius, xx, y).type === 'land' && !S.db.get('SELECT 1 AS x FROM towns WHERE world_id = ? AND x = ? AND y = ?', S.world.id, xx, y)) return { x: xx, y };
}
throw new Error('no land near ' + x + ',' + y);
}
function placeTown(S, townId, x, y) {
const p = landNear(S, x, y);
S.db.run('UPDATE towns SET x = ?, y = ? WHERE id = ?', p.x, p.y, townId);
return p;
}
function setBuildings(S, townId, levels) {
for (const type of Object.keys(levels)) {
if (S.db.get('SELECT 1 AS x FROM buildings WHERE town_id = ? AND key = ?', townId, type)) S.db.run('UPDATE buildings SET level = ? WHERE town_id = ? AND key = ?', levels[type], townId, type);
else S.db.run('INSERT INTO buildings (town_id, key, type, level) VALUES (?, ?, ?, ?)', townId, type, type, levels[type]);
}
}
function giveUnits(S, townId, units) {
for (const k of Object.keys(units)) S.db.run('INSERT INTO town_units (town_id, unit, count) VALUES (?, ?, ?) ON CONFLICT (town_id, unit) DO UPDATE SET count = count + excluded.count', townId, k, units[k]);
}
// ---------------------------------------------------------------- browser pages
const PROFILES = {
desktop: { viewport: { width: 1280, height: 800 } },
phone: { viewport: { width: 390, height: 844 }, hasTouch: true, isMobile: true, deviceScaleFactor: 2 },
landscape: { viewport: { width: 844, height: 390 }, hasTouch: true, isMobile: true, deviceScaleFactor: 2 },
};
// A page with console/page-error/5xx capture. `errors` holds everything that must stay empty.
async function newPage(browser, ctxOpts, o) {
o = o || {};
const ctx = await browser.newContext(ctxOpts);
const page = await ctx.newPage();
const errors = [];
page.on('console', (m) => { if (m.type() === 'error' || m.type() === 'warning') errors.push(m.type() + ': ' + m.text() + (m.location() && m.location().url ? ' @ ' + m.location().url : '')); });
page.on('pageerror', (e) => errors.push('pageerror: ' + e.message));
page.on('requestfailed', (r) => { if (!/\/ws(\?|$)/.test(r.url()) && !(r.failure() && /ERR_ABORTED/.test(r.failure().errorText))) errors.push('requestfailed: ' + r.url() + ' ' + (r.failure() && r.failure().errorText)); });
page.on('response', (r) => { if (r.status() >= 400 && !(o.allowStatus || []).includes(r.status())) errors.push('HTTP ' + r.status() + ' ' + r.request().method() + ' ' + r.url()); });
page.on('dialog', (d) => { errors.push('dialog: ' + d.message()); d.dismiss(); });
await page.addInitScript(() => { try { localStorage.setItem('upstream.lang', 'en'); } catch (e) { /* ignore */ } });
return { ctx, page, errors };
}
// Sign in by token injection (fast path used by the layout matrix and the push test).
async function openSignedIn(browser, S, user, ctxOpts, hash, o) {
const p = await newPage(browser, ctxOpts, o);
await p.page.addInitScript((tok) => { try { localStorage.setItem('upstream.token', tok); } catch (e) { /* ignore */ } }, user.token);
await p.page.goto(S.base + '/' + (hash || '#/pop'));
await p.page.waitForSelector('#nav:not([hidden])', { timeout: 15000 });
return p;
}
// Horizontal overflow, as a player sees it. The app sets overflow-x:hidden on html/body/#view, so scrollWidth stays equal to the
// viewport even when content is cut off. Therefore: (1) the page itself must not scroll, and (2) no visible element may extend
// past the viewport edges unless a component-level ancestor deliberately clips or scrolls it (carousels, ellipsis text, bars).
// Returns a description of the problem or null.
async function overflowReport(page) {
return page.evaluate(() => {
const de = document.documentElement, b = document.body, vw = de.clientWidth;
const out = [];
if (de.scrollWidth > vw + 1) out.push('documentElement.scrollWidth ' + de.scrollWidth + ' > ' + vw);
if (b.scrollWidth > vw + 1) out.push('body.scrollWidth ' + b.scrollWidth + ' > ' + vw);
const page = new Set([document.documentElement, document.body, document.getElementById('app'), document.getElementById('view')]);
const clips = (el) => { const o = getComputedStyle(el).overflowX; return o === 'auto' || o === 'scroll' || o === 'hidden' || o === 'clip'; };
const name = (el) => el.tagName.toLowerCase() + (el.id ? '#' + el.id : '') + (typeof el.className === 'string' && el.className.trim() ? '.' + el.className.trim().split(/\s+/).join('.') : '');
const bad = [];
for (const el of document.querySelectorAll('#app *')) {
if (el.closest('[hidden]') || el.closest('canvas') || el.tagName === 'CANVAS' || el instanceof SVGElement) continue;
const cs = getComputedStyle(el);
if (cs.visibility === 'hidden' || cs.display === 'none' || cs.position === 'fixed') continue;
const r = el.getBoundingClientRect();
if (r.width === 0 || r.height === 0) continue;
if (r.right <= vw + 1 && r.left >= -1) continue;
let clipped = false;
for (let a = el.parentElement; a && !page.has(a); a = a.parentElement) { if (clips(a)) { clipped = true; break; } }
if (!clipped && el !== document.getElementById('view')) bad.push(name(el) + ' [' + Math.round(r.left) + '..' + Math.round(r.right) + '] vs viewport ' + vw);
}
if (bad.length) out.push(bad.length + ' element(s) escape the viewport: ' + bad.slice(0, 4).join('; '));
return out.length ? out.join('; ') : null;
});
}
module.exports = { ROOT, PASSWORD, sleep, group, check, record, summary, results, bootServer, landNear, placeTown, setBuildings, giveUnits, PROFILES, newPage, openSignedIn, overflowReport, R };

280
e2e/run.js Normal file
View file

@ -0,0 +1,280 @@
'use strict';
/*
* UPSTREAM smoke e2e (npm run e2e). Boots the real server in-process (temp SQLite file, fast world) and drives real Chromium
* through playwright-core. Target: 1-2 minutes. Exit code 1 if any check fails.
*
* node e2e/run.js all suites
* node e2e/run.js push layout only the named suites (desktop, phone, layout, push)
* E2E_HEADED=1 node e2e/run.js watch it
* E2E_SHOTS=dir node e2e/run.js save a screenshot after each flow / on each failure into dir
*
* What it does NOT do: it is not the full suite (no combat balance, no alliance/trade flows, no Firefox/WebKit, no real proxy).
*/
const fs = require('fs');
const path = require('path');
const { chromium } = require('playwright-core');
const L = require('./lib.js');
const { check, group, sleep, PROFILES } = L;
const SHOTS = process.env.E2E_SHOTS || '';
const want = process.argv.slice(2);
const wanted = (n) => !want.length || want.includes(n);
if (SHOTS) fs.mkdirSync(SHOTS, { recursive: true });
const shot = async (page, name) => { if (SHOTS) await page.screenshot({ path: path.join(SHOTS, name + '.png') }).catch(() => {}); };
const noErrors = (p, label) => (p.errors.length ? (label || 'console') + ' errors:\n' + p.errors.join('\n') : true);
// ---------------------------------------------------------------- shared flow pieces
// Tap/click that does the right thing for the profile (real touch events on phones, real mouse on desktop).
const tapper = (page, touch) => (sel, opts) => (touch ? page.tap(sel, opts) : page.click(sel, opts));
async function signUpThroughUi(P, name, touch) {
const tap = tapper(P.page, touch);
await P.page.goto(P.base + '/');
await P.page.waitForSelector('.auth-form');
await tap('.auth-form .linklike'); // login -> signup
await P.page.fill('#f-user', name);
await P.page.fill('#f-pass', L.PASSWORD);
await tap('.auth-form button[type=submit]');
await P.page.waitForSelector('#nav:not([hidden])', { timeout: 15000 });
await P.page.waitForSelector('.town-name');
}
async function buildFieldAndWait(page, touch) {
const tap = tapper(page, touch);
const before = await page.evaluate(() => { const t = document.querySelector('.tile[data-key="f1"]'); return t ? t.innerText.trim() : null; });
if (before === null) throw new Error('no f1 tile on the POP screen');
await tap('.tile[data-key="f1"]');
await page.waitForSelector('.sheet .btn.primary');
await tap('.sheet .btn.primary');
await page.waitForSelector('.q-item', { timeout: 5000 });
const t1 = (await page.innerText('.q-item')).replace(/\s+/g, ' ');
if (!/\d:\d\d/.test(t1)) throw new Error('queue item shows no countdown: ' + JSON.stringify(t1));
await page.waitForFunction(() => !document.querySelector('.q-item'), null, { timeout: 45000 }); // the countdown reaches zero and the item leaves the queue
await page.waitForFunction((b) => { const t = document.querySelector('.tile[data-key="f1"]'); return t && t.innerText.trim() !== b; }, before, { timeout: 8000 });
return { before, after: await page.evaluate(() => document.querySelector('.tile[data-key="f1"]').innerText.trim()), queue: t1 };
}
// Cable the tapped map tile: tap near the middle of the canvas, expect a tile info sheet.
async function mapTap(page, touch) {
await page.evaluate(() => App.go('map'));
await page.waitForSelector('[data-screen="map"]:not([hidden]) .map-canvas');
await sleep(1200); // first chunk fetch + draw
const box = await page.locator('.map-canvas').boundingBox();
if (!box || box.width < 50 || box.height < 50) throw new Error('map canvas has no size: ' + JSON.stringify(box));
const x = box.x + box.width / 2 + 3, y = box.y + box.height / 2 + 5;
if (touch) await page.touchscreen.tap(x, y); else await page.mouse.click(x, y);
await page.waitForSelector('.sheet .sheet-title', { timeout: 4000 });
const title = (await page.innerText('.sheet .sheet-title')).trim();
if (!title) throw new Error('tile sheet has no title');
await page.keyboard.press('Escape');
await page.waitForSelector('.sheet', { state: 'detached', timeout: 3000 }).catch(() => {});
return title;
}
// Open a "More" screen (Rankings, Alerts, Settings, Trade, World) the way a player does: nav -> More -> row.
async function openFromMore(page, touch, id, label) {
const tap = tapper(page, touch);
await tap('#nav [data-screen="more"]');
await page.waitForSelector('.more-list .row-btn');
await page.locator('.more-list .row-btn', { hasText: label }).first().waitFor({ timeout: 3000 });
await tap('.more-list .row-btn:has-text("' + label + '")');
await page.waitForSelector('[data-screen="' + id + '"]:not([hidden])', { timeout: 5000 });
await sleep(500); // let its first fetch land (errors show up here)
}
async function navReachable(page, vw, vh) {
return page.evaluate(([w, h]) => {
const nav = document.getElementById('nav');
const nr = nav.getBoundingClientRect();
if (nr.width < 20 || nr.height < 20) return 'nav has no size';
if (nr.left < -1 || nr.top < -1 || nr.right > w + 1 || nr.bottom > h + 1) return 'nav outside the viewport: ' + JSON.stringify(nr);
const bad = [];
for (const b of nav.children) {
const r = b.getBoundingClientRect();
if (r.width < 30 || r.height < 30) { bad.push(b.dataset.screen + ' too small ' + Math.round(r.width) + 'x' + Math.round(r.height)); continue; }
const el = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2);
if (!el || !b.contains(el)) bad.push(b.dataset.screen + ' covered by ' + (el ? el.tagName + '.' + el.className : 'nothing'));
}
return bad.length ? bad.join('; ') : null;
}, [vw, vh]);
}
// The core player flow, used by desktop, phone portrait and phone landscape.
async function coreFlow(P, name, touch, signup) {
const { page } = P;
const tap = tapper(page, touch);
if (signup) {
await check(name + ': sign up through the form, land on the POP screen', async () => {
await signUpThroughUi(P, name.replace(/\W+/g, '') + Date.now() % 1e5, touch);
const title = (await page.innerText('.town-name')).trim();
if (!title) return 'empty POP name';
const tiles = await page.locator('.tile[data-key]').count();
if (tiles < 16) return 'expected >= 16 resource field tiles, got ' + tiles;
});
} else {
await page.goto(P.base + '/#/pop');
await page.waitForSelector('.town-name');
}
await check(name + ': build a field, countdown runs, level goes up', async () => {
const r = await buildFieldAndWait(page, touch);
if (r.before === r.after) return 'tile did not change';
});
await shot(page, name.replace(/\W+/g, '-') + '-pop');
await check(name + ': map opens, tapping a tile opens its sheet', async () => { await mapTap(page, touch); });
await shot(page, name.replace(/\W+/g, '-') + '-map');
for (const [id, label] of [['rankings', 'Rankings'], ['alerts', 'Alerts'], ['settings', 'Settings']]) {
await check(name + ': ' + label + ' screen opens from More', async () => { await openFromMore(page, touch, id, label); });
}
await check(name + ': bottom nav is reachable (inside viewport, nothing covers the buttons)', async () => {
const vp = page.viewportSize();
return (await navReachable(page, vp.width, vp.height)) || true;
});
await check(name + ': nav tab switches screens (POP <-> Map <-> Units)', async () => {
for (const id of ['pop', 'map', 'units', 'pop']) {
await tap('#nav [data-screen="' + id + '"]');
await page.waitForSelector('[data-screen="' + id + '"]:not([hidden])', { timeout: 4000 });
}
});
await check(name + ': no horizontal scroll on any screen visited', async () => {
for (const id of ['pop', 'map', 'rankings', 'alerts', 'settings']) {
await page.evaluate((s) => App.go(s), id);
await page.waitForSelector('[data-screen="' + id + '"]:not([hidden])');
await sleep(350);
const o = await L.overflowReport(page);
if (o) return id + ': ' + o;
}
});
await check(name + ': no console errors, warnings, page errors or failed requests', async () => noErrors(P));
}
// ---------------------------------------------------------------- suites
async function suiteDesktop(browser, S) {
group('1. desktop 1280x800');
const P = await L.newPage(browser, PROFILES.desktop);
P.base = S.base;
await coreFlow(P, 'desktop', false, true);
await P.ctx.close();
}
async function suitePhone(browser, S) {
group('2a. phone touch, portrait 390x844');
let P = await L.newPage(browser, PROFILES.phone);
P.base = S.base;
await coreFlow(P, 'phone portrait', true, true);
await P.ctx.close();
group('2b. phone touch, landscape 844x390');
const u = await S.signup('landscape' + Date.now() % 1e5);
P = await L.openSignedIn(browser, S, u, PROFILES.landscape);
P.base = S.base;
await check('landscape: touch is on', async () => (await P.page.evaluate(() => navigator.maxTouchPoints > 0)) || 'maxTouchPoints is 0');
await coreFlow(P, 'phone landscape', true, false);
await P.ctx.close();
}
async function suiteLayout(browser, S) {
group('3. layout matrix: pop / map / trade / world, no overflow, no console errors');
const viewports = [[360, 640, true], [390, 844, true], [844, 390, true], [768, 1024, false], [1280, 800, false]];
const u = await S.signup('layout' + Date.now() % 1e5);
for (const [w, h, touch] of viewports) {
const ctx = touch ? { viewport: { width: w, height: h }, hasTouch: true, isMobile: true, deviceScaleFactor: 2 } : { viewport: { width: w, height: h } };
const P = await L.openSignedIn(browser, S, u, ctx);
for (const id of ['pop', 'map', 'trade', 'world']) {
await check(w + 'x' + h + ' ' + id + ': renders, no horizontal overflow', async () => {
await P.page.evaluate((s) => App.go(s), id);
await P.page.waitForSelector('[data-screen="' + id + '"]:not([hidden])', { timeout: 5000 });
await sleep(id === 'map' ? 1200 : 600);
const visible = await P.page.evaluate((s) => { const el = document.querySelector('[data-screen="' + s + '"]'); const r = el.getBoundingClientRect(); return r.width > 50 && r.height > 50 && el.innerText.trim().length + el.querySelectorAll('canvas').length > 0; }, id);
if (!visible) return 'screen empty or zero size';
await shot(P.page, 'layout-' + w + 'x' + h + '-' + id);
return (await L.overflowReport(P.page)) || true;
});
}
await check(w + 'x' + h + ': nav reachable, no console errors', async () => {
const n = await navReachable(P.page, w, h);
if (n) return n;
return noErrors(P);
});
await P.ctx.close();
}
}
// Push needs a slow world (a raid must stay in flight for a while), so it gets its own server at speed 1.
async function suitePush(browser) {
group('4. push: incoming raid shows on the defender without a reload (WebSocket)');
const S = await L.bootServer({ speed: 1 });
try {
const alice = await S.signup('Alice'), bob = await S.signup('Bob');
const aT = S.db.get('SELECT * FROM towns WHERE id = ?', alice.townId);
L.placeTown(S, bob.townId, aT.x + 4, aT.y + 1);
S.db.run('UPDATE operators SET protection_until = 0');
L.setBuildings(S, alice.townId, { core_router: 10, ops_lab: 6, noc: 5, rack_hall: 6, battery_bank: 6 });
for (const k of ['f13', 'f14', 'f15', 'f16']) S.db.run('UPDATE buildings SET level = 8 WHERE town_id = ? AND key = ?', alice.townId, k);
S.db.run('UPDATE towns SET battery = 900, footprint = 100 WHERE id = ?', alice.townId);
L.giveUnits(S, alice.townId, { script_crew: 40 });
const P = await L.openSignedIn(browser, S, bob, PROFILES.desktop);
const { page } = P;
const hasBanner = () => page.evaluate(() => { const el = document.querySelector('.mil-banner'); return !!el && !el.hidden && el.innerText.trim().length > 0; });
await check('defender: WebSocket connects, no banner yet', async () => {
await page.waitForFunction(() => window.App && App.ws && App.ws.open, null, { timeout: 10000 });
if (await hasBanner()) return 'banner visible before any raid';
await page.evaluate(() => { window.__noReload = 'still-here'; });
});
let sentAt = 0;
await check('attacker launches a raid at the defender through the API', async () => {
sentAt = Date.now();
await S.api('/movements', 'POST', { fromTownId: alice.townId, type: 'raid', toTownId: bob.townId, units: { script_crew: 20 }, confirmEndProtection: true }, alice.token);
});
await check('defender: incoming banner appears by push (<= 6 s), same page, no reload', async () => {
await page.waitForFunction(() => { const el = document.querySelector('.mil-banner'); return !!el && !el.hidden && el.innerText.trim().length > 0; }, null, { timeout: 6000, polling: 100 });
const ms = Date.now() - sentAt;
const marker = await page.evaluate(() => window.__noReload);
if (marker !== 'still-here') return 'page was reloaded';
const mode = await page.evaluate(() => App.ws.open);
if (!mode) return 'socket not open when the banner showed: it came from polling, not push';
console.log(' (banner after ' + ms + ' ms)');
await shot(page, 'push-banner');
});
await check('defender: Moves nav badge shows the incoming raid', async () => {
await page.waitForFunction(() => { const b = document.querySelector('#nav [data-screen="movements"] .nav-badge'); return b && !b.hidden && b.textContent.trim() !== ''; }, null, { timeout: 3000 });
});
await check('raid arrives (accelerated): banner goes away and the report badge appears by push', async () => {
const mv = S.db.get("SELECT * FROM movements WHERE status = 'out' ORDER BY id DESC LIMIT 1");
if (!mv) throw new Error('no movement in flight');
const at = Date.now() + 2500;
S.db.run('UPDATE movements SET arrive_at = ? WHERE id = ?', at, mv.id);
S.db.run("UPDATE events SET due_at = ? WHERE status = 'pending' AND type = 'arrive' AND payload LIKE ?", at, '%"movementId":' + mv.id + '%');
S.srv.scheduler.arm();
await page.waitForFunction(() => App.mil && App.mil.reportsUnread > 0, null, { timeout: 12000, polling: 100 });
await page.waitForFunction(() => { const el = document.querySelector('.mil-banner'); return !el || el.hidden; }, null, { timeout: 4000 });
if ((await page.evaluate(() => window.__noReload)) !== 'still-here') return 'page was reloaded';
});
await check('defender page: no console errors', async () => noErrors(P));
await P.ctx.close();
} finally { await S.close(); }
}
// ---------------------------------------------------------------- main
(async () => {
const t0 = Date.now();
let S = null, browser = null;
const hardStop = setTimeout(() => { console.error('\nE2E TIMEOUT after 5 min'); process.exit(2); }, 5 * 60 * 1000); hardStop.unref();
try {
browser = await chromium.launch({ headless: !process.env.E2E_HEADED });
if (wanted('desktop') || wanted('phone') || wanted('layout')) S = await L.bootServer({ speed: 4000 });
if (wanted('desktop')) await suiteDesktop(browser, S);
if (wanted('phone')) await suitePhone(browser, S);
if (wanted('layout')) await suiteLayout(browser, S);
if (wanted('push')) await suitePush(browser);
} catch (e) {
L.record('harness: unexpected exception', false, e && e.stack || String(e));
} finally {
if (browser) await browser.close().catch(() => {});
if (S) await S.close().catch(() => {});
}
const failed = L.summary();
console.log('elapsed ' + Math.round((Date.now() - t0) / 1000) + ' s');
process.exit(failed ? 1 : 0);
})();