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; each row carries the player's chat titles, and on one wipe of a server with Economics their coin balance
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
Player	GET /api/v1/player/rust/economics — your coin balances on every server, per linked account
Player	GET /api/v1/player/rust/backpacks?serverId=&steamId= — your own backpack on one server, read live
Admin	GET/PUT/DELETE /api/v1/admin/rust/servers and POST …/:id/test — the PUT carries the wipe schedule
Admin	GET/PUT /api/v1/admin/rust/visibility — who may see who is online, fleet-wide and per server
Admin	PUT …/servers/:id/titles, GET …/servers/:id/integrations, GET/PUT /api/v1/admin/rust/voice — chat titles, the optional mods a server has, and the announcement voice
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
Pages	/admin/rust/servers — add, edit, test and remove servers, set each one's wipe schedule and chat titles, and choose the announcement voice
Discord	/status, /wipe, /top, /online, /clan — read-only, answered from this module's tables
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 next wipe is the operator's to state (Admin → Rust servers): a rule — the monthly forced wipe only, weekly or every other week, each in the server's own time zone and always including the forced wipe (first Thursday, 19:00 UK time) — plus an optional one-off date that replaces the next computed wipe. It is computed on every read and never stored, so it cannot go stale after a wipe. The server list, the server page, the Android app and /wipe all show it.

Rust's own world events need no plugin (docs/modules/rust/PLAN_REDESIGNS.md §14.3.1). The patrol helicopter, Bradley, the cargo ship, the Chinook, airdrops, locked crates, the Travelling Vendor, the satellite and the Deep Sea reach the feed (a World events filter) and each is an engagement trigger (rust.world.<event>), so a notice or an event's phase can follow one. The event and its grid are public; a player's name in it only for the presence audience, a Steam id only for staff. Who downs a helicopter or a Bradley is the operator's rule per server — killing blow (the default), last hit, most damage, or everyone who hurt it — and the same rule writes the line and counts toward Rotorbane and Tankbreaker. Safecracker (locked crates hacked) and Scavenger (airdrops looted first) are title categories with leaderboard columns, and the Call a world event step (rust.world.call) calls one now, kept when the run ends: an airdrop or a patrol helicopter can be sent to a point.

Four uMod plugins are optional, and the module works without any of them (docs/modules/rust/PLAN.md §33). The bridge plugin's hard requirements are Kits and ZoneManager.

