wtclaude
22fd8c5da7
Phase 4. `/rust` is the server list and the module's landing page (D12);
`/rust/servers/:id` is one server with four tabs — feed, leaderboard, who is
on, wipes (D13). Everything selectable lives in the URL, so any view of the
page is a link. The feed and the presence list poll every twenty seconds while
the tab is visible and not at all when it is not (D14); the leaderboard and the
wipe list load once. `site.footer.status` is filled with a live server and
player count (D15).
Nothing on these pages calls a game server. Every field comes from this
module's own tables, which is what the phase criterion is about: the site
renders the last thing each server said while every server is off.
Walking that criterion in a browser against a live rig found four defects, two
of them already shipped in phase 3:
* An unreachable refresh called `putState` — the whole-row write — with two
fields, so a host that rebooted lost its hostname, map, size, seed and wipe
id. The list then read "Offline" with nothing beside it, which is not "here
is what we know" but "we have never heard of it". `markUnreachable` now
moves three columns and mentions no others.
* "Last reported" read `updated_at`, which a FAILED poll writes too — so an
offline server claimed it had reported just now, every thirty seconds, for
as long as it stayed down. `last_seen_at` is the new column, moved only by a
frame that arrived.
* Feed rows showed a bare time of day, so three events from six weeks ago all
read as this afternoon once the feed was filtered to a past wipe.
* `/rust/servers/typo` rendered core's ErrorState under its own heading and
read "No such server / Something went wrong", sending a reader who mistyped
a URL looking for an outage.
Also: a detail route (`GET …/servers/:id`), because it is the only route under
that path that can say a server does not exist — the other four answer an empty
list for an id nobody configured, and each of those is a good answer to its own
question.
`useAsync` cannot poll: it blanks its data on every dependency change, so a
twenty-second refresh built on it would clear the killfeed and re-fill it four
times a minute. `hooks/usePolled.js` is the module's own, invisible when it
succeeds and keeping the rows when it fails.
The client test fake was *nearly* core — it prefixed routes without stripping
the trailing separator, so the first module to register an index route failed
the nav check for a link that works in a browser. It now copies core's line
character for character.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4
166 lines
9.2 KiB
Markdown
166 lines
9.2 KiB
Markdown
# Module-Rust
|
|
|
|
The **[Rust](https://rust.facepunch.com/) 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`](https://gitea.whitlocktech.com/RunicGateway/Module-uo).
|
|
|
|
It is also the first module built from the
|
|
[Integration Kit](https://gitea.whitlocktech.com/RunicGateway/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.
|
|
|
|
## Build and check
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`](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`](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`](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`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/rust-link/PROTOCOL.md).
|
|
The module's own design of record is
|
|
[`docs/modules/rust/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/modules/rust/PLAN.md).
|
|
|
|
## Licence
|
|
|
|
GPL-3.0-or-later. See [LICENSE.md](LICENSE.md).
|