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
190 lines
20 KiB
Markdown
190 lines
20 KiB
Markdown
# NEXT
|
|
|
|
Honest status, updated at the end of every stage.
|
|
|
|
## Done
|
|
- Stage 0 skeleton: db + migrations, clock, scheduler with catch-up, router, auth/tokens, error envelope, openapi generation, static server.
|
|
- Stage 1 economy (server): lazy resources, buildings, build queue, storage caps, power battery.
|
|
- Stage 2 world (server): seeded tiles, spawn ring, map viewport query.
|
|
|
|
## Stage 5 (partial): social, server only
|
|
Built (migration `003_social.sql`): alliances (found, invite/accept/decline/cancel, leave, kick, roles, leader transfer, disband,
|
|
pinned notes, member list with POP count and last online), diplomacy between alliances (war, neutral, NAP, confederation;
|
|
proposals; 24 h / speed pact cancel through the `diploChange` event; revoke), messages (DM, alliance broadcast, inbox/outbox/thread/
|
|
alliance feed, read, delete own copy, block list, DB-backed rate limit, text sanitising), rankings (operators, alliances, battles),
|
|
`alliance` in `/me` and `/map`, lookup helpers in `server/alliances.js` (`operatorRelation`, `atWar`, `confederated`, `pactPartners`).
|
|
Tests: `test/social-*.test.js` (pure rules, alliances, diplomacy with the fake clock and event queue, messages, rankings), every
|
|
response in them is checked against its declared schema (`createTestServer({ contract: true })` in `test/helpers.js`).
|
|
|
|
Not done:
|
|
- 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.
|
|
|
|
## Stage 3/4: military and expansion (server only)
|
|
Built (migration `002_military.sql`: `town_units`, `stationed`, `town_research`, `town_power`, `movements`, `reports`, `report_recipients`,
|
|
`operator_stats`, `incumbent_takes`): 10 unit types and research in `data.js`/`rules.js`; training queue (`trainDone` per batch,
|
|
sequential per building); research (`researchDone`); movements scan/raid/attack/takeover/reinforce/settle/transport with latency, ETA,
|
|
recall (90 s), return legs with loot; combat resolved at arrival in the event queue (full attack, raid, firewall vs DDoS rigs, exploit
|
|
kits on a chosen building, loot with Rack hall cache, losses, reinforcements, research, battle points in `operator_stats`);
|
|
scans with intel and detection; takeover with loyalty, capital and last-POP protection, footprint gate; founding POPs with wild-slot
|
|
choice; incumbent sites (static defence growing with world age, one-time Hardware bonus, +10% research speed per site); beginner
|
|
protection (both directions, re-checked at arrival); power: offline units when the battery is empty, decommission after 24 h
|
|
(`powerCheck`); incoming warnings with hidden type; reports (shared row, per-user read flag, 14 day cleanup event); transport movement
|
|
and arrival hook (`movements.hooks.transportArrived`) for the trade stage. Routes: see docs/API.md, all in `docs/openapi.json`.
|
|
Tests: `test/military-*.test.js` (rules as pure functions, train queue order, raid end to end, event order and determinism, takeover and
|
|
its protections, offline units and decommission, restart catch-up from a reopened DB file, protection, settle, incumbent, transport,
|
|
recall, research, reports/cursor/retention, API smoke over HTTP). Fake clock, in-memory DB, port 0; no Playwright.
|
|
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; 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: 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).
|
|
- Shell (`js/main.js`): session, `App.registerScreen({id, titleKey, navKey, icon, hud, render, onShow, onHide, onLang})`, bottom nav
|
|
(left rail in landscape and on wide screens), live resource bar ticked with `rules.resourcesAt` from the server clock, hash routing.
|
|
- Screens (`js/screens/`): login/signup (invite field appears after `signup_closed`), POP (resource fields by type, infrastructure,
|
|
build queue with countdowns and cancel, power panel, detail sheet with the server's `next` plan, live affordability, rename),
|
|
map (`js/render.js` canvas: pan, pinch, wheel, keyboard, culling; chunked `GET /map` cache; tile info sheet), alerts
|
|
(`GET /notifications`), settings (language, device tokens + revoke, logout).
|
|
- `js/api.js`: bearer token, serverTime offset, retry/backoff (network, 429 + Retry-After, 502-504), `Idempotency-Key` per intent,
|
|
`ApiError.code`, event emitter with a reserved `push` event (no WebSocket client yet).
|
|
- `js/i18n.js`: en + nb, all player-facing names; `PWA`: manifest + icons (no service worker, so no offline mode).
|
|
- Tests: `test/client-i18n.test.js` (key parity, names, error codes, formatting), `test/client-api.test.js` (retry, idempotency, offset).
|
|
- Looked at with headless Chromium screenshots (phone portrait, phone landscape, desktop) and one scripted signup/build/cancel/map-tap
|
|
flow on a phone profile. Not run: real devices, Safari/iOS, Playwright suite.
|
|
Gaps: the unread badge is stored in localStorage (no "mark read" route); `/me` exposes the world seed which the client ignores;
|
|
no push, no service worker, canvas has no inertia/fling, no light theme.
|
|
|
|
## 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".
|