Stage 3-5 server (military, expansion, social), web client for stages 1-2, ops/deploy
Built: units/research/training, movements (scan, raid, attack, takeover, reinforce, settle, transport), deterministic combat resolved in the event queue, reports, power/offline units, founding + conquest + incumbent sites; alliances, roles, diplomacy (24h pact cancel via events), messages, rankings; vanilla-JS phone-first client (auth, POP, map, alerts, settings, en/nb); systemd units, backup timer, DEPLOY.md, tools/admin.js. Tested: npm test 96/96 (fake clock, in-memory db, a few real-HTTP tests); client checked with headless Chromium screenshots only. NOT done: marketplace/transport trade, client screens for military/social, WebSocket push, bots/balance, e2e suite. All unit stats and costs are unbalanced first guesses. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q2MJaQ5LXAHzGnTDgceT14
This commit is contained in:
parent
b56b13880e
commit
249818a7aa
111 changed files with 17472 additions and 13 deletions
90
docs/API.md
90
docs/API.md
|
|
@ -27,4 +27,94 @@ REST JSON under `/api/v1/`. The machine-readable contract is `docs/openapi.json`
|
|||
| `GET /map?x&y&r` | rural areas, incumbent sites, POPs in the viewport |
|
||||
| `GET /notifications?after&limit` | durable notification feed (build done, ...) |
|
||||
|
||||
## Social (stage 5, no marketplace/transport yet)
|
||||
|
||||
`worldId` is optional everywhere a caller's operator is needed (default: their oldest operator). Most commands are
|
||||
idempotent where that makes sense and answer `{ changed: false }` when there was nothing to do (leaving twice, kicking someone
|
||||
already gone, accepting an invite twice). `forbidden` carries `details.need` (the missing permission).
|
||||
|
||||
**Alliances.** Roles `leader`, `diplomat`, `officer`, `member`; the permission table is `SOCIAL.permissions` in `data.js`
|
||||
(`GET /alliances/mine` returns the caller's permissions). Founding and joining need a Peering office level >= 1 on one of the
|
||||
operator's POPs (`peering_office_required`). Size cap: `10 + 2 * level` of the founder's best Peering office when founding, stored;
|
||||
it is raised (never lowered) whenever a command runs that depends on it (invite, accept, transfer) if the current leader's best
|
||||
office would give more; reads show the effective cap. One alliance per operator.
|
||||
|
||||
| Route | Purpose |
|
||||
| ----- | ------- |
|
||||
| `POST /alliances {name, tag}` | found (201); name 3-30 chars, tag 2-5 letters/digits, both unique per world, case-insensitive |
|
||||
| `GET /alliances?q&after&limit`, `GET /alliances/mine`, `GET /alliances/:id` | directory (cursor: id), your alliance + role + permissions, public profile (size, leader, summed footprint, your relation) |
|
||||
| `GET /alliances/:id/members` | members only: role, POP count, footprint, `lastOnline` (newest token use of the user, updated at most once a minute); bounded by the cap, so not paginated (`next` is always null) |
|
||||
| `POST /alliances/:id/invite {operatorId \| name}`, `GET /alliances/:id/invites`, `DELETE /alliances/:id/invites/:inviteId` | invite (201; repeating returns the pending invite with 200), list sent, cancel. Invites expire after 7 days (real time) |
|
||||
| `GET /alliance-invites`, `POST /alliance-invites/:id/accept`, `POST /alliance-invites/:id/decline` | the invitee's side |
|
||||
| `POST /alliances/:id/leave`, `/kick {operatorId}`, `/role {operatorId, role}`, `/transfer {operatorId}`, `/disband` | leaving (the leader must transfer first, or is alone and disbands), kick (only members the actor outranks), set role (leader only), hand over leadership, disband |
|
||||
| `GET/POST /alliances/:id/notes`, `POST/DELETE /alliances/:id/notes/:noteId` | pinned notes (max 10, 1000 chars, plain text) |
|
||||
|
||||
**Diplomacy.** States `war`, `neutral`, `nap`, `confed`. `POST /alliances/:id/diplomacy {targetId, state}` answers with
|
||||
`result`: `applied` (declaring war from neutral takes effect at once), `proposed` (pacts, and peace out of war: the other alliance
|
||||
must accept within 72 h, real time) or `scheduled` (cancelling a pact, or going to war out of one, takes 24 h / world speed:
|
||||
`effectiveAt`, applied by the `diploChange` event). While a change is scheduled the old state holds and further changes between the
|
||||
pair are `diplomacy_pending`; the alliance that started it can take it back. The move table is `SOCIAL.diplomacyMoves`.
|
||||
|
||||
| Route | Purpose |
|
||||
| ----- | ------- |
|
||||
| `GET /alliances/:id/diplomacy` | members only: relations (with scheduled change), incoming and outgoing open proposals |
|
||||
| `POST /diplomacy/proposals/:proposalId/accept` / `.../decline`, `DELETE /diplomacy/proposals/:proposalId` | answer (receiving alliance) / withdraw (proposing alliance); all need `diplomacy` |
|
||||
| `DELETE /alliances/:id/diplomacy/:otherId/pending` | revoke a scheduled cancel you started |
|
||||
|
||||
Notification types written: `alliance_invite`, `alliance_invite_declined`, `alliance_member_joined`, `alliance_member_left`,
|
||||
`alliance_kicked`, `alliance_role`, `alliance_leader`, `alliance_disbanded`, `diplomacy_proposal`, `diplomacy_declined`,
|
||||
`diplomacy_changed`, `diplomacy_cancel_pending`, `diplomacy_cancel_revoked`, `message`, `alliance_message`.
|
||||
|
||||
**Messages.** Plain text, 1-2000 characters; control characters, bidi overrides and invisible characters are stripped
|
||||
(`server/text.js`) before anything is stored. Lists are newest first and the cursor is the last id of the previous page
|
||||
(`?after=<next>` gives the next, older page). Sending is limited per sender by counting their recent messages (15 DMs / 10 min,
|
||||
60 DMs / h, 20 alliance broadcasts / h, `SOCIAL.messageLimits`): `429 rate_limited` with `details.retryAfter`. Deleting removes only
|
||||
your own copy. A recipient who blocked the sender gets nothing; the sender is not told (`recipients: 0`).
|
||||
|
||||
| Route | Purpose |
|
||||
| ----- | ------- |
|
||||
| `POST /messages {toOperatorId \| toName \| toAlliance, text}` | send (201) |
|
||||
| `GET /messages/inbox?unread`, `/messages/outbox`, `/messages/thread/:operatorId`, `/messages/alliance` | lists; the inbox also returns `unread` |
|
||||
| `GET /messages/:id`, `DELETE /messages/:id`, `POST /messages/read {ids \| all}` | one message, delete own copy, mark read |
|
||||
| `GET/POST /messages/blocks`, `DELETE /messages/blocks/:operatorId` | block list (max 100) |
|
||||
|
||||
**Rankings.** `GET /rankings/operators` (footprint, `rules.footprintAt` over the operator's POPs), `/rankings/alliances` (sum over
|
||||
members), `/rankings/battles?by=attack|defense|total` (from `operator_stats`, `available: false` and empty when that table does not
|
||||
exist). The cursor is a rank offset (`next` = ranks already seen). Each response has `total` and `you` (the caller's own entry).
|
||||
|
||||
`GET /me` operators and `GET /map` town owners now carry `alliance: { id, tag, name } | null` next to `allianceId`.
|
||||
|
||||
## Military and expansion (stages 3-4)
|
||||
|
||||
Units are plain `{ unitId: count }` objects with the generic ids of `data.UNITS` (`port_scanner`, `soc_analyst`, `blue_team`,
|
||||
`honeypot`, `script_crew`, `botnet`, `ddos_rig`, `exploit_kit`, `rollout_crew`, `ma_team`); names live in `i18n.js`. `GET /towns/:id`
|
||||
now carries `town.military`: units at home (`online` flag, `offlineSince`), reinforcements standing here and away, the training queue,
|
||||
what can be trained (cost, time, missing requirements), research levels and queue, transport links, and this POP's outgoing/incoming
|
||||
movements. Nothing resolves when you send it: combat, loot and arrival happen in the event queue at the arrival time, and reports and
|
||||
notifications (`incoming`, `report`, `train_done`, `research_done`, `movement_returned`, `transport_arrived`, `units_offline`,
|
||||
`units_decommissioned`, `town_lost`, `town_gained`) tell you afterwards.
|
||||
|
||||
| Route | Purpose |
|
||||
| ----- | ------- |
|
||||
| `POST /towns/:id/train {unit, count}` | queue a batch (201). Batches of one training building (NOC / Ops lab / Rollout depot) run in order, buildings in parallel; queue limit 8 per building (`queue_full`) |
|
||||
| `POST /towns/:id/research {unit, stat}` | +5% `attack` or `defence` per level for one unit type, one research at a time per POP, level n needs a Research lab of level n + 2 |
|
||||
| `POST /movements {fromTownId, type, toTownId \| x,y, units, ...}` | send `scan`, `raid`, `attack`, `takeover`, `reinforce`, `settle` (201). `type: transport` carries `cargo: {fiber, hardware, capital}` (Internet exchange: level = concurrent transports, 500 each). Extra fields: `target` (building for exploit kits), `wild` (two field types for a new POP), `confirmEndProtection` |
|
||||
| `GET /movements` | your active movements (full detail, `recallableUntil`) and incoming ones from others: origin and ETA only, `type: "unknown"` |
|
||||
| `POST /movements/:id/recall` | turn an outbound movement around within the first 90 s (`recall_expired` after) |
|
||||
| `POST /towns/:id/withdraw {ownerTownId, units?}` | reinforcements in this POP go home (host kicks them out, or their owner calls them back) |
|
||||
| `GET /reports?after&limit&unread`, `GET /reports/:id`, `POST /reports/:id/read`, `POST /reports/read-all` | reports, **newest first**: `after` = id of the last report you have, the next page holds older ones. One shared row per battle, per-user read flag; kept 14 days |
|
||||
| `GET /map/tile?x&y` | public facts about one tile for the send dialog: what is there, owner/protection, distance from each of your POPs, whether you could settle it (`settle.possible/code`) |
|
||||
|
||||
Rules the server enforces on `POST /movements` (error codes in `x-error-codes`): `not_enough_units`, `units_offline` (battery empty),
|
||||
`invalid_target` (`details.reason`: own town, nothing there, pact partner, not allied, occupied tile ...), `target_protected` (beginner
|
||||
protection still running at the arrival time; scans are allowed), `protection_active` (attacking from protected status needs
|
||||
`confirmEndProtection: true` and ends your protection), `cannot_takeover` (last POP), `footprint_too_low` / `out_of_range` (settle and
|
||||
takeover), `capacity_exceeded` / `no_transport_link` (transport). Pact partners (same alliance, NAP, confederation) cannot raid, attack
|
||||
or take over each other; only the same alliance or a confederation may reinforce. The server re-checks target, protection and pact when
|
||||
the movement arrives and bounces it (units come home, a `movement_failed` report says why) if something changed.
|
||||
|
||||
Report types: `raid`, `attack`, `takeover` (the same combat report: outcome, both sides' units and losses, attack/defence values,
|
||||
firewall, loot, siege, takeover/loyalty), `scan` (attacker; intel when it succeeded), `scan_detected` (defender; attacker identity only
|
||||
if the defender's scanners won), `incumbent`, `settle`, `reinforce`, `movement_failed`.
|
||||
|
||||
Later stages append their routes here and to the route table.
|
||||
|
|
|
|||
|
|
@ -33,3 +33,98 @@ committed file is stale, which satisfies "updated in the same commit as any rout
|
|||
## D8 — Resource fields are slot-keyed
|
||||
Buildings table key: `f1..f18` for resource fields (type fixed at founding, 4 per type + 2 wild), the building type for infrastructure.
|
||||
Build "slots": 1 concurrent build, 2 from Core router 10 (queue = pending `buildDone` events).
|
||||
|
||||
## S5-1 — Alliance size cap is stored, only ever raised
|
||||
DESIGN says the Peering office level sets the size you can found. The cap is stored at founding (`10 + 2 * best level`). A lost or
|
||||
downgraded building must never kick anyone, so the cap is monotonic: commands that depend on it (invite, accept, transfer) raise it if
|
||||
the CURRENT leader's best office would give more; reads show `max(stored, formula)` without writing. The floor is therefore 10 even
|
||||
for a leader without an office after a transfer. The office requirement (>= 1) is checked when founding and when accepting an invite,
|
||||
not afterwards.
|
||||
|
||||
## S5-2 — Diplomacy move table is data, three kinds of change
|
||||
`SOCIAL.diplomacyMoves` (data.js) says for each (from, to) whether it is `immediate`, a `proposal` or `delayed`. War from neutral is
|
||||
immediate (no consent needed). Anything that leaves a pact (nap/confed -> neutral/war, confed -> nap) is `delayed`: 24 h / world speed
|
||||
via a `diploChange` event, so you cannot betray a partner without warning. Pacts and peace need acceptance. While a delayed change is
|
||||
pending the pair is locked (`diplomacy_pending`); only the starter can revoke. A pair at `neutral` with nothing pending has no row in
|
||||
`alliance_relations`. Acceptance re-validates against the current state, because the relation may have moved since the proposal.
|
||||
`war -> confed` is not allowed (go through a pact first).
|
||||
|
||||
## S5-3 — Membership lives in two tables, one writer
|
||||
`operators.alliance_id` (from 001, cheap joins in /map, /me) and `alliance_members` (role, joined_at, one leader per alliance by a partial
|
||||
unique index). `alliances.js` addMember/removeMember are the only writers. Alliance rows are hard-deleted on disband; messages keep a
|
||||
`alliance_tag` snapshot and carry no foreign key to alliances so broadcasts survive.
|
||||
|
||||
## S5-4 — Last online comes from tokens
|
||||
No new column: `lastOnline` = newest `tokens.last_used_at` of the member's user, which auth.js refreshes at most once a minute. So it
|
||||
is accurate to about a minute and includes revoked tokens (a logout still counts as having been online).
|
||||
|
||||
## S5-5 — Message rate limit is DB-backed, not the in-memory Limiter
|
||||
`server/http.js` Limiter keys on monotonic real time and forgets on restart; message limits are a product rule that should follow the
|
||||
(fake) clock and survive restarts, so the sender's recent rows in `messages` are counted (`SOCIAL.messageLimits`, indexed by
|
||||
`messages_sender`). The per-token/IP limiters still apply on top.
|
||||
|
||||
## S5-6 — Messages: per-recipient rows, sanitising on write
|
||||
One `messages` row plus one `message_recipients` row per recipient (broadcast fan-out at send time: members who join later do not see
|
||||
old broadcasts; members who leave keep what they received). Read/delete state is per recipient; the sender's copy is hidden with
|
||||
`sender_deleted_at`; the row is purged when nobody has a copy. A blocked sender is silently not delivered to (no row), so blocking does
|
||||
not leak. Text is sanitised once on write (`server/text.js`): C0/C1 controls, bidi overrides and isolates, zero-width and invisible
|
||||
tag characters are stripped, NFC, `\r\n` -> `\n`; ZWJ/ZWNJ are kept for emoji. Clients render with `textContent` only.
|
||||
|
||||
## S5-7 — Rankings are computed per request, no cache
|
||||
Footprint for a whole world comes from two queries (towns, buildings) and `rules.footprintAt`; fine for the expected 50-300 operators.
|
||||
If it ever shows up in a profile, cache per (world, minute). Cursor is a rank offset because rankings are a computed snapshot, not rows.
|
||||
|
||||
## S5-8 — Route params and list order
|
||||
`inviteId`, `noteId`, `proposalId`, `otherId`, `operatorId` were added to `INT_PARAMS` in http.js. Lists that are newest-first (messages)
|
||||
use the last id as the `after` cursor and return older items; this is the one place `after` does not mean "newer than".
|
||||
|
||||
## S3-1 — Online/offline is computed lazily; `powerCheck` only does the side effects
|
||||
Units are offline while the battery is empty and net power is negative. That is derived from the lazy battery value (`power.online`) at
|
||||
the moment it matters (sending, combat, the town view), never from an event having run. The `powerCheck` event (one pending per POP,
|
||||
re-armed by `power.reschedule` after anything that changes unit draw or building levels, including `buildDone`) only writes the
|
||||
"units offline" notification and does the decommission after 24 h / world speed. Offline is all-or-nothing per POP (the contract of
|
||||
`rules.unitsOnline`); the decommission then removes the most expensive units (home first, then reinforcements) until the draw fits the
|
||||
output, not everything. Offline units are neither counted in defence nor hurt by a raid, but a full attack lost by the defender still
|
||||
wipes them. Reinforcements draw from the host (`state.unitDraw` reads `stationed`); units in transit draw from nobody.
|
||||
|
||||
## S3-2 — Research is per POP, speed bonus per operator
|
||||
`town_research(town_id, unit, stat, level)`; level n needs a Research lab of level n + 2, one research at a time per POP. An attack uses a
|
||||
snapshot of the origin POP's research taken at departure (`movements.extra.research`); defenders use the research of the POP each group
|
||||
belongs to. Incumbent sites: +10% research speed per distinct site taken (cap +50%), and a one-time +2500 Hardware per site and operator.
|
||||
Taking a site does not remove it: it stays a static fortress for everybody else.
|
||||
|
||||
## S3-3 — One report row, many recipients; cleanup armed at the earliest expiry
|
||||
A battle is one `reports` row shared through `report_recipients(report_id, user_id, role, read_at)`, so both sides see the same data (a
|
||||
scan is two separate rows: intel for the scanner, "a scan happened" for the target, with the scanner's identity only if the target's
|
||||
scanners won). `reportCleanup` is armed at the earliest `expires_at` (14 days, real time, not divided by world speed) and re-arms itself
|
||||
only while reports remain: at most one pending cleanup per world, none on a quiet world.
|
||||
|
||||
## S3-4 — Arrival re-validates everything and bounces
|
||||
A movement is validated when it is sent and again when it arrives (the target may have changed owner, got protection, joined a pact, the
|
||||
tile may have been taken). If it no longer holds, the units turn around with the loot they carry and the sender gets a `movement_failed`
|
||||
report. Return legs whose origin POP changed hands go to the operator's capital (or oldest POP).
|
||||
|
||||
## S3-5 — Takeover details
|
||||
Only `takeover` movements (with an M&A team) can lower loyalty; one team per attack counts and is used up when it does. `takeoverBlock`:
|
||||
a player's last POP wins over "capital" (refused at send); a capital with siblings is only dragged to loyalty 0. Loot is taken in the same
|
||||
arrival, before the POP changes hands. On transfer the old owner's pending training/research is cancelled, pending builds are re-keyed to
|
||||
the new owner's user, and that POP's units standing elsewhere are re-homed to the old owner's capital. A captured POP keeps its footprint.
|
||||
|
||||
## S3-6 — Transport links
|
||||
`links` = Internet exchange level, each carries 500 (`D.TRANSPORT`). A link is busy while the transport is out and while its empty carriers
|
||||
drive back (a `return` movement with `extra.link`). Cargo above the receiver's Rack hall cap is lost (the notification says how much).
|
||||
`transport` movements keep arbitrary `extra` and `movements.hooks.transportArrived` is called on delivery, so the trade stage needs no
|
||||
change in the movement code.
|
||||
|
||||
## S3-7 — Protection
|
||||
Beginner protection blocks raid/attack/takeover in both directions. Sending one from a protected operator needs `confirmEndProtection`
|
||||
and ends it at once; attacking an incumbent site does not end it; scans never do. The target's protection is compared with the ARRIVAL
|
||||
time at send, and re-checked at arrival.
|
||||
|
||||
## S3-8 — Footprint gate counts the operator's total
|
||||
`footprintNeeded(n)` with n = POPs owned now (second POP: n = 1). Founding and takeover both need `sum(footprint of own POPs) >= need`,
|
||||
nothing is spent. New POPs start with every field at level 0, no infrastructure, 250 of each resource and loyalty 100.
|
||||
|
||||
## 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.
|
||||
|
|
|
|||
397
docs/DEPLOY.md
Normal file
397
docs/DEPLOY.md
Normal file
|
|
@ -0,0 +1,397 @@
|
|||
# Deploying UPSTREAM
|
||||
|
||||
UPSTREAM is one Node process: it serves the static client from `public/`, the REST API under `/api/v1/` and (stage 6)
|
||||
a WebSocket at `/ws`. Unlike NETWALL it **keeps state**: one SQLite file, owned by that process. A restart loses
|
||||
nothing: overdue events are caught up in order before the server accepts traffic.
|
||||
|
||||
```
|
||||
phone / laptop --https--> nginx Proxy Manager (TLS, :443) --http (+ WebSocket)--> Debian 13 LXC: node :8080
|
||||
/opt/upstream (code, read-only)
|
||||
/var/lib/upstream (game.db, backups/)
|
||||
```
|
||||
|
||||
Same shape as NETWALL (`docs/DEPLOY.md` there): same proxy, same hardening notes, same env vars for the network
|
||||
layer. The differences are the Node version (`node:sqlite` needs 22.13+), a state directory and backups.
|
||||
|
||||
**What was and was not run while writing this** (so you know what to check on the real box):
|
||||
|
||||
* **Run:** `systemd-analyze verify` on the three unit files (syntax and directives only), the CLI `tools/admin.js`
|
||||
and its tests on a dev machine (Node 24.21), a backup, verify and prune cycle, `sh -n` on `deploy/upstream-admin`.
|
||||
* **Taken from NETWALL's docs, not re-run for UPSTREAM:** everything about nginx Proxy Manager (labels, header
|
||||
behaviour, "Client addresses"). NETWALL's guide records what was observed against NPM v2.16.0.
|
||||
* **Never run:** a Proxmox LXC, a started unit under systemd, the timer firing on its own, a Node install from the
|
||||
tarball or NodeSource on Debian 13, `rrsync`, Let's Encrypt, a restore on the real box. Treat those steps as a
|
||||
checklist to confirm, and fix this file when reality differs.
|
||||
|
||||
## 1. Requirements
|
||||
|
||||
* Debian 13 (trixie) LXC with its own IPv4 (optionally IPv6) address the proxy can reach. 1 core, 512 MB RAM and 4 GB
|
||||
disk are plenty for a small world; the database grows with the event and notification history (measure it with
|
||||
`upstream-admin status`), and snapshots multiply it by the retention count.
|
||||
* **Node 22.13 or newer.** Debian 13 ships `nodejs` **20.19.2** (checked on tracker.debian.org: stable has 20.19.2,
|
||||
testing and unstable have 24.21). Node 20 has no `node:sqlite`, so `apt install nodejs` is **not enough**. `package.json`
|
||||
says `"engines": {"node": ">=22.13"}`; 22.5 to 22.12 only have `node:sqlite` behind `--experimental-sqlite`, which
|
||||
the unit does not pass. Development is on Node 24.21.
|
||||
* A DNS name for the game (for example `upstream.example.com`) pointing at the proxy.
|
||||
|
||||
### Getting a suitable Node (pick one)
|
||||
|
||||
**A. Official tarball (no third-party apt repo, nothing piped into a shell).** Pick a current 24.x (Active LTS) or
|
||||
22.x from https://nodejs.org/en/download and put its version in `V`:
|
||||
|
||||
```sh
|
||||
apt update && apt install -y curl xz-utils ca-certificates
|
||||
V=24.21.0 # example: use the current 24.x (or >= 22.13) you picked
|
||||
ARCH=linux-x64 # linux-arm64 on ARM hosts (uname -m: aarch64)
|
||||
cd /tmp
|
||||
curl -fsSLO https://nodejs.org/dist/v$V/node-v$V-$ARCH.tar.xz
|
||||
curl -fsSLO https://nodejs.org/dist/v$V/SHASUMS256.txt
|
||||
grep " node-v$V-$ARCH.tar.xz\$" SHASUMS256.txt | sha256sum -c - # must print: ... OK
|
||||
tar -C /opt -xJf node-v$V-$ARCH.tar.xz
|
||||
ln -sfn /opt/node-v$V-$ARCH /opt/node
|
||||
ln -sf /opt/node/bin/node /usr/local/bin/node
|
||||
ln -sf /opt/node/bin/npm /usr/local/bin/npm
|
||||
ln -sf /opt/node/bin/npx /usr/local/bin/npx
|
||||
```
|
||||
|
||||
(For extra assurance also verify the signature of `SHASUMS256.txt` as described on nodejs.org.) An upgrade later is
|
||||
a new tarball and `ln -sfn` to it, then `systemctl restart upstream`. `upstream.service` starts `/usr/bin/env node`, and
|
||||
systemd's default PATH lists `/usr/local/bin` before `/usr/bin`, so the tarball wins over any distro Node.
|
||||
|
||||
**B. NodeSource apt repository** (follows their documentation; not run here). It puts Node in `/usr/bin/node`:
|
||||
|
||||
```sh
|
||||
apt install -y ca-certificates curl gnupg
|
||||
install -d -m 0755 /etc/apt/keyrings
|
||||
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
|
||||
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_24.x nodistro main" > /etc/apt/sources.list.d/nodesource.list
|
||||
apt update && apt install -y nodejs # includes npm; do not also install Debian's npm package
|
||||
```
|
||||
|
||||
**Verify either way** (all three must succeed):
|
||||
|
||||
```sh
|
||||
node --version # v22.13.0 or newer
|
||||
node -e "require('node:sqlite'); console.log('node:sqlite ok')"
|
||||
which -a node # the first one is the one the unit will use
|
||||
```
|
||||
|
||||
On 22.x/24.x Node may print `ExperimentalWarning: SQLite is an experimental feature` to stderr; that is harmless (it
|
||||
shows up in the journal once per start). `No such built-in module: node:sqlite` means Node is too old (or it is the
|
||||
distro's 20.x earlier on the PATH). If `node:sqlite` ever misbehaves, `DECISIONS.md` D1 describes the one-file swap
|
||||
to `better-sqlite3` in `server/db.js`; that would add a native dependency and a build toolchain to the LXC.
|
||||
|
||||
## 2. Create the LXC (Proxmox)
|
||||
|
||||
Container creation, the Proxmox UI way (CLI `pct create` works too):
|
||||
|
||||
* Template `debian-13-standard`, **unprivileged**, hostname `upstream`, 1 core, 512 MB RAM (+256 MB swap), 4-8 GB disk.
|
||||
* Network: a static address (or a DHCP reservation) on a bridge the NPM host can reach. The proxy forwards to that
|
||||
address, so it must not change.
|
||||
* Features: **Nesting** is optional; tick it only if you want the namespace-based hardening block in the unit
|
||||
(section 3). Everything else works without it.
|
||||
* Start on boot: yes. Timezone does not matter: the game uses UTC ms, the backup timer uses the container's clock.
|
||||
* Proxmox's own CT backups (`vzdump`) are not a substitute for the snapshots in section 7: a running-container copy of
|
||||
a SQLite file is crash-consistent at best. Use them for the OS and let the verified snapshots be the data backup.
|
||||
|
||||
## 3. Install in the LXC
|
||||
|
||||
Run as root inside the container (Node from section 1 is already in place).
|
||||
|
||||
```sh
|
||||
apt install -y rsync # for the copy below (or use git)
|
||||
|
||||
# a dedicated, login-less user that only runs the game
|
||||
useradd --system --home-dir /var/lib/upstream --shell /usr/sbin/nologin upstream
|
||||
|
||||
# code: read-only for the service user, owned by root
|
||||
mkdir -p /opt/upstream
|
||||
# from your workstation:
|
||||
# rsync -a --delete --exclude node_modules --exclude .git --exclude data --exclude e2e ./ root@<lxc>:/opt/upstream/
|
||||
# (needs server/, public/, tools/, deploy/, docs/, package.json, package-lock.json; `test/` is optional)
|
||||
cd /opt/upstream
|
||||
npm ci --omit=dev # only "ws"; follows the lockfile exactly
|
||||
chown -R root:root /opt/upstream
|
||||
|
||||
# the admin helper on the PATH
|
||||
install -m 0755 /opt/upstream/deploy/upstream-admin /usr/local/bin/upstream-admin
|
||||
|
||||
# optional settings / secrets file (read by the unit and by upstream-admin)
|
||||
install -d -m 0750 -o root -g upstream /etc/upstream
|
||||
install -m 0640 -o root -g upstream /dev/null /etc/upstream/upstream.env
|
||||
# edit it: SIGNUP_CODE=choose-a-long-random-string
|
||||
# ALLOWED_ORIGINS=https://upstream.example.com
|
||||
|
||||
# the units
|
||||
install -m 0644 /opt/upstream/deploy/upstream.service /opt/upstream/deploy/upstream-backup.service /opt/upstream/deploy/upstream-backup.timer /etc/systemd/system/
|
||||
systemctl daemon-reload
|
||||
systemctl enable --now upstream upstream-backup.timer
|
||||
systemctl status upstream
|
||||
journalctl -u upstream -f
|
||||
```
|
||||
|
||||
The first start prints `applied migrations: 001_init.sql, ...`, `created world 1` and the listen banner with
|
||||
`database: /var/lib/upstream/game.db`. Quick manual run as the service user instead of systemd (Ctrl-C to stop):
|
||||
`runuser -u upstream -- env PORT=8080 DB_PATH=/var/lib/upstream/game.db node /opt/upstream/server/index.js`.
|
||||
|
||||
### What the units do
|
||||
|
||||
* `deploy/upstream.service`: user `upstream`, `WorkingDirectory=/opt/upstream`, `StateDirectory=upstream` (systemd creates
|
||||
`/var/lib/upstream` owned by that user, mode 0700, so the game can write nowhere else), `Restart=on-failure`,
|
||||
`EnvironmentFile=-/etc/upstream/upstream.env` (overrides the `Environment=` lines), `UMask=0077` (database and
|
||||
snapshots hold password hashes: owner-only).
|
||||
* Hardening that works in any container: `NoNewPrivileges`, empty capability set (port 8080 needs none),
|
||||
`RestrictAddressFamilies`, `RestrictRealtime`, `RestrictSUIDSGID`, `LockPersonality`, `SystemCallArchitectures`.
|
||||
No `MemoryDenyWriteExecute` (V8 would crash).
|
||||
* The namespace block (`ProtectSystem=strict`, `ReadWritePaths=/var/lib/upstream`, `PrivateTmp`, ...) is commented out.
|
||||
In an unprivileged LXC it fails with `status=226/NAMESPACE` unless **Options > Features > Nesting** is on. Because the
|
||||
app writes to disk, `ProtectSystem=strict` needs the `ReadWritePaths=` line that is already next to it in the unit;
|
||||
without it the database cannot be opened.
|
||||
* Shutdown: SIGTERM stops the scheduler timer, closes the listener and the database and exits 0 in about a second.
|
||||
Even a SIGKILL or power cut is survivable (WAL replay on the next open, then overdue events are caught up).
|
||||
* `deploy/upstream-backup.service` (oneshot) and `.timer`: see section 7.
|
||||
|
||||
## 4. Configuration
|
||||
|
||||
Environment variables read by `node server/index.js`. Put changes in `/etc/upstream/upstream.env` (`KEY=value`, one per
|
||||
line, no `export`) or in a `systemctl edit upstream` override, then `systemctl restart upstream`.
|
||||
|
||||
| Variable | Default (unit) | Meaning |
|
||||
|---|---|---|
|
||||
| `PORT` | `8080` | TCP port. Unprivileged, so no capabilities needed. `0` picks a free one (banner prints it). |
|
||||
| `HOST` | `::` | Bind address. `::` = one dual-stack socket for IPv4 and IPv6 (falls back to `0.0.0.0` if the kernel has no IPv6). `127.0.0.1` = this container only. |
|
||||
| `DB_PATH` | `/var/lib/upstream/game.db` | SQLite file. The code default is `./data/game.db`; the unit overrides it. Its directory is created if missing, it must be writable by the service user. `-wal` and `-shm` files appear next to it: always copy via a snapshot (section 7), never with `cp` while running. |
|
||||
| `TRUST_PROXY` | `auto` | `auto`: believe `X-Forwarded-For` / `X-Forwarded-Host` only from loopback / private-range peers. `1`: always (then firewall the port). `0`: never. Used for the per-IP rate limits and the log. |
|
||||
| `TRUSTED_PROXIES` | empty | Extra IPs / CIDRs `auto` believes: needed when the proxy reaches the LXC from a global IPv6, Tailscale / CGNAT `100.64.0.0/10` or another routable address. |
|
||||
| `ALLOWED_ORIGINS` | empty | Extra origins for the WebSocket origin check (stage 6), comma separated, with the port when it is not 80/443. The REST API uses bearer tokens (no cookies) and does not check origins. |
|
||||
| `MAX_CONN_PER_IP` | `40` | Open connections per client address (WebSocket cap, stage 6). `0` disables. |
|
||||
| `WORLD_SPEED` | unset (1) | World speed multiplier, **first boot only**, when the database has no world yet. |
|
||||
| `WORLD_RADIUS` | unset (50) | Map radius in tiles (coordinates `-R..R`, so 50 = 101 x 101), **first boot only**. |
|
||||
| `WORLD_NAME` | unset (`World 1`) | Name of the first world, **first boot only**. |
|
||||
| `SIGNUP_CODE` | empty | If set, `POST /auth/signup` needs `"invite": "<this>"` in the body or answers `signup_closed` (403). Empty = open signup. Keep it in `/etc/upstream/upstream.env`, not in the unit file. |
|
||||
| `UPSTREAM_DIR`, `UPSTREAM_ENV_FILE` | `/opt/upstream`, `/etc/upstream/upstream.env` | Only for the `upstream-admin` wrapper. |
|
||||
|
||||
Fixed in code (options of `createServer()`): per-IP and per-token rate limits (login and signup are stricter: about one
|
||||
per 10 s sustained, burst 8, per client address), 32 KB request bodies, idempotency keys pruned hourly.
|
||||
|
||||
### First boot
|
||||
|
||||
An empty or missing database is created, all migrations are applied, and **one world is created** from `WORLD_SPEED`,
|
||||
`WORLD_RADIUS`, `WORLD_NAME` (seed random). After that those variables are ignored: changing them does not touch the
|
||||
existing world. More worlds, a different seed, ending or resetting a world are admin tasks (section 6). The first
|
||||
player to sign up becomes an ordinary operator; there is no special admin account, admin work is the CLI on the box.
|
||||
|
||||
## 5. nginx Proxy Manager
|
||||
|
||||
In NPM: **Hosts > Proxy Hosts > Add Proxy Host**.
|
||||
|
||||
| Tab / field | Value |
|
||||
|---|---|
|
||||
| Details: Domain Names | `upstream.example.com` |
|
||||
| Details: Scheme | `http` |
|
||||
| Details: Forward Hostname / IP | the LXC's address (for example `192.168.1.51`), not `127.0.0.1` when NPM runs elsewhere or in its own container |
|
||||
| Details: Forward Port | `8080` |
|
||||
| Details: Cache Assets | **off** (static files are `no-cache` and revalidated by ETag; the game must see new versions) |
|
||||
| Details: Block Common Exploits | optional |
|
||||
| Details: **Websockets Support** | **on.** The REST game works without it, but stage 6 adds `/ws` and it fails with HTTP 426 when this is off. Switch it on now so you do not forget. |
|
||||
| Custom Locations | none needed |
|
||||
| SSL | Request a new Let's Encrypt certificate, **Force SSL**, **HTTP/2** (HSTS optional) |
|
||||
| Advanced (gear) | nothing required; optional gzip below |
|
||||
|
||||
Optional, Advanced box, to compress JS/JSON for phones (the Node server does not compress; NPM's own `gzip on` only
|
||||
covers HTML):
|
||||
|
||||
```nginx
|
||||
gzip on;
|
||||
gzip_types text/css text/javascript application/javascript application/json application/manifest+json image/svg+xml;
|
||||
```
|
||||
|
||||
Notes carried over from NETWALL's setup (observed there against NPM v2.16.0, not re-run for UPSTREAM):
|
||||
|
||||
* NPM sends `Host` **without the public port** and no `X-Forwarded-Host`. On a public port other than 443 the browser
|
||||
`Origin` then differs from `Host`; list the origin with its port in `ALLOWED_ORIGINS` (matters for `/ws`).
|
||||
* A proxy on a non-private address (global IPv6, Tailscale) is not believed by `TRUST_PROXY=auto`: every player then
|
||||
shares one rate-limit budget and the log shows the proxy's address. Fix: `TRUSTED_PROXIES=<its address or CIDR>`.
|
||||
* Clients on your own LAN can pick their address through NPM's `real_ip` handling, so the per-IP limits protect against
|
||||
public abuse, not against LAN users.
|
||||
* **Heads-up for stage 6:** NPM's default `proxy_read_timeout` is 90 s. NETWALL never idles because it streams 20
|
||||
snapshots a second; UPSTREAM's socket will be quiet for long stretches. The WebSocket server must send a ping
|
||||
well under 90 s (NETWALL's pings every 25 s), or the proxy drops idle players.
|
||||
|
||||
Firewall and dual stack: identical to NETWALL (`docs/DEPLOY.md` there, section 6): only the proxy needs to reach port
|
||||
8080. `curl -i http://127.0.0.1:8080/healthz` and `curl -gi 'http://[::1]:8080/healthz'` check both families.
|
||||
|
||||
## 6. Operating: `upstream-admin`
|
||||
|
||||
`tools/admin.js` is the operator CLI (Node core only, uses the game's own `db.js`, `state.js`, `rules.js`).
|
||||
`deploy/upstream-admin` runs it as the service user against the service's database (it reads `DB_PATH` from
|
||||
`/etc/upstream/upstream.env`). **Do not run `node tools/admin.js` as root**: SQLite would create `game.db-wal` and
|
||||
`-shm` owned by root and the game could no longer open its database (symptom in section 10).
|
||||
|
||||
```sh
|
||||
upstream-admin help
|
||||
upstream-admin status # file, size, migrations, overdue events
|
||||
upstream-admin worlds
|
||||
upstream-admin create-world --name "Summer" --speed 2 --radius 60 --seed 1234 --end-in 90d
|
||||
upstream-admin end-world 1 --yes
|
||||
upstream-admin users [--banned] # no hashes or tokens are ever printed
|
||||
upstream-admin operators [--world 1]
|
||||
upstream-admin ban mallory # sets banned, revokes all tokens: old tokens give 401, login 403
|
||||
upstream-admin unban mallory
|
||||
upstream-admin revoke-tokens ada # log out everywhere
|
||||
upstream-admin inspect-operator ada # (--world N when the name exists in several worlds, --id N by operator id)
|
||||
upstream-admin inspect-town 12 # resources now (rules.resourcesAt), buildings, queue, units if the table exists
|
||||
upstream-admin events --pending [--type buildDone --town 12 --limit 100]
|
||||
upstream-admin replay-events --until +6h # dry run: what the scheduler would process, in order
|
||||
upstream-admin replay-events --until +6h --simulate # + run the real handlers on a scratch copy, report outcome and follow-ups
|
||||
upstream-admin backup /var/lib/upstream/backups --keep 14
|
||||
upstream-admin verify-backup /var/lib/upstream/backups/upstream-20261011T041500Z.db
|
||||
upstream-admin grant 12 --fiber 5000 --capital 2000 --yes # testing only
|
||||
upstream-admin reset-world 1 --yes-destroy --backup /var/lib/upstream/backups --new-seed
|
||||
upstream-admin migrate # apply pending migrations without starting the server
|
||||
```
|
||||
|
||||
All commands take `--json` (machine output) and `--db FILE` (otherwise `$DB_PATH`, otherwise `./data/game.db`).
|
||||
Exit codes: `0` ok, `1` failed, `2` usage error **or a destructive command missing its flag**, `3` not found.
|
||||
|
||||
Safety rules the CLI follows:
|
||||
|
||||
* Destructive or test-only commands refuse without a flag: `end-world` and `grant` need `--yes`; `reset-world`
|
||||
needs `--yes-destroy` (without it, it prints what it would delete and exits 2). `ban`, `unban`, `revoke-tokens` are
|
||||
reversible and need none.
|
||||
* `reset-world` deletes the world's game rows (everything with a `world_id`, plus tables pointing at them: towns,
|
||||
buildings, events, operators, alliances, messages, ... discovered from the schema, so tables added by later stages
|
||||
are covered) and **keeps accounts and tokens**; players must join the world again. It resets `start_at`, clears
|
||||
`end_at` and sets the world running. It rolls back if it would leave dangling references. Stop the game first
|
||||
(`systemctl stop upstream`): the server does not know the world was swept while it is running. Use `--backup DIR`.
|
||||
* Everything runs on a running server's database: writes are single short `BEGIN IMMEDIATE` transactions, the
|
||||
connection is always closed, and SQLite's 5 s busy timeout covers collisions with the game (`database is locked`
|
||||
from the CLI just means: try again).
|
||||
* `grant` adds to the town's stored amounts (valid at its `res_at`); the lazy model carries them forward. Amounts above
|
||||
the Rack hall cap are kept but stop growing, like a lowered cap.
|
||||
* `inspect-town` shows values as of now **ignoring** overdue events; it says so when there are any (server stopped).
|
||||
|
||||
## 7. Backups and restore
|
||||
|
||||
`upstream-backup.timer` runs `upstream-backup.service` daily at 04:15 (10 min jitter, `Persistent=true`). It runs
|
||||
`tools/admin.js backup /var/lib/upstream/backups --keep 14` as the service user. A snapshot is:
|
||||
|
||||
1. `VACUUM INTO` a temporary `.partial-*` file: a consistent copy as of one moment, safe while the game runs (WAL readers do
|
||||
not block the writer; the game keeps its own 5 s busy timeout);
|
||||
2. verified: opened read-only, `PRAGMA integrity_check` = `ok`, `worlds` and `schema_migrations` present;
|
||||
3. published under a dated name `upstream-YYYYMMDDTHHMMSSZ.db` (UTC) with a hard link, so an existing file is never
|
||||
replaced (a same-second collision becomes `...Z-1.db`), mode 0600;
|
||||
4. only then older snapshots are pruned: `--keep N` keeps the newest N, `--keep-days D` keeps those younger than D days,
|
||||
both = survive if either keeps it, neither = no pruning. The newest snapshot and any file not matching the naming
|
||||
pattern are never deleted. A failed verification leaves nothing behind and prunes nothing, and the unit fails
|
||||
(`systemctl status upstream-backup`, `journalctl -u upstream-backup`).
|
||||
|
||||
Snapshots are plain SQLite files (journal mode `delete`), not `-wal` dependent: copy a single file.
|
||||
|
||||
```sh
|
||||
systemctl list-timers upstream-backup.timer # next run
|
||||
systemctl start upstream-backup # one right now
|
||||
journalctl -u upstream-backup -n 20
|
||||
ls -l /var/lib/upstream/backups
|
||||
```
|
||||
|
||||
Change the schedule or retention with `systemctl edit upstream-backup.timer` / `upstream-backup.service` (for every
|
||||
6 hours: `OnCalendar=*-*-* 00/6:15:00` and a larger `--keep`). Before an upgrade or a `reset-world`, take one by hand.
|
||||
|
||||
### Off-box copy
|
||||
|
||||
Snapshots on the same disk die with the container. Pull them from another machine (NAS, workstation, the Proxmox host),
|
||||
for example from cron or a timer there:
|
||||
|
||||
```sh
|
||||
rsync -a --ignore-existing root@<lxc>:/var/lib/upstream/backups/ /srv/backups/upstream/
|
||||
```
|
||||
|
||||
`--ignore-existing` makes it append-only on your side (nothing already stored is overwritten, and snapshots pruned on
|
||||
the LXC stay on the backup host until you decide otherwise). Better than a root key: a dedicated key restricted in
|
||||
`authorized_keys` to `command="rrsync -ro /var/lib/upstream/backups",restrict ...` (`rrsync` comes with the `rsync`
|
||||
package; not run here). The files are owner-only (`upstream`), so the reading user needs root or a group ACL.
|
||||
|
||||
### Restore
|
||||
|
||||
The restore is a file copy, and the time model makes it clean: the restored world simply fast-forwards. Every event that
|
||||
fell due since the snapshot is processed in order at start-up, each at its own due time. What is lost is what players did after
|
||||
the snapshot (builds started, signups, messages) and their tokens: players log in again.
|
||||
|
||||
```sh
|
||||
systemctl stop upstream-backup.timer upstream
|
||||
upstream-admin verify-backup /var/lib/upstream/backups/upstream-20261011T041500Z.db # exit 0 or stop here
|
||||
mkdir -p /var/lib/upstream/pre-restore
|
||||
mv /var/lib/upstream/game.db* /var/lib/upstream/pre-restore/ 2>/dev/null # keep the old one, incl. -wal/-shm
|
||||
install -o upstream -g upstream -m 0600 /var/lib/upstream/backups/upstream-20261011T041500Z.db /var/lib/upstream/game.db
|
||||
systemctl start upstream upstream-backup.timer
|
||||
journalctl -u upstream -n 20 # look for "caught up N overdue event(s)"
|
||||
upstream-admin status
|
||||
```
|
||||
|
||||
Restoring onto another machine works the same way (install code and Node, copy the file to `DB_PATH`). Migrations in
|
||||
the snapshot are checksummed: if the code is newer than the snapshot, the missing migrations are applied at boot; run
|
||||
code that is **older** than the snapshot's last migration (`upstream-admin status` shows it) only if you know the schema
|
||||
still fits, the server does not check for that.
|
||||
|
||||
## 8. Upgrading
|
||||
|
||||
```sh
|
||||
upstream-admin backup /var/lib/upstream/backups --keep 14 # 1. snapshot first
|
||||
rsync -a --delete --exclude node_modules --exclude .git --exclude data ./ root@<lxc>:/opt/upstream/ # 2. new code (from your workstation)
|
||||
cd /opt/upstream && npm ci --omit=dev && chown -R root:root /opt/upstream # 3. dependencies, ownership
|
||||
systemctl restart upstream # 4. migrations apply at boot
|
||||
journalctl -u upstream -n 30 # 5. "applied migrations: ..." then the listen banner
|
||||
curl -i http://127.0.0.1:8080/healthz
|
||||
```
|
||||
|
||||
* Migrations are `server/migrations/NNN_name.sql`, applied in order inside a transaction each, **recorded with a
|
||||
checksum and never edited after they shipped**. If one that was applied has changed, the server refuses to start
|
||||
(`migration 001_init.sql was edited after it was applied`): restore that file from git and ship a **new** numbered
|
||||
migration instead. `upstream-admin status` lists applied and pending migrations; `upstream-admin migrate` applies
|
||||
them without starting the game.
|
||||
* Each migration runs in its own transaction: a failing one rolls back and the server exits, earlier ones of the same
|
||||
boot stay applied. Going back to the old code after a migration committed means restoring the pre-upgrade snapshot
|
||||
(section 7).
|
||||
* Updated unit files: `install -m 0644 ...`, `systemctl daemon-reload`, `systemctl restart upstream`.
|
||||
* Players reconnecting after the restart need no action; clients get `serverTime` in every response and refetch.
|
||||
|
||||
## 9. Health, logs, checks
|
||||
|
||||
```sh
|
||||
curl -i https://upstream.example.com/healthz # 200 ok (only says the process answers HTTP)
|
||||
curl -I https://upstream.example.com/ # 200 + Content-Security-Policy
|
||||
upstream-admin status # database, migrations, events pending / OVERDUE
|
||||
journalctl -u upstream -f # live log; -p err for failures only
|
||||
journalctl -u upstream --since "1 hour ago" | grep -E "failed|refused"
|
||||
```
|
||||
|
||||
The log has: applied migrations, created world, caught-up events, `refused rate_limited(...) ip=...`, and
|
||||
`event N (type) failed: ...` for a handler that threw (that event is marked `failed` and the queue moves on; list them
|
||||
with `upstream-admin events --status failed`). Player IP addresses appear in the log; passwords and tokens never do.
|
||||
A healthy server has **no overdue events** in `status`: the timer processes events within milliseconds of their due time.
|
||||
|
||||
## 10. Troubleshooting
|
||||
|
||||
| Symptom | Cause and fix |
|
||||
|---|---|
|
||||
| Service dies at start: `No such built-in module: node:sqlite` | Node is older than 22.13, or the distro's Node 20 is first on the PATH. `node --version`, `which -a node`, section 1. |
|
||||
| `ExperimentalWarning: SQLite is an experimental feature` in the journal | Harmless. Printed once per start on some Node versions. |
|
||||
| `SQLITE_CANTOPEN` / `unable to open database file` | `DB_PATH`'s directory is not writable by `upstream`: wrong path in `upstream.env`, `/var/lib/upstream` created by hand with other ownership (`chown -R upstream:upstream /var/lib/upstream`), or `ProtectSystem=strict` enabled without `ReadWritePaths=/var/lib/upstream`. |
|
||||
| `attempt to write a readonly database` / `unable to open database file` right after using the CLI | `admin.js` was run as root and left root-owned `game.db-wal` / `-shm`. Stop the game, `chown upstream:upstream /var/lib/upstream/game.db*`, start. Use `upstream-admin`, which switches user. |
|
||||
| `migration NNN_x.sql was edited after it was applied` | An applied migration changed on disk (checksum mismatch). Restore it from git; changes go in a new migration. |
|
||||
| `UPSTREAM failed to start: ...` with `EADDRINUSE` | Another process on the port (`ss -ltnp \| grep 8080`) or two copies. Change `PORT` and the NPM forward port together. |
|
||||
| `IPv6 is not available (...); falling back to 0.0.0.0` | The kernel has no IPv6. IPv4 keeps working; set `HOST=0.0.0.0` to silence it. |
|
||||
| `status=226/NAMESPACE` | The optional namespace hardening is on in an LXC without Nesting: enable **Options > Features > Nesting** and restart the CT, or comment the block out. |
|
||||
| `Cannot find module 'ws'` | `npm ci --omit=dev` was not run in `/opt/upstream`. |
|
||||
| 502 Bad Gateway from NPM | Upstream unreachable: `systemctl status upstream`, `curl -i http://<lxc>:8080/healthz` from the NPM host, forward IP/port, firewall. |
|
||||
| Page loads but a new deploy still shows the old client | NPM *Cache Assets* is on, or a service layer ignores `no-cache`. Switch it off, hard-reload. |
|
||||
| Signup answers 403 `signup_closed` | `SIGNUP_CODE` is set. Send `{"invite": "<code>"}` in the signup body, or unset it and restart. |
|
||||
| Login/signup answers 429 `rate_limited` for many players | They all arrive from one address: the proxy is not trusted so the per-IP budget is shared (log says `ip=<the proxy>`). Set `TRUSTED_PROXIES`. Login and signup allow about one request per 10 s per address, burst 8; a whole classroom behind one NAT can hit that. |
|
||||
| Game seems frozen: builds never finish | `upstream-admin status`: `OVERDUE` events mean the scheduler is not running (server stopped or stuck) or handlers fail: `upstream-admin events --status failed`, journal `event N ... failed`. A restart catches up everything in order. |
|
||||
| Banned user still plays | They cannot: `ban` revokes every token and blocks login. Check the username spelling (`upstream-admin users --banned`). |
|
||||
| `database is locked` from the CLI | The game held a write lock longer than the 5 s busy timeout. Retry. |
|
||||
| `upstream-backup.service` failed | `journalctl -u upstream-backup`. Typical: disk full, or the integrity check of the new snapshot failed (then nothing was kept and nothing pruned; check the disk and the `game.db` itself). |
|
||||
| Backups not appearing | `systemctl list-timers upstream-backup.timer`; the timer must be **enabled** (`systemctl enable --now upstream-backup.timer`), not just installed. |
|
||||
| World reset by mistake | Restore the snapshot taken before (section 7), or the one `reset-world --backup` wrote. |
|
||||
| (stage 6) WebSocket upgrade answered 426 / 403 / 429 | 426: **Websockets Support** off in NPM. 403: origin check, see `ALLOWED_ORIGINS` and the notes in section 5. 429: more than `MAX_CONN_PER_IP` sockets from one address. |
|
||||
|
|
@ -184,6 +184,27 @@ POP view (buildings + queue), Resource view (slots), Map (pan/zoom, tile info, s
|
|||
station, movements list), Reports, Messages, Alliance, Exchange, Rankings, Profile/settings. Every countdown is
|
||||
computed from `serverTime`.
|
||||
|
||||
## Stage 3/4 clarifications (what the server does, where DESIGN.md was silent)
|
||||
|
||||
- **Training/research:** training time = unit time x count / (1 + 0.03 x level of the training building) / world speed; batches of one
|
||||
building queue one after another. Research cost = 8 x the unit's cost x 1.35^(level-1), time 30 min x 1.3^(level-1) / (1 + 0.03 x lab
|
||||
level); research level n needs Research lab n + 2.
|
||||
- **Roles per movement:** scan = port scanners only; raid = attackers and defenders (no siege); attack = + DDoS rigs and exploit kits;
|
||||
takeover = + M&A teams (at least one); reinforce = anything that moves; settle = exactly three Rollout crews. Honeypots never move.
|
||||
- **Combat:** formulas as above; ties go to the defender; a unit group loses `round(n x fraction)` per type. Raid: BOTH sides lose
|
||||
`0.5 x (weaker/stronger)^1.5` whoever wins. Defenders are home crews plus each reinforcement group (own research each), counted only
|
||||
while online. The cold-spare cache applies to raids only; a full attack takes loot from the whole stock. Loot is split evenly over Fiber,
|
||||
Hardware, Capital, leftovers going to the others, capped by the survivors' carry. Exploit kits count by survivors.
|
||||
- **Scan:** `sa` vs `sd` = scanners x (1 + 5% per defence-research level of port_scanner). Success needs `sa > sd`; `detail` is `basic`
|
||||
(units, resources) and `full` at 2:1 (+ buildings, loyalty, the target's outgoing movements with their types). A failed scan loses all
|
||||
scanners and reveals the scanner to the target; a successful one loses `0.5 x (sd/sa)^1.5`.
|
||||
- **Incumbent site defence:** `600 x (1 +- 25% per site, seeded) x (1 + 4% x world days)`, world days = real days x speed; sites are scanned
|
||||
or attacked, never raided or taken over, and never fight back.
|
||||
- **Power:** when the battery is empty and net power is negative, all units in that POP are offline; after 24 h / speed the most
|
||||
expensive are decommissioned until the draw fits.
|
||||
- **Transport:** 12 tiles/h, 500 per link, links = Internet exchange level; a link is busy until the empty carriers are back.
|
||||
- **Protection and recall:** see S3-4 and S3-7 in DECISIONS.md; the recall window is 90 s of real time (not divided by world speed).
|
||||
|
||||
## Open questions
|
||||
|
||||
- One or two defence stats per unit?
|
||||
|
|
|
|||
59
docs/NEXT.md
59
docs/NEXT.md
|
|
@ -7,5 +7,64 @@ Honest status, updated at the end of every stage.
|
|||
- Stage 1 economy (server): lazy resources, buildings, build queue, storage caps, power battery.
|
||||
- Stage 2 world (server): seeded tiles, spawn ring, map viewport query.
|
||||
|
||||
## Stage 5 (partial): social, server only
|
||||
Built (migration `003_social.sql`): alliances (found, invite/accept/decline/cancel, leave, kick, roles, leader transfer, disband,
|
||||
pinned notes, member list with POP count and last online), diplomacy between alliances (war, neutral, NAP, confederation;
|
||||
proposals; 24 h / speed pact cancel through the `diploChange` event; revoke), messages (DM, alliance broadcast, inbox/outbox/thread/
|
||||
alliance feed, read, delete own copy, block list, DB-backed rate limit, text sanitising), rankings (operators, alliances, battles),
|
||||
`alliance` in `/me` and `/map`, lookup helpers in `server/alliances.js` (`operatorRelation`, `atWar`, `confederated`, `pactPartners`).
|
||||
Tests: `test/social-*.test.js` (pure rules, alliances, diplomacy with the fake clock and event queue, messages, rankings), every
|
||||
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).
|
||||
- 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.
|
||||
|
||||
## Stage 3/4: military and expansion (server only)
|
||||
Built (migration `002_military.sql`: `town_units`, `stationed`, `town_research`, `town_power`, `movements`, `reports`, `report_recipients`,
|
||||
`operator_stats`, `incumbent_takes`): 10 unit types and research in `data.js`/`rules.js`; training queue (`trainDone` per batch,
|
||||
sequential per building); research (`researchDone`); movements scan/raid/attack/takeover/reinforce/settle/transport with latency, ETA,
|
||||
recall (90 s), return legs with loot; combat resolved at arrival in the event queue (full attack, raid, firewall vs DDoS rigs, exploit
|
||||
kits on a chosen building, loot with Rack hall cache, losses, reinforcements, research, battle points in `operator_stats`);
|
||||
scans with intel and detection; takeover with loyalty, capital and last-POP protection, footprint gate; founding POPs with wild-slot
|
||||
choice; incumbent sites (static defence growing with world age, one-time Hardware bonus, +10% research speed per site); beginner
|
||||
protection (both directions, re-checked at arrival); power: offline units when the battery is empty, decommission after 24 h
|
||||
(`powerCheck`); incoming warnings with hidden type; reports (shared row, per-user read flag, 14 day cleanup event); transport movement
|
||||
and arrival hook (`movements.hooks.transportArrived`) for the trade stage. Routes: see docs/API.md, all in `docs/openapi.json`.
|
||||
Tests: `test/military-*.test.js` (rules as pure functions, train queue order, raid end to end, event order and determinism, takeover and
|
||||
its protections, offline units and decommission, restart catch-up from a reopened DB file, protection, settle, incumbent, transport,
|
||||
recall, research, reports/cursor/retention, API smoke over HTTP). Fake clock, in-memory DB, port 0; no Playwright.
|
||||
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).
|
||||
- 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.
|
||||
|
||||
## Client (stages 1-2 web client)
|
||||
Built: `public/` vanilla JS, no build step, strict-CSP friendly (no inline scripts or handlers, no external requests).
|
||||
- Shell (`js/main.js`): session, `App.registerScreen({id, titleKey, navKey, icon, hud, render, onShow, onHide, onLang})`, bottom nav
|
||||
(left rail in landscape and on wide screens), live resource bar ticked with `rules.resourcesAt` from the server clock, hash routing.
|
||||
- Screens (`js/screens/`): login/signup (invite field appears after `signup_closed`), POP (resource fields by type, infrastructure,
|
||||
build queue with countdowns and cancel, power panel, detail sheet with the server's `next` plan, live affordability, rename),
|
||||
map (`js/render.js` canvas: pan, pinch, wheel, keyboard, culling; chunked `GET /map` cache; tile info sheet), alerts
|
||||
(`GET /notifications`), settings (language, device tokens + revoke, logout).
|
||||
- `js/api.js`: bearer token, serverTime offset, retry/backoff (network, 429 + Retry-After, 502-504), `Idempotency-Key` per intent,
|
||||
`ApiError.code`, event emitter with a reserved `push` event (no WebSocket client yet).
|
||||
- `js/i18n.js`: en + nb, all player-facing names; `PWA`: manifest + icons (no service worker, so no offline mode).
|
||||
- Tests: `test/client-i18n.test.js` (key parity, names, error codes, formatting), `test/client-api.test.js` (retry, idempotency, offset).
|
||||
- Looked at with headless Chromium screenshots (phone portrait, phone landscape, desktop) and one scripted signup/build/cancel/map-tap
|
||||
flow on a phone profile. Not run: real devices, Safari/iOS, Playwright suite.
|
||||
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.
|
||||
|
||||
## Not done
|
||||
- Everything else. See CLAUDE.md "Working in stages".
|
||||
|
|
|
|||
6600
docs/openapi.json
6600
docs/openapi.json
File diff suppressed because it is too large
Load diff
Loading…
Add table
Add a link
Reference in a new issue