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:
parent
249818a7aa
commit
b18645dca1
87 changed files with 10201 additions and 71 deletions
53
docs/API.md
53
docs/API.md
|
|
@ -118,3 +118,56 @@ firewall, loot, siege, takeover/loyalty), `scan` (attacker; intel when it succee
|
|||
if the defender's scanners won), `incumbent`, `settle`, `reinforce`, `movement_failed`.
|
||||
|
||||
Later stages append their routes here and to the route table.
|
||||
|
||||
## Trade, end game, shared reports (stage 5 rest, stage 7 start)
|
||||
|
||||
**Internet exchange trade.** Offers "give X of A for Y of B within Z tiles". Amounts are whole numbers, each side 1..500 (one transport
|
||||
link), the two amounts differ by at most 1:2, the resources differ; `maxDistance` 1..300. Lists are newest first, `after` = id of the last
|
||||
offer you have (older ones follow). `status`: `open`, `accepted`, `completed`, `cancelled`, `expired`, `void`.
|
||||
|
||||
| Route | Purpose |
|
||||
| ----- | ------- |
|
||||
| `POST /trade/offers {townId, giveRes, giveAmount, wantRes, wantAmount, maxDistance}` | post (201). The offered amount leaves the POP (escrow) and one transport link is held in reserve. `trade_ratio`, `capacity_exceeded`, `no_transport_link` (no exchange, or all links busy/reserved), `not_enough_resources` |
|
||||
| `GET /trade/offers?worldId&townId&give&want&after&limit` | open offers of others that one of your POPs (or `townId`) can take: within `min(maxDistance, 10 x exchange level)`. Each carries `acceptableFrom: [{townId, distance}]`; `exchangeLevels` lists your exchanges and their reach |
|
||||
| `GET /trade/offers/mine?worldId&status&after&limit` | offers you posted or accepted, any status, with `role` |
|
||||
| `GET /trade/offers/:id` | one offer: open ones to every operator of the world, closed ones to the two parties (`not_found` otherwise) |
|
||||
| `DELETE /trade/offers/:id` | cancel your open offer; the escrow returns to the POP (`offer_closed` when it is not open) |
|
||||
| `POST /trade/offers/:id/accept {townId}` | take it with one of your POPs (201): two transports leave at once (your payment, their goods); `own_offer`, `offer_closed`, `trade_out_of_range`, `no_transport_link`, `not_enough_resources`; all or nothing |
|
||||
|
||||
Notifications: `trade_accepted` (poster), `trade_completed` (both, when both transports arrived), `trade_expired`, `trade_void` (the POP
|
||||
was taken over). Delivery notifications are the existing `transport_arrived` / `transport_delivered`. Direct transports (own POPs, any
|
||||
player) stay `POST /movements` with `type: "transport"`.
|
||||
|
||||
**World status and the end game.** The backbone sites open at world day 100 (real days x speed).
|
||||
|
||||
| Route | Purpose |
|
||||
| ----- | ------- |
|
||||
| `GET /worlds/:id/status` | `phase` (`running`, `backbone_open`, `ended`), `ageDays`, `opensAt`, the 7 `sites` (empty before opening: `id` (null until first touched), `index`, `x`, `y`, `holder` `{allianceId, tag, name}` or null = incumbent, `takenBy`, `level`/`maxLevel`/`progress`, `pool` (stockpile), `build` `{toLevel, startedAt, dueAt}`, `next` `{toLevel, cost, durationMs}`), `winner`, `endsAt` (set once somebody won), `endedAt` |
|
||||
| `GET /worlds/:id/results` | the final snapshot once ended (`available: false` before): `winner`, `results.{operators, alliances, attackers, defenders, sites, totals}` (top 100 each, ranked) |
|
||||
| `GET /backbone/:id` | one site; holders also get `contributions` (who shipped what) and `you` `{holder, canBuild, canShip, canAttack}` |
|
||||
| `POST /backbone/:id/ship {fromTownId, cargo}` | send resources to a site your alliance holds (201, a transport: same links and capacity); arrives into the stockpile, or rides home if the site changed hands |
|
||||
| `POST /backbone/:id/build` | start the next node level (201), paid from the stockpile at once, one level at a time, any holder with `backboneBuild`; `max_level`, `already_queued`, `not_enough_resources`, `forbidden` (not a holder), `backbone_closed` |
|
||||
|
||||
Taking a site is `POST /movements` with `type: "scan"` or `"attack"` and the site's `x, y` (no `toTownId`): needs an alliance, not against
|
||||
the own alliance or a NAP/confederation partner (`invalid_target`, `details.reason`: `no_alliance`, `own_site`, `pact`,
|
||||
`landing_scan_or_attack_only`); before opening `backbone_closed`. Settling a landing tile is `invalid_target` (`backbone_site`), also before
|
||||
it opens. Defence is static: `incumbentDefence x 12 x (1 + 0.03 x node level)`; a scan report shows it. Reports: scans as `scan` (with
|
||||
`site.type: "backbone"`), attacks as the new type `landing` (outcome, attack/defence, `taken`; recipients: the attacker and every member of the
|
||||
previous holder). `GET /map` lists open sites in `specials` as `type: "backbone"` with `site: {id, index, holder, level, maxLevel}`;
|
||||
`GET /map/tile` returns `type: "backbone"` and `backbone: {siteId, holder, level, pool, build, mine, canAttack}`.
|
||||
|
||||
Notifications: `backbone_open` (first touch), `backbone_taken` / `backbone_lost` (alliance members), `backbone_level` (every 10th level and the
|
||||
last, holder members), `backbone_delivered` / `backbone_ship_bounced` (sender), `backbone_won` (everybody), `world_ended` (everybody).
|
||||
|
||||
**An ended world** answers every game command with `409 world_ended` (build, send, train, trade, alliances, diplomacy, backbone, report
|
||||
sharing, ...). Still allowed: `GET` everything (map, reports, rankings, towns, status, results), `POST /reports/read-all`, `POST
|
||||
/reports/:id/read`, messages (send, read, delete, block).
|
||||
|
||||
**Shared report folder.** `POST /reports/:id/share` puts one of YOUR reports into your alliance's folder (needs `shareReport`; the report
|
||||
is kept 14 days from the share), `DELETE /reports/:id/share` takes it out (the sharer, or `unshareReport`: leader, officer), `GET
|
||||
/alliances/:id/reports?after&limit` lists the folder newest first (cursor: id of the last report seen), `GET /alliances/:id/reports/:reportId`
|
||||
reads one with its full data. Members with `viewSharedReports` only; `GET /alliances/mine` permissions list the new keys.
|
||||
|
||||
**Allied incoming.** `GET /movements` has a new `alliedIncoming` list: movements heading for POPs of your alliance mates and of
|
||||
confederated alliances, same shape as `incoming` (type `unknown`, origin and ETA only) plus `ally: true` and `toOperator`. Friendly traffic
|
||||
(from partners of the target) is left out.
|
||||
|
|
|
|||
|
|
@ -128,3 +128,85 @@ nothing is spent. New POPs start with every field at level 0, no infrastructure,
|
|||
## S3-9 — Moving units between your own POPs
|
||||
`reinforce` to an own POP puts the units into `town_units` of the target (they live there now). Only units of OTHER operators are
|
||||
`stationed` rows.
|
||||
|
||||
## S6-1 — Push hints leave only after the commit, through an outbox
|
||||
`scheduler.notify` runs inside the transaction of the event or command, so pushing there would announce changes that may still roll
|
||||
back. `notify` queues into `scheduler.outbox` (only when a listener is set); `process()` and `commands.run` flush it after COMMIT
|
||||
(`db.depth === 0`) and truncate it to their mark on rollback. `town` hints use the existing `scheduler.onEvent` (post-commit already)
|
||||
and a new `commands.hooks.onCommand`. `push.js` itself knows no game rules (it gets `townOwner` / `tokenValid` injected), the routing
|
||||
lives in `pushHooks.js`. No new dependency (`ws` was already listed).
|
||||
|
||||
## S6-2 — Revocation is polled, not pushed
|
||||
Tokens are revoked by plain SQL in routes and the admin tool. Instead of hooking each place, the ping tick (30 s) re-checks
|
||||
`tokens.revoked_at` and `users.banned` for every authenticated socket and closes with 4401. Worst case 30 s of hints after logout on
|
||||
another device; hints carry no data, so nothing leaks. If that is ever not good enough, call a `push.disconnectToken(id)` from the routes.
|
||||
|
||||
## S6-3 — Hints are merged per tick, `town` is not sent to the target at launch
|
||||
Identical JSON hints produced in one tick (a catch-up) are deduplicated per socket via `setImmediate`. A launched movement tells the
|
||||
target's owner `incoming` (town + ETA) and no plain `town` hint, so the type and origin of a launch cannot be inferred from extra traffic.
|
||||
|
||||
|
||||
## E1 — A landing site is a row of its own, not a POP
|
||||
`landing_sites(world_id, idx, x, y, holder_alliance_id, holder_operator_id, level, stockpile, build_*)` (migration 004), positions from
|
||||
`rules.backboneSites(seed, radius)`. A town row of kind `landing` owned by the leader was considered and rejected: a "POP" that nobody plays
|
||||
would have to be excluded from footprint rankings, the last-POP / capital / footprint-gate counts, `homeTownFor`, `/me`, spawn spacing and
|
||||
the Rack hall cap (shipped resources would be thrown away at 250), and a leader change would have to re-own it. The holder is the
|
||||
alliance (`holder_alliance_id`, FK `ON DELETE SET NULL`, the disband hook also clears it), `holder_operator_id` only records who took it.
|
||||
Consequence, on purpose and to be revisited after the first world: **no units can stand at a site**, so there is no garrison and no
|
||||
reinforcement. A site is defended by the static value `incumbentDefence x 12 x (1 + 0.03 x level)` only, i.e. exactly the "incumbent
|
||||
with a backbone multiplier" of DESIGN.md; holders defend by growing the node (higher level = harder to take), attackers can scan the exact
|
||||
number. Hooks into the military code are small: `combat.arriveSite` hands `backbone` tiles to `military/landing.js`,
|
||||
`arrivals.arriveTransport` hands shipments (`extra.siteId`) to `endgame.deliverShipment`, `sendMovement` calls `endgame.checkLandingTarget`.
|
||||
|
||||
## E2 — Site rows are created lazily, there is no timer event
|
||||
`ensureSites` creates the 7 rows when something first touches a site (an attack/scan sent or arriving, a shipment, a build) once the world is
|
||||
at day 100 / speed; that first call also writes a `backbone_open` notification for every operator. Reads (`/worlds/:id/status`, `/map`, tile
|
||||
info) never write: untouched sites are shown as the incumbent's, level 0, `id: null`. A `backboneOpen` event at world creation was
|
||||
dropped: a pending event 100 days ahead sits in every quiet world and breaks tooling that counts pending events (the admin CLI test).
|
||||
Cost: nobody is pushed the moment the sites appear unless a first touch happens; clients see `phase: backbone_open` when they poll status.
|
||||
|
||||
## E3 — The winner is fixed at level 100; the world is frozen when it ends
|
||||
The holder of a node whose level completes at 100 wins (`worlds.winner_*`, once per world) and `worldEnd` is scheduled
|
||||
`graceDays x 24 h / speed` later. Losing the node meanwhile does not change the winner (the race is over; the grace days are for the ranking
|
||||
and the post-game). If a level-100 node is taken while nobody holds it (the holder disbanded mid-build) the new holder wins. `worldEnd`
|
||||
writes the ranking snapshot, sets `status = 'ended'`, closes open trade offers (`expired`, escrow back in its POP: every unit stays accounted
|
||||
for) and CANCELS every other pending event of the world: nothing arrives, trains,
|
||||
expires or builds after the snapshot, so the stored ranking stays the truth. Movements still `out` and queued builds stay as they were.
|
||||
A running build of a site continues for whoever holds the site when it lands (the level belongs to the site; the cost was paid from the
|
||||
stockpile at the start); the stockpile and the ledger stay with the site when it is taken.
|
||||
|
||||
## E4 — `world_ended` is one gate in `commands.run`, found by probing the arguments
|
||||
`ownedTown`, `operatorOf` and `requireRole` are shared with reads (rankings, map), so gating there would break "readable after the end".
|
||||
`commands.run` calls `endgame.guard(db, name, args)`: the world is `args.worldId`, else the world of `townId/fromTownId/hostTownId`,
|
||||
`allianceId`, `movementId`, `inviteId`, `proposalId`, `offerId`, `siteId`, `reportId`, else the caller's oldest operator (the default every
|
||||
command already uses). Allowed after the end: `markReportRead`, `messageSend/Read/Delete`, `messageBlock/Unblock`. New commands are gated
|
||||
automatically as long as they carry one of those arguments.
|
||||
|
||||
## E5 — Backbone cost curve is not the building curve
|
||||
`4000 x 1.28^99` is unreachable; the node has its own `ENDGAME.costGrowth = 1.045` and `timeGrowth = 1.025` (about 7.2 M of each resource and
|
||||
about 36 world days of building in total, level 100 alone 312 k each and 23 h). Pure guesses until a bot run (stage 7) says how much an
|
||||
alliance can ship; nothing here is balanced.
|
||||
|
||||
## T1 — Trade: escrow, one link per side, reach by exchange level
|
||||
- Offers are escrowed in `trade_offers` and hold one transport link of the poster's POP while open (`movements.activeLinks` counts open
|
||||
offers), so accepting never fails for lack of a link on the poster's side and cannot exceed the exchange level.
|
||||
- Each side of an offer must fit ONE transport (<= 500); larger deals are several offers. The ratio band is count-based 1:2.
|
||||
- Escrow returns without the Rack hall cap (conservation beats the cap here); deliveries keep the existing cap rule (`cargoLost`).
|
||||
- Reach: `10 tiles x exchange level` of the taker's POP, and the offer's own `maxDistance`; the poster's level only matters for the number of
|
||||
offers they can hold open.
|
||||
- A POP changing hands voids its open offers (`combat.transferTown` calls `trade.onTownTransferred`); the escrow stays in the POP.
|
||||
- `transportArrived` hook: `server/trade.js` registers itself when required (both `commands/index.js` and `events/index.js` load it), so the
|
||||
consumer exists in every test fixture that builds commands or events.
|
||||
- Offer expiry: one `tradeExpire` event per offer, cancelled on accept/cancel/void, idempotent (acts only while `open`).
|
||||
|
||||
## T2 — Shared reports extend the report's life
|
||||
Sharing sets `expires_at = max(expires_at, now + 14 days)` on the single shared `reports` row, so the folder is not emptied by a report that
|
||||
was nearly due; the cascade `report_shares.report_id ... ON DELETE CASCADE` removes the share when the report is cleaned up.
|
||||
|
||||
## G1 — `buildDone` adds one level to what the building is NOW
|
||||
Each build event adds exactly one level to the current level (never lowers, never above the queued `toLevel`), so an upgrade in flight
|
||||
cannot undo exploit-kit damage; a building knocked to 0 comes back at 1. The notification reports the real level.
|
||||
|
||||
## G2 — Allied incoming is a separate list
|
||||
`GET /movements` keeps `incoming` as "heading for YOUR POPs" and adds `alliedIncoming` for partners' POPs (own alliance + confederations),
|
||||
each entry with `ally: true` and `toOperator`. Mixing them would make clients count allies' attacks as their own.
|
||||
|
|
|
|||
|
|
@ -148,6 +148,12 @@ A new POP starts at level 0 everything and 1 h of resources. Takeover requires t
|
|||
- Diplomacy states between alliances: war, neutral, non-aggression pact, confederation (can reinforce each other,
|
||||
see each other's incoming). Pacts take 24 h to cancel.
|
||||
- Messages: player-to-player and alliance broadcast, plain text, 2000 chars, basic rate limit.
|
||||
- **Shared report folder (server):** a member puts one of their own reports (any type) into the alliance's folder (`shareReport`); every
|
||||
member reads it (`viewSharedReports`), the sharer or leader/officer (`unshareReport`) takes it out. Sharing pushes the report's expiry
|
||||
out to 14 days from the share (it is one row for everybody) and it goes with the report or the alliance.
|
||||
- **Seeing each other's incoming (server):** members of one alliance and of confederated alliances get `alliedIncoming` in `GET /movements`:
|
||||
movements heading for a partner's POP, origin and ETA only (type, units and cargo hidden), except traffic from operators who are partners
|
||||
of the target themselves (friendly).
|
||||
|
||||
## Trade
|
||||
|
||||
|
|
@ -155,6 +161,22 @@ The Internet exchange lists offers "give X of A for Y of B, max distance Z". Rat
|
|||
pump-feeding. Accepting an offer spawns two transport movements. Direct transports to own POPs or to any player
|
||||
(e.g. alliance support) use the same links. Transport links: level of the exchange, capacity 500 each.
|
||||
|
||||
**Clarified (what the server does).**
|
||||
- An offer is "give `giveAmount` of `giveRes` for `wantAmount` of `wantRes`, within `maxDistance` tiles", posted from one POP that has
|
||||
an Internet exchange. Each side must fit ONE transport link (1..500) and the two amounts differ by at most 1:2:
|
||||
`give <= 2 x want` and `want <= 2 x give` (count-based, the resources are not weighted). The resources must differ.
|
||||
- The offered amount is **escrowed**: it leaves the POP when the offer is posted. Cancelling or expiry (48 h / world speed) credits it back
|
||||
to the POP without the Rack hall cap (an amount above the cap is kept, it only stops growing), so nothing is created or lost.
|
||||
- **Reach:** a POP sees and takes offers of other operators within `min(offer.maxDistance, 10 x Internet exchange level)` tiles. The poster
|
||||
cannot take their own offer.
|
||||
- **Links:** an open offer holds one transport link of the poster's POP in reserve (open offers + running transports + returning carriers
|
||||
<= links); accepting converts the reservation into the real transport. Direct transports see the reservation as a busy link.
|
||||
- **Accepting** (one transaction): the acceptor's payment leaves their POP as a transport to the poster's POP (needs a free link and the
|
||||
resources there), the escrow leaves the poster's POP as a transport to the acceptor's POP; both arrive after `distance / 12 tiles/h /
|
||||
world speed`. The offer is `accepted`, then `completed` when both have been delivered. A delivery above the receiver's Rack hall cap
|
||||
loses the overflow and says so (the existing transport rule). If the poster's POP is taken over while the offer is open, the offer
|
||||
ends (`void`) and the escrow stays in the POP.
|
||||
|
||||
## Incumbent (NPC)
|
||||
|
||||
The legacy telco. Holds incumbent sites spread over the map with large static defences that scale with world age.
|
||||
|
|
@ -169,6 +191,33 @@ far more than anything else and requiring resources shipped in from members (tra
|
|||
wins and the world ends two days later with a final ranking. Backbone nodes can be attacked and taken; the level
|
||||
stays with the site. Landing sites cannot be settled, only taken.
|
||||
|
||||
**Clarified (what the server does).** World age is in world days (real days x speed). All numbers below are first guesses, no bot run.
|
||||
- **Sites:** `rules.backboneSites(seed, radius)`: 7 fixed positions, one per sector of the circle (jittered), on plain land between 35% and
|
||||
80% of the map radius, at least 6 tiles apart, never in the free centre. They exist from the start (spawning and settling refuse them),
|
||||
the tile reads `backbone` from day 100 / speed (`rules.tileAt(seed, radius, x, y, ageDays)`; without the age argument terrain is unchanged).
|
||||
- **A site is not a POP** (DECISIONS E1): it has a holder alliance, a Backbone node level, a stockpile of Fiber/Hardware/Capital and at most
|
||||
one level in progress. No units can stand there, so a site is defended by a static value only:
|
||||
`defence = incumbentDefence(seed, x, y, age) x 12 x (1 + 0.03 x node level)`. At day 100 that is about 40 000 with no node, 160 000 at
|
||||
level 100 (a Script crew attacks with 40).
|
||||
- **Taking:** `scan` and `attack` only (no raid: the stockpile would be lootable; no takeover, no reinforce, no settle). The attacker must be in
|
||||
an alliance, and may not be in the holder's alliance or in a NAP / confederation with it (checked when sent and again on arrival, units come
|
||||
home otherwise). A full attack with attack > defence wins: the attacker's alliance holds the site. No loot, the site loses nothing, the
|
||||
survivors drive home. Level, stockpile and a running build stay with the site. A holder that disbands leaves the site to the incumbent
|
||||
(level kept).
|
||||
- **Feeding the node:** members of the holder alliance send resources by transport (`POST /backbone/:id/ship`, same links, 500 per link, 12
|
||||
tiles/h). On arrival they join the stockpile if the sender's alliance still holds the site, otherwise they ride home. A ledger records
|
||||
who sent what.
|
||||
- **Building:** level L (1..100) costs `4000 x 1.045^(L-1)` of each resource (level 100: 312 301; about 7.2 million of each in total) and
|
||||
takes `2 h x 1.025^(L-1) / world speed` (level 100: 23 h; about 36 days of world time in total, one level at a time). The cost is paid from
|
||||
the stockpile when the level starts; any holder with `backboneBuild` may start it.
|
||||
- **Winning:** when a level completes and the node is at level 100, the holder at that moment wins (once per world) and the world ends two world
|
||||
days later (`worlds.end_at`). The winner is final: losing the node during those two days does not change it. If a finished node is taken while
|
||||
nobody held it, the new holder wins.
|
||||
- **Ending:** the `worldEnd` event stores a ranking snapshot (operators by footprint, alliances by the sum, top attackers and defenders by
|
||||
battle points, winner, the sites), sets the status `ended`, and cancels everything still pending in that world. An ended world refuses
|
||||
every game command with `world_ended`; reading (map, reports, rankings, town views, status, results) and chatting (messages, marking reports
|
||||
read) keep working.
|
||||
|
||||
Rankings throughout: operators by footprint, alliances by sum, attackers/defenders by points from battles.
|
||||
|
||||
## Fairness and anti-frustration
|
||||
|
|
|
|||
138
docs/NEXT.md
138
docs/NEXT.md
|
|
@ -17,11 +17,10 @@ Tests: `test/social-*.test.js` (pure rules, alliances, diplomacy with the fake c
|
|||
response in them is checked against its declared schema (`createTestServer({ contract: true })` in `test/helpers.js`).
|
||||
|
||||
Not done:
|
||||
- Marketplace / Internet exchange and resource transport (waits for the movement system of stage 3).
|
||||
- Shared report folder of the alliance (needs reports from stage 3), confederation effects (reinforce, see incoming) and the pact
|
||||
effect "no attacks inside a NAP/confederation": the military stage must call `alliances.pactPartners` / `confederated`; nothing
|
||||
enforces it yet.
|
||||
- No web client, no WebSocket push (notifications rows are written; stage 6 pushes them).
|
||||
- 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.
|
||||
|
|
@ -43,11 +42,9 @@ recall, research, reports/cursor/retention, API smoke over HTTP). Fake clock, in
|
|||
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; reports cannot be shared to the alliance yet (the shared report folder needs a table in the social stage);
|
||||
confederates do not see each other's incoming movements (only reinforce is wired); no sitter, no night protection.
|
||||
- A building damaged by exploit kits that has an upgrade in flight jumps to the queued level when that finishes (`buildDone` sets absolute levels).
|
||||
- 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 (end game) are not part of this stage.
|
||||
- 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).
|
||||
|
|
@ -66,5 +63,128 @@ Built: `public/` vanilla JS, no build step, strict-CSP friendly (no inline scrip
|
|||
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".
|
||||
|
|
|
|||
146
docs/PROTOCOL.md
Normal file
146
docs/PROTOCOL.md
Normal 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).
|
||||
2236
docs/openapi.json
2236
docs/openapi.json
File diff suppressed because it is too large
Load diff
Loading…
Add table
Add a link
Reference in a new issue