Phase 2: client military/social screens, WebSocket push, trade + endgame, review findings pending

Built: units/movements/reports/send/expansion screens, alliance/messages/rankings screens, ws client + server /ws push
(docs/PROTOCOL.md), Internet exchange trade, backbone endgame + world end, shared reports, buildDone relative levels.
Tested: npm test 175/175. Two adversarial reviews found issues (trade-leg recall exploit, __proto__ via validate.js,
rankings DoS, static headers, ...): fixes follow in the next commit.
NOT done: bots/balance, e2e suite, real-device checks.

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 19:05:03 +02:00
parent 249818a7aa
commit b18645dca1
87 changed files with 10201 additions and 71 deletions

View file

@ -118,3 +118,56 @@ firewall, loot, siege, takeover/loyalty), `scan` (attacker; intel when it succee
if the defender's scanners won), `incumbent`, `settle`, `reinforce`, `movement_failed`.
Later stages append their routes here and to the route table.
## Trade, end game, shared reports (stage 5 rest, stage 7 start)
**Internet exchange trade.** Offers "give X of A for Y of B within Z tiles". Amounts are whole numbers, each side 1..500 (one transport
link), the two amounts differ by at most 1:2, the resources differ; `maxDistance` 1..300. Lists are newest first, `after` = id of the last
offer you have (older ones follow). `status`: `open`, `accepted`, `completed`, `cancelled`, `expired`, `void`.
| Route | Purpose |
| ----- | ------- |
| `POST /trade/offers {townId, giveRes, giveAmount, wantRes, wantAmount, maxDistance}` | post (201). The offered amount leaves the POP (escrow) and one transport link is held in reserve. `trade_ratio`, `capacity_exceeded`, `no_transport_link` (no exchange, or all links busy/reserved), `not_enough_resources` |
| `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) |
| `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
was taken over). Delivery notifications are the existing `transport_arrived` / `transport_delivered`. Direct transports (own POPs, any
player) stay `POST /movements` with `type: "transport"`.
**World status and the end game.** The backbone sites open at world day 100 (real days x speed).
| Route | Purpose |
| ----- | ------- |
| `GET /worlds/:id/status` | `phase` (`running`, `backbone_open`, `ended`), `ageDays`, `opensAt`, the 7 `sites` (empty before opening: `id` (null until first touched), `index`, `x`, `y`, `holder` `{allianceId, tag, name}` or null = incumbent, `takenBy`, `level`/`maxLevel`/`progress`, `pool` (stockpile), `build` `{toLevel, startedAt, dueAt}`, `next` `{toLevel, cost, durationMs}`), `winner`, `endsAt` (set once somebody won), `endedAt` |
| `GET /worlds/:id/results` | the final snapshot once ended (`available: false` before): `winner`, `results.{operators, alliances, attackers, defenders, sites, totals}` (top 100 each, ranked) |
| `GET /backbone/:id` | one site; holders also get `contributions` (who shipped what) and `you` `{holder, canBuild, canShip, canAttack}` |
| `POST /backbone/:id/ship {fromTownId, cargo}` | send resources to a site your alliance holds (201, a transport: same links and capacity); arrives into the stockpile, or rides home if the site changed hands |
| `POST /backbone/:id/build` | start the next node level (201), paid from the stockpile at once, one level at a time, any holder with `backboneBuild`; `max_level`, `already_queued`, `not_enough_resources`, `forbidden` (not a holder), `backbone_closed` |
Taking a site is `POST /movements` with `type: "scan"` or `"attack"` and the site's `x, y` (no `toTownId`): needs an alliance, not against
the own alliance or a NAP/confederation partner (`invalid_target`, `details.reason`: `no_alliance`, `own_site`, `pact`,
`landing_scan_or_attack_only`); before opening `backbone_closed`. Settling a landing tile is `invalid_target` (`backbone_site`), also before
it opens. Defence is static: `incumbentDefence x 12 x (1 + 0.03 x node level)`; a scan report shows it. Reports: scans as `scan` (with
`site.type: "backbone"`), attacks as the new type `landing` (outcome, attack/defence, `taken`; recipients: the attacker and every member of the
previous holder). `GET /map` lists open sites in `specials` as `type: "backbone"` with `site: {id, index, holder, level, maxLevel}`;
`GET /map/tile` returns `type: "backbone"` and `backbone: {siteId, holder, level, pool, build, mine, canAttack}`.
Notifications: `backbone_open` (first touch), `backbone_taken` / `backbone_lost` (alliance members), `backbone_level` (every 10th level and the
last, holder members), `backbone_delivered` / `backbone_ship_bounced` (sender), `backbone_won` (everybody), `world_ended` (everybody).
**An ended world** answers every game command with `409 world_ended` (build, send, train, trade, alliances, diplomacy, backbone, report
sharing, ...). Still allowed: `GET` everything (map, reports, rankings, towns, status, results), `POST /reports/read-all`, `POST
/reports/:id/read`, messages (send, read, delete, block).
**Shared report folder.** `POST /reports/:id/share` puts one of YOUR reports into your alliance's folder (needs `shareReport`; the report
is kept 14 days from the share), `DELETE /reports/:id/share` takes it out (the sharer, or `unshareReport`: leader, officer), `GET
/alliances/:id/reports?after&limit` lists the folder newest first (cursor: id of the last report seen), `GET /alliances/:id/reports/:reportId`
reads one with its full data. Members with `viewSharedReports` only; `GET /alliances/mine` permissions list the new keys.
**Allied incoming.** `GET /movements` has a new `alliedIncoming` list: movements heading for POPs of your alliance mates and of
confederated alliances, same shape as `incoming` (type `unknown`, origin and ETA only) plus `ally: true` and `toOperator`. Friendly traffic
(from partners of the target) is left out.

