wtclaude
baffaa46c9
R1's identity link, site-side, and R13's first extension slot. A player types /link in game, the plugin hands them a six-character code privately, and they enter it here; the site records who owns which Steam account, and an operator sees that on core's own `/admin/users/:id` page. **The site is the author of record and the game holds nothing.** There is no per-account store in Rust that survives a wipe, and phase 7 needs the site authoritative anyway — it pushes permissions INTO the game keyed by Steam id. A copy in the game would be a second thing to reconcile every wipe, for no question it could answer better. ## D24 — a code is minted by ONE server, so every server is asked Nothing in six characters says where it came from. The fleet is asked in turn and the first `link.ok` wins; the others answer `unknown` and nothing happens there, because a code is only spent at the server that actually holds it. Asking the player to pick was rejected: a wrong pick would come back indistinguishable from a wrong code, and that is the one refusal which must not be ambiguous. **"Every reachable server refused" is not the same answer as "a server was unreachable."** Collapsing them tells a player whose server is down that their code is wrong — so they run /link again on that same server and are told the same thing for as long as it stays down. `unsure` is that case, and it says to try again rather than to fetch a new code. ## D23 — a Steam id another account holds is refused, never moved The primary key is `steam_id`, and it is load-bearing rather than tidy: phase 7 grants permissions against a link and phase 13 hangs entitlements off it, so a silent move is an account takeover performed by typing six characters. The refusal names the holder, because the advice is unusable without it. The INSERT is a plain INSERT for the same reason — `ON DUPLICATE KEY UPDATE` here would BE that move — and the duplicate-key error is the refusal for the race the check above cannot close. The way out is `/unlink` in game, which reaches the site off the ingest feed rather than through a route (the plugin has no link to delete). D25 adds the other way out: staff can sever a link from the admin panel, for a player who cannot reach that Steam account in game. ## The slot, and the hole it found in this repo's own generator `admin.users.detail` is declared in `module.json` AND registered in `index.js` AND filled by the chunk — three places, because the server half and the client half are different registrations that share one name. `swaggerFragment.js` knew only about tier routers, so the two routes under `/admin/users/:id` were generated by nothing: a fragment that was internally consistent and described two routes fewer than the module serves. A slot's mount is core's and cannot be derived here, so it is a fourth constant beside `TIER_BASE` — held to account by the frozen-manifest job, which was verified to catch exactly this by removing the two paths and watching it fail. ## Smaller things worth knowing - **Core's `useAsync` has no `refresh`.** A counter in the deps is how a page re-reads after its own write; it blanks while it re-reads, which is right here and is exactly what made it wrong for a poll. - **Every player-portal nav row needs an `icon`** — core draws one on every row, and the client suite says so. This module had no icons file until now, because the public header is text buttons. - The two new frame kinds are STAFF-only. Neither carries a code, but both name a Steam id beside a website account's activity, and that join is not a public fact about what happened on a server. - The link code route carries its own rate limiter rather than core's `accountChangeLimiter`: this is guessing somebody else's secret, not changing your own password, and a shared counter would let one policy set the other. Protocol 3 on all three declaration sites; 17 new tests, 136 green. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PMH6bw1jXMgbyF3ZWGEzSM
Module-Rust
The Rust module for the Runic Gateway platform: everything that
makes a Runic Gateway site a site for Rust. It installs into a website core as
modules/rust/ and is the platform's second game module, after
Module-uo.
It is also the first module built from the Integration Kit rather than extracted from the website — which makes it the kit's acceptance test from the inside.
The repository name is not the module id. This ships a module whose id is rust, because the
contract requires id to equal the directory core loads it from (modules/rust/), and that id is
the prefix of every table and every mount.
What it is, in one diagram
Rust server + Oxide (RunicGateway/Rust-Plugins)
│ loopback TCP, the plugin dials out
▼
rust-link sidecar (RunicGateway/Rust-Link) one per game server
│ HTTPS + WebSocket, bearer token
▼
this module, inside a website core one client per server
│ same-origin JSON
▼
browser · Android app
One server, one sidecar. A community running six Rust servers runs six pairs and configures six rows here; the website core never learns there is more than one.
What ships today
| Surface | Route |
|---|---|
| Public | GET /api/v1/public/rust/servers — every server and what it last reported |
| Public | GET …/servers/:id — one server, or a 404; the only route under :id that can say a server does not exist |
| Public | GET …/servers/:id/events — the feed, served from a default-deny allowlist (server/catalogue.js) |
| Public | GET …/servers/:id/leaderboard — per wipe, or all-time as those rows summed |
| Public | GET …/servers/:id/wipes and …/online |
| Player | GET /api/v1/player/rust/servers — the server list, on the authenticated tier |
| Admin | GET/PUT/DELETE /api/v1/admin/rust/servers and POST …/:id/test |
| Pages | /rust — the server list, and the module's landing page |
| Pages | /rust/servers/:id — one server: feed, leaderboard, who is on, wipes |
| Slot | site.footer.status — a live server/player count in core's footer |
Every page reads this module's own tables and never calls a game server, which is what lets the whole surface render while every server in the fleet is off. Tab, feed filter, wipe and leaderboard sort all live in the URL, so any view of it is a link.
Seven tables: rust_servers (configuration), rust_server_state and rust_presence (observed
state), rust_wipes, rust_players, rust_player_wipe_stats and rust_gather_totals (the record a
wipe does not erase), plus the bounded rust_events window and the rust_ingest_cursor.
The rest of the module — identity, site-owned permissions, Teams from Rust's clans, notifications, events, the live map, Discord commands — arrives phase by phase. Nothing is registered before it has something behind it: a declared trigger nothing emits and a declared slot nothing fills are both surfaces an operator can configure and then wait on, which is worse than an absent one.
What a client feature-detects on
module.json declares six capability strings, and GET /api/v1/public/modules hands them to any
client that asks — the website's own nav, and the Android app (docs/modules/rust/PLAN.md R10).
Five of them name a surface: servers, killfeed, leaderboard, presence, wipes.
The sixth is rust, and it names the module itself. It looks redundant beside id, and it is
not, for two reasons worth writing down before somebody tidies it away:
- A client that asks "is this module installed" has nowhere else to ask. Core flattens every
started module's capabilities into one list, so
serversalone is a word another module could declare tomorrow and silently reveal this one's screens.rustis the string that can only mean this module, and it is the single gate a whole navigation group hangs on — exactly the jobsharddoes formodule-uo. idanswers a different question. It is a mount prefix (§2.1 requires it to equal the directory core loads the module from), andMODULE_API.md§2.9 is explicit that a client must never infer a route from a capability. Gating onidwould quietly make the two the same thing, and the day a client builds/<id>/serversfrom it, the contract that lets this module move its own pages is gone.
An unknown capability is absent, and no route is ever derived from one.
Build and check
npm ci --prefix server && npm test --prefix server
npm run check:imports --prefix server
npm run check:bundle --prefix server
npm run check:swagger --prefix server
npm ci --prefix client && npm run build --prefix client
npm run check:externals --prefix client && npm test --prefix client
Build the client BEFORE running its tests — two of them read the built chunk and skip when there is none, so a run in the other order passes while asking nothing about the artifact that ships.
Regenerate the OpenAPI fragment whenever a route or an annotation changes:
npm run swagger --prefix server # writes swagger-fragment.json; commit it
.gitea/workflows/pr-checks.yml runs all of the above on every pull request, plus one job this
machine cannot run on its own: frozen-manifest clones core at the sha pinned in
ci/core-ref.json, generates its route table without this module and then with
it, and takes the difference. That difference is the URL surface this module serves — checked
against the committed routes.manifest.json, against the OpenAPI fragment
in both directions, and against the rule that a module may only add. It is the only thing that
can see whether /rust collides with one of the routes core mounts at a tier root (/status,
/version), which the loader's own collision probe cannot find.
How it reaches an operator
An operator never builds anything. 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.
Every merge to main carrying a releasable commit publishes a bundle. The next version is
computed from conventional-commit subjects since the newest v* tag, as in link, installer and
Module-uo: feat!: or BREAKING CHANGE is a major, feat: a minor, fix: or perf: a patch,
and a main that gained none of those cuts no release. The number that ships is the tag, and CI
writes it into the module.json inside the bundle. module.json's version survives as a floor:
name a version there above the newest tag and that version releases, which is how you overrule the
subjects. For a change with nothing releasable behind it — a widened coreApi, a new mount, a
capability — run the Release workflow by hand (Actions → Release → Run workflow).
Each release carries:
| Asset | What it is |
|---|---|
module-rust-<version>.tar.gz |
the directory core expects at modules/rust/, already assembled |
module-rust-<version>.json |
the install manifest: id, version, coreApi, the artifact's URL, size and sha256 |
SHA256SUMS |
the same hash, in the shape every other repo here publishes |
Releases are unsigned; the sha256 is the trust anchor, and the website verifies it before
unpacking. That is the model installer's bundles already use, and a second trust model would be a
second thing to get right.
The tarball is assembled from an include list (ci/bundle.json), never an
exclude list — an exclude list ships whatever it forgot. Tests, scripts, client/src, ci/ and the
dev dependencies are not in it. It carries no node_modules, because the shipped half declares
no runtime dependencies: everything it needs arrives on ctx. npm run check:bundle holds both
halves of that — that the list still covers every file server/index.js can reach, and that no
runtime dependency has appeared without the release learning to pack it.
Install it into a core
From a release, which is the supported path: in Admin → Modules, paste the URL of that release's
module-rust-<version>.json, and restart when the panel offers. Core fetches the manifest, checks
every URL and redirect hop against its own host allowlist, streams the artifact under a byte cap
while hashing it, verifies the sha256, inspects the archive in full before unpacking it to a
temporary directory, and only then moves it into modules/rust/. Nothing is written into the
modules directory until every check has passed. The allowlist must contain
gitea.whitlocktech.com — it is seeded from MODULE_SOURCE_HOSTS on a fresh install and is
DB-owned from then on, edited on that same screen. An empty allowlist forbids every install rather
than permitting all of them.
From a working tree, for development: copy the whole tree to <website>/modules/rust/ and
restart. Copy, do not symlink — the loader lists directory entries and asks each whether it is a
directory; a symlink answers no and the module is skipped in complete silence.
Either way, the module appears when the process restarts: the volume is read at require time.
Then, in Admin → Rust, add a server: its name, the sidecar's base URL, and the token the sidecar
printed on first start (rust-link-sidecar --print-config). The token is write-only — it is
stored encrypted through core's own secret box and never returned to any client; the panel reports
only whether one is set.
POST /api/v1/admin/rust/servers/:id/test probes a sidecar and reports what came back in one word.
That is the route that tells a wrong URL from a wrong token from a mismatched protocol version —
all three present as "the site says my server is offline" and each has a different fix.
The protocol is a contract
PROTOCOL_VERSION in server/sidecarClient.js is sent on every request as X-RustLink-Version,
and a sidecar speaking a different one answers 409 rather than serving something this module will
mis-parse. It must agree with the sidecar's own constant and with overlay.toml in the plugin repo.
Canonical spec:
docs/rust-link/PROTOCOL.md.
The module's own design of record is
docs/modules/rust/PLAN.md.
Licence
GPL-3.0-or-later. See LICENSE.md.