|
|
|
|
@@ -979,10 +979,10 @@ Each phase ends with its findings written down, as every workstream here does.
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
| 0 | **The rig.** ✅ **Done 2026-09-15 — as built and findings in §12.** Updated to the current wipe (the script was fixed *again*, properly), Oxide re-laid, base set installed, the grant path proven end to end and both zone transitions observed live with a player connected. **Both criteria met** | docs | A current server boots with all four loaded, `oxide.grant` demonstrably gates something, and a test zone reports who is standing in it |
|
|
|
|
|
| 1 | **Protocol 1, three skeletons, and every bundle seam at once.** ✅ **Done 2026-09-15 — as built and findings in §13.** Plugin, sidecar and module all exist and all three were exercised against the live rig; three org-lead decisions (§13.0), five defects only a running server found (§13.3), and a correction to §11.3 (§13.2). **Both criteria met** | all 3 + docs | One hello line travels game -> sidecar -> module; killing the sidecar does not stall the game; all five guards green on an untouched skeleton |
|
|
|
|
|
| 2 | **Packaging and release.** `release.yml`, the install manifest, the `sha256`, the host allowlist — and a real install into a running core from a manifest URL | Module-Rust + docs | An operator installs the empty module from Admin -> Modules and it reaches `started` |
|
|
|
|
|
| 3 | **The read path, on both frameworks.** First hook wave from [`HOOKS.md`](HOOKS.md); events and snapshots distinct at the wire; `wipe_id` **and server id** on every row (R8); all-time rollups (R12); every board re-emitted on connect. **First phase to run against the Carbon rig (R19/R21)** — it turns [`CARBON.md`](CARBON.md) from a source-read hypothesis into tested fact, including whether the 13 unlisted hook names are renames or holes | all 3 + docs | A restarted sidecar is fully populated within one connection, a wipe does not erase a player's history, and **the same plugin file does all of that on Oxide and on Carbon** |
|
|
|
|
|
| 4 | **The first pages.** Server list as the landing page, `/rust/servers/:id` beneath it, killfeed, leaderboard; nav rows; the UI kit (`PublicLayout` `shell`, `PageHeader` props); `capabilities`; the `site.footer.status` slot (R13) | Module-Rust | The site renders the last thing each server said while every server is off |
|
|
|
|
|
| 5 | **Android leg A** (R10). Capability-driven shell from `GET /api/v1/public/modules`, plus the phase-4 screens | Android-app | The app renders a Rust site it has never seen, and a UO site unchanged |
|
|
|
|
|
| 2 | **Packaging and release.** ✅ **Done 2026-09-16 — as built and findings in §15.** `release.yml` *and* the gate that was missing entirely (`pr-checks.yml`, including the frozen-manifest job); the include list with two readers; `v0.1.0` published and installed into a running core from its manifest URL. Three org-lead decisions (§15.0), and the first proof by a core that `/rust` collides with nothing (§15.2). **Criterion met** | Module-Rust + docs | An operator installs the empty module from Admin -> Modules and it reaches `started` |
|
|
|
|
|
| 3 | **The read path, on both frameworks.** ✅ **Built and largely proven 2026-09-16 — as built and findings in §16.** Protocol 2: fifteen hooks, an envelope every frame carries, boards, a cursor feed and bounded history; four org-lead decisions (§16.0), two defects only a booted server could find (§16.2), and CI for the two bridge repositories that had none. **The player half of the catalogue is written down as a walk to run rather than measured** — see §16.7. First hook wave from [`HOOKS.md`](HOOKS.md); events and snapshots distinct at the wire; `wipe_id` **and server id** on every row (R8); all-time rollups (R12); every board re-emitted on connect. **First phase to run against the Carbon rig (R19/R21)** — it turns [`CARBON.md`](CARBON.md) from a source-read hypothesis into tested fact, including whether the 13 unlisted hook names are renames or holes | all 3 + docs | A restarted sidecar is fully populated within one connection, a wipe does not erase a player's history, and **the same plugin file does all of that on Oxide and on Carbon** |
|
|
|
|
|
| 4 | **The first pages.** ✅ **Done 2026-09-16 — as built and findings in §17.** `/rust` is the list (D12), `/rust/servers/:id` is one server with four tabs (D13), everything selectable in the URL; visibility-gated polling (D14); the `site.footer.status` slot filled with a live count (D15). Four decisions (§17.0) and **four defects a browser walk found, two of them already shipped in phase 3** (§17.2) — an unreachable refresh that erased the server's description, and a "last reported" line reading the wrong timestamp. **Criterion met**, walked against a live rig | Module-Rust | The site renders the last thing each server said while every server is off |
|
|
|
|
|
| 5 | **Android leg A** (R10). ✅ **Done 2026-09-17 — as built and findings in §18.** The server list and one server with four tabs, gated on a NEW capability the module had to declare (D16 — its five named surfaces, and a client needs one that names the module); a poll that keeps its rows when it fails, which the app had no shape for (D17); the drawer badge as D15 translated (D19). Four decisions (§18.0) and **three defects an emulator walk found that 644 green tests did not** (§18.4). **Both halves of the criterion walked on one device against two cores** | Android-app + Module-Rust + docs | The app renders a Rust site it has never seen, and a UO site unchanged |
|
|
|
|
|
| 6 | **Identity** (R1), and the `admin.users.detail` slot (R13) | 3 + docs | A player links an account in-game; an operator sees the Steam id inside core's own user page |
|
|
|
|
|
| 7 | **Site-owned permissions** (R2). Groups and grants authored on the site; full set pushed on connect, deltas after; drift reported. The `PermissionExists` pre-check stays the mechanism on **both** frameworks (R19); Carbon's 14 permission hooks are tested here as a possible live drift signal, and suppressed against our own pushes if they fire | all 3 + docs | A grant made on the website gates a third-party plugin in-game, survives a wipe, and behaves the same against Oxide's JSON store and Carbon's Protobuf/SQLite one |
|
|
|
|
|
| 7b | **Mod configuration from the site** (R18). **Recursive** walk of `Interface.Oxide.ConfigDirectory` — never `DataDirectory`, and never either as a literal path (R19) — generated form from the live values, raw-JSON advanced tier, explicit reload target, versioned read/write, auto-reload watched on `OnPluginLoaded`, **automatic rollback** over the whole file set, path-traversal guards, secret redaction, its own permission and an audit trail | all 3 + docs | An admin flips a ZoneManager setting from the website and it takes effect; a deliberately broken config rolls itself back and says why; a nested `<Mod>/x.json` is found and reloads the right plugin |
|
|
|
|
|
@@ -2004,6 +2004,733 @@ API. Anything driving the console has to read a log to know, which is the same c
|
|
|
|
|
reached about `oxide.reload` and the same shape R18's rollback needs.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## 15. Phase 2 as built — packaging and release, 2026-09-16
|
|
|
|
|
|
|
|
|
|
The first phase with no game server in it, and the one that turns a directory somebody copied into a
|
|
|
|
|
thing an operator can install. [`Module-Rust#2`][mr] is the whole of it.
|
|
|
|
|
|
|
|
|
|
**The starting position was worse than the phase row implied.** Phase 1 built five guards and ran
|
|
|
|
|
every one of them by hand: the repository had no `.gitea/workflows/` at all. So nothing gated the
|
|
|
|
|
branch that gets released, and there was no way to release it. This phase adds both halves, and the
|
|
|
|
|
org lead widened it to include the gate rather than only the release.
|
|
|
|
|
|
|
|
|
|
### 15.0 The three decisions this phase needed
|
|
|
|
|
|
|
|
|
|
- **D4 — the full CI suite, not only `release.yml`.** The phase row names the release; the repo had
|
|
|
|
|
no gate at all. Both ship, and the frozen-manifest job ships with them rather than waiting for a
|
|
|
|
|
later phase — see §15.2 for what it found on its first run.
|
|
|
|
|
- **D5 — the bundle carries no `node_modules`, and the emptiness is asserted rather than assumed.**
|
|
|
|
|
The shipped half declares no runtime dependencies: everything it needs arrives on `ctx`. So the
|
|
|
|
|
release runs no `npm ci` and packs no dependency tree. The whole value of that decision is that
|
|
|
|
|
*the day it stops being true is a loud day*, so `checkBundle.js` fails the PR that adds a
|
|
|
|
|
`dependencies` entry without also teaching the release to install and pack it. Module-uo ships
|
|
|
|
|
`ws` and does the opposite; this is a different answer to the same question, not a divergence
|
|
|
|
|
from a rule.
|
|
|
|
|
- **D6 — no SonarQube for the three Rust repos yet.** Phase 2 is packaging; scanning is quality
|
|
|
|
|
tooling and phase 19 is already the sweep where `CLAUDE.md`'s project-key table gets updated.
|
|
|
|
|
Three half-populated projects while the repos are skeletons buy nothing.
|
|
|
|
|
|
|
|
|
|
### 15.1 What is in a release, and what decides its number
|
|
|
|
|
|
|
|
|
|
A release is **not source**. It is the directory core's loader expects at `modules/rust/`, already
|
|
|
|
|
assembled — the prebuilt client chunk, the schema fragment and the OpenAPI fragment, packed as they
|
|
|
|
|
will be unpacked — because an operator never builds anything (`MODULE_SYSTEM.md` §1.14).
|
|
|
|
|
|
|
|
|
|
| Asset | What it is |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `module-rust-<version>.tar.gz` | the assembled directory, one top-level entry, no `node_modules` |
|
|
|
|
|
| `module-rust-<version>.json` | the install manifest: id, name, version, `coreApi`, url, size, **`sha256`** |
|
|
|
|
|
| `SHA256SUMS` | the same hash, in the shape every other repo here publishes |
|
|
|
|
|
|
|
|
|
|
The version is **derived**, using the engine `link`, `installer` and `Module-uo` already run:
|
|
|
|
|
conventional-commit subjects since the newest `v*` tag decide major/minor/patch, nothing releasable
|
|
|
|
|
cuts no release, and `module.json`'s version survives as a **floor** rather than as a record. The
|
|
|
|
|
number that ships is the **tag**, and CI stamps it into the bundle's own `module.json` at assembly
|
|
|
|
|
time — which is why the release also asserts that the assembled `module.json` carries the version
|
|
|
|
|
being released, since a bundle that still declared the floor would install under a number that is
|
|
|
|
|
not the one it came from.
|
|
|
|
|
|
|
|
|
|
Module-uo is the argument for deriving rather than declaring: it released only on a hand-edited
|
|
|
|
|
version line, and between 2026-08-12 and 2026-08-19 that cost it *every* bundle, because nine phases
|
|
|
|
|
of work landed without anyone touching that line. `workflow_dispatch` survives as the backdoor for
|
|
|
|
|
the case the rules cannot reach — a widened `coreApi`, a new mount, a capability, with no releasable
|
|
|
|
|
code behind it.
|
|
|
|
|
|
|
|
|
|
**Two failure modes are guarded before anything is built.** The credential check runs first, so a
|
|
|
|
|
repository without `REGISTRY_TOKEN` fails with a named error instead of pushing a tag and then 401ing
|
|
|
|
|
on the release API — the state `servuo-plugins` got stuck in on its own first release. And a tag that
|
|
|
|
|
exists with **no release behind it** is deliberately not treated as "nothing to do": that is the
|
|
|
|
|
signature of the same half-failure, and standing down on the tag alone would make it permanent.
|
|
|
|
|
|
|
|
|
|
### 15.2 The frozen manifest answers the question phase 1 had to take on trust
|
|
|
|
|
|
|
|
|
|
`§13`'s registration comment says `/rust` "collides with nothing on any of the three tiers, checked
|
|
|
|
|
against core's mount tables rather than assumed" — and then names the limit of that check: **core
|
|
|
|
|
answers several public routes mounted at the tier root rather than under a prefix**, `/status` and
|
|
|
|
|
`/version` among them, which the loader's own collision probe cannot see.
|
|
|
|
|
|
|
|
|
|
The `frozen-manifest` job is the thing that can. It clones core at the sha pinned in
|
|
|
|
|
`ci/core-ref.json`, generates core's route table **without** this module and then **with** it, and
|
|
|
|
|
takes the difference. That difference is what the module serves, and it is checked three ways: it
|
|
|
|
|
must match the committed `routes.manifest.json`, every route in it must have an operation in
|
|
|
|
|
`swagger-fragment.json` *and* every operation must be a route, and — the half that matters most —
|
|
|
|
|
**no core route may have been removed or changed**. A module whose mount displaced a core route
|
|
|
|
|
cannot show up as an addition, because the URL is unchanged; only the diff sees it.
|
|
|
|
|
|
|
|
|
|
Run locally against the pinned ref before it was committed, and again in CI against a fresh clone,
|
|
|
|
|
both agreeing:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
route manifest up to date (280 routes)
|
|
|
|
|
wrote routes.manifest.json (282 public + 4 internal)
|
|
|
|
|
routes.manifest.json is current — 6 routes, all documented
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Six routes, all documented, nothing of core's moved. **`/rust` is now free by proof rather than by
|
|
|
|
|
reading**, and it stays that way on every pull request.
|
|
|
|
|
|
|
|
|
|
**The pin starts on `main`, unlike Module-uo's.** That repo spent the whole Event System window
|
|
|
|
|
pinned to `edge`, because it depended on contract members that had not reached `main` yet. This
|
|
|
|
|
module needs `MODULE_API` 1.10.0, which the Event System cutover already put there, so
|
|
|
|
|
`ci/core-ref.json` names `efa9db7` on `main` and should stay on `main` until this module comes to
|
|
|
|
|
depend on something unreleased.
|
|
|
|
|
|
|
|
|
|
### 15.3 One declaration, two readers — and it was verified by breaking it
|
|
|
|
|
|
|
|
|
|
`ci/bundle.json` is an **include** list, never an exclude list: an exclude list ships whatever it
|
|
|
|
|
forgot, and the day somebody adds `server/tools/` with a scratch credential in it, an exclude list
|
|
|
|
|
packs it and nobody finds out. The cost of that choice is the opposite failure — a new directory
|
|
|
|
|
silently drops *out* of every release — which is exactly what happened to Module-uo between v0.3.0
|
|
|
|
|
and v1.0.0, where `server/commands/` arrived in a cutover, the list did not learn about it, and the
|
|
|
|
|
module installed cleanly and then died at the register stage on the operator's box.
|
|
|
|
|
|
|
|
|
|
Nothing caught it there because the PR checks copy the **whole repo** into core: they only ever
|
|
|
|
|
exercised a tree that had the file. **The subset exists only in the release.** So the list has two
|
|
|
|
|
readers — `release.yml`, which packs from it, and `server/scripts/checkBundle.js`, which asks on
|
|
|
|
|
every PR whether it still covers everything `server/index.js` can reach.
|
|
|
|
|
|
|
|
|
|
It reaches requires written **inside `register()`**, which is not a detail: this module's entry point
|
|
|
|
|
requires its routers inside the function on purpose, because `core.init(ctx)` has to run before
|
|
|
|
|
anything under `router/` is required. A check that only saw file-scope requires would have missed
|
|
|
|
|
every router the module has.
|
|
|
|
|
|
|
|
|
|
Verified the only way a check is worth anything — by breaking it. Dropping `"model"` from the list:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
ci/bundle.json does not ship everything server/index.js reaches.
|
|
|
|
|
server/model (2 files reachable)
|
|
|
|
|
Add "model" to ci/bundle.json's server[].
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
It names the exact edit, in the units the list is written in.
|
|
|
|
|
|
|
|
|
|
### 15.4 The release, as published
|
|
|
|
|
|
|
|
|
|
`v0.1.0`, cut by the first push to `main`, with no tag before it — so the engine took the first-run
|
|
|
|
|
branch and shipped what `module.json` declared. Three assets:
|
|
|
|
|
|
|
|
|
|
| Asset | Size |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `module-rust-0.1.0.tar.gz` | 41,310 bytes |
|
|
|
|
|
| `module-rust-0.1.0.json` | 355 bytes |
|
|
|
|
|
| `SHA256SUMS` | 91 bytes |
|
|
|
|
|
|
|
|
|
|
Downloaded and hashed independently of CI, the artifact is
|
|
|
|
|
`7296c76b988c6191840a1dc4ed1a77d96ad35e8c26f9b6b55e88fe4c10878b32` — byte-for-byte the `sha256` the
|
|
|
|
|
manifest declares.
|
|
|
|
|
|
|
|
|
|
**`REGISTRY_TOKEN` was already configured on the repository**, which was the one prerequisite this
|
|
|
|
|
work could not verify for itself: the bot identity can read neither repository nor organisation
|
|
|
|
|
Actions secrets (`user should be the owner of the repo`). The credential check exists precisely
|
|
|
|
|
because the answer was unknowable from here, and the first release ran clean through it.
|
|
|
|
|
|
|
|
|
|
### 15.5 The acceptance criterion, walked
|
|
|
|
|
|
|
|
|
|
> *An operator installs the empty module from Admin → Modules and it reaches `started`.*
|
|
|
|
|
|
|
|
|
|
**Met.** Walked as an operator would, against the local core on `edge`, with the phase-1 state
|
|
|
|
|
deliberately torn down first — the hand-copied `modules/rust/` directory moved aside and its
|
|
|
|
|
`installed_modules` row deleted, so this was a first install and not an upgrade. Before it,
|
|
|
|
|
`GET /api/v1/public/rust/servers` answered **404**.
|
|
|
|
|
|
|
|
|
|
1. Admin → Modules, with no `rust` row and `gitea.whitlocktech.com` on the allowlist.
|
|
|
|
|
2. Pasted the release's `module-rust-0.1.0.json` URL and pressed Install.
|
|
|
|
|
→ *"Installed Rust v0.1.0. Restart to load it."*, and a row reading **Restart to start —
|
|
|
|
|
installed, it mounts when the server next starts**, carrying the manifest URL and
|
|
|
|
|
`sha256 7296c76b988c…`.
|
|
|
|
|
3. Restarted.
|
|
|
|
|
→ `registered module "rust" v0.1.0`, `schema ensured for module "rust" {"statements":2}`,
|
|
|
|
|
`[rust:boot] booted {"refreshMs":30000}`, `module "rust" started`.
|
|
|
|
|
|
|
|
|
|
The row is now `state = started` with `started_at` set, the source URL and the released hash — where
|
|
|
|
|
phase 1's row had `source` and `sha256` **null**, because a directory somebody copied has no
|
|
|
|
|
provenance to record. The screen reads **Running — mounted and serving**.
|
|
|
|
|
|
|
|
|
|
**What the volume received is exactly the include list and nothing else: twenty files.** No tests, no
|
|
|
|
|
`server/scripts/`, no `ci/`, no `client/src/`, no `node_modules`, and no dotfiles. `client/dist/entry.js`
|
|
|
|
|
is the chunk CI built.
|
|
|
|
|
|
|
|
|
|
And the three checks that prove it is *serving* rather than merely loaded:
|
|
|
|
|
|
|
|
|
|
| | |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `GET /api/v1/public/rust/servers` | **200**, answering with the rig's `main` server |
|
|
|
|
|
| `GET /api/v1/player/rust/servers` · `GET /api/v1/admin/rust/servers` | **401** — the tier gates are on, not bypassed |
|
|
|
|
|
| `/api/docs.json` | carries all **five** `/rust` paths: the fragment merged into core's own spec |
|
|
|
|
|
|
|
|
|
|
**Two things this walk is honest about.** The first is that the *restart* was done from the shell
|
|
|
|
|
rather than with the screen's own **Restart the server** button: that button runs the same graceful
|
|
|
|
|
shutdown a `SIGTERM` does and relies on a supervisor to bring the process back, which the shipped
|
|
|
|
|
`docker-compose.yml` provides and a bare `npm start` does not. The button was not exercised, and it
|
|
|
|
|
is core's, not this module's. The second is that the module's two tables were left in place when the
|
|
|
|
|
row was deleted, so the rig's `main` server row survived the reinstall — the schema fragment replayed
|
|
|
|
|
on boot (`statements: 2`) exactly as R12 requires of a fragment that runs every time.
|
|
|
|
|
|
|
|
|
|
**The one operational finding, and it is about the rig rather than the module.** Docker Desktop's
|
|
|
|
|
Linux engine was found dead — its WSL distribution stopped, the `uomm-db` container exited, and
|
|
|
|
|
`docker` answered every call with `500 Internal Server Error` rather than anything naming the cause.
|
|
|
|
|
Restarting Docker Desktop and the container fixed it. Worth writing down because the failure presents
|
|
|
|
|
as the *website* being broken (`ECONNREFUSED` to a database that is simply not there), and because
|
|
|
|
|
`CLAUDE.md` points every smoketest at that one container.
|
|
|
|
|
|
|
|
|
|
## 16. Phase 3 as built — the read path, 2026-09-16
|
|
|
|
|
|
|
|
|
|
The first phase that had to be true on two mod frameworks, and the first with a
|
|
|
|
|
catalogue rather than a message. Four repositories moved: the spec here, the plugin, the sidecar,
|
|
|
|
|
and the module.
|
|
|
|
|
|
|
|
|
|
**Status: the bridge half is done and proven; two proofs are queued on the org lead.** What the
|
|
|
|
|
plugin sends and what the sidecar does with it are built, tested and exercised against live Oxide
|
|
|
|
|
and Carbon servers. The player-facing half of the catalogue — deaths, chat, gathering, sessions —
|
|
|
|
|
cannot fire without somebody holding a mouse, and is written down as a walk to run rather than
|
|
|
|
|
guessed at: [`PLAYER_WALK.md`](../../rust-link/PLAYER_WALK.md). §16.7 lists everything still open.
|
|
|
|
|
|
|
|
|
|
### 16.0 The four decisions this phase needed
|
|
|
|
|
|
|
|
|
|
- **D7 — the widest first hook wave.** The options ran from "presence, deaths and the wipe" to
|
|
|
|
|
"everything read-only worth having", and the widest was chosen: fifteen hooks, including the
|
|
|
|
|
moderation set that carries IP addresses and player reports. The consequence is real and is
|
|
|
|
|
designed around rather than deferred — those frames arrive **nine phases before** the visibility
|
|
|
|
|
framework phase 14 builds, so the classification and its default-deny allowlist ship now (§16.4).
|
|
|
|
|
- **D8 — the plugin derives `wipeId`.** `PROTOCOL.md` §3.2 had reserved that for the website. By
|
|
|
|
|
protocol 2 three components store rows that need it and only one of them can read the value, so
|
|
|
|
|
the reversal is written into §8.2 rather than left as a contradiction.
|
|
|
|
|
- **D9 — the live feed is a cursor, and D5 stands.** Core runs Node 20, where a global `WebSocket`
|
|
|
|
|
is still behind a flag, so a socket means taking `ws` — against a release that asserts it ships no
|
|
|
|
|
runtime dependencies. The deciding argument was the other one: **a socket needs a cursor anyway**
|
|
|
|
|
for what it missed while the module was restarting, and the catch-up path is the one that must be
|
|
|
|
|
right. One mechanism exercised every five seconds beats two where the second only runs after an
|
|
|
|
|
outage nobody planned.
|
|
|
|
|
- **D10 — rollups permanent, raw bounded.** The website keeps per-player-per-wipe totals for ever
|
|
|
|
|
and a 30-day window of raw events; the sidecar keeps 14 days and prunes hourly. R12's "a wipe does
|
|
|
|
|
not erase a player's history" is met by the totals, which is the row an operator actually reads.
|
|
|
|
|
- **D11 — CI for both bridge repositories**, which had none at all. Phase 2 found that hole in
|
|
|
|
|
Module-Rust; it was still open in the two repositories that ship the half running inside somebody
|
|
|
|
|
else's game server.
|
|
|
|
|
|
|
|
|
|
### 16.1 `type` is the whole of protocol 2 in the sidecar
|
|
|
|
|
|
|
|
|
|
Protocol 1 routed on `kind`, in a `match` that needed a new arm per addition. Protocol 2 adds
|
|
|
|
|
**`type`** — `event`, `snapshot`, `reply`, `control` — and the sidecar files on that and nothing
|
|
|
|
|
else. Ten new event kinds are now zero change in Rust-Link, which is the property that matters when
|
|
|
|
|
the thing growing fastest is the catalogue.
|
|
|
|
|
|
|
|
|
|
A frame whose `type` this build does not know is **dropped and counted**, never guessed at.
|
|
|
|
|
Defaulting an absent one to `event` would file a *board* as history — the presence board appended a
|
|
|
|
|
few thousand times, which nothing reports and nobody notices until they wonder why the database is
|
|
|
|
|
large.
|
|
|
|
|
|
|
|
|
|
**It caught a real mismatch three seconds after it first ran**, which was not planned: a protocol 1
|
|
|
|
|
plugin was still live on the retired workstation rig, dialled the new sidecar, and its `server.hello`
|
|
|
|
|
went straight into the counter. The game link has no version handshake by design (§2), so
|
|
|
|
|
`untyped_frames` on `/health` is the only place that failure is visible — and the symptom without it
|
|
|
|
|
is a website showing nothing while the game is plainly up.
|
|
|
|
|
|
|
|
|
|
### 16.2 Two defects a live server found, and neither could have been found anywhere else
|
|
|
|
|
|
|
|
|
|
**The wipe id was null for every real session.** `Init` runs *before* the save is loaded, so
|
|
|
|
|
`SaveRestore.SaveCreatedTime` is not yet meaningful there, and the id resolved at load time stayed
|
|
|
|
|
null for the life of the process — every frame shipping without the field R12 splits history on.
|
|
|
|
|
|
|
|
|
|
It was invisible for the reason such things usually are: a **hot-reloaded** plugin reads an
|
|
|
|
|
already-loaded world and gets the right answer every time. Every development iteration on the
|
|
|
|
|
workstation rig was a hot reload. It took a server that *booted* with the plugin installed — which
|
|
|
|
|
is every real one — to show `wipeId=none` beside a save sitting on disk. Now resolved again at
|
|
|
|
|
`OnServerInitialized`, and lazily while still unknown.
|
|
|
|
|
|
|
|
|
|
**`Unload` blocked the game's main thread for two seconds.** Carbon reported it exactly:
|
|
|
|
|
`hook 'Unload' took longer than 100ms [2002ms]`, next to `link thread did not stop cleanly`. That is
|
|
|
|
|
phase 1's stall arriving by a different road — the link thread sits in a blocking
|
|
|
|
|
`TcpClient.Connect`, which has no timeout of its own and cannot be woken, and `Unload` joins it from
|
|
|
|
|
the main thread.
|
|
|
|
|
|
|
|
|
|
The reason two phases missed it is worth keeping: **a host that refuses answers instantly, and a
|
|
|
|
|
host that drops does not answer at all.** Every loopback test is the first kind. A firewalled
|
|
|
|
|
address, a typo, a machine that is off are all the second, and the deployment this phase was being
|
|
|
|
|
tested through happened to be one. The connect is now bounded and waits on a stop handle of its own
|
|
|
|
|
— it cannot share `Wake`, which also means "the queue has something in it" and is signalled by every
|
|
|
|
|
hook that fires. After the fix the same reload logs no slow-hook warning and no stranded thread.
|
|
|
|
|
|
|
|
|
|
### 16.3 The aggregate, and the rule it generalises
|
|
|
|
|
|
|
|
|
|
`OnDispenserGather` fires on **every swing at a tree**. A frame per swing would make the bridge the
|
|
|
|
|
most expensive thing on a busy server, and nobody wants a killfeed of chickens either, so gathering
|
|
|
|
|
and NPC kills are counted in the plugin and flushed once a minute as one `player.tally` frame.
|
|
|
|
|
|
|
|
|
|
The rule: **if a hook can fire more than once a second per player, it is a counter, not an event.**
|
|
|
|
|
R17's warning about chatty zone transitions is the same rule arriving early.
|
|
|
|
|
|
|
|
|
|
A tally is a **delta, not a running total** — what happened since the last flush — so the consumer
|
|
|
|
|
sums rather than diffs, and a dropped frame costs one interval instead of corrupting the series. The
|
|
|
|
|
outbound queue is drop-oldest by design, so frames are genuinely allowed to go missing; a running
|
|
|
|
|
total over a lossy link is a number that is quietly wrong for ever.
|
|
|
|
|
|
|
|
|
|
One honest limitation, corrected in the code rather than in the comment that first claimed
|
|
|
|
|
otherwise: **a plugin reload loses up to a minute of one player's tally.** `Unload` enqueues the
|
|
|
|
|
flush, but the writer stops on the same flag and the queue is cleared after the join. Draining it
|
|
|
|
|
first would mean waiting on a socket from the main thread — the stall §16.2 just removed — so the
|
|
|
|
|
loss is taken deliberately. A real shutdown flushes at `OnServerShutdown`, and a player leaving
|
|
|
|
|
flushes at their disconnect.
|
|
|
|
|
|
|
|
|
|
### 16.4 The boundary is enforced by the side that serves
|
|
|
|
|
|
|
|
|
|
The widest hook wave brings IP addresses (`CanUserLogin`, `OnUserApproved`, `OnUserBanned`), one
|
|
|
|
|
player's report about another, and the grid reference of somebody's base — nine phases before the
|
|
|
|
|
visibility framework §11.2 costed. So the classification ships with the catalogue.
|
|
|
|
|
|
|
|
|
|
**It is not a field on the wire.** The plugin could have stamped a class on every frame; it
|
|
|
|
|
deliberately does not. A boundary declared by the *sender* is one a compromised — or merely
|
|
|
|
|
out-of-date — game host can widen. The website's own shard fan-out works the same way: a public
|
|
|
|
|
stream with an allowlist of kinds and an admin stream that adds the rest, and what makes it
|
|
|
|
|
trustworthy is that the decision lives on the serving side.
|
|
|
|
|
|
|
|
|
|
So `module-rust/server/catalogue.js` holds it, **default-deny**: a kind this build has never heard
|
|
|
|
|
of is not public. That is the shape of the mistake it prevents — the next protocol version adds a
|
|
|
|
|
kind, the module stores it happily, and a deny-list filter would publish it the day it first
|
|
|
|
|
arrived, before anybody decided whether it should be. A test holds the list against §8.4's table, so
|
|
|
|
|
adding a kind to the protocol without classifying it fails a build.
|
|
|
|
|
|
|
|
|
|
### 16.5 A login denial is not a hook, and §10 says it is
|
|
|
|
|
|
|
|
|
|
`PLAN.md` §10 sources the `rust.login.denied` trigger from `CanUserLogin`. Reading the hook says that
|
|
|
|
|
cannot work: it fires on **every** connection attempt, and the only way to learn of a denial from it
|
|
|
|
|
is to *be* the denier — which §8.7 forbids, structurally, by declaring every read-path hook `void` so
|
|
|
|
|
it cannot answer. uMod publishes no `OnUserRejected`.
|
|
|
|
|
|
|
|
|
|
What the game can tell us is two facts: an attempt, and an approval. Protocol 2 emits both, and a
|
|
|
|
|
denial is **the absence of an approval** — a deferred read, phase 10's to make. The trigger survives;
|
|
|
|
|
its source changes. (The same shape the engagement workstream hit at its own phase 10, which is
|
|
|
|
|
either a coincidence or a property of login paths.)
|
|
|
|
|
|
|
|
|
|
### 16.6 What was proven, and how
|
|
|
|
|
|
|
|
|
|
| Claim | How | Result |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| The read path compiles and loads on **Oxide** | live server, protocol 2, 15 hooks bound | ✅ |
|
|
|
|
|
| …and on **Carbon** 2.0.259.0, from the **byte-identical file** | the Pterodactyl rig, config read from `carbon/configs/` | ✅ |
|
|
|
|
|
| Every frame carries `type`, `serverId`, `wipeId` | `server.hello` and `players.online` read back off the sidecar | ✅ |
|
|
|
|
|
| A wipe id derived from the save, changing only with the save | `rg.link` reports `w-20260915T195817Z` against `saveCreatedAt 2026-09-15T19:58:17Z` | ✅ |
|
|
|
|
|
| **A restarted sidecar is fully populated within one connection** | store deleted, process restarted: both boards present **0.3 s** after the listener bound, and **zero** events in history | ✅ |
|
|
|
|
|
| Boards are not replayed as history | the same walk: `/events` returned 0 rows while `/boards` returned 2 | ✅ |
|
|
|
|
|
| Moderation frames reach the sidecar whole | `banid` / `unban` over RCON | ✅ |
|
|
|
|
|
| A protocol mismatch is counted, not mis-filed | a live protocol 1 plugin against the protocol 2 sidecar | ✅ |
|
|
|
|
|
| `rg.hooks` answers on both frameworks | Oxide and Carbon, identical output shape | ✅ |
|
|
|
|
|
| 44 sidecar tests, 95 module server tests, 20 client tests, every guard | locally, and now in CI on both repos | ✅ |
|
|
|
|
|
| The module's route manifest against a **real core** at the pinned ref | 10 routes, all documented, none of core's moved | ✅ |
|
|
|
|
|
| **The module ingests a live game** | the working tree installed into a running core, pointed at the workstation sidecar: `cursor started at the feed tail`, then a console `banid`/`unban` arrived as two `rust_events` rows with their wipe id, cursor advanced | ✅ |
|
|
|
|
|
| **The allowlist holds against real rows** | with both ban events in the table, `GET /public/rust/servers/:id/events` answered `{"events":[]}` — **and answered the same when asked for `player.banned` by name** | ✅ |
|
|
|
|
|
| A wipe row is created by being mentioned | `w-20260915T195817Z` appeared in `rust_wipes` from the first frame carrying it, with no "a wipe started" call anywhere | ✅ |
|
|
|
|
|
|
|
|
|
|
**One finding about the rigs rather than the code:** the panel rigs cannot reach a sidecar running on
|
|
|
|
|
the workstation, because Windows Firewall holds two program-scoped **Block** rules for
|
|
|
|
|
`rust-link-sidecar.exe` — created by a dismissed prompt at some point — and a program-level block
|
|
|
|
|
beats any port-level allow. Removing them needs elevation. It is a rig problem only: the shipped
|
|
|
|
|
design puts the sidecar on the game host's own loopback (D2, R20), where it is the deployment that
|
|
|
|
|
never needs a rule at all.
|
|
|
|
|
|
|
|
|
|
The local workstation rig, which does reach its sidecar on loopback, is what proved everything in the
|
|
|
|
|
table above that needs a live socket. **`D:\rust` is therefore not as retired as R21 assumed** — it
|
|
|
|
|
survives as the fast loop (a saved file is a reloaded plugin in about ten seconds, against nine
|
|
|
|
|
minutes of world generation on the panel), and the panel rigs are what answer "on both frameworks".
|
|
|
|
|
|
|
|
|
|
### 16.7 What is still open, and who it is waiting on
|
|
|
|
|
|
|
|
|
|
Three things, all of them measurements rather than decisions, and all of them the org lead's to run:
|
|
|
|
|
|
|
|
|
|
1. **The player walk** — [`PLAYER_WALK.md`](../../rust-link/PLAYER_WALK.md). Ten minutes on a rig
|
|
|
|
|
with a mouse, and it closes `OnPlayerDeath`, `OnPlayerChat`, `OnDispenserGather`,
|
|
|
|
|
`OnPlayerRespawned`, `OnEntityDeath`-by-a-player, and `sessionSec`. The document says what each
|
|
|
|
|
step should produce, so it can be run without anybody watching the output live.
|
|
|
|
|
2. **The wipe walk.** `OnNewSave` fires when a server starts with no save — the panel rigs wipe
|
|
|
|
|
through the egg's own `REMOVE_FILES`, so this is the rig's own mechanism rather than a special
|
|
|
|
|
test. What it proves is the second half of the acceptance criterion: that the old wipe's rows are
|
|
|
|
|
still queryable by `?wipe=` afterwards.
|
|
|
|
|
3. **The Carbon socket leg.** Everything up to the socket is proven on Carbon; what is not is frames
|
|
|
|
|
actually arriving over a live link, which is one elevated firewall command away
|
|
|
|
|
(`Remove-NetFirewallRule -DisplayName "rust-link-sidecar.exe"`, then an allow for the rig).
|
|
|
|
|
|
|
|
|
|
Until 1 and 2 are run, the honest statement of this phase is: **the transport, the envelope, the
|
|
|
|
|
boards and the classification are proven on both frameworks; the player half of the catalogue is
|
|
|
|
|
built, reviewed against the hook documentation, and unmeasured.** That is written here rather than
|
|
|
|
|
in a commit message because it is the kind of thing a later phase will want to know it inherited.
|
|
|
|
|
|
|
|
|
|
### 16.7b The ingest walk, and the trap it walked into
|
|
|
|
|
|
|
|
|
|
The module half was exercised against the live rig rather than only against its own tests: the
|
|
|
|
|
working tree installed into a running core, pointed at the workstation sidecar with a real Rust
|
|
|
|
|
server behind it. It logged `cursor started at the feed tail {at: 1}` — the fresh-install path,
|
|
|
|
|
starting at the end rather than replaying — and a console `banid`/`unban` pair then arrived as two
|
|
|
|
|
`rust_events` rows carrying the wipe id, with the cursor advancing to 3 and `events_seen` at 2.
|
|
|
|
|
|
|
|
|
|
Then the boundary, on real rows rather than fixtures: with both ban events sitting in the table, the
|
|
|
|
|
public events route answered `{"events":[]}`, **and answered the same when asked for
|
|
|
|
|
`player.banned` by name**. That is the difference between a filter and a refusal — the kinds are, as
|
|
|
|
|
far as a public caller is concerned, not there.
|
|
|
|
|
|
|
|
|
|
**The trap, and it is the same one the Pterodactyl work recorded.** The server-state row read as
|
|
|
|
|
`online=1` with `hostname=NULL` and `protocol=NULL`, which is a shape no code path writes. The cause
|
|
|
|
|
was two cores sharing one database: a second instance left running from earlier in the day still
|
|
|
|
|
holds the **phase 2 release** in memory, speaks protocol 1, is refused `409` by a protocol 2 sidecar,
|
|
|
|
|
and writes the row back as unreachable every thirty seconds. Nothing was wrong with either of them.
|
|
|
|
|
|
|
|
|
|
What made it *look* like a defect was the measurement: two `SELECT`s in two round trips, assuming
|
|
|
|
|
the state did not move between them. A single atomic read caught the coherent row a moment later —
|
|
|
|
|
`online: 1, protocol: 2, hostname: Test Server` — alternating with the other writer's.
|
|
|
|
|
**A differential diagnosis across two calls is only valid if nothing else holds the controls**, and
|
|
|
|
|
on a shared rig something usually does.
|
|
|
|
|
|
|
|
|
|
### 16.8 Smaller things worth keeping
|
|
|
|
|
|
|
|
|
|
- **`rg.hooks` collides with `RGProbe`**, the phase-0 rig plugin, which registered the same console
|
|
|
|
|
command first. Oxide warns and the last loaded wins, which happens to be the bridge. Left alone:
|
|
|
|
|
`RGProbe` is rig scaffolding that never ships, and renaming the shipping command to avoid a
|
|
|
|
|
test tool would be the wrong way round.
|
|
|
|
|
- **The IP a console ban reports is the literal string `"0"`**, not an address and not a null, when
|
|
|
|
|
the banned id is offline. Observed, not guessed. The plugin omits the field instead of forwarding
|
|
|
|
|
it — a column full of `"0"` survives every is-it-missing test a reader writes and then fails
|
|
|
|
|
whatever parses it.
|
|
|
|
|
- **`--print-config` reports the *effective* configuration and writes the *file* one.** Environment
|
|
|
|
|
variables override the file (R22 depends on that), and the written file never contains them. Not a
|
|
|
|
|
bug, but the two are not the same document and an installer reading one should not assume the
|
|
|
|
|
other.
|
|
|
|
|
- **A `cargo clippy` run does not produce a binary.** Two rig readings disagreed with the source
|
|
|
|
|
because the sidecar under test was an older `cargo build`; `clippy` and `test` compile without
|
|
|
|
|
writing one. Rebuild before believing a rig.
|
|
|
|
|
|
|
|
|
|
## 17. Phase 4 as built — the first pages, 2026-09-16
|
|
|
|
|
|
|
|
|
|
One repository, and the first phase whose whole deliverable is something a visitor looks at. It
|
|
|
|
|
consumes exactly the routes phase 3 built and adds one of its own; nothing here talks to a game
|
|
|
|
|
server, which is the point of the criterion it was written against: **the site renders the last
|
|
|
|
|
thing each server said while every server is off.**
|
|
|
|
|
|
|
|
|
|
**Status: criterion met, and met the hard way.** The pages were walked in a browser against a live
|
|
|
|
|
rig — a real Rust server behind the real sidecar for `main`, and a second, deliberately unreachable
|
|
|
|
|
server for everything the record holds. That walk found four defects, two of them in code phase 3
|
|
|
|
|
had already shipped, and all four are fixed here (§17.2).
|
|
|
|
|
|
|
|
|
|
### 17.0 The four decisions this phase needed
|
|
|
|
|
|
|
|
|
|
- **D12 — `/rust` is the server list.** Phase 1 registered it at `/rust/servers` and left the
|
|
|
|
|
module's own namespace root answering core's CMS catch-all. R8 calls the list "the landing page",
|
|
|
|
|
so it is registered with an **empty path** — core renders that as `/rust` — and the detail page
|
|
|
|
|
hangs beneath it at `/rust/servers/:id`. One canonical address, and it is the module's name.
|
|
|
|
|
- **D13 — one page with in-page tabs**, not four routes. `/rust/servers/:id` carries a header and
|
|
|
|
|
four panels (feed, leaderboard, online, wipes). A tab strip is not in the shared UI kit, so the
|
|
|
|
|
module bundles its own — which is the kit working as designed rather than a gap in it (§3.4 is a
|
|
|
|
|
closed list of nine members, and everything above them is the module's).
|
|
|
|
|
- **D14 — poll while the tab is visible.** The feed and the presence list re-fetch every twenty
|
|
|
|
|
seconds, paused by the Page Visibility API and refreshed the instant a viewer comes back. The
|
|
|
|
|
leaderboard and the wipe list load once: a table that re-sorts itself under the reader's cursor is
|
|
|
|
|
worse than one four minutes old. Server-Sent Events were considered and are not this phase — core
|
|
|
|
|
has a fan-out, but the module registers no stream, and a cursor-driven one is phase scope.
|
|
|
|
|
- **D15 — the footer slot carries a live count**, not a static link: `2 servers · 42 online`, linking
|
|
|
|
|
to `/rust`. The cost is stated rather than assumed — see §17.4.
|
|
|
|
|
|
|
|
|
|
### 17.1 What is on the pages
|
|
|
|
|
|
|
|
|
|
`/rust` is the list: name, map, size, when it was wiped, when it last reported, and the player count
|
|
|
|
|
or `Offline`. The whole row is the link.
|
|
|
|
|
|
|
|
|
|
`/rust/servers/:id` is the server. The header is what a Rust player asks first — map, world size,
|
|
|
|
|
seed, wipe date — with live status beside it and a wipe selector that applies to the whole page.
|
|
|
|
|
Then four tabs:
|
|
|
|
|
|
|
|
|
|
| Tab | Reads | Refresh |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| Feed | `…/events`, with a filter that maps to the `kind` parameter | 20s, visibility-gated |
|
|
|
|
|
| Leaderboard | `…/leaderboard`, sortable, per wipe or all-time | on mount |
|
|
|
|
|
| Online | `…/online` — the presence **board**, not counted transitions | 20s, visibility-gated |
|
|
|
|
|
| Wipes | `…/wipes`; picking one filters the feed | on mount |
|
|
|
|
|
|
|
|
|
|
**Everything selectable is in the URL** — tab, filter, wipe, sort. That costs a little ceremony in
|
|
|
|
|
the page and buys the thing a community site is for: *"last wipe's leaderboard on Main"* is a link,
|
|
|
|
|
the back button undoes a click rather than leaving the page, and a refresh lands where the reader
|
|
|
|
|
was. `wipe=current` is a word rather than an id on purpose, so a shared link stays about now.
|
|
|
|
|
|
|
|
|
|
**The feed renders parts, not sentences.** `lib/feed.js` turns a stored frame into
|
|
|
|
|
`{tone, actor, join, verb, subject, detail}`, which keeps the names emphasised without any HTML in a
|
|
|
|
|
string, and makes the whole thing testable in a runner with no DOM. A death is four sentences, not
|
|
|
|
|
one — `player`, `self`, `npc`, `environment` — because the plugin distinguishes them so a reader does
|
|
|
|
|
not have to guess, and a fall reported as a kill by nobody is the failure that avoids. **A kind this
|
|
|
|
|
build has never heard of renders as itself** rather than vanishing: the server's allowlist has
|
|
|
|
|
already decided the row may be seen, so what is left here is presentation, and the honest
|
|
|
|
|
presentation of a kind we have no words for is its own name.
|
|
|
|
|
|
|
|
|
|
**`player.tally` is public and deliberately not in the feed.** It is an aggregate the plugin flushes
|
|
|
|
|
once a minute per active player (PROTOCOL.md §8.6), so a feed carrying it would be mostly wood
|
|
|
|
|
counts. It is the leaderboard's input, and that is where it shows up.
|
|
|
|
|
|
|
|
|
|
### 17.2 Four defects the page walk found, and two of them were already shipped
|
|
|
|
|
|
|
|
|
|
The walk was the whole point of doing one. None of these is visible in a test that stubs a sidecar
|
|
|
|
|
which answers.
|
|
|
|
|
|
|
|
|
|
1. **An unreachable refresh erased what the server last said.** Phase 3's refresh loop called
|
|
|
|
|
`putState` — the whole-row write — with two fields when a sidecar did not answer, so `hostname`,
|
|
|
|
|
`level`, `seed`, `world_size` and `wipe_id` all went to NULL the first time a game host rebooted.
|
|
|
|
|
The list then read `Offline` with nothing beside it, which is not *"here is what we know about a
|
|
|
|
|
server that is down"*, it is *"we have never heard of it"* — and it defeats this phase's
|
|
|
|
|
criterion exactly. Fixed with `markUnreachable`, which moves three columns and mentions no
|
|
|
|
|
others; `server/test/refresh.test.js` asserts against the SQL, because the defect is about which
|
|
|
|
|
columns a statement names.
|
|
|
|
|
2. **"Last reported" was reading the wrong timestamp.** `updated_at` is when this module last WROTE
|
|
|
|
|
the row, which a failed poll does too — so an offline server claimed it had reported just now,
|
|
|
|
|
every thirty seconds, for as long as it stayed down. They are two facts and both are wanted:
|
|
|
|
|
`updated_at` decides staleness, and a new `last_seen_at` records when a `server.hello` last
|
|
|
|
|
arrived. Only a successful refresh moves it.
|
|
|
|
|
3. **Every feed row showed a bare time of day.** Correct for today's killfeed and wrong the moment
|
|
|
|
|
the feed is filtered to a past wipe: three events from six weeks ago all rendered as `02:03 PM`.
|
|
|
|
|
Rows from another calendar day now carry the date. The boundary is the calendar rather than a
|
|
|
|
|
duration, because that is what a reader means by "what time was that".
|
|
|
|
|
4. **A mistyped address was dressed as a fault.** The detail page rendered core's `ErrorState` under
|
|
|
|
|
its own heading, so `/rust/servers/typo` read "No such server / Something went wrong" and sent a
|
|
|
|
|
reader looking for an outage. A 404 is now its own answer and `ErrorState` is kept for a request
|
|
|
|
|
that failed for a reason nobody can see.
|
|
|
|
|
|
|
|
|
|
A fifth, smaller: the Online tab listed three players under a header reading `Offline`. An
|
|
|
|
|
unreachable sidecar does not clear the presence board — deliberately, the rows are still the best
|
|
|
|
|
answer anybody has — but presented bare they read as *who is on right now*, which is the one thing
|
|
|
|
|
an offline server cannot be saying. The panel now says which it is.
|
|
|
|
|
|
|
|
|
|
### 17.3 `useAsync` cannot poll, and that is not a defect in it
|
|
|
|
|
|
|
|
|
|
Core's fetch hook (§3.4) blanks `data` and sets `loading` on every dependency change. That is right
|
|
|
|
|
for a page load and wrong for a poll: bumping a dependency every twenty seconds would clear the
|
|
|
|
|
killfeed, render a spinner in its place and re-fill it, four times a minute, for ever.
|
|
|
|
|
|
|
|
|
|
So the module bundles `hooks/usePolled.js`: a refresh that is **invisible when it succeeds** and
|
|
|
|
|
keeps the rows *and* reports the error when it fails — because a site whose premise is "it renders
|
|
|
|
|
while the game is off" must not blank itself the first time a request does. `key` (the question)
|
|
|
|
|
resets the data; the interval does not. `useAsync` is still the right hook for everything that loads
|
|
|
|
|
once, and both are used here.
|
|
|
|
|
|
|
|
|
|
The live proof: with the tab hidden the log shows no requests at all, and the instant it became
|
|
|
|
|
visible there was one refresh followed by one every 20.0 seconds.
|
|
|
|
|
|
|
|
|
|
### 17.4 The footer slot's real cost, stated
|
|
|
|
|
|
|
|
|
|
Core renders `SiteFooter` inside `PublicLayout`, and **every public page renders `PublicLayout`
|
|
|
|
|
itself** (§3.3) — so a component in that slot mounts once per public page view, not once per
|
|
|
|
|
session. D15's live count therefore puts one `/public/rust/servers` request on every public page of
|
|
|
|
|
the site, including pages with nothing to do with Rust.
|
|
|
|
|
|
|
|
|
|
Two things keep that honest rather than merely cheap. It **renders nothing until it has an answer,
|
|
|
|
|
and nothing at all if the request fails** — core's `<Slot wrap>` takes its separator with it, so a
|
|
|
|
|
failure degrades to exactly the footer an instance with no module installed has. And it **never
|
|
|
|
|
polls**: one request per page view is a cost; a timer in the footer of every page is a different
|
|
|
|
|
kind of thing. If it ever shows up in an operator's logs, the fix is a short-lived cache in that one
|
|
|
|
|
file and nothing else on the site changes.
|
|
|
|
|
|
|
|
|
|
### 17.5 Smaller things worth keeping
|
|
|
|
|
|
|
|
|
|
- **The registration fake was *nearly* core, which is worse than obviously not.** `client/test`'s
|
|
|
|
|
fake registry prefixed routes as `` `${id}/${path}` ``; core strips the trailing separator too,
|
|
|
|
|
which is exactly what lets a module register `path: ''` and own its namespace root. The day a
|
|
|
|
|
module did, the fake produced `rust/` where a real core produces `rust`, and the suite failed the
|
|
|
|
|
nav check for a link that works perfectly in a browser. The fake now copies core's line character
|
|
|
|
|
for character.
|
|
|
|
|
- **A SQL comment inside a JS template literal may not contain a backtick.** Obvious written down,
|
|
|
|
|
invisible while writing prose about `markUnreachable` inside a query string; the file stops
|
|
|
|
|
parsing several lines later and the error names an argument list.
|
|
|
|
|
- **The detail route exists so that a page can 404.** Every other route under `/servers/:id` answers
|
|
|
|
|
an empty list for an id nobody configured — an unknown server genuinely has no events, no
|
|
|
|
|
leaderboard and nobody online, and each of those is a good answer to its own question. Only
|
|
|
|
|
`GET …/servers/:id` can say the server is not there. A disabled server answers the same 404 as a
|
|
|
|
|
missing one: an operator who switched a server off did not switch it into a 403.
|
|
|
|
|
- **`capabilities` grew to what the pages serve** — `servers`, `killfeed`, `leaderboard`,
|
|
|
|
|
`presence`, `wipes` — which is the list phase 5's Android leg feature-detects against.
|
|
|
|
|
- **The rig had two cores again**, and this time the mechanism was visible rather than inferred: a
|
|
|
|
|
leftover core holding an older module release spoke protocol 1, was refused `409`, and rewrote the
|
|
|
|
|
state row as unreachable every thirty seconds — the phase-3 trap, and also how defect 1 above was
|
|
|
|
|
found. One of the two was stopped with the org lead's say-so before the walk continued.
|
|
|
|
|
|
|
|
|
|
### 17.6 What was proven, and how
|
|
|
|
|
|
|
|
|
|
- **The criterion, directly.** A second server was configured pointing at a dead address and seeded
|
|
|
|
|
with a fixture shaped exactly as the plugin emits (two wipes, 26 events, four players, a presence
|
|
|
|
|
board). With that server unreachable and reporting `Offline`, its page still rendered its map,
|
|
|
|
|
size, seed, wipe date, killfeed, per-wipe and all-time leaderboards, last known board and wipe
|
|
|
|
|
history. That is the phase criterion in one screenshot.
|
|
|
|
|
- **The allowlist, on real rows.** The fixture includes a kind this build has never heard of. The
|
|
|
|
|
public route answered `{"events":[]}` for it when asked **by name** — a refusal, not a filter.
|
|
|
|
|
- **R12's arithmetic, on the page.** All-time equals the two wipes summed (41 + 18 = 59), and a
|
|
|
|
|
player who only appears in the older wipe drops out of the current one rather than reading zero.
|
|
|
|
|
- **The footer slot**, live in core's own footer on every public page, linking to `/rust`.
|
|
|
|
|
- **The chunk's identity check**, which is the one failure only a browser can show: the console
|
|
|
|
|
carried the module's own registration line and nothing else — no second React, no bare import.
|
|
|
|
|
|
|
|
|
|
What is **not** proven here and is deliberately left: the pages have not been read on a phone-width
|
|
|
|
|
viewport, and the Android leg (phase 5) is where the same surface gets a second client anyway.
|
|
|
|
|
|
|
|
|
|
## 18. Phase 5 as built — Android leg A, 2026-09-17
|
|
|
|
|
|
|
|
|
|
The first leg of R10, and the first time this module's surface has had a second client. The app's
|
|
|
|
|
own record of it is [`../../android/PLAN.md`](../../android/PLAN.md) **M14**; what follows is what
|
|
|
|
|
the phase decided and what the walk found.
|
|
|
|
|
|
|
|
|
|
**Criterion met, and walked in an emulator rather than asserted:** *the app renders a Rust site it
|
|
|
|
|
has never seen, and a UO site unchanged.* Both halves were shown on one device against two running
|
|
|
|
|
cores.
|
|
|
|
|
|
|
|
|
|
### 18.0 Four org-lead decisions
|
|
|
|
|
|
|
|
|
|
- **D16 — the app gates on a new capability, `rust`.** This module declared five strings and every
|
|
|
|
|
one names a **surface**: `servers`, `killfeed`, `leaderboard`, `presence`, `wipes`. Core flattens
|
|
|
|
|
every started module's capabilities into one list, so a client gating a whole navigation group on
|
|
|
|
|
`servers` would have those screens revealed by any future module that declared the same generic
|
|
|
|
|
word. `module-uo` has exactly one string for this job — `shard` — and this module had none.
|
|
|
|
|
|
|
|
|
|
**Gating on the module `id` was considered and rejected.** It is the strongest fact available and
|
|
|
|
|
it is already on the wire, but `id` is a **mount prefix** (§2.1 requires it to equal the directory
|
|
|
|
|
core loads the module from) and `MODULE_API.md` §2.9 forbids a client inferring a route from a
|
|
|
|
|
capability. Letting a client gate on `id` makes the two the same value in practice, and the day one
|
|
|
|
|
builds `/<id>/servers` from it the separation that lets this module move its own pages is gone.
|
|
|
|
|
|
|
|
|
|
So `module.json` declares its own name as a sixth capability, and `server/test/entry.test.js`
|
|
|
|
|
asserts it **against `manifest.id`** rather than against the literal `"rust"` — the day the id
|
|
|
|
|
changes, the string a client gates on has to change with it. Module-Rust#5.
|
|
|
|
|
|
|
|
|
|
- **D17 — the app polls every 20 seconds while its screen is RESUMED.** D14's Page Visibility gate,
|
|
|
|
|
translated. `repeatOnLifecycle(RESUMED)` gives the same three behaviours from one line: nothing at
|
|
|
|
|
all while the app is away, an immediate refresh on return, and a pause behind a dialog. `STARTED`
|
|
|
|
|
was rejected — it keeps polling behind a partially obscured screen, which is precisely the reader
|
|
|
|
|
who is not reading.
|
|
|
|
|
|
|
|
|
|
- **D18 — the three Rust repositories move to `edge`** for the rest of the workstream, with releases
|
|
|
|
|
cut at the cutover rather than per phase. `edge` branches were created from `main` in Module-Rust,
|
|
|
|
|
Rust-Link and Rust-Plugins; `pr-checks.yml` in all three (and in Android-app) already triggers on
|
|
|
|
|
`[main, edge]`, so this costs no CI. `release.yml` still fires only on a push to `main`, which is
|
|
|
|
|
what makes the cutover the release.
|
|
|
|
|
|
|
|
|
|
- **D19 — the drawer row carries a live player count, and `NavPaths` learns `/rust`.** The second is
|
|
|
|
|
small and load-bearing: without it an admin's nav override on the module's own `Servers` row, or an
|
|
|
|
|
added link to `/rust`, hands off to a browser rather than opening the native screen.
|
|
|
|
|
|
|
|
|
|
### 18.1 D15 has no analogue on a phone, so it was translated
|
|
|
|
|
|
|
|
|
|
The footer slot works on the web because every public page renders the same footer (§17.4). The app
|
|
|
|
|
has no footer and no slot. What it has is one drawer row per surface and, since engagement Phase 8, a
|
|
|
|
|
precedent for a number beside one — the inbox's unread badge, in `NavigationDrawerItem`'s badge slot,
|
|
|
|
|
with a `contentDescription` so a screen reader says *"42 players online"* and not *"42"*.
|
|
|
|
|
|
|
|
|
|
The count rides there and keeps all three of the website version's rules: **zero renders nothing** (an
|
|
|
|
|
empty fleet is not a notification, and a badge reading `0` on a quiet evening is worse than none), a
|
|
|
|
|
failed read keeps the last number rather than dropping to zero, and it **never polls**. It is asked
|
|
|
|
|
for only where the module is installed, so a UO site makes no request at all.
|
|
|
|
|
|
|
|
|
|
**The number is players, not servers.** A badge is one integer, and of D15's two halves the live one
|
|
|
|
|
is how many people are on — a server count changes when an operator edits configuration, which is not
|
|
|
|
|
news, and is on the page the row opens anyway.
|
|
|
|
|
|
|
|
|
|
### 18.2 What the app had to grow: a refresh that is not a load
|
|
|
|
|
|
|
|
|
|
The app has had exactly one shape for a read since its first milestone — set `Loading`, ask, replace.
|
|
|
|
|
That is right for opening a screen and wrong for a poll, and it is the *same* wall this module hit one
|
|
|
|
|
tier along with core's `useAsync` (§17.3). A twenty-second refresh built on it would clear the
|
|
|
|
|
killfeed, render a spinner in its place and re-fill it, three times a minute, for ever.
|
|
|
|
|
|
|
|
|
|
`ui/Polling.kt` is `usePolled`'s other half, and it keeps the same rule: **a refresh is invisible when
|
|
|
|
|
it succeeds and keeps the rows when it fails.** Three cases, and the middle one is the whole point:
|
|
|
|
|
|
|
|
|
|
| Result | What the reader sees |
|
|
|
|
|
| --- | --- |
|
|
|
|
|
| It answered | New rows. Nothing else. |
|
|
|
|
|
| It failed, and there are rows | The same rows, and one quiet line saying the refresh failed. |
|
|
|
|
|
| It failed, and there is nothing yet | An ordinary error with a retry — a first load that failed. |
|
|
|
|
|
|
|
|
|
|
Only the **visible** live panel is polled. The website can afford to mount the one tab it is
|
|
|
|
|
rendering; the app's four tabs are one screen, so the refresh asks what the reader is actually looking
|
|
|
|
|
at. The leaderboard and the wipe list are never polled at all.
|
|
|
|
|
|
|
|
|
|
**Changing the question is not a poll.** Filter, sort and wipe blank their panel and load, because
|
|
|
|
|
what is on screen is an answer to something the reader has stopped asking — leaving it up would show
|
|
|
|
|
last wipe's killfeed under this wipe's heading.
|
|
|
|
|
|
|
|
|
|
### 18.3 What the walk proved, and how
|
|
|
|
|
|
|
|
|
|
The rig is phase 4's, unchanged: a core on `:3200` with this module installed, one live server
|
|
|
|
|
(`main`, a real sidecar and a real game host) and the seeded `demo` fixture that has never reported.
|
|
|
|
|
A second core on `:3100` serves `module-uo` and no Rust.
|
|
|
|
|
|
|
|
|
|
- **The criterion, first half.** With `demo` unreachable and reading *Offline*, the phone rendered its
|
|
|
|
|
map, size, seed, wipe date, killfeed, per-wipe and all-time leaderboards, its last known presence
|
|
|
|
|
board and its wipe history. Nothing on the screen is a live call to a game host.
|
|
|
|
|
- **The criterion, second half.** The same app, switched to the UO core, showed Shard / Rules / Atlas
|
|
|
|
|
/ Leaderboards / Market and **no Rust row**.
|
|
|
|
|
- **`refreshInto` against a genuinely dead backend.** The core was stopped with the list on screen. A
|
|
|
|
|
poll tick later the rows were unchanged, under one line reading *"Could not refresh just now. This
|
|
|
|
|
is the last thing the site heard."* — no spinner, no error page, nothing blanked.
|
|
|
|
|
- **R12's arithmetic, on a phone.** All-time 59 = 41 + 18 across two wipes, and Drift — who appears
|
|
|
|
|
only in the current wipe — **drops out** of the August board rather than reading zero.
|
|
|
|
|
- **Every `describe` branch, from real rows**: a player kill with weapon, distance and grid; an NPC
|
|
|
|
|
kill with the prefab read as words; a suicide; an environment death (the fall that must not read as
|
|
|
|
|
a kill by nobody); chat with its colon in the join and a non-Global channel beside it; a disconnect
|
|
|
|
|
with reason and session length; and *while sleeping*.
|
|
|
|
|
- **The calendar-day rule.** Filtering to the August wipe produced three rows six weeks old, each
|
|
|
|
|
carrying its date — the §17.2 defect, not re-introduced in Kotlin.
|
|
|
|
|
- **The presence panel saying which it is.** The offline server's board rendered under *"The last
|
|
|
|
|
board this server sent. It is offline, so this is who was on then — not who is on now."*
|
|
|
|
|
- **The badge**, showing a live count on the drawer row.
|
|
|
|
|
|
|
|
|
|
### 18.4 The walk found three defects, and a green suite found none of them
|
|
|
|
|
|
|
|
|
|
1. **The drawer's live count resolved once per process.** It was keyed on the capability answer alone,
|
|
|
|
|
so it was read when the app connected and never again — which is not what *live* means on a row
|
|
|
|
|
somebody opens the drawer to look at. It now refreshes on resume, beside the unread badge and for
|
|
|
|
|
the same reason: coming back to the app is exactly when a stale number would be noticed. *Visible
|
|
|
|
|
only by backgrounding the app and returning to it.*
|
|
|
|
|
2. **Every card's text sat flush against its edge.** The app's themed `ShardCard` is a `Card` and
|
|
|
|
|
nothing more — it carries no padding, and each caller pads its own content. Four new call sites did
|
|
|
|
|
not, and on a phone the first glyph of each line read as clipped.
|
|
|
|
|
3. **A name touched its own kill count.** Five numeric columns beside an equal-weight name column left
|
|
|
|
|
*Brannock* and *50* reading as one field. The name now takes a wider share and ellipsizes — and the
|
|
|
|
|
**active sort moved to the header**, because the header is the control: tinting a column of numbers
|
|
|
|
|
says *these are special* where tinting the header says *this is what the table is ordered by*.
|
|
|
|
|
|
|
|
|
|
### 18.5 The rig note worth keeping
|
|
|
|
|
|
|
|
|
|
The app's debug `network_security_config.xml` permits cleartext to **`127.0.0.1` and `localhost`
|
|
|
|
|
only** — not `10.0.2.2`. An emulator walk against a local core therefore needs
|
|
|
|
|
`adb reverse tcp:<port> tcp:<port>` and the loopback address. Typed as `10.0.2.2`, every request fails
|
|
|
|
|
with `UnknownServiceException: CLEARTEXT communication to 10.0.2.2 not permitted`, and the connect
|
|
|
|
|
screen reports *"Couldn't reach that site"* — correct, and indistinguishable from a core that is not
|
|
|
|
|
running.
|
|
|
|
|
|
|
|
|
|
Two smaller things: the first AVD tried had 95% of `/data` used and refused a 44 MB install with
|
|
|
|
|
*"Requested internal only, but not enough space"* — `pm trim-caches` freed nothing, and the second AVD
|
|
|
|
|
was the answer. And the app's own `pm clear` is the way to reach the first-run connect screen, because
|
|
|
|
|
an `install -r` over an earlier install keeps the stored base URL.
|
|
|
|
|
|
|
|
|
|
### 18.6 What is not proven here
|
|
|
|
|
|
|
|
|
|
- **A phone-width read of the website's own pages**, which §17.6 deliberately left open. This phase
|
|
|
|
|
gave the surface a second client rather than re-reading the first, and the pages have still not been
|
|
|
|
|
looked at in a narrow browser.
|
|
|
|
|
- **The badge's non-zero case on real traffic.** Nobody was playing on the rig, so the count was shown
|
|
|
|
|
by seeding a player count on the unreachable server and reading the badge before the 30-second
|
|
|
|
|
refresh zeroed it. The arithmetic and the rendering are proven; a fleet with people on it is not.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
[rl]: https://gitea.whitlocktech.com/RunicGateway/Rust-Link
|
|
|
|
|
|
