Upstream/docs/PROTOCOL.md
jvanvik b18645dca1 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
2026-10-11 19:05:03 +02:00

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

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

    {"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

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