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
9.5 KiB
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
-
Open
/ws. The upgrade is refused with plain HTTP status (the client sees a failed handshake, not a close code):HTTP Why 403 Originheader present and not allowed: same host asHost, or listed inALLOWED_ORIGINS(same rule asnet.originAllowed). NoOrigin(non-browser clients) is fine.404 any path other than /ws429 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 -
Send the first message within 10 s. It must be exactly this, never put the token in the URL (proxy logs):
{"type":"auth","token":"<bearer token from /auth/login or /auth/signup>"} -
The server answers
{"type":"ready","serverTime":1767225600000}. Only afterreadydo 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
townhint per POP), order is otherwise preserved per socket. - A command's own
townhint 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 plaintownhint;townfor 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
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
notificationstable is the hook for it (scheduler.onNotifysees 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
reporthint, not by atownhint for their home POP. - Confederates do not get
incomingfor each other's POPs (nothing in the game layer produces it yet).