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

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).