Built: - Economy: raid loot capped to the room the raiders have at home (rest stays with the victim, "lootLeft" in the report); trade escrow reserves its room so refunds always fit; trade accept refuses with no_room_for_goods when the goods would not fit. Loot destroyed per 30-day run 31-61k -> ~1k, refunds clipped ~27k -> 0 (docs/BALANCE.md, 3 seeds). - End game: members of the holding alliance garrison landing sites (migration 005_site_garrison.sql), garrison counts in site defence, 72 h capture shield, withdraw route, POP view lists garrisoned units. Shipping capacity scales with world speed (3x world: winner 76-98 -> ~30-36 days after sites open). Bot runs show real contests (84-194 attacks on held sites at 1x). - Ops: deploy/update.sh (backup, stop, ff-merge, npm ci --ignore-scripts, health check, rollback), deploy/upstream-offsite (rsync only), admin end-world snapshots results, EPIPE fix, docs/workflows/ filled in. - e2e 62 -> 163 checks: units, raids/reports, alliance+messages, trade, end game, nb, PWA, reconnect, slow polling fallback (opt-in). Two app bugs found: message push ignored, "New" button stayed English. Tested: npm test 274/274, openapi check, npm run e2e 163/163 (137 s), bot runs 50x30d seeds 1-3 and 140-day/60-day speed-3 end-game runs INVARIANTS OK, adversarial review pass (findings fixed or documented). NOT tested: update.sh on a real box (systemd, real npm, runuser; stubs only, shellcheck not installed), garrison card/loot text on a phone, Node 22.13, humans. Known leaks left open and documented (BALANCE S6): loot/shipments can still overflow when stock arrives in flight, bounced backbone shipments lose overflow (reported to the sender). Garrison numbers (heldDefenceMult 2, shield 72 h) are first guesses from 2 seeds. Not claimed: balanced. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
146 lines
9.7 KiB
Markdown
146 lines
9.7 KiB
Markdown
# 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`, `trade_refund_clipped`, `backbone_incoming`, `garrison_arrived`, `garrison_released`, ... (the complete list with payloads is "Notification types" at the end of docs/API.md; 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`, `garrison_arrived`, `garrison_released`) |
|
|
| 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).
|