View file

@ -128,3 +128,85 @@ nothing is spent. New POPs start with every field at level 0, no infrastructure,
## S3-9 — Moving units between your own POPs
`reinforce` to an own POP puts the units into `town_units` of the target (they live there now). Only units of OTHER operators are
`stationed` rows.
## S6-1 — Push hints leave only after the commit, through an outbox
`scheduler.notify` runs inside the transaction of the event or command, so pushing there would announce changes that may still roll
back. `notify` queues into `scheduler.outbox` (only when a listener is set); `process()` and `commands.run` flush it after COMMIT
(`db.depth === 0`) and truncate it to their mark on rollback. `town` hints use the existing `scheduler.onEvent` (post-commit already)
and a new `commands.hooks.onCommand`. `push.js` itself knows no game rules (it gets `townOwner` / `tokenValid` injected), the routing
lives in `pushHooks.js`. No new dependency (`ws` was already listed).
## S6-2 — Revocation is polled, not pushed
Tokens are revoked by plain SQL in routes and the admin tool. Instead of hooking each place, the ping tick (30 s) re-checks
`tokens.revoked_at` and `users.banned` for every authenticated socket and closes with 4401. Worst case 30 s of hints after logout on
another device; hints carry no data, so nothing leaks. If that is ever not good enough, call a `push.disconnectToken(id)` from the routes.
## S6-3 — Hints are merged per tick, `town` is not sent to the target at launch
Identical JSON hints produced in one tick (a catch-up) are deduplicated per socket via `setImmediate`. A launched movement tells the
target's owner `incoming` (town + ETA) and no plain `town` hint, so the type and origin of a launch cannot be inferred from extra traffic.
## E1 — A landing site is a row of its own, not a POP
`landing_sites(world_id, idx, x, y, holder_alliance_id, holder_operator_id, level, stockpile, build_*)` (migration 004), positions from
`rules.backboneSites(seed, radius)`. A town row of kind `landing` owned by the leader was considered and rejected: a "POP" that nobody plays
would have to be excluded from footprint rankings, the last-POP / capital / footprint-gate counts, `homeTownFor`, `/me`, spawn spacing and
the Rack hall cap (shipped resources would be thrown away at 250), and a leader change would have to re-own it. The holder is the
alliance (`holder_alliance_id`, FK `ON DELETE SET NULL`, the disband hook also clears it), `holder_operator_id` only records who took it.
Consequence, on purpose and to be revisited after the first world: **no units can stand at a site**, so there is no garrison and no
reinforcement. A site is defended by the static value `incumbentDefence x 12 x (1 + 0.03 x level)` only, i.e. exactly the "incumbent
with a backbone multiplier" of DESIGN.md; holders defend by growing the node (higher level = harder to take), attackers can scan the exact
number. Hooks into the military code are small: `combat.arriveSite` hands `backbone` tiles to `military/landing.js`,
`arrivals.arriveTransport` hands shipments (`extra.siteId`) to `endgame.deliverShipment`, `sendMovement` calls `endgame.checkLandingTarget`.
## E2 — Site rows are created lazily, there is no timer event
`ensureSites` creates the 7 rows when something first touches a site (an attack/scan sent or arriving, a shipment, a build) once the world is
at day 100 / speed; that first call also writes a `backbone_open` notification for every operator. Reads (`/worlds/:id/status`, `/map`, tile
info) never write: untouched sites are shown as the incumbent's, level 0, `id: null`. A `backboneOpen` event at world creation was
dropped: a pending event 100 days ahead sits in every quiet world and breaks tooling that counts pending events (the admin CLI test).
Cost: nobody is pushed the moment the sites appear unless a first touch happens; clients see `phase: backbone_open` when they poll status.
## E3 — The winner is fixed at level 100; the world is frozen when it ends
The holder of a node whose level completes at 100 wins (`worlds.winner_*`, once per world) and `worldEnd` is scheduled
`graceDays x 24 h / speed` later. Losing the node meanwhile does not change the winner (the race is over; the grace days are for the ranking
and the post-game). If a level-100 node is taken while nobody holds it (the holder disbanded mid-build) the new holder wins. `worldEnd`
writes the ranking snapshot, sets `status = 'ended'`, closes open trade offers (`expired`, escrow back in its POP: every unit stays accounted
for) and CANCELS every other pending event of the world: nothing arrives, trains,
expires or builds after the snapshot, so the stored ranking stays the truth. Movements still `out` and queued builds stay as they were.
A running build of a site continues for whoever holds the site when it lands (the level belongs to the site; the cost was paid from the
stockpile at the start); the stockpile and the ledger stay with the site when it is taken.
## E4 — `world_ended` is one gate in `commands.run`, found by probing the arguments
`ownedTown`, `operatorOf` and `requireRole` are shared with reads (rankings, map), so gating there would break "readable after the end".
`commands.run` calls `endgame.guard(db, name, args)`: the world is `args.worldId`, else the world of `townId/fromTownId/hostTownId`,
`allianceId`, `movementId`, `inviteId`, `proposalId`, `offerId`, `siteId`, `reportId`, else the caller's oldest operator (the default every
command already uses). Allowed after the end: `markReportRead`, `messageSend/Read/Delete`, `messageBlock/Unblock`. New commands are gated
automatically as long as they carry one of those arguments.
## E5 — Backbone cost curve is not the building curve
`4000 x 1.28^99` is unreachable; the node has its own `ENDGAME.costGrowth = 1.045` and `timeGrowth = 1.025` (about 7.2 M of each resource and
about 36 world days of building in total, level 100 alone 312 k each and 23 h). Pure guesses until a bot run (stage 7) says how much an
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`).
- 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.
- `transportArrived` hook: `server/trade.js` registers itself when required (both `commands/index.js` and `events/index.js` load it), so the
consumer exists in every test fixture that builds commands or events.
- Offer expiry: one `tradeExpire` event per offer, cancelled on accept/cancel/void, idempotent (acts only while `open`).
## T2 — Shared reports extend the report's life
Sharing sets `expires_at = max(expires_at, now + 14 days)` on the single shared `reports` row, so the folder is not emptied by a report that
was nearly due; the cascade `report_shares.report_id ... ON DELETE CASCADE` removes the share when the report is cleaned up.
## G1 — `buildDone` adds one level to what the building is NOW
Each build event adds exactly one level to the current level (never lowers, never above the queued `toLevel`), so an upgrade in flight
cannot undo exploit-kit damage; a building knocked to 0 comes back at 1. The notification reports the real level.
## G2 — Allied incoming is a separate list
`GET /movements` keeps `incoming` as "heading for YOUR POPs" and adds `alliedIncoming` for partners' POPs (own alliance + confederations),
each entry with `ally: true` and `toOperator`. Mixing them would make clients count allies' attacks as their own.

View file

@ -148,6 +148,12 @@ A new POP starts at level 0 everything and 1 h of resources. Takeover requires t
- Diplomacy states between alliances: war, neutral, non-aggression pact, confederation (can reinforce each other,
see each other's incoming). Pacts take 24 h to cancel.
- Messages: player-to-player and alliance broadcast, plain text, 2000 chars, basic rate limit.
- **Shared report folder (server):** a member puts one of their own reports (any type) into the alliance's folder (`shareReport`); every
member reads it (`viewSharedReports`), the sharer or leader/officer (`unshareReport`) takes it out. Sharing pushes the report's expiry
out to 14 days from the share (it is one row for everybody) and it goes with the report or the alliance.
- **Seeing each other's incoming (server):** members of one alliance and of confederated alliances get `alliedIncoming` in `GET /movements`:
movements heading for a partner's POP, origin and ETA only (type, units and cargo hidden), except traffic from operators who are partners
of the target themselves (friendly).
## Trade
@ -155,6 +161,22 @@ The Internet exchange lists offers "give X of A for Y of B, max distance Z". Rat
pump-feeding. Accepting an offer spawns two transport movements. Direct transports to own POPs or to any player
(e.g. alliance support) use the same links. Transport links: level of the exchange, capacity 500 each.
**Clarified (what the server does).**
- An offer is "give `giveAmount` of `giveRes` for `wantAmount` of `wantRes`, within `maxDistance` tiles", posted from one POP that has
an Internet exchange. Each side must fit ONE transport link (1..500) 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.
- **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
<= links); accepting converts the reservation into the real transport. Direct transports see the reservation as a busy link.
- **Accepting** (one transaction): the acceptor's payment leaves their POP as a transport to the poster's POP (needs a free link and the
resources there), the escrow leaves the poster's POP as a transport to the acceptor's POP; both arrive after `distance / 12 tiles/h /
world speed`. The offer is `accepted`, then `completed` when both have been delivered. A delivery above the receiver's Rack hall cap
loses the overflow and says so (the existing transport rule). If the poster's POP is taken over while the offer is open, the offer
ends (`void`) and the escrow stays in the POP.
## Incumbent (NPC)
The legacy telco. Holds incumbent sites spread over the map with large static defences that scale with world age.
@ -169,6 +191,33 @@ far more than anything else and requiring resources shipped in from members (tra
wins and the world ends two days later with a final ranking. Backbone nodes can be attacked and taken; the level
stays with the site. Landing sites cannot be settled, only taken.
**Clarified (what the server does).** World age is in world days (real days x speed). All numbers below are first guesses, no bot run.
- **Sites:** `rules.backboneSites(seed, radius)`: 7 fixed positions, one per sector of the circle (jittered), on plain land between 35% and
80% of the map radius, at least 6 tiles apart, never in the free centre. They exist from the start (spawning and settling refuse them),
the tile reads `backbone` from day 100 / speed (`rules.tileAt(seed, radius, x, y, ageDays)`; without the age argument terrain is unchanged).
- **A site is not a POP** (DECISIONS E1): it has a holder alliance, a Backbone node level, a stockpile of Fiber/Hardware/Capital and at most
one level in progress. No units can stand there, so a site is defended by a static value only:
`defence = incumbentDefence(seed, x, y, age) x 12 x (1 + 0.03 x node level)`. At day 100 that is about 40 000 with no node, 160 000 at
level 100 (a Script crew attacks with 40).
- **Taking:** `scan` and `attack` only (no raid: the stockpile would be lootable; no takeover, no reinforce, no settle). The attacker must be in
an alliance, and may not be in the holder's alliance or in a NAP / confederation with it (checked when sent and again on arrival, units come
home otherwise). A full attack with attack > defence wins: the attacker's alliance holds the site. No loot, the site loses nothing, the
survivors drive home. Level, stockpile and a running build stay with the site. A holder that disbands leaves the site to the incumbent
(level kept).
- **Feeding the node:** members of the holder alliance send resources by transport (`POST /backbone/:id/ship`, same links, 500 per link, 12
tiles/h). On arrival they join the stockpile if the sender's alliance still holds the site, otherwise they ride home. A ledger records
who sent what.
- **Building:** level L (1..100) costs `4000 x 1.045^(L-1)` of each resource (level 100: 312 301; about 7.2 million of each in total) and
takes `2 h x 1.025^(L-1) / world speed` (level 100: 23 h; about 36 days of world time in total, one level at a time). The cost is paid from
the stockpile when the level starts; any holder with `backboneBuild` may start it.
- **Winning:** when a level completes and the node is at level 100, the holder at that moment wins (once per world) and the world ends two world
days later (`worlds.end_at`). The winner is final: losing the node during those two days does not change it. If a finished node is taken while
nobody held it, the new holder wins.
- **Ending:** the `worldEnd` event stores a ranking snapshot (operators by footprint, alliances by the sum, top attackers and defenders by
battle points, winner, the sites), sets the status `ended`, and cancels everything still pending in that world. An ended world refuses
every game command with `world_ended`; reading (map, reports, rankings, town views, status, results) and chatting (messages, marking reports
read) keep working.
Rankings throughout: operators by footprint, alliances by sum, attackers/defenders by points from battles.
## Fairness and anti-frustration

View file

@ -17,11 +17,10 @@ Tests: `test/social-*.test.js` (pure rules, alliances, diplomacy with the fake c
response in them is checked against its declared schema (`createTestServer({ contract: true })` in `test/helpers.js`).
Not done:
- Marketplace / Internet exchange and resource transport (waits for the movement system of stage 3).
- Shared report folder of the alliance (needs reports from stage 3), confederation effects (reinforce, see incoming) and the pact
effect "no attacks inside a NAP/confederation": the military stage must call `alliances.pactPartners` / `confederated`; nothing
enforces it yet.
- No web client, no WebSocket push (notifications rows are written; stage 6 pushes them).
- Marketplace / Internet exchange: DONE on the server, see "Trade, end game, gaps" below.
- Shared report folder and "see each other's incoming": DONE on the server (below). The pact effect "no attacks inside a NAP/confederation"
is enforced by the military stage (`pactBlocks`).
- No web client; WebSocket push (stage 6) now exists server-side, see "Stage 6" below.
- 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.
@ -43,11 +42,9 @@ recall, research, reports/cursor/retention, API smoke over HTTP). Fake clock, in
Not done / not claimed:
- **Nothing is balanced.** All unit stats, costs, research curves, incumbent defence and the 50-unit-scale combat numbers are first guesses;
there was no bot run (`tools/bot.js` does not exist yet). Do not cite any of them as tuned.
- Training cannot be cancelled; reports cannot be shared to the alliance yet (the shared report folder needs a table in the social stage);
confederates do not see each other's incoming movements (only reinforce is wired); no sitter, no night protection.
- A building damaged by exploit kits that has an upgrade in flight jumps to the queued level when that finishes (`buildDone` sets absolute levels).
- Training cannot be cancelled; no sitter, no night protection. (Report sharing and allied incoming: done, see below.)
- Units in transit draw no power from anyone; an operator cannot choose a new capital POP (no command); a captured POP keeps its footprint.
- Backbone landing sites and the Backbone node (end game) are not part of this stage.
- Backbone landing sites and the Backbone node: see "Trade, end game, gaps" below.
## Client (stages 1-2 web client)
Built: `public/` vanilla JS, no build step, strict-CSP friendly (no inline scripts or handlers, no external requests).
@ -66,5 +63,128 @@ Built: `public/` vanilla JS, no build step, strict-CSP friendly (no inline scrip
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.
## 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
errors; received invites accept/decline; overview with size, pinned notes add/remove, leave/disband; members with role, POPs,
footprint, last online, a member sheet for message / role / transfer / kick; invite by name, pending invites with cancel; diplomacy
with relations, proposals in/out, "new move" via directory search with only the moves `rules.diplomacyMove` allows, pact-cancel
and proposal countdowns, take-back), `screens/messages.js` (inbox with unread filter / mark all read, sent, alliance feed with
broadcast composer, per-operator thread with older-page cursor, compose by name, 2000 char counter, delete own copy, block list and
block/unblock, 429 shown as a countdown with the text kept, unread count on the nav via `App.setBadge`, polled every 60 s),
`screens/rankings.js` (operators, alliances, battles attack/defense/total, your row highlighted plus the server's `you` card, rank-offset
"load more"). Shared bits: `screens/social-ui.js` (`window.SocUI`: composer, confirm sheet, alliance profile sheet, error mapping),
`js/social.js` (pure logic: what to show per role via `rules.allianceCan/outranks`, diplomacy options, counters, cursor merges),
`js/strings/social.js` (en + nb), new sprite icons users / mail / trophy / back, `.soc-` CSS. All player text goes in with
`textContent` (a test fails on any `innerHTML` in these files).
Tests: `test/client-social.test.js` (pure logic, string coverage of every static key the screens use, error codes, no HTML sinks).
Looked at with headless Chromium (phone portrait/landscape, desktop) against the real server in-process, plus a scripted flow on
a phone profile (markup in a message stays text, counter/over-limit, 429 countdown, unknown recipient, leader vs member views, diplomacy
move sheet, name-taken error, nb). Not run: real devices, Safari, Playwright suite, a long-list scroll test (>100 ranks), accepting an
invite when the alliance is full, alliances at the size cap.
Gaps: alliance rename/description and note editing have no UI (server has edit-note); no operator profile page; blocking needs an existing
conversation or message (the API takes an operator id and there is no name lookup); no live refresh (push is not wired, screens refetch
on open and on manual refresh); the alliance screen does not auto-refresh countdowns' targets after they pass; `App.state.operator.alliance`
is refreshed from `/me` after alliance changes but is stale if you are kicked while away until the screen is opened.
## Client: military, expansion, WebSocket
Built (`public/`, same rules as before: no innerHTML for player text, no inline handlers):
- **Nav overflow** (`main.js`): 5 slots; `registerScreen({ navGroup: 'main' | 'more' })`, with any `more` screen the 5th slot is a
"More" sheet; `App.setBadge(screenId, n, 'alert'|'info')` (More sums its screens, red if any is an alert). Bar now: POP, Map, Units,
Moves, More (Reports, Alerts, Settings, the social screens). `App.alertKinds[type]` lets a screen describe its own notification types in
the Alerts feed; `App.popSections` lets screens add cards to the POP screen (incoming banner, expansion card).
- **Shared state** (`milstate.js`): `App.mil.moves` (last `GET /movements`: outgoing, incoming, alliedIncoming) is the one source for the
nav badge, POP banner, movements screen and map lines; `App.refreshMovements/refreshReportsUnread/refreshTowns` (the last refetches `/me`
without the destructive `setSession`, used after a settle/takeover); `[data-cd]` countdown elements driven by one ticker; refetch when
anything on the wire is overdue.
- **Units** (`screens/units.js`): home units with research-adjusted stats, reinforcements here (send home) and your units elsewhere (call
back), training queue with countdowns + train sheet (`rules.trainPlan` preview, max-affordable, queue-full), research list + sheet
(`rules.researchPlan`, lab level / cost / time / reason), offline warning with the decommission countdown.
- **Movements** (`screens/movements.js`): incoming list on top in red (origin + ETA only, as the API gives it), your outgoing legs with
progress and a Recall button for the first 90 s, allied incoming; the POP screen gets a pulsing banner, the nav button a red badge.
- **Send dialog** (`screens/send.js`, `App.openSend({x,y,fromTownId,type})`, from the map tile sheet, Units, Movements): `GET /map/tile`,
types filtered by `milcore.moveOptions` (greyed ones say why), unit pickers (slider + stepper + all), cargo for transport, settle with
the wild-slot choice, latency/ETA/carry preview from `rules.movementMs`, `confirmEndProtection` checkbox, exploit-kit target, an
idempotency intent per opened dialog, server errors shown inline (`invalid_target` reasons translated).
- **Reports** (`screens/reports.js`, in More): cursor-paginated list, unread highlight + badge, mark read on open, mark all read, detail
layouts for raid/attack/takeover (role-aware victory/defeat, units sent/lost/left per group, strength, loot, siege, takeover loyalty),
scan (+ incumbent intel), scan_detected, incumbent, settle (opens the new POP), reinforce, movement_failed; coordinates jump to the map.
- **Expansion** (`screens/expand.js`, `send.js`, `main.js`, `render.js`): POP switcher in the resource bar, expansion card on the POP screen
(crews at home, footprint gate, POP list), settle through the send dialog; map draws your/incoming/allied movement lines with markers,
a red ring on your POPs that something is heading for, and a Send button in the tile sheet.
- **WebSocket** (`ws.js`): `createSocketClient` (injectable WebSocket and timers) + browser wiring. Auth as first message, ping every 25 s with
an 8 s pong timeout, jittered backoff 1 s .. 60 s, PROTOCOL close codes (4401/4400/1009 stop, 4429 waits 30 s), refetch after every
re-`ready`. Pushes go to `api.emit('push')` and refetch the affected thing; slow REST poll (45 s with the socket down, 3 min with it up).
- Tests: `test/client-mil.test.js` (type filter, unit roles, previews, perspective, backoff), `test/client-ws.test.js` (auth, ping/pong, backoff,
close codes, no token, throwing constructor); `client-i18n` parity covers `strings/military.js`.
- Looked at: headless Chromium (phone portrait/landscape, desktop; en and nb on the phone) against the real server in-process with a real
clock, seeded units/movements/reports, plus scripted flows on a phone profile: real WebSocket `open`, an `incoming` push from another
operator adding a row and a toast without polling, recall, raid/attack/transport/settle sends through the dialog (protection checkbox
gates the button, exploit-kit target reaches the server), train, withdraw, offline warning, report details of every type, POP list after
a settle resolved (`refreshTowns`).
Not done / not claimed:
- Not run: real devices or Safari, throttled networks, a socket behind nginx Proxy Manager, long sessions, the Playwright suite. The settle and
takeover resolution was exercised by fast-forwarding movement times in the DB, not by waiting.
- Takeover and capture flows (town_lost/town_gained pushes, losing the current POP) and the confederation `alliedIncoming` view have no
browser run. The Hostile takeover button stays enabled on a capital / last POP (the client cannot know); the server's refusal is shown.
- Withdraw and "call back" are one-tap with no confirmation. No unit icons (role icons only), no battle simulator / odds preview, no
cancel of training (the server has none), no sound or system notifications, no reports search/filter.
- The exploit-kit target picker only offers infrastructure types (the server also takes field slots f1..f18). Report group labels for
reinforcements show `#<townId>` because the report carries no names.
- Close 4401 stops the socket but does not itself send the player to login: that happens on the next REST 401 (`api` `unauthorized`).
- `ready.serverTime` is not used for the clock offset (no round-trip estimate on the socket); REST responses keep doing that.
## Stage 6 (server half): WebSocket push
Built: `/ws` on the game's HTTP server (`server/push.js` transport, `server/pushHooks.js` routing), contract in `docs/PROTOCOL.md`.
Auth as first message (`ready` / close 4401), Origin check (`net.originAllowed`), per-IP cap `MAX_CONN_PER_IP` (HTTP 429), 1 KB frames,
10 s auth timeout (4408), per-socket token bucket (4429), bad-message budget (4400), ping/pong keepalive that terminates dead sockets and
re-checks the token on every tick (revoked/banned: 4401), graceful 1001 close inside `srv.close()`. Hints: `town`, `incoming`,
`notification`, `report`, `message`, `pong`. Every `notifications` row (via `scheduler.notify` -> post-commit outbox -> `onNotify`) pushes a
`notification` hint, plus the typed ones; finished events and committed commands push `town` to the owners of the POPs they touched.
Hints go out only after the transaction that caused them committed (a rolled-back event or command pushes nothing); identical hints of
one tick are merged. Small edits outside the new files: `scheduler.js` (outbox, `notify` returns the row id), `commands/index.js`
(`hooks.onCommand`, outbox flush/rollback), `index.js` (upgrade + shutdown).
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).
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.
- No load test (many sockets, large catch-ups), no test behind a real nginx Proxy Manager (upgrade headers, idle timeouts, `X-Forwarded-For`
for the per-IP cap); only the code paths of `net.clientIp` are reused. The proxy's idle timeout (NPM default 60 s) is above nothing we
send: the 30 s ping keeps sockets alive, but that is reasoning, not a measurement.
- Hint gaps: owners of reinforcements standing in an attacked POP get `report` but no `town` hint for their home POP; no `incoming` for
confederates; no APNs/FCM sender (the `notifications` table plus `scheduler.onNotify` is where it would attach); no resume after a gap.
- The ws tuning knobs (`wsPingMs`, `wsRate`, ...) are `createServer` options only, not environment variables.
## Trade, end game, gaps (server only; migration `004_trade_endgame.sql`)
Built and tested (`test/trade-*.test.js`, `test/endgame-*.test.js`; fake clock, in-memory db, port 0; contract-checked responses over HTTP):
- **Trade:** offers "give X of A for Y of B within Z tiles" with escrow, a link reserved per open offer, 1:2 ratio band, expiry event,
cancel, accept = two transports in one transaction (all or nothing), the `transportArrived` consumer completes the offer, void when the
POP is taken over. Conservation is asserted (every unit in POPs + escrow + on the road, before and after; the only loss is the existing
Rack hall overflow, asserted too). Routes under `/trade/offers`.
- **End game:** 7 seed-derived landing sites (`rules.backboneSites`, `tileAt` with the world age; spawn and settle refuse them from day 0),
open at world day 100 / speed, taken with scan/attack against a static heavy defence, node level 1..100 built from a stockpile fed by
transports (`/backbone/:id/ship`, `/build`), winner at level 100, `worldEnd` two world days later with a stored ranking snapshot and a frozen
world, `world_ended` for every game command, `GET /worlds/:id/status` and `/results`. One end-to-end test runs day 100 -> take -> ship ->
build -> win -> ended on a speed-2 world; the ended-world gate is also driven over HTTP.
- **Gaps closed:** shared report folder (`report_shares`, `/reports/:id/share`, `/alliances/:id/reports`), `alliedIncoming` in `GET /movements`,
`buildDone` is relative to the building's current level (test written first, failed before the fix).
Not done / not claimed:
- **Nothing here is balanced.** Defence multiplier 12 (+3% per level), node cost 4000 x 1.045^(L-1) (about 7.2 M of each resource in total),
node time 2 h x 1.025^(L-1) (about 36 world days), 48 h offer ttl, 10 tiles of reach per exchange level, 500-per-side offers: first guesses,
no bot run (`tools/bot.js` still does not exist). Whether an alliance can actually ship 7 M of everything in time is unknown.
- **No garrison at landing sites** (E1): defence is static, holders cannot station units. If the first world shows the race is decided by who
hits first, the next step is a small `site_units` table with reinforce-to-site and defenders in `landing.js`.
- 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.
- The ranking snapshot is the same numbers as `/rankings`, computed once; `/rankings/*` after the end still compute live from the frozen state.
- Client: nothing in `public/` was touched. New notification types (`trade_*`, `backbone_*`, `world_ended`), the `landing` report type, the
`backbone` map special / tile, `world_ended` and the new error codes (`trade_ratio`, `offer_closed`, `own_offer`, `trade_out_of_range`,
`world_ended`, `backbone_closed`) need strings and screens.
## Not done
- Everything else. See CLAUDE.md "Working in stages".