• BetterChat (LaserHydra, 5.2.15). With it: chat titles an operator sets per server — "top 3 playtime", "#1 kills" on the current wipe — shown in game chat and beside the name on the web and app leaderboards; and a chat style on any permission group this site authors, all twelve of BetterChat's group fields, mirrored like the group's permissions (a field changed in game is reported, never overwritten). Without it the titles still show on the web and the app, and the styles wait until it is installed.
• PopupNotifications (k1lly0u, 0.2.1). With it: rust.announce and a server's news posts can be a popup instead of a chat line. Without it a popup is refused with a sentence saying so, and chat works as before.
• Economics (Wulf, 3.9.2). With it: the Pay coins event step (rust.coins.pay, kept once paid), each player's balance on their account page and in the app, staff deposit / withdraw / set from a user's admin page, a Coins leaderboard column and the Magnate title — both ranking only balances above the server's starting balance. Without it each of those says "Economics is not installed on this server" (docs/modules/rust/PLAN_REDESIGNS.md §11.2).
• Backpacks (WhiteThunder, 3.17.8). With it: staff open any player's backpack from their admin page and a player sees their own on the account page and in the app — read live, never stored, and never written — and the Bigger backpack event step (rust.backpack.size) lends one of the server's backpacks.size.N sizes until the run ends, pushed like a kit reward. Without it each of those says "Backpacks is not installed on this server" (docs/modules/rust/PLAN_REDESIGNS.md §11.3).
• TruePVE (nivex, 2.4.6). With it: the Open a zone step (rust.zone.open) can say No PvP protection in this zone, or name one of the server's TruePVE rulesets, which holds for the zone's life and goes with it. A ruleset TruePVE does not have fails the step when it runs, with the name. Without it either one says "TruePVE is not installed on this server" (docs/modules/rust/PLAN_REDESIGNS.md §14.3.2).
• Dynamic PVP (HunterZ, 5.2.0; needs ZoneManager and TruePVE). With it: the PvP zones it opens around a downed patrol helicopter, a Bradley, the cargo ship and the rest show on the live map's PvP zones layer (public by default, set in Admin → Rust visibility) and as a public feed line — "A PvP zone opened around the downed patrol helicopter · G7 · for 10 min" — that names nobody. Its zones are its own: no step and no trigger (docs/modules/rust/PLAN_REDESIGNS.md §14.3.3).
• Dangerous Treasures (nivex, 3.0.0). With it: a treasure event starting and being won are public feed lines and triggers ("Alice won the treasure · K12 · 3 players fought for it", the name only for the presence audience), a running chest is on the live map's world layer, the Treasures leaderboard column and the Treasure Hunter title count the chests a player emptied, and the step Start a Dangerous Treasures event opens one at a chosen difficulty where DT picks. In the first ten minutes after DT loads the step says "Dangerous Treasures is not ready yet" and tries again ten minutes later. Refused where DT is absent, or where the framework cannot run DT's console command (docs/modules/rust/PLAN_REDESIGNS.md §14.3.4).
• Guarded Crate (Bazz3l, 2.0.17), with NpcSpawn (Codefling) for its guards. With both: a guarded crate landing and being cleared are public feed lines and triggers ("Alice cleared the guarded crate · M4", the name only for the presence audience), a running crate is on the live map's world layer, the Crates cleared leaderboard column and the Warden title count the crates a player cleared by killing the last guard, and the step Place a guarded crate places one of its events at a monument or a point. The crate is kept when the run ends — Guarded Crate cannot end one alone — and the run log says so. Refused where Guarded Crate or NpcSpawn is absent, where the event is not one the server has, or where the framework cannot run its console command (docs/modules/rust/PLAN_REDESIGNS.md §14.3.5).
• RaidableBases (nivex, 3.2.2, free or paid), with CopyPaste to paste its bases, and the raids helper RunicGatewayRaids.cs the plugin ships beside the bridge. With them: a base appearing, raided, bought or locked to a player are public feed lines ("Alice and Bob raided a Hard raid base · G7", the names only for the presence audience), every live base is on the live map's own Raid bases layer (public by default, set in Admin → Rust visibility), the Raid bases leaderboard column and the Warlord title count the bases a player raided, and the step Spawn a raid base spawns one: at a difficulty, a profile or a named base, where RaidableBases picks or at a spot, with its own PvP, NPCs, despawn time and lock. That base is the event's, despawned when the run ends. A dry run checks a spot and says what is in the way, as advice. Every difficulty, profile and base name is the server's own. Without the helper the step can still ask RaidableBases for a base where it picks, but it despawns on its own timer, and the step says so. RaidableBases' profiles are editable from Mod configuration, reloaded and rolled back like any config (docs/modules/rust/PLAN_REDESIGNS.md §11.4).
• ZLevels Remastered (nivex, 3.3.1). The servers page says whether it is loaded, and that is all: its levels are never read, and the leaderboard has no column for them. Its XP boosts are its own permissions (zlevelsremastered.vip1–vip3), so a Double XP weekend is a Permissions until the event ends step, which takes effect at once and is taken back when the run ends (docs/modules/rust/PLAN_REDESIGNS.md §14.3.6).

Any other plugin, by console command. Run console commands runs the commands an admin types (at most ten) once on one server, such as RaidableBases' rbe, and optional teardown commands when the run ends or is cancelled. Reward by console command runs them once for each person the kit reward's picker picks, with {steamid} and {name} filled in by the bridge, such as sr add {steamid} 100. Anyone offline at that moment is skipped and named in the run log. There is no allowlist. Both steps are rated irreversible, so they are off until an admin switches them on, only an admin can author them, and each needs its "I am sure" toggle ticked. A command the server does not know stops the step as unknown-command. The run log shows what the console answered: "it ran" is not "it worked". The site learns nothing afterwards, so none of it reaches the feed, the map or a title (docs/modules/rust/PLAN_REDESIGNS.md §16).

News and event lines said in chat can wear one styled group's title and colours — the announcement voice, chosen in Admin → Rust servers. The line is said by the bridge plugin with no player as its sender, so it looks the same with or without BetterChat.

The Discord commands answer from the tables, never from a game server, inside core's three-second budget. Every refusal is private. An answer narrower than public goes to the caller alone: a moderator's /online in a public channel shows the names to the moderator, never to the channel, and the same for a clan roster. Everything else is posted where it was asked.

The rest of the module 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 servers, 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.