Module-Rust/README.md

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
Public	GET …/servers/:id/clans — the server's clans, best score first (public: names nobody)
Public	GET /api/v1/public/rust/clans/:externalId — one clan, and its roster inside the roster audience
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
Admin	GET/PUT /api/v1/admin/rust/visibility — who may see who is online, fleet-wide and per server
Pages	/rust — the server list, and the module's landing page
Pages	/rust/servers/:id — one server: feed, leaderboard, who is on, wipes, clans
Pages	/rust/clans/:externalId — one clan, with core's Team notify, activity and forum in three module slots
Teams	The deployment's Team provider: a first-party Rust clan is a Team
Slot	site.footer.status — a live server/player count in core's footer

Nothing names who is online by default. The Online list, every feed item that says a named player was on the server (connects, respawns, deaths, chat, gather tallies) and the leaderboard's "last seen" reach staff unless an operator widens them in Admin → Rust visibility — fleet-wide, with an optional override per server. How many players are online is public at every setting. The viewer's standing is re-read from the database on each request, so a demotion or a ban applies at once rather than when a token expires.

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.

Teams come from Rust's own clans, not from the uMod Clans plugin, which is optional and whose clans never become Teams. A clan's roster reaches its own members and staff unless an operator widens it in Admin → Rust visibility; its name, colour, score and count are public. The game lists at most 100 clans per server, and a server at that ceiling answers core partially, so core never removes a Team on its word. Core holds one Team provider per site, which is one reason a site runs one module: core's installer refuses a second.

The rest of the module — 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 servers alone is a word another module could declare tomorrow and silently reveal this one's screens. rust is the string that can only mean this module, and it is the single gate a whole navigation group hangs on — exactly the job shard does for module-uo.
• id answers a different question. It is a mount prefix (§2.1 requires it to equal the directory core loads the module from), and MODULE_API.md §2.9 is explicit that a client must never infer a route from a capability. Gating on id would quietly make the two the same thing, and the day a client builds /<id>/servers from 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.