146
docs/PROTOCOL.md Normal file
View file

@ -0,0 +1,146 @@
# PROTOCOL: WebSocket push
Endpoint `/ws` on the same HTTP server and port as the REST API (`ws://host:port/ws`, `wss://` behind the proxy).
Implementation: `server/push.js` (sockets), `server/pushHooks.js` (who gets which hint). Tests: `test/push-ws.test.js`,
`test/push-game.test.js`.
**Push is a hint, never state.** A message says "something changed, go and look" and carries ids and times only. The client
refetches over REST (`GET /towns/:id`, `/movements`, `/reports`, `/notifications` ...). The game is fully playable with the socket
disconnected, lost hints are harmless, and nothing a hint says may be trusted without the REST read. Hints are sent only after
the database transaction that caused them committed.
All messages are JSON text frames, one object per frame with a string `type`. Times are integer ms since the epoch (UTC),
server clock.
## Connecting
1. Open `/ws`. The upgrade is refused with plain HTTP status (the client sees a failed handshake, not a close code):
| HTTP | Why |
| ---- | --- |
| 403 | `Origin` header present and not allowed: same host as `Host`, or listed in `ALLOWED_ORIGINS` (same rule as `net.originAllowed`). No `Origin` (non-browser clients) is fine. |
| 404 | any path other than `/ws` |
| 429 | already `MAX_CONN_PER_IP` (default 40, `0` = off) open sockets from this client address (`net.clientIp`, proxy aware). Counts sockets that have not authenticated yet. |
| 503 | server is shutting down |
| 426 | not from us: nginx Proxy Manager with **Websockets Support** off, see `docs/DEPLOY.md` |
2. Send the first message within **10 s**. It must be exactly this, **never put the token in the URL** (proxy logs):
```json
{"type":"auth","token":"<bearer token from /auth/login or /auth/signup>"}
```
3. The server answers `{"type":"ready","serverTime":1767225600000}`. Only after `ready` do hints flow.
Anything else as first message, an invalid, revoked or banned token, or no message in time closes the socket (below).
One socket per device is enough; a user may have several (phone + desktop), each gets every hint.
## Server to client
| Message | Meaning | Client reaction |
| ------- | ------- | --------------- |
| `{"type":"ready","serverTime":n}` | authenticated | use `serverTime` to refresh the clock offset |
| `{"type":"pong","serverTime":n}` | answer to `ping` | same |
| `{"type":"town","townId":n}` | POP `n` (yours) changed: build/train/research done, resources spent, units arrived, returned or died, attacked, ownership changed, a command from another device | refetch `GET /towns/:id` (if on screen) |
| `{"type":"incoming","townId":n,"arriveAt":n}` | a movement from another operator was launched at your POP `townId`, arrives at `arriveAt`. Type and origin hidden on purpose (could be a scan, a raid, reinforcements or a transport). | show a warning with a countdown, refetch `GET /movements` for the details the API allows |
| `{"type":"notification","id":n,"kind":"..."}` | a row was added to your notifications. `kind` is `notifications.type`: `build_done`, `train_done`, `research_done`, `incoming`, `report`, `message`, `alliance_message`, `alliance_invite`, `town_lost`, `town_gained`, `transport_arrived`, `movement_returned`, `units_offline`, ... (the list grows, treat unknown kinds as generic) | bump the unread badge, `GET /notifications` |
| `{"type":"report","id":n}` | a battle or scan report with id `n` is ready for you | `GET /reports/:id` or refresh the list |
| `{"type":"message","id":n}` | a direct or alliance message with id `n` arrived for you (not sent to its sender) | refresh the inbox |
`incoming`, `report` and `message` always come together with the matching `notification` hint (same event, two messages).
The generic `notification` hint is the one to build the badge on; the typed ones let the client skip a round trip.
Guarantees and non-guarantees:
* Hints are best effort: after a reconnect, refetch what is on screen (and `/notifications`, `/movements`); do not assume nothing
was missed.
* Identical hints produced in the same tick are merged (a 50 event catch-up gives one `town` hint per POP), order is otherwise
preserved per socket.
* A command's own `town` hint is also sent to the device that issued it (ignore your own echo if you already refetch).
* Reads (`GET`) never push. A hint is not sent for a refused or rolled-back command.
* At launch of a movement the target's owner gets `incoming`, not a plain `town` hint; `town` for that POP follows when it
arrives.
## Client to server
| Message | Answer |
| ------- | ------ |
| `{"type":"auth","token":"..."}` | only as the first message (see above); a second one counts as a bad message |
| `{"type":"ping"}` | `{"type":"pong","serverTime":n}` |
Anything else (unknown `type`, invalid JSON, not an object, binary frame) is a **bad message**: ignored, counted. The 5th bad
message on a socket closes it with 4400. Before authentication any non-auth first message is fatal (4401).
Keepalive: the server sends a protocol ping every 30 s and terminates a socket that did not answer (or send anything) by the next
tick. Browsers answer protocol pings automatically. The `{"type":"ping"}` message is for clients that want a clock sample or a
liveness probe of their own; it is not required.
## Limits
| Limit | Value | On exceeding |
| ----- | ----- | ------------ |
| Client message size | 1024 bytes | close 1009 |
| Time to send `auth` | 10 s | close 4408 |
| Messages per socket | 5 per second sustained, burst 15 (`net.TokenBucket`; authentication counts) | close 4429 |
| Bad messages | 5 per socket | close 4400 |
| Sockets per client address | `MAX_CONN_PER_IP`, default 40 | HTTP 429 on upgrade |
| Server-side backlog | a client that leaves 1 MB unread is terminated | close 1006 on the client |
Server-side tuning for tests lives in the `createServer` options `wsAuthTimeoutMs`, `wsPingMs`, `wsRate`, `wsBurst`, `wsBadBudget`
(no environment variables; the defaults above are what production runs).
## Close codes
| Code | Reason string | Meaning | Client should |
| ---- | ------------- | ------- | ------------- |
| 1001 | `shutdown` | server is restarting | reconnect with backoff (a few seconds, then up to 30 s) and refetch |
| 1006 | | abnormal (network, proxy, server terminated a dead or backlogged socket) | reconnect with backoff, refetch |
| 1009 | | a client frame was larger than 1024 bytes | bug in the client; do not retry in a loop |
| 4400 | `too_many_bad_messages` | 5 bad messages | bug in the client; do not retry in a loop |
| 4401 | `invalid_token`, `auth_required`, `token_revoked` | token unknown, revoked, user banned, or first message was not `auth` | **do not reconnect** with this token: go to login. `token_revoked` is sent as soon as the next ping tick (at most 30 s) notices the revocation (logout on that device, revoked in settings, ban) |
| 4408 | `auth_timeout` | no `auth` within 10 s | reconnect |
| 4429 | `rate_limited` | more than 5 msg/s sustained | back off at least 30 s |
Suggested client loop: connect, send auth, on `ready` reset the backoff, on close with 4401/4400/1009 stop, otherwise retry after
`min(30 s, 1 s * 2^n)` plus jitter; after every `ready` following a gap, refetch the visible screen and `/notifications`.
## Example session
```text
C: {"type":"auth","token":"mQ3...43 chars"}
S: {"type":"ready","serverTime":1767225600000}
... alice queues a building on a phone ...
S: {"type":"town","townId":1} (the other devices; the phone gets its echo)
... the building finishes ...
S: {"type":"town","townId":1}
S: {"type":"notification","id":14,"kind":"build_done"}
... bobby sends a raid at POP 1 ...
S: {"type":"incoming","townId":1,"arriveAt":1767236400000}
S: {"type":"notification","id":15,"kind":"incoming"}
... it lands ...
S: {"type":"town","townId":1}
S: {"type":"report","id":3}
S: {"type":"notification","id":16,"kind":"report"}
C: {"type":"ping"}
S: {"type":"pong","serverTime":1767236401000}
```
## Where the hints come from
| Source | Hint |
| ------ | ---- |
| any `notifications` row (`scheduler.notify`, after the transaction committed) | `notification`; plus `incoming` / `report` / `message` for kinds `incoming` / `report` / `message`, `alliance_message`; plus `town` for kinds that change a POP whose owner may differ from the event's POP (`town_lost`, `town_gained`, `transport_arrived`, `transport_delivered`, `movement_returned`, `reinforcements_sent_home`) |
| a finished event (`scheduler.onEvent`) | `town` to the owner of `events.town_id` (build, train, research, power check) and of both ends of the movement for `arrive` / `return` |
| a committed command (`commands.hooks.onCommand`) | `town` to the owner of the POP named in `townId`, `fromTownId`, `hostTownId`, `ownerTownId` or the new POP of `joinWorld`; for `recallMovement` both ends of the movement |
Adding a notification kind needs no change here (it arrives as a generic `notification`). A new kind that deserves its own typed
hint is one `case` in `server/pushHooks.js` plus a row in the table above.
## Not covered (yet)
* No APNs/FCM: the `notifications` table is the hook for it (`scheduler.onNotify` sees every row).
* No subscription channels: every authenticated socket gets all hints of its user, across worlds (the hint carries `townId`).
* No per-device mute, no "last seen id" resume: reconnect and refetch.
* Reinforcing owners (units stationed in a POP that gets attacked) are told by the `report` hint, not by a `town` hint for their
home POP.
* Confederates do not get `incoming` for each other's POPs (nothing in the game layer produces it yet).

File diff suppressed because it is too large Load diff