feat: ingest protocol 2, and keep the record a wipe cannot erase

The module half of the read path. Seven tables, an ingest cursor, four public
routes, and one file whose only job is deciding who may see what.

**The record and the window are different things.** `rust_player_wipe_stats` and
`rust_gather_totals` are permanent and per-wipe, so all-time is those rows SUMmed
rather than a second set of counters that can disagree with them — that is R12's
"per-wipe detail plus all-time rollups" in one table instead of two.
`rust_events` is a bounded 30-day window of raw frames for the killfeed, and
`rust_presence` is a board: replaced wholesale, never appended.

**The feed is a cursor, not a socket, and the header says why.** 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 has no runtime dependencies (D5). The
deciding argument is the other one though: a socket needs a cursor anyway, for
whatever it missed while the module was restarting, and the catch-up path is the
one that has to be right. A cursor alone is one mechanism exercised every five
seconds rather than two where the second only runs after an outage.

**The cursor advances after the batch, never before.** A crash between the two
re-reads events already counted, which inflates a total; the other order loses
them silently and for ever. One is visible and bounded, the other is invisible
and permanent, so the code fails in the visible direction. A server with no
cursor starts at the sidecar's current END rather than at zero — replaying a
fortnight of deaths into stats for wipes the site never saw is not a catch-up.

**`catalogue.js` is a security boundary, default-deny.** Protocol 2 carries IP
addresses (login attempts, approvals, bans), one player's report about another,
and the grid reference of somebody's base. They are stored, because an operator
chasing ban evasion needs them; they are not served below the admin tier. The
allowlist lives here rather than as a field on the wire, because a boundary
declared by the sender is one a compromised or merely out-of-date game host can
widen — the same reason core's own shard fan-out filters on the serving side. A
kind this build has never heard of is not public, and a test holds the list
against PROTOCOL.md §8.4 so that adding a kind to the protocol without
classifying it fails a build.

`PROTOCOL_VERSION` goes to 2 here in the same change as the emitters, though this
module consumes none of the new frames yet: the sidecar refuses a mismatched
client with a 409, so a module left on 1 would stop being able to read the board
it has been reading all along. A constant that lags the deployment is an outage
with a version number on it.

95 server tests, 20 client tests, every guard green, and `routes.manifest.json`
regenerated against a real core at the pinned ref: 10 routes, all documented,
none of core's moved.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4

ci/bundle.json

@@ -28,9 +28,11 @@
   ],
   "server": [
     "boot.js",
+    "catalogue.js",
     "core.js",
     "db",
     "index.js",
+    "ingest.js",
     "model",
     "package.json",
     "router",

routes.manifest.json

@@ -21,6 +21,26 @@
       "path": "/api/v1/public/rust/servers",
       "tier": "public"
     },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/rust/servers/:id/events",
+      "tier": "public"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/rust/servers/:id/leaderboard",
+      "tier": "public"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/rust/servers/:id/online",
+      "tier": "public"
+    },
+    {
+      "method": "GET",
+      "path": "/api/v1/public/rust/servers/:id/wipes",
+      "tier": "public"
+    },
     {
       "method": "POST",
       "path": "/api/v1/admin/rust/servers/:id/test",

server/boot.js

@@ -21,25 +21,52 @@
 // letting that fail the boot would make installing the module before installing
 // the bridge impossible.
 //
-// ── Polling, in phase 1 ───────────────────────────────────────────────────
+// ── Three timers, and they answer three different questions ───────────────
 //
-// This is a poll, and the live feed it will become is a later phase's work. The
-// poll is not a placeholder for it: a sidecar's store-backed reads are exactly
-// what answers while a game server is off, and the module will keep reading them
-// on an interval to notice a server that went away without saying anything.
-// What the feed adds is latency, not coverage.
+//   refresh   (30s)  what is each server, and who is on it — the BOARDS
+//   ingest     (5s)  what has happened since we last looked — the CURSOR
+//   prune       (1h)  forgetting the detail we promised not to keep for ever
+//
+// The boards poll and the ingest are deliberately separate rather than one loop
+// reading both. They fail differently and they matter differently: a board that
+// is 30 seconds stale shows a player count slightly behind, and an ingest that
+// is 30 seconds behind shows a killfeed that feels broken. Splitting them lets
+// the cheap one run often and the expensive one run rarely, and it means a
+// sidecar that answers one and not the other degrades in exactly one place.
+//
+// The poll was never a placeholder for a socket: a sidecar's store-backed reads
+// are what answer while a game server is off, which is most of what this module
+// renders. See `ingest.js` for why the live feed is a cursor and not a
+// WebSocket.
 
 const core = require('./core')
 
 const db = require('./model/servers/servers.db')
+const eventsDb = require('./model/events/events.db')
+const ingest = require('./ingest')
 const servers = require('./model/servers/servers.model')
 const sidecar = require('./sidecarClient')
 
 const log = core.logger('boot')
 
 let refreshTimer = null
+let ingestTimer = null
+let pruneTimer = null
 
 const REFRESH_MS = 30 * 1000
+const INGEST_MS = 5 * 1000
+const PRUNE_MS = 60 * 60 * 1000
+
+/**
+ * How long this module keeps raw events.
+ *
+ * Longer than the sidecar's 14 days, because this is the richer store and the
+ * one a page reads — and because the sidecar lives on somebody's game host while
+ * this lives on the website's own database. What is NOT bounded by it is the
+ * record: `rust_player_wipe_stats` and `rust_gather_totals` are permanent, which
+ * is the whole of R12's "a wipe does not erase a player's history".
+ */
+const EVENT_RETENTION_DAYS = 30
 
 /**
  * Ask every configured sidecar how its server is doing, and store what it said.
@@ -63,7 +90,10 @@ async function refresh() {
 
 async function refreshOne(server) {
   try {
-    const board = await sidecar.serverBoard(server)
+    // One call for both boards. `/server` would answer the same question about
+    // the server itself, but presence would then be a second round trip to the
+    // same process for a fact it already had in hand.
+    const board = await sidecar.boards(server)
 
     // Three outcomes, and collapsing any two of them loses something an operator
     // needs:
@@ -80,12 +110,20 @@ async function refreshOne(server) {
       return
     }
 
-    const frame = board.data
+    const boards = (board.data && board.data.boards) || {}
+    const frame = boards['server.hello']
+
     if (!frame) {
+      // The sidecar is up and has never heard from the game. Presence is emptied
+      // rather than left alone: a stale list of players on a server nobody can
+      // reach is worse than an empty one, because it looks current.
       await db.putState({ serverId: server.id, reachable: true, online: false })
+      await ingest.applyBoards(server.id, {})
       return
     }
 
+    await ingest.applyBoards(server.id, boards)
+
     await db.putState({
       serverId: server.id,
       reachable: true,
@@ -102,6 +140,7 @@ async function refreshOne(server) {
       worldSize: frame.worldSize === undefined ? null : Number(frame.worldSize),
       bootId: frame.bootId || null,
       saveCreatedAt: frame.saveCreatedAt || null,
+      wipeId: frame.wipeId || null,
       protocol: frame.protocol === undefined ? null : Number(frame.protocol),
       raw: frame,
     })
@@ -119,14 +158,44 @@ async function refreshOne(server) {
  * built to look like it — so a module that only needs core at boot time can skip
  * `core.init` entirely and use this argument.
  */
+/** Runs the cursor for every configured server, independently. */
+async function ingestAll() {
+  let rows
+
+  try {
+    rows = await servers.listForPolling()
+  } catch (err) {
+    log.warn('could not read the server list', { error: err.message })
+    return
+  }
+
+  // `allSettled`, for the same reason the board poll uses it: six servers behind
+  // one unreachable host must not stop the other five being ingested.
+  await Promise.allSettled(rows.map((server) => ingest.ingestServer(server)))
+}
+
+async function prune() {
+  try {
+    const gone = await eventsDb.pruneEvents(EVENT_RETENTION_DAYS)
+    if (gone > 0) log.info('pruned old events', { events: gone, days: EVENT_RETENTION_DAYS })
+  } catch (err) {
+    log.warn('could not prune events', { error: err.message })
+  }
+}
+
 async function onBoot() {
   await refresh()
   refreshTimer = setInterval(refresh, REFRESH_MS)
+  ingestTimer = setInterval(ingestAll, INGEST_MS)
+  pruneTimer = setInterval(prune, PRUNE_MS)
   // Node keeps the process alive for a pending timer. Core's own intervals are
   // unref'd for exactly this reason: a module that forgets turns `Ctrl-C` into a
   // thirty-second wait, and on a host it turns a `systemctl stop` into a SIGKILL.
-  if (typeof refreshTimer.unref === 'function') refreshTimer.unref()
-  log.info('booted', { refreshMs: REFRESH_MS })
+  for (const timer of [refreshTimer, ingestTimer, pruneTimer]) {
+    if (timer && typeof timer.unref === 'function') timer.unref()
+  }
+
+  log.info('booted', { refreshMs: REFRESH_MS, ingestMs: INGEST_MS })
 }
 
 /**
@@ -138,9 +207,25 @@ async function onBoot() {
  * rather than cancelled, since nothing can stop a promise that is still running.
  */
 async function onShutdown() {
-  if (refreshTimer) clearInterval(refreshTimer)
+  for (const timer of [refreshTimer, ingestTimer, pruneTimer]) {
+    if (timer) clearInterval(timer)
+  }
+
   refreshTimer = null
+  ingestTimer = null
+  pruneTimer = null
+
   log.info('shut down')
 }
 
-module.exports = { onBoot, onShutdown, refresh, refreshOne, REFRESH_MS }
+module.exports = {
+  onBoot,
+  onShutdown,
+  refresh,
+  refreshOne,
+  ingestAll,
+  prune,
+  REFRESH_MS,
+  INGEST_MS,
+  EVENT_RETENTION_DAYS,
+}

server/catalogue.js

@@ -0,0 +1,118 @@
+// ── What the bridge can say, and who may hear it ──────────────────────────
+//
+// One file, because these two questions have to be answered together or the
+// second one rots: which frame kinds exist, and which of them a member of the
+// public may see.
+//
+// ── The boundary ──────────────────────────────────────────────────────────
+//
+// Protocol 2's catalogue includes frames carrying **IP addresses** (a login
+// attempt, an approval, a ban) and **one player's complaint about another** (a
+// report), and one — a destroyed structure — that names where somebody lives.
+// They are stored, because an operator chasing ban evasion needs them and
+// because the sidecar persists what it is told. They must never reach a public
+// page.
+//
+// **The boundary is enforced HERE, on the side that serves, and not on the wire.**
+// The plugin could have stamped a `class` on every frame and saved this file the
+// trouble; it deliberately does not (PROTOCOL.md §8.5). A boundary declared by
+// the sender is a boundary a compromised — or merely out-of-date — game host can
+// widen. Core'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.
+//
+// ── Default deny, and why it is not paranoia ──────────────────────────────
+//
+// `isPublic` answers `false` for a kind it has never heard of. That matters
+// because of the shape of the mistake it prevents: the next protocol version
+// adds a kind, this module ingests it happily (`rust_events` stores what it is
+// given), and a page that filtered by a DENY list would publish it the day it
+// first arrived — before anybody had decided whether it should be public. With
+// an allowlist the new kind is invisible until somebody adds it here, which is
+// the same moment they think about it.
+//
+// The test holds this list against `docs/rust-link/PROTOCOL.md` §8.4's table, so
+// adding a kind to the spec without classifying it fails a build rather than
+// shipping an address to a public page.
+
+/**
+ * Kinds a public, signed-out visitor may see.
+ *
+ * Each entry is a decision. `player.chat` is here because a shard's chat is
+ * public by the same logic that makes a killfeed public — it happened in front
+ * of everyone who was on the server — and an operator who disagrees turns the
+ * feature off rather than relying on this list being wrong.
+ */
+const PUBLIC_KINDS = Object.freeze([
+  'player.connected',
+  'player.disconnected',
+  'player.respawned',
+  'player.death',
+  'player.chat',
+  'player.tally',
+  'server.wipe',
+  'server.initialized',
+  'server.shutdown',
+])
+
+/**
+ * Kinds an admin may see and nobody else.
+ *
+ * Listed rather than implied by absence, so that "we know about this kind and it
+ * is restricted" is distinguishable from "nobody has classified this kind" — the
+ * second is a finding, and a bare allowlist cannot tell you which you are
+ * looking at.
+ */
+const STAFF_KINDS = Object.freeze([
+  'entity.destroyed',
+  'player.reported',
+  'player.banned',
+  'player.unbanned',
+  'player.login.attempt',
+  'player.approved',
+])
+
+/** Every kind protocol 2 defines. */
+const ALL_KINDS = Object.freeze([...PUBLIC_KINDS, ...STAFF_KINDS])
+
+const PUBLIC = new Set(PUBLIC_KINDS)
+const STAFF = new Set(STAFF_KINDS)
+
+/**
+ * May a signed-out visitor see this kind?
+ *
+ * Default deny: an unknown kind is not public. Callers pass whatever arrived on
+ * the wire, including a kind from a newer protocol this build has never seen.
+ */
+function isPublic(kind) {
+  return PUBLIC.has(kind)
+}
+
+/** Is this a kind this build knows about at all? */
+function isKnown(kind) {
+  return PUBLIC.has(kind) || STAFF.has(kind)
+}
+
+/**
+ * Narrows a list of requested kinds to the ones a viewer may have.
+ *
+ * Returning the allowlist itself when nothing was requested is what makes the
+ * public route safe by construction rather than by remembering to filter: there
+ * is no code path where "no filter" means "everything".
+ */
+function kindsFor({ admin = false, requested = null } = {}) {
+  const permitted = admin ? ALL_KINDS : PUBLIC_KINDS
+
+  if (!requested || requested.length === 0) return [...permitted]
+
+  const allowed = new Set(permitted)
+  return requested.filter((k) => allowed.has(k))
+}
+
+module.exports = {
+  PUBLIC_KINDS,
+  STAFF_KINDS,
+  ALL_KINDS,
+  isPublic,
+  isKnown,
+  kindsFor,
+}

server/db/purge.sql

@@ -19,5 +19,12 @@
 -- it knows this module registered, because it is the side that knows which
 -- registrant owned what.
 
+DROP TABLE IF EXISTS rust_ingest_cursor;
+DROP TABLE IF EXISTS rust_presence;
+DROP TABLE IF EXISTS rust_events;
+DROP TABLE IF EXISTS rust_gather_totals;
+DROP TABLE IF EXISTS rust_player_wipe_stats;
+DROP TABLE IF EXISTS rust_players;
+DROP TABLE IF EXISTS rust_wipes;
 DROP TABLE IF EXISTS rust_server_state;
 DROP TABLE IF EXISTS rust_servers;

server/db/schema.sql

@@ -14,14 +14,20 @@
 -- Every table here is prefixed `rust_`, which is this module's id and the only
 -- prefix it may create under.
 --
--- ── Two tables, and the split between them is the whole design ────────────
+-- ── Four kinds of table, and the split between them is the whole design ───
 --
--- `rust_servers` is CONFIGURATION: rows an operator writes, from Admin → Rust.
--- `rust_server_state` is OBSERVED STATE: rows this module writes from what a
--- sidecar reported. They are separate tables rather than columns on one because
--- they have different writers, different lifetimes and different audiences —
--- and because a purge of observed state while keeping the configuration is a
--- thing an operator will eventually want.
+-- CONFIGURATION   `rust_servers` — rows an operator writes, from Admin → Rust.
+-- OBSERVED STATE  `rust_server_state`, `rust_presence` — what a sidecar last
+--                 reported, replaced rather than appended.
+-- THE RECORD      `rust_wipes`, `rust_players`, `rust_player_wipe_stats`,
+--                 `rust_gather_totals` — permanent, and the reason a wipe does
+--                 not erase a player's history.
+-- THE WINDOW      `rust_events` — recent detail, bounded by a sweep.
+--
+-- They are separate tables rather than columns on one because they have
+-- different writers, different lifetimes and different audiences — and because
+-- a purge of observed state while keeping the configuration is a thing an
+-- operator will eventually want.
 --
 -- Teardown is `purge.sql`, which no boot ever runs.
 
@@ -97,3 +103,198 @@ CREATE TABLE IF NOT EXISTS rust_server_state (
   CONSTRAINT fk_rust_server_state_server
     FOREIGN KEY (server_id) REFERENCES rust_servers (id) ON DELETE CASCADE
 );
+
+
+-- ── The read path ─────────────────────────────────────────────────────────
+--
+-- Protocol 2 turned the bridge from a greeting into a catalogue, and these are
+-- the tables that hold it. They divide on one line, and it is the line R12 drew:
+--
+--   PERMANENT   `rust_wipes`, `rust_players`, `rust_player_wipe_stats`,
+--               `rust_gather_totals` — a player's record, kept for ever. All-time
+--               is a SUM across wipes rather than a second set of counters, so
+--               there is no second number that can disagree with the first.
+--
+--   BOUNDED     `rust_events` — the recent raw window the killfeed reads, pruned
+--               on a sweep. It is detail, not record: losing last month's
+--               individual deaths costs a scroll-back, losing last month's
+--               totals costs a player their history.
+--
+--   DERIVED     `rust_presence` — who is on right now, replaced wholesale from
+--               the `players.online` board. Never a history, never appended.
+--
+-- The sidecar keeps its own bounded copy of the same events (default 14 days),
+-- so shortening either window loses recent detail and neither loses a total.
+
+
+-- ── Wipes ─────────────────────────────────────────────────────────────────
+--
+-- One row per (server, wipe). The id is the plugin's, derived from the save's
+-- creation time and stamped on every frame (PROTOCOL.md §8.2) — this module
+-- never derives one, because two derivations of one fact eventually disagree
+-- about a boundary.
+--
+-- Rows appear by being MENTIONED: the first frame carrying a wipe id this module
+-- has not seen creates it. There is no "start a wipe" call and there must not be
+-- one, because the website is not present when a wipe happens — a wipe is a fact
+-- about a world that was restarted while nobody was watching.
+CREATE TABLE IF NOT EXISTS rust_wipes (
+  server_id   VARCHAR(64)  NOT NULL,
+  wipe_id     VARCHAR(48)  NOT NULL,
+  save_created_at VARCHAR(32) NULL,
+  first_seen  DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  last_seen   DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (server_id, wipe_id),
+  CONSTRAINT fk_rust_wipes_server
+    FOREIGN KEY (server_id) REFERENCES rust_servers (id) ON DELETE CASCADE
+);
+
+
+-- ── Players ───────────────────────────────────────────────────────────────
+--
+-- Identity, and deliberately nothing else. It is keyed on the Steam id alone
+-- and carries no server: a player is the same person on all six of a community's
+-- servers, and everything that is per-server lives in the stats table.
+--
+-- `user_id` is NOT here. Linking a Steam id to a website account is phase 6's
+-- work (R1), and a column waiting for it would be a column every read has to
+-- remember is always null.
+CREATE TABLE IF NOT EXISTS rust_players (
+  steam_id    VARCHAR(32)  NOT NULL PRIMARY KEY,
+  name        VARCHAR(191) NULL,
+  first_seen  DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  last_seen   DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+
+-- ── The permanent record ──────────────────────────────────────────────────
+--
+-- One row per player per wipe per server, and the only counters this module
+-- keeps. R12's "per-wipe detail plus all-time rollups" is satisfied by SUMming
+-- this rather than by maintaining a second all-time row, because two counters
+-- for one fact drift the first time an ingest is replayed.
+--
+-- Every column is a COUNT that only ever goes up within a wipe, which is what
+-- makes ingest idempotent-ish in the only way that matters: the cursor advances
+-- only after the batch commits, so a crash re-reads a batch it has not counted.
+--
+-- `playtime_sec` comes from `sessionSec` on a disconnect, and a session whose
+-- start this module never saw contributes NOTHING rather than zero — the plugin
+-- omits the field, the ingest skips it, and the number stays honestly short
+-- instead of quietly wrong.
+CREATE TABLE IF NOT EXISTS rust_player_wipe_stats (
+  server_id     VARCHAR(64)     NOT NULL,
+  wipe_id       VARCHAR(48)     NOT NULL,
+  steam_id      VARCHAR(32)     NOT NULL,
+  kills         INT UNSIGNED    NOT NULL DEFAULT 0,
+  deaths        INT UNSIGNED    NOT NULL DEFAULT 0,
+  suicides      INT UNSIGNED    NOT NULL DEFAULT 0,
+  npc_kills     INT UNSIGNED    NOT NULL DEFAULT 0,
+  structures    INT UNSIGNED    NOT NULL DEFAULT 0,
+  sessions      INT UNSIGNED    NOT NULL DEFAULT 0,
+  playtime_sec  BIGINT UNSIGNED NOT NULL DEFAULT 0,
+  last_seen     DATETIME        NULL,
+  PRIMARY KEY (server_id, wipe_id, steam_id),
+  KEY idx_rust_stats_kills (server_id, wipe_id, kills DESC),
+  KEY idx_rust_stats_player (steam_id)
+);
+
+
+-- ── What they gathered ────────────────────────────────────────────────────
+--
+-- A row per resource rather than a JSON blob on the stats row, for one reason:
+-- the leaderboard question is "who gathered the most sulfur this wipe", and that
+-- is an ORDER BY over a column in every SQL engine and a JSON function call in
+-- exactly one. The resource name is the game's own shortname, unknown in advance
+-- and not worth a lookup table.
+CREATE TABLE IF NOT EXISTS rust_gather_totals (
+  server_id  VARCHAR(64)     NOT NULL,
+  wipe_id    VARCHAR(48)     NOT NULL,
+  steam_id   VARCHAR(32)     NOT NULL,
+  resource   VARCHAR(64)     NOT NULL,
+  amount     BIGINT UNSIGNED NOT NULL DEFAULT 0,
+  PRIMARY KEY (server_id, wipe_id, steam_id, resource),
+  KEY idx_rust_gather_top (server_id, wipe_id, resource, amount DESC)
+);
+
+
+-- ── The recent raw window ─────────────────────────────────────────────────
+--
+-- Every ingested event, whole, for as long as the retention sweep keeps it. The
+-- killfeed reads this; so does an admin looking at what happened.
+--
+-- `raw` holds the entire frame and the columns beside it are only what a query
+-- needs to reach — the same rule the sidecar's own store follows, one hop along:
+-- a protocol version that adds a field needs no migration here.
+--
+-- **`kind` is a security boundary, not a label.** Some kinds carry IP addresses
+-- and player reports (PROTOCOL.md §8.4), and what makes them safe is that the
+-- public read is filtered by an allowlist this module holds, default-deny. The
+-- rows are stored either way, because an operator chasing ban evasion needs them.
+CREATE TABLE IF NOT EXISTS rust_events (
+  id          BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  server_id   VARCHAR(64)     NOT NULL,
+  wipe_id     VARCHAR(48)     NULL,
+  kind        VARCHAR(64)     NOT NULL,
+  t           BIGINT          NOT NULL,
+  steam_id    VARCHAR(32)     NULL,
+  raw         LONGTEXT        NOT NULL,
+  created_at  DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  KEY idx_rust_events_server (server_id, id DESC),
+  KEY idx_rust_events_kind (server_id, kind, id DESC),
+  KEY idx_rust_events_wipe (server_id, wipe_id, id DESC),
+  KEY idx_rust_events_created (created_at)
+);
+
+
+-- ── Who is on right now ───────────────────────────────────────────────────
+--
+-- Replaced wholesale every time the `players.online` board arrives, which is on
+-- every bridge connect and every 60 seconds. It is a BOARD, and the reason it is
+-- its own table rather than rows in `rust_events` is that a board answers "now"
+-- and an event answers "then"; storing a board as history is the mistake the
+-- wire's `type` field exists to prevent, and it would be a shame to make it here
+-- after the sidecar went to the trouble of not making it there.
+CREATE TABLE IF NOT EXISTS rust_presence (
+  server_id     VARCHAR(64)  NOT NULL,
+  steam_id      VARCHAR(32)  NOT NULL,
+  name          VARCHAR(191) NULL,
+  sleeping      TINYINT(1)   NOT NULL DEFAULT 0,
+  connected_at  DATETIME     NULL,
+  updated_at    DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (server_id, steam_id)
+);
+
+
+-- ── The ingest cursor ─────────────────────────────────────────────────────
+--
+-- Where this module has read up to in each sidecar's feed. One row per server.
+--
+-- It is persisted rather than held in memory because the alternative is a module
+-- that re-reads everything on every boot or nothing at all, and both are wrong in
+-- a way that only shows up in production. The cursor advances **after** the batch
+-- is written, never before: a crash mid-batch re-reads rows it has not counted,
+-- which is the safe direction to be wrong in.
+--
+-- A NEW server starts at the sidecar's current end rather than at zero (see
+-- `GET /feed` with no `since`). A module installed today against a sidecar that
+-- has been running a month wants what happens next — replaying a fortnight of
+-- deaths into stats whose wipes it never saw is not a catch-up, it is a
+-- fabrication of history it was not present for.
+CREATE TABLE IF NOT EXISTS rust_ingest_cursor (
+  server_id      VARCHAR(64)     NOT NULL PRIMARY KEY,
+  last_event_id  BIGINT UNSIGNED NOT NULL DEFAULT 0,
+  events_seen    BIGINT UNSIGNED NOT NULL DEFAULT 0,
+  updated_at     DATETIME        NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  CONSTRAINT fk_rust_cursor_server
+    FOREIGN KEY (server_id) REFERENCES rust_servers (id) ON DELETE CASCADE
+);
+
+
+-- ── Changes to tables that already shipped ────────────────────────────────
+--
+-- An ALTER below the CREATE, never an edit to it: `CREATE TABLE IF NOT EXISTS`
+-- does nothing against a database that already has the table, so an edited column
+-- would reach fresh installs only — which is the worst possible distribution for
+-- a schema change, because it works everywhere it is tested.
+ALTER TABLE rust_server_state ADD COLUMN IF NOT EXISTS wipe_id VARCHAR(48) NULL;

server/ingest.js

@@ -0,0 +1,242 @@
+// ── Reading a sidecar's feed, and turning it into a record ────────────────
+//
+// One job: move each server's cursor forward, and apply what it passed.
+//
+// ── Why a cursor and not a socket ─────────────────────────────────────────
+//
+// The obvious design is a WebSocket — the sidecar has one, and module-uo takes
+// exactly that route for the UO bridge. This module polls a cursor instead, and
+// the reason is not laziness about latency.
+//
+// Core runs on Node 20, where a global `WebSocket` is still behind a flag, so a
+// socket means taking `ws` as a runtime dependency — and this module's release
+// asserts that it has none (D5: everything it needs arrives on `ctx`, and the
+// bundle ships no `node_modules`). That is a cost worth paying for latency, but
+// the deciding argument is the other one: **a socket needs a cursor anyway.**
+// Whatever a feed misses while a module is restarting has to be caught up from
+// somewhere, and the catch-up path is the one that must be right. A socket on
+// top of a cursor is two mechanisms where the second is load-bearing; a cursor
+// alone is one mechanism that is exercised every few seconds rather than only
+// after an outage nobody planned.
+//
+// What it costs is seconds of latency on a killfeed. What it buys is that the
+// path which recovers from a five-hour outage is the same path that ran a moment
+// ago.
+//
+// ── The ordering the whole thing rests on ─────────────────────────────────
+//
+// **The cursor advances after the batch is written, never before.** A crash
+// between the two re-reads events already counted, which inflates a total; a
+// crash the other way round loses them silently and for ever. Neither is good and
+// they are not equally bad — one is visible and bounded, the other is invisible
+// and permanent — so the code is arranged to fail in the visible direction.
+
+const core = require('./core')
+
+const db = require('./model/events/events.db')
+const sidecar = require('./sidecarClient')
+
+const log = core.logger('ingest')
+
+/** How many events to ask for at once. */
+const BATCH = 200
+
+/**
+ * How many batches one tick will drain before letting the loop breathe.
+ *
+ * A module that has been down for a day has thousands of events waiting, and
+ * draining them in one unbounded loop would hold the tick — and a pool
+ * connection — for as long as that takes. Bounded, it catches up over several
+ * ticks and the site stays responsive while it does.
+ */
+const MAX_BATCHES_PER_TICK = 10
+
+/**
+ * Applies one feed item.
+ *
+ * Every frame is stored raw, and only some of them move a counter. That split is
+ * deliberate: the raw row is what an admin reads and what a later phase can
+ * re-derive from, and the counters are what a leaderboard sums. A kind this
+ * build has never heard of still lands in `rust_events` — it costs nothing and
+ * the alternative is losing the one copy of an event the next version will know
+ * how to read.
+ */
+async function apply(serverId, item) {
+  const frame = (item && item.frame) || {}
+  const kind = item.kind || frame.kind
+  const wipeId = frame.wipeId || null
+
+  // A wipe exists because something mentioned it. There is no "a wipe started"
+  // call and there must not be one: the website is not there when a wipe happens.
+  await db.touchWipe(serverId, wipeId, frame.saveCreatedAt || null)
+
+  await db.insertEvent({
+    serverId,
+    wipeId,
+    kind,
+    t: Number(frame.t) || item.t || Date.now(),
+    steamId: frame.steamId || null,
+    raw: frame,
+  })
+
+  const at = { serverId, wipeId, steamId: frame.steamId }
+
+  switch (kind) {
+    case 'player.connected':
+      await db.touchPlayer(frame.steamId, frame.name || null)
+      break
+
+    case 'player.disconnected': {
+      await db.touchPlayer(frame.steamId, frame.name || null)
+
+      // `sessionSec` is ABSENT when the plugin never saw the connect — a player
+      // already on the server when it loaded. Absent is not zero: adding a zero
+      // would be recording a session of no length, which is a different claim
+      // from recording no session, and it is the one that quietly under-reports
+      // playtime for ever.
+      const seconds = Number(frame.sessionSec)
+      await db.addStats(at, {
+        sessions: Number.isFinite(seconds) ? 1 : 0,
+        playtimeSec: Number.isFinite(seconds) && seconds > 0 ? seconds : 0,
+      })
+      break
+    }
+
+    case 'player.death': {
+      await db.touchPlayer(frame.steamId, frame.name || null)
+
+      // A suicide is a death AND a suicide, not one instead of the other: the
+      // deaths column is "how many times did this player die", and a leaderboard
+      // that silently omitted self-inflicted ones would disagree with the
+      // killfeed sitting next to it on the same page.
+      await db.addStats(at, { deaths: 1, suicides: frame.attackerType === 'self' ? 1 : 0 })
+
+      // Only a real player's kill counts. `npc` and `environment` have no
+      // attacker to credit, and `self` must not credit the victim with a kill —
+      // which is the one line here that would look right in review and produce a
+      // leaderboard topped by whoever died the most.
+      if (frame.attackerType === 'player' && frame.attackerId) {
+        await db.touchPlayer(frame.attackerId, frame.attackerName || null)
+        await db.addStats({ ...at, steamId: frame.attackerId }, { kills: 1 })
+      }
+      break
+    }
+
+    case 'player.tally': {
+      await db.touchPlayer(frame.steamId, frame.name || null)
+      await db.addStats(at, {
+        npcKills: Number(frame.npcKills) || 0,
+        structures: Number(frame.structures) || 0,
+      })
+
+      // A tally is a DELTA since the last flush, which is what makes adding it
+      // correct. If it ever becomes a running total this loop doubles every
+      // number in it, slowly, and looks right the whole time.
+      const gathered = frame.gathered || {}
+      for (const [resource, amount] of Object.entries(gathered)) {
+        await db.addGathered(at, resource, Number(amount) || 0)
+      }
+      break
+    }
+
+    case 'player.chat':
+    case 'player.respawned':
+      await db.touchPlayer(frame.steamId, frame.name || null)
+      break
+
+    default:
+      // Stored, not counted. Moderation frames, the server lifecycle, and
+      // anything a newer protocol sends that this build does not understand.
+      break
+  }
+}
+
+/**
+ * Brings one server's cursor up to date.
+ *
+ * Returns the number of events applied, for the log and for the tests.
+ */
+async function ingestServer(server) {
+  const cursor = await db.getCursor(server.id)
+
+  // A server this module has never ingested starts at the sidecar's CURRENT end,
+  // not at zero. A module installed today against a sidecar that has been running
+  // for a month should read what happens next — replaying a fortnight of deaths
+  // into stats for wipes it never saw is not a catch-up, it is inventing a
+  // history it was not present for. `/feed` with no `since` asks exactly that
+  // question, which is why the sidecar answers it that way.
+  if (!cursor) {
+    const tail = await sidecar.feedTail(server)
+
+    if (!tail.ok || !tail.data) {
+      // Unreachable. Write nothing: a cursor of 0 written now would replay the
+      // whole retained history the moment the sidecar came back.
+      return 0
+    }
+
+    await db.setCursor(server.id, Number(tail.data.lastId) || 0, 0)
+    log.info('cursor started at the feed tail', { server: server.id, at: tail.data.lastId })
+    return 0
+  }
+
+  let since = Number(cursor.lastEventId) || 0
+  let applied = 0
+
+  for (let batch = 0; batch < MAX_BATCHES_PER_TICK; batch += 1) {
+    const res = await sidecar.feed(server, since, BATCH)
+
+    if (!res.ok || !res.data) return applied
+
+    const items = Array.isArray(res.data.items) ? res.data.items : []
+
+    for (const item of items) {
+      try {
+        await apply(server.id, item)
+        applied += 1
+      } catch (err) {
+        // One malformed event must not wedge a server's cursor for ever. It is
+        // logged with its id so it can be found, and the cursor moves past it:
+        // the alternative is an ingest that stops at a single bad row and then
+        // silently stops being a feed at all.
+        log.warn('could not apply an event', {
+          server: server.id,
+          id: item && item.id,
+          kind: item && item.kind,
+          error: err.message,
+        })
+      }
+    }
+
+    const lastId = Number(res.data.lastId)
+
+    if (Number.isFinite(lastId) && lastId > since) {
+      // AFTER the batch. See the header.
+      await db.setCursor(server.id, lastId, items.length)
+      since = lastId
+    }
+
+    if (!res.data.more) break
+  }
+
+  if (applied > 0) log.info('ingested', { server: server.id, events: applied, cursor: since })
+
+  return applied
+}
+
+/**
+ * Applies the boards: what is true right now, rather than what happened.
+ *
+ * `players.online` replaces the presence rows wholesale, because that is what a
+ * board is. Storing it as history is the mistake the wire's `type` field exists
+ * to prevent, and it would be a poor return for the sidecar's trouble to make it
+ * here after it went out of its way not to make it there.
+ */
+async function applyBoards(serverId, boards) {
+  const presence = boards && boards['players.online']
+
+  if (presence && Array.isArray(presence.players)) {
+    await db.replacePresence(serverId, presence.players)
+  }
+}
+
+module.exports = { apply, applyBoards, ingestServer, BATCH, MAX_BATCHES_PER_TICK }

server/model/events/events.db.js

@@ -0,0 +1,289 @@
+// ── SQL for the read path ─────────────────────────────────────────────────
+//
+// Writes come from one caller (`server/ingest.js`) and reads from the routers.
+// They live together because they are the same tables and the invariants are
+// easier to keep true when the UPDATE and the SELECT are on the same screen.
+//
+// Raw parameterised SQL through `core.query`, no ORM. Placeholders always —
+// except for one place where a list of kinds is expanded into placeholders, and
+// that expansion is checked in `events.model.js` before it ever reaches here.
+
+const core = require('../../core')
+
+const EVENTS = 'rust_events'
+const STATS = 'rust_player_wipe_stats'
+const GATHER = 'rust_gather_totals'
+const PLAYERS = 'rust_players'
+const WIPES = 'rust_wipes'
+const PRESENCE = 'rust_presence'
+const CURSOR = 'rust_ingest_cursor'
+
+// ── The cursor ────────────────────────────────────────────────────────────
+
+async function getCursor(serverId) {
+  const rows = await core.query(
+    `SELECT server_id AS serverId, last_event_id AS lastEventId, events_seen AS eventsSeen
+       FROM ${CURSOR} WHERE server_id = ?`,
+    [serverId],
+  )
+  return rows[0] || null
+}
+
+/**
+ * Moves a server's cursor forward, counting what it passed.
+ *
+ * **Called only after the batch it describes has been written.** The whole
+ * correctness of the ingest is in that ordering: if this ran first, a crash
+ * between the two would skip events for ever, silently, with no way to notice.
+ * Running it last means a crash re-reads events it has already counted at worst
+ * — see `ingest.js` for what makes that survivable.
+ */
+async function setCursor(serverId, lastEventId, seen = 0) {
+  await core.query(
+    `INSERT INTO ${CURSOR} (server_id, last_event_id, events_seen, updated_at)
+     VALUES (?, ?, ?, CURRENT_TIMESTAMP)
+     ON DUPLICATE KEY UPDATE
+       last_event_id = VALUES(last_event_id),
+       events_seen = events_seen + VALUES(events_seen),
+       updated_at = CURRENT_TIMESTAMP`,
+    [serverId, lastEventId, seen],
+  )
+}
+
+// ── Writes ────────────────────────────────────────────────────────────────
+
+async function insertEvent({ serverId, wipeId, kind, t, steamId, raw }) {
+  await core.query(
+    `INSERT INTO ${EVENTS} (server_id, wipe_id, kind, t, steam_id, raw)
+     VALUES (?, ?, ?, ?, ?, ?)`,
+    [serverId, wipeId || null, kind, t, steamId || null, JSON.stringify(raw)],
+  )
+}
+
+/**
+ * Notes that a wipe exists, from any frame that mentions it.
+ *
+ * There is no "a wipe started" call, because the website is not there when one
+ * does — a wipe happens to a game server that was restarted while nobody was
+ * watching. A wipe is therefore created by being mentioned, and `last_seen`
+ * moves every time it is mentioned again.
+ */
+async function touchWipe(serverId, wipeId, saveCreatedAt = null) {
+  if (!wipeId) return
+
+  await core.query(
+    `INSERT INTO ${WIPES} (server_id, wipe_id, save_created_at, first_seen, last_seen)
+     VALUES (?, ?, ?, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
+     ON DUPLICATE KEY UPDATE
+       last_seen = CURRENT_TIMESTAMP,
+       save_created_at = COALESCE(VALUES(save_created_at), save_created_at)`,
+    [serverId, wipeId, saveCreatedAt],
+  )
+}
+
+/**
+ * Notes that a player exists and what they were last called.
+ *
+ * `name` is COALESCEd rather than overwritten so that a frame which carries no
+ * name — a ban by id, a tally — cannot blank out the name every other frame
+ * supplied.
+ */
+async function touchPlayer(steamId, name = null) {
+  if (!steamId) return
+
+  await core.query(
+    `INSERT INTO ${PLAYERS} (steam_id, name, first_seen, last_seen)
+     VALUES (?, ?, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
+     ON DUPLICATE KEY UPDATE
+       name = COALESCE(VALUES(name), name),
+       last_seen = CURRENT_TIMESTAMP`,
+    [steamId, name],
+  )
+}
+
+/**
+ * Adds to one player's counters for one wipe.
+ *
+ * Every column is a running total that only rises within a wipe, so this is an
+ * upsert that ADDS rather than sets. `deltas` names only what moved; a `+ 0` on
+ * everything else is what keeps the caller from having to read the row first.
+ */
+async function addStats({ serverId, wipeId, steamId }, deltas = {}) {
+  if (!serverId || !steamId) return
+
+  const cols = ['kills', 'deaths', 'suicides', 'npc_kills', 'structures', 'sessions', 'playtime_sec']
+  const values = {
+    kills: deltas.kills || 0,
+    deaths: deltas.deaths || 0,
+    suicides: deltas.suicides || 0,
+    npc_kills: deltas.npcKills || 0,
+    structures: deltas.structures || 0,
+    sessions: deltas.sessions || 0,
+    playtime_sec: deltas.playtimeSec || 0,
+  }
+
+  await core.query(
+    `INSERT INTO ${STATS} (server_id, wipe_id, steam_id, ${cols.join(', ')}, last_seen)
+     VALUES (?, ?, ?, ${cols.map(() => '?').join(', ')}, CURRENT_TIMESTAMP)
+     ON DUPLICATE KEY UPDATE
+       ${cols.map((c) => `${c} = ${c} + VALUES(${c})`).join(',\n       ')},
+       last_seen = CURRENT_TIMESTAMP`,
+    [serverId, wipeId || '', steamId, ...cols.map((c) => values[c])],
+  )
+}
+
+async function addGathered({ serverId, wipeId, steamId }, resource, amount) {
+  if (!serverId || !steamId || !resource || !(amount > 0)) return
+
+  await core.query(
+    `INSERT INTO ${GATHER} (server_id, wipe_id, steam_id, resource, amount)
+     VALUES (?, ?, ?, ?, ?)
+     ON DUPLICATE KEY UPDATE amount = amount + VALUES(amount)`,
+    [serverId, wipeId || '', steamId, resource, amount],
+  )
+}
+
+/**
+ * Replaces a server's presence rows with exactly what the board said.
+ *
+ * Two statements, delete then insert, because a board is a REPLACEMENT: a player
+ * who left between two boards has to disappear, and an upsert alone would leave
+ * them online for ever. It is not wrapped in a transaction on purpose — the
+ * window between the two is a fraction of a second of a page possibly showing an
+ * empty player list, against holding a lock on a table two routes read.
+ */
+async function replacePresence(serverId, players = []) {
+  await core.query(`DELETE FROM ${PRESENCE} WHERE server_id = ?`, [serverId])
+
+  for (const p of players) {
+    if (!p || !p.steamId) continue
+
+    await core.query(
+      `INSERT INTO ${PRESENCE} (server_id, steam_id, name, sleeping, connected_at, updated_at)
+       VALUES (?, ?, ?, ?, ${p.connectedAt ? 'FROM_UNIXTIME(? / 1000)' : 'NULL'}, CURRENT_TIMESTAMP)
+       ON DUPLICATE KEY UPDATE
+         name = VALUES(name), sleeping = VALUES(sleeping), updated_at = CURRENT_TIMESTAMP`,
+      p.connectedAt
+        ? [serverId, p.steamId, p.name || null, p.sleeping ? 1 : 0, p.connectedAt]
+        : [serverId, p.steamId, p.name || null, p.sleeping ? 1 : 0],
+    )
+  }
+}
+
+/** Deletes raw events older than `days`. Totals are never touched — that is the point of them. */
+async function pruneEvents(days) {
+  if (!(days > 0)) return 0
+
+  const res = await core.query(
+    `DELETE FROM ${EVENTS} WHERE created_at < DATE_SUB(CURRENT_TIMESTAMP, INTERVAL ? DAY)`,
+    [days],
+  )
+  return (res && res.affectedRows) || 0
+}
+
+// ── Reads ─────────────────────────────────────────────────────────────────
+
+/**
+ * Recent events, newest first, restricted to `kinds`.
+ *
+ * **`kinds` is never optional.** A default of "all kinds" is one forgotten
+ * argument away from publishing an IP address, so the caller is made to say it
+ * every time; `events.model.js` builds the list from the catalogue's allowlist
+ * and an empty list answers with no rows rather than with everything.
+ */
+async function recentEvents({ serverId, kinds, wipeId = null, limit = 50 }) {
+  if (!Array.isArray(kinds) || kinds.length === 0) return []
+
+  const holes = kinds.map(() => '?').join(', ')
+  const params = [serverId, ...kinds]
+
+  let sql = `SELECT id, server_id AS serverId, wipe_id AS wipeId, kind, t, steam_id AS steamId, raw
+               FROM ${EVENTS}
+              WHERE server_id = ? AND kind IN (${holes})`
+
+  if (wipeId) {
+    sql += ' AND wipe_id = ?'
+    params.push(wipeId)
+  }
+
+  sql += ' ORDER BY id DESC LIMIT ?'
+  params.push(limit)
+
+  return core.query(sql, params)
+}
+
+/**
+ * The leaderboard for one wipe, or across every wipe when `wipeId` is null.
+ *
+ * All-time is a SUM over the per-wipe rows rather than a separate set of
+ * counters, which is what makes it impossible for the two to disagree — there
+ * is only ever one number, added up differently.
+ */
+async function leaderboard({ serverId, wipeId = null, sort = 'kills', limit = 25 }) {
+  const column = { kills: 'kills', deaths: 'deaths', npcKills: 'npc_kills', playtime: 'playtime_sec' }[sort] || 'kills'
+
+  const params = [serverId]
+  let where = 's.server_id = ?'
+
+  if (wipeId) {
+    where += ' AND s.wipe_id = ?'
+    params.push(wipeId)
+  }
+
+  params.push(limit)
+
+  return core.query(
+    `SELECT s.steam_id AS steamId,
+            p.name AS name,
+            SUM(s.kills) AS kills,
+            SUM(s.deaths) AS deaths,
+            SUM(s.npc_kills) AS npcKills,
+            SUM(s.structures) AS structures,
+            SUM(s.playtime_sec) AS playtimeSec,
+            MAX(s.last_seen) AS lastSeen
+       FROM ${STATS} s
+       LEFT JOIN ${PLAYERS} p ON p.steam_id = s.steam_id
+      WHERE ${where}
+      GROUP BY s.steam_id, p.name
+      ORDER BY SUM(s.${column}) DESC, MAX(s.last_seen) DESC
+      LIMIT ?`,
+    params,
+  )
+}
+
+async function listWipes(serverId) {
+  return core.query(
+    `SELECT wipe_id AS wipeId, save_created_at AS saveCreatedAt,
+            first_seen AS firstSeen, last_seen AS lastSeen
+       FROM ${WIPES}
+      WHERE server_id = ?
+      ORDER BY wipe_id DESC`,
+    [serverId],
+  )
+}
+
+async function presenceFor(serverId) {
+  return core.query(
+    `SELECT steam_id AS steamId, name, sleeping, connected_at AS connectedAt
+       FROM ${PRESENCE}
+      WHERE server_id = ?
+      ORDER BY name ASC`,
+    [serverId],
+  )
+}
+
+module.exports = {
+  getCursor,
+  setCursor,
+  insertEvent,
+  touchWipe,
+  touchPlayer,
+  addStats,
+  addGathered,
+  replacePresence,
+  pruneEvents,
+  recentEvents,
+  leaderboard,
+  listWipes,
+  presenceFor,
+}

server/model/events/events.model.js

@@ -0,0 +1,162 @@
+// ── The read path's logic ─────────────────────────────────────────────────
+//
+// Everything that decides WHAT a caller gets, separated from the SQL that
+// fetches it, so this file can be tested with no database and `events.db.js` has
+// no branching to test.
+//
+// The decision that matters here is not a business rule, it is a boundary: what
+// a signed-out visitor may see. Protocol 2 carries IP addresses and player
+// reports, and the only thing standing between them and a public page is
+// `catalogue.js`'s allowlist and the fact that **every read on this file takes an
+// explicit viewer**. There is no default, because a default is what a caller
+// gets when they forget — and the safe value is never the one that is easier to
+// type.
+
+const catalogue = require('../../catalogue')
+const db = require('./events.db')
+
+/** Hard ceiling on a page, whatever a caller asks for. */
+const MAX_LIMIT = 200
+
+function boundedLimit(requested, fallback = 50) {
+  const n = Number(requested)
+  if (!Number.isFinite(n) || n <= 0) return fallback
+  return Math.min(Math.trunc(n), MAX_LIMIT)
+}
+
+/**
+ * Parses a `kind` query parameter into a list.
+ *
+ * Accepts `?kind=player.death` and `?kind=player.death,player.chat`, and answers
+ * `null` for anything empty — which means "whatever this viewer may see" rather
+ * than "nothing", and is then narrowed by the catalogue.
+ */
+function parseKinds(raw) {
+  if (!raw) return null
+
+  const list = String(raw)
+    .split(',')
+    .map((k) => k.trim())
+    .filter(Boolean)
+
+  return list.length > 0 ? list : null
+}
+
+/**
+ * Recent events for one server, already narrowed to what this viewer may see.
+ *
+ * **`admin` is a parameter, not a default.** A route that forgets it gets the
+ * public list, which is the direction it is safe to be wrong in. And a kind the
+ * caller asked for that they may not see is dropped silently rather than
+ * refused: naming it in an error would confirm the kind exists, which is a small
+ * thing to leak and a free one to avoid.
+ */
+async function recent({ serverId, admin = false, kind = null, wipeId = null, limit }) {
+  const kinds = catalogue.kindsFor({ admin, requested: parseKinds(kind) })
+
+  // Every requested kind was refused. Answering with an empty list is right —
+  // the events they asked for are, as far as they are concerned, not there.
+  if (kinds.length === 0) return []
+
+  const rows = await db.recentEvents({
+    serverId,
+    kinds,
+    wipeId,
+    limit: boundedLimit(limit),
+  })
+
+  return rows.map(shape)
+}
+
+/**
+ * One stored row as an API object.
+ *
+ * `raw` comes back from the database as text and is parsed here rather than in
+ * the db layer, because a row whose JSON will not parse is a reporting problem
+ * and not a query problem: it answers with the envelope it does know and an
+ * empty body, instead of failing a whole page over one bad row.
+ */
+function shape(row) {
+  let frame = {}
+
+  try {
+    frame = typeof row.raw === 'string' ? JSON.parse(row.raw) : row.raw || {}
+  } catch {
+    frame = {}
+  }
+
+  return {
+    id: Number(row.id),
+    kind: row.kind,
+    t: Number(row.t),
+    wipeId: row.wipeId || null,
+    steamId: row.steamId || null,
+    frame,
+  }
+}
+
+/**
+ * The leaderboard for a server, per wipe or all-time.
+ *
+ * All-time is the same rows summed differently rather than a second set of
+ * counters, so the two can never disagree — which is the whole reason R12's
+ * "per-wipe detail plus all-time rollups" is one table and not two.
+ */
+async function leaderboard({ serverId, wipeId = null, sort = 'kills', limit }) {
+  const rows = await db.leaderboard({
+    serverId,
+    wipeId,
+    sort,
+    limit: boundedLimit(limit, 25),
+  })
+
+  return rows.map((r) => ({
+    steamId: r.steamId,
+    name: r.name || null,
+    kills: Number(r.kills) || 0,
+    deaths: Number(r.deaths) || 0,
+    npcKills: Number(r.npcKills) || 0,
+    structures: Number(r.structures) || 0,
+    playtimeSec: Number(r.playtimeSec) || 0,
+    lastSeen: r.lastSeen || null,
+  }))
+}
+
+/**
+ * Every wipe this server has had, newest first.
+ *
+ * The list is what makes the per-wipe view navigable, and it is also the proof
+ * R12 asks for: a wipe that ended is still here, with its stats still attached.
+ */
+async function wipes(serverId) {
+  const rows = await db.listWipes(serverId)
+
+  return rows.map((r) => ({
+    wipeId: r.wipeId,
+    saveCreatedAt: r.saveCreatedAt || null,
+    firstSeen: r.firstSeen,
+    lastSeen: r.lastSeen,
+  }))
+}
+
+/**
+ * Who is on the server right now.
+ *
+ * Read from the presence board rather than counted from connect and disconnect
+ * events: the board is re-sent on every bridge connect and every minute, so it
+ * is right even after this module has missed something. Counting transitions
+ * instead would drift, and drift in exactly the direction people notice —
+ * players who never left.
+ */
+async function online(serverId) {
+  const rows = await db.presenceFor(serverId)
+
+  return rows.map((r) => ({
+    steamId: r.steamId,
+    name: r.name || null,
+    sleeping: Boolean(r.sleeping),
+    connectedAt: r.connectedAt || null,
+  }))
+}
+
+module.exports = { recent, leaderboard, wipes, online, parseKinds, boundedLimit, MAX_LIMIT }

server/model/servers/servers.db.js

@@ -79,7 +79,8 @@ async function listState() {
   return core.query(
     `SELECT server_id AS serverId, reachable, online, players, max_players AS maxPlayers,
             hostname, level, seed, world_size AS worldSize, boot_id AS bootId,
-            save_created_at AS saveCreatedAt, protocol, updated_at AS updatedAt
+            save_created_at AS saveCreatedAt, wipe_id AS wipeId, protocol,
+            updated_at AS updatedAt
        FROM ${STATE}`,
   )
 }
@@ -99,13 +100,14 @@ async function putState(state) {
   await core.query(
     `INSERT INTO ${STATE}
        (server_id, reachable, online, players, max_players, hostname, level, seed,
-        world_size, boot_id, save_created_at, protocol, raw, updated_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
+        world_size, boot_id, save_created_at, wipe_id, protocol, raw, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
      ON DUPLICATE KEY UPDATE
        reachable = VALUES(reachable), online = VALUES(online), players = VALUES(players),
        max_players = VALUES(max_players), hostname = VALUES(hostname), level = VALUES(level),
        seed = VALUES(seed), world_size = VALUES(world_size), boot_id = VALUES(boot_id),
-       save_created_at = VALUES(save_created_at), protocol = VALUES(protocol),
+       save_created_at = VALUES(save_created_at), wipe_id = VALUES(wipe_id),
+       protocol = VALUES(protocol),
        raw = VALUES(raw), updated_at = CURRENT_TIMESTAMP`,
     [
       state.serverId,
@@ -119,6 +121,7 @@ async function putState(state) {
       state.worldSize === undefined ? null : state.worldSize,
       state.bootId || null,
       state.saveCreatedAt || null,
+      state.wipeId || null,
       state.protocol === undefined ? null : state.protocol,
       state.raw ? JSON.stringify(state.raw) : null,
     ],

server/router/public/rust.controller.js

@@ -11,6 +11,7 @@
 
 const core = require('../../core')
 
+const events = require('../../model/events/events.model')
 const servers = require('../../model/servers/servers.model')
 
 const log = core.logger('public')
@@ -24,4 +25,62 @@ async function listServers(req, res) {
   }
 }
 
-module.exports = { listServers }
+/**
+ * The killfeed, and everything else public that happened on one server.
+ *
+ * **`admin` is not passed, and that is the whole security posture of this
+ * handler.** `events.recent` takes the viewer explicitly and defaults to the
+ * public allowlist, so the way to leak an IP address from here is to add an
+ * argument rather than to forget one.
+ */
+async function listEvents(req, res) {
+  try {
+    res.json({
+      events: await events.recent({
+        serverId: req.params.id,
+        kind: req.query.kind,
+        wipeId: req.query.wipe || null,
+        limit: req.query.limit,
+      }),
+    })
+  } catch (err) {
+    log.error('failed to read events', { server: req.params.id, error: err.message })
+    res.status(500).json({ error: 'Failed to read events' })
+  }
+}
+
+async function listLeaderboard(req, res) {
+  try {
+    res.json({
+      leaderboard: await events.leaderboard({
+        serverId: req.params.id,
+        wipeId: req.query.wipe || null,
+        sort: req.query.sort,
+        limit: req.query.limit,
+      }),
+    })
+  } catch (err) {
+    log.error('failed to read the leaderboard', { server: req.params.id, error: err.message })
+    res.status(500).json({ error: 'Failed to read the leaderboard' })
+  }
+}
+
+async function listWipes(req, res) {
+  try {
+    res.json({ wipes: await events.wipes(req.params.id) })
+  } catch (err) {
+    log.error('failed to read wipes', { server: req.params.id, error: err.message })
+    res.status(500).json({ error: 'Failed to read wipes' })
+  }
+}
+
+async function listOnline(req, res) {
+  try {
+    res.json({ players: await events.online(req.params.id) })
+  } catch (err) {
+    log.error('failed to read presence', { server: req.params.id, error: err.message })
+    res.status(500).json({ error: 'Failed to read who is online' })
+  }
+}
+
+module.exports = { listServers, listEvents, listLeaderboard, listWipes, listOnline }

server/router/public/rust.router.js

@@ -41,4 +41,65 @@ rustRouter.get(
   servers.listServers,
 )
 
+// ── One server's read path ────────────────────────────────────────────────
+//
+// Every route below is public, and every one of them answers from this module's
+// own tables — never from a live call to a sidecar. That is what lets the
+// killfeed and the leaderboard render while every game server in the fleet is
+// off, which is the same promise the server list makes.
+//
+// **The events route serves an ALLOWLIST, default-deny** (`catalogue.js`).
+// Protocol 2 carries IP addresses and player reports; they are stored, and they
+// do not come out here.
+
+rustRouter.get(
+  '/servers/:id/events',
+  // #swagger.tags = ['Public · Rust']
+  // #swagger.summary = 'Recent events on one Rust server'
+  // #swagger.description = 'The killfeed and everything else public that happened on a server, newest first. Narrow with `kind` (comma-separated) and `wipe`. Only publicly classified kinds are ever returned — moderation events, login attempts and anything carrying an IP address are stored but never served here.'
+  // #swagger.parameters['id'] = { in: 'path', required: true, description: 'The server’s slug', schema: { type: 'string' } }
+  // #swagger.parameters['kind'] = { in: 'query', required: false, description: 'One kind, or several comma-separated', schema: { type: 'string' } }
+  // #swagger.parameters['wipe'] = { in: 'query', required: false, description: 'Restrict to one wipe id', schema: { type: 'string' } }
+  // #swagger.parameters['limit'] = { in: 'query', required: false, description: 'Rows to return, capped at 200', schema: { type: 'integer' } }
+  /* #swagger.responses[200] = { description: 'Recent events, newest first' } */
+  siteMode,
+  servers.listEvents,
+)
+
+rustRouter.get(
+  '/servers/:id/leaderboard',
+  // #swagger.tags = ['Public · Rust']
+  // #swagger.summary = 'The leaderboard for one Rust server'
+  // #swagger.description = 'Per-wipe when `wipe` is given, all-time otherwise. All-time is the per-wipe rows summed rather than a second set of counters, so a wipe splits a player’s history without ending it.'
+  // #swagger.parameters['id'] = { in: 'path', required: true, description: 'The server’s slug', schema: { type: 'string' } }
+  // #swagger.parameters['wipe'] = { in: 'query', required: false, description: 'Restrict to one wipe id', schema: { type: 'string' } }
+  // #swagger.parameters['sort'] = { in: 'query', required: false, description: 'kills, deaths, npcKills or playtime', schema: { type: 'string' } }
+  // #swagger.parameters['limit'] = { in: 'query', required: false, description: 'Rows to return, capped at 200', schema: { type: 'integer' } }
+  /* #swagger.responses[200] = { description: 'The leaderboard' } */
+  siteMode,
+  servers.listLeaderboard,
+)
+
+rustRouter.get(
+  '/servers/:id/wipes',
+  // #swagger.tags = ['Public · Rust']
+  // #swagger.summary = 'Every wipe this server has had'
+  // #swagger.description = 'Newest first. A wipe id is derived by the bridge plugin from the save’s creation time and stamped on every frame, so it is the same id the events and the leaderboard are filtered by.'
+  // #swagger.parameters['id'] = { in: 'path', required: true, description: 'The server’s slug', schema: { type: 'string' } }
+  /* #swagger.responses[200] = { description: 'The wipes' } */
+  siteMode,
+  servers.listWipes,
+)
+
+rustRouter.get(
+  '/servers/:id/online',
+  // #swagger.tags = ['Public · Rust']
+  // #swagger.summary = 'Who is on one Rust server right now'
+  // #swagger.description = 'Read from the presence board the bridge re-sends on every connect and every minute, rather than counted from connect and disconnect events — so it is correct even after the website has missed one.'
+  // #swagger.parameters['id'] = { in: 'path', required: true, description: 'The server’s slug', schema: { type: 'string' } }
+  /* #swagger.responses[200] = { description: 'Who is online' } */
+  siteMode,
+  servers.listOnline,
+)
+
 module.exports = rustRouter

server/sidecarClient.js

@@ -48,14 +48,22 @@ const log = core.logger('sidecar')
 const TIMEOUT_MS = 12000
 
 /**
- * The wire version this module speaks. Declared in three places that must agree:
- * here, `PROTOCOL_VERSION` in the sidecar, and `overlay.toml` in Rust-Plugins.
+ * The wire version this module speaks. Declared in FOUR places that must agree:
+ * here, `PROTOCOL_VERSION` in the sidecar, `ProtocolVersion` in the bridge
+ * plugin, and `protocol` in its `overlay.toml`.
+ *
+ * **2 — the read path.** The bump lands here in the same change as the emitters,
+ * even though this module does not yet consume any of the new frames: the
+ * sidecar refuses a client declaring a different version with a `409`, so a
+ * module left on 1 would stop being able to read the server board it has been
+ * reading all along. A constant that lags the deployment is not a safe default;
+ * it is an outage with a version number on it.
  *
  * It is sent on every request as `X-RustLink-Version`, which turns a mismatched
  * deployment into a `409` naming both numbers instead of a parse failure three
  * layers further in.
  */
-const PROTOCOL_VERSION = 1
+const PROTOCOL_VERSION = 2
 
 /** What a caller gets back. Shaped once so every call site reads the same. */
 function reply(ok, status, data = null) {
@@ -163,6 +171,24 @@ const serverBoard = (server) => request(server, '/server')
 /** A live round trip through the sidecar to the game. Fails when the game is down, by design. */
 const liveStatus = (server) => request(server, '/status')
 
+/** Every board at once: what is true now, before following what happens next. */
+const boards = (server) => request(server, '/boards')
+
+/**
+ * The ingest cursor: events after `since`, oldest first.
+ *
+ * **`since` is required here, unlike on the wire.** The sidecar treats an omitted
+ * cursor as "tell me where the end is", which is a genuinely useful question and
+ * a catastrophic default for an ingest loop that would silently store nothing
+ * and advance past everything. So the question is asked explicitly, by name, and
+ * a caller cannot get it by forgetting an argument.
+ */
+const feed = (server, since, limit = 200) =>
+  request(server, `/feed?since=${encodeURIComponent(since)}&limit=${encodeURIComponent(limit)}`)
+
+/** Where the sidecar's history currently ends. What a new server's cursor starts at. */
+const feedTail = (server) => request(server, '/feed')
+
 module.exports = {
   TIMEOUT_MS,
   PROTOCOL_VERSION,
@@ -170,5 +196,8 @@ module.exports = {
   health,
   serverBoard,
   liveStatus,
+  boards,
+  feed,
+  feedTail,
   joinUrl,
 }

server/test/catalogue.test.js

@@ -0,0 +1,110 @@
+// ── The boundary, asserted ────────────────────────────────────────────────
+//
+// `catalogue.js` is the only thing standing between a frame carrying an IP
+// address and a public page, so it gets a suite of its own rather than being
+// covered incidentally by a route test.
+//
+// The most valuable test here is the last one: it holds the classification
+// against the specification in `docs/rust-link/PROTOCOL.md` §8.4. Without it the
+// two drift the first time somebody adds a kind to the protocol, and the drift
+// is silent in the direction that matters — a new kind is simply never served,
+// until the day somebody "fixes" that by adding it to the wrong list.
+
+const test = require('node:test')
+const assert = require('node:assert')
+
+const catalogue = require('../catalogue')
+
+test('an unknown kind is not public — the default is deny', () => {
+  assert.equal(catalogue.isPublic('player.death'), true)
+  assert.equal(catalogue.isPublic('something.new'), false)
+  assert.equal(catalogue.isPublic(''), false)
+  assert.equal(catalogue.isPublic(undefined), false)
+
+  // The shape of the mistake this prevents: a kind a LATER protocol adds, which
+  // this build ingests happily and would publish on the day it first arrived if
+  // the filter were a deny list.
+  assert.equal(catalogue.isKnown('player.location'), false)
+  assert.equal(catalogue.isPublic('player.location'), false)
+})
+
+test('nothing carrying an IP address or a report is public', () => {
+  for (const kind of [
+    'player.login.attempt',
+    'player.approved',
+    'player.banned',
+    'player.unbanned',
+    'player.reported',
+    'entity.destroyed',
+  ]) {
+    assert.equal(catalogue.isPublic(kind), false, `${kind} must not be public`)
+    assert.ok(catalogue.STAFF_KINDS.includes(kind), `${kind} must be classified, not merely absent`)
+  }
+})
+
+test('a viewer with no kinds asked for gets the allowlist, never everything', () => {
+  const asPublic = catalogue.kindsFor({})
+  const asAdmin = catalogue.kindsFor({ admin: true })
+
+  assert.deepEqual(asPublic, [...catalogue.PUBLIC_KINDS])
+  assert.equal(asAdmin.length, catalogue.ALL_KINDS.length)
+
+  // The property that makes the route safe by construction: there is no argument
+  // a caller can omit that turns the filter off.
+  assert.ok(asPublic.length > 0)
+  assert.ok(!asPublic.includes('player.banned'))
+})
+
+test('a kind a viewer may not see is dropped, not refused', () => {
+  const asked = catalogue.kindsFor({ requested: ['player.death', 'player.banned'] })
+
+  assert.deepEqual(asked, ['player.death'])
+
+  // Asking for only forbidden kinds answers with nothing to select, which the
+  // model turns into an empty list — the events are, as far as this viewer is
+  // concerned, not there.
+  assert.deepEqual(catalogue.kindsFor({ requested: ['player.banned'] }), [])
+
+  // And an admin gets what they asked for.
+  assert.deepEqual(catalogue.kindsFor({ admin: true, requested: ['player.banned'] }), [
+    'player.banned',
+  ])
+})
+
+test('every kind is classified exactly once', () => {
+  const seen = new Set()
+
+  for (const kind of catalogue.ALL_KINDS) {
+    assert.ok(!seen.has(kind), `${kind} appears in both lists`)
+    seen.add(kind)
+  }
+
+  assert.equal(seen.size, catalogue.PUBLIC_KINDS.length + catalogue.STAFF_KINDS.length)
+})
+
+test('the classification covers exactly the kinds protocol 2 defines', () => {
+  // The spec lives in another repository, so the list is restated here rather
+  // than parsed — and restating it is the point: adding a kind to the protocol
+  // without deciding who may see it has to fail somewhere, and this is where.
+  //
+  // Sourced from docs/rust-link/PROTOCOL.md §8.4.
+  const PROTOCOL_2 = [
+    'player.connected',
+    'player.disconnected',
+    'player.respawned',
+    'player.death',
+    'player.chat',
+    'player.tally',
+    'entity.destroyed',
+    'player.reported',
+    'player.banned',
+    'player.unbanned',
+    'player.login.attempt',
+    'player.approved',
+    'server.wipe',
+    'server.initialized',
+    'server.shutdown',
+  ]
+
+  assert.deepEqual([...catalogue.ALL_KINDS].sort(), [...PROTOCOL_2].sort())
+})

server/test/events.test.js

@@ -0,0 +1,144 @@
+// ── The read path's logic ─────────────────────────────────────────────────
+//
+// The model decides what a caller gets. Two properties are worth more than the
+// rest, and both are about a caller who did something slightly wrong:
+//
+//   • a route that forgets to say who is asking gets the PUBLIC view;
+//   • a caller asking for a million rows gets two hundred.
+
+const test = require('node:test')
+const assert = require('node:assert')
+
+const { fakeCtx } = require('./_fakes')
+
+function withCore() {
+  require('../core')._reset()
+  require('../core').init(fakeCtx())
+}
+
+test('the limit is bounded, whatever was asked for', () => {
+  withCore()
+  const model = require('../model/events/events.model')
+
+  assert.equal(model.boundedLimit(10), 10)
+  assert.equal(model.boundedLimit(undefined), 50)
+  assert.equal(model.boundedLimit('nonsense'), 50)
+  assert.equal(model.boundedLimit(-5), 50)
+  assert.equal(model.boundedLimit(0), 50)
+  assert.equal(model.boundedLimit(1e9), model.MAX_LIMIT)
+  assert.equal(model.boundedLimit(12.9), 12)
+})
+
+test('kinds parse from one name or a list, and nothing means "not specified"', () => {
+  withCore()
+  const model = require('../model/events/events.model')
+
+  assert.deepEqual(model.parseKinds('player.death'), ['player.death'])
+  assert.deepEqual(model.parseKinds('player.death, player.chat'), ['player.death', 'player.chat'])
+
+  // Null rather than an empty list: "I did not ask" and "I asked for nothing"
+  // are different, and only the first means "whatever I am allowed".
+  assert.equal(model.parseKinds(''), null)
+  assert.equal(model.parseKinds(undefined), null)
+  assert.equal(model.parseKinds(' , , '), null)
+})
+
+test('a reader who does not say who they are gets the public view', async () => {
+  withCore()
+
+  const db = require('../model/events/events.db')
+  const model = require('../model/events/events.model')
+  const original = db.recentEvents
+  let asked = null
+
+  db.recentEvents = async (args) => {
+    asked = args
+    return []
+  }
+
+  try {
+    await model.recent({ serverId: 'main' })
+
+    assert.ok(!asked.kinds.includes('player.banned'), 'no IP-carrying kind by default')
+    assert.ok(asked.kinds.includes('player.death'))
+
+    await model.recent({ serverId: 'main', admin: true })
+    assert.ok(asked.kinds.includes('player.banned'), 'an admin who says so gets them')
+  } finally {
+    db.recentEvents = original
+  }
+})
+
+test('asking only for kinds you may not see answers with nothing, and queries nothing', async () => {
+  withCore()
+
+  const db = require('../model/events/events.db')
+  const model = require('../model/events/events.model')
+  const original = db.recentEvents
+  let called = false
+
+  db.recentEvents = async () => {
+    called = true
+    return []
+  }
+
+  try {
+    const rows = await model.recent({ serverId: 'main', kind: 'player.banned,player.approved' })
+
+    assert.deepEqual(rows, [])
+    assert.equal(called, false, 'a query with no permitted kinds must not reach the database')
+  } finally {
+    db.recentEvents = original
+  }
+})
+
+test('a row whose stored frame will not parse still answers with its envelope', async () => {
+  withCore()
+
+  const db = require('../model/events/events.db')
+  const model = require('../model/events/events.model')
+  const original = db.recentEvents
+
+  db.recentEvents = async () => [
+    { id: 7, kind: 'player.death', t: 12, wipeId: 'w-1', steamId: 'p1', raw: '{not json' },
+  ]
+
+  try {
+    const [row] = await model.recent({ serverId: 'main' })
+
+    // One unreadable row must not fail a whole page. What is known is still
+    // reported; the body is empty rather than absent.
+    assert.equal(row.id, 7)
+    assert.equal(row.kind, 'player.death')
+    assert.deepEqual(row.frame, {})
+  } finally {
+    db.recentEvents = original
+  }
+})
+
+test('the leaderboard answers numbers, never nulls', async () => {
+  withCore()
+
+  const db = require('../model/events/events.db')
+  const model = require('../model/events/events.model')
+  const original = db.leaderboard
+
+  // SUM() over no rows is NULL in SQL, and a JOIN with no player row gives a
+  // null name. A page that has to defend against both is a page with the
+  // defence in three places.
+  db.leaderboard = async () => [
+    { steamId: 'p1', name: null, kills: null, deaths: '3', npcKills: null, playtimeSec: null },
+  ]
+
+  try {
+    const [row] = await model.leaderboard({ serverId: 'main' })
+
+    assert.equal(row.kills, 0)
+    assert.equal(row.deaths, 3)
+    assert.equal(row.npcKills, 0)
+    assert.equal(row.playtimeSec, 0)
+    assert.equal(row.name, null)
+  } finally {
+    db.leaderboard = original
+  }
+})

server/test/ingest.test.js

@@ -0,0 +1,329 @@
+// ── The ingest ────────────────────────────────────────────────────────────
+//
+// Every test here is about one of three things, and all three are mistakes that
+// look correct in review:
+//
+//   • **who gets credited.** A suicide must not credit the victim with a kill.
+//     That single line would produce a leaderboard topped by whoever died most,
+//     and it would look plausible for a whole wipe.
+//   • **the cursor's ordering.** It advances AFTER the batch, never before, so a
+//     crash re-reads rather than skips. Skipping is silent and permanent.
+//   • **absent is not zero.** A session whose start was never seen contributes
+//     no playtime rather than zero playtime.
+//
+// The database is a recorder. Asserting the SQL exactly would be a test of the
+// SQL's punctuation, so each case asserts the *statement shape* and the values —
+// which table was written, and with what.
+
+const test = require('node:test')
+const assert = require('node:assert')
+
+const { fakeCtx } = require('./_fakes')
+
+/** Installs a core whose `db.query` records every statement. */
+function withRecorder() {
+  const statements = []
+
+  const ctx = fakeCtx({
+    db: {
+      query: (sql, params = []) => {
+        statements.push({ sql, params })
+        return Promise.resolve([])
+      },
+      pool: {},
+    },
+  })
+
+  require('../core')._reset()
+  require('../core').init(ctx)
+
+  return {
+    statements,
+    /** Every statement that touched a table, with its parameters. */
+    touching(table) {
+      return statements.filter((s) => s.sql.includes(table))
+    },
+  }
+}
+
+const frame = (over = {}) => ({
+  type: 'event',
+  t: 1789560564452,
+  serverId: 'main',
+  wipeId: 'w-20260915T195817Z',
+  ...over,
+})
+
+const item = (kind, over = {}) => ({ id: 1, t: 1, kind, frame: frame({ kind, ...over }) })
+
+test('every frame is stored, whether or not this build understands it', async () => {
+  const rec = withRecorder()
+  const { apply } = require('../ingest')
+
+  await apply('main', item('player.death', { steamId: '76561198000000001' }))
+  await apply('main', item('something.from.protocol.9'))
+
+  const stored = rec.touching('rust_events')
+  assert.equal(stored.length, 2, 'an unrecognised kind must still be stored')
+
+  // The one copy of an event a later version will know how to read is the one
+  // this version chose not to throw away.
+  assert.ok(stored[1].params.includes('something.from.protocol.9'))
+})
+
+test('a wipe exists because a frame mentioned it', async () => {
+  const rec = withRecorder()
+  const { apply } = require('../ingest')
+
+  await apply('main', item('player.chat', { steamId: '1', message: 'hello' }))
+
+  const wipes = rec.touching('rust_wipes')
+  assert.equal(wipes.length, 1)
+  assert.deepEqual(wipes[0].params.slice(0, 2), ['main', 'w-20260915T195817Z'])
+})
+
+test('a kill credits the attacker and a death the victim', async () => {
+  const rec = withRecorder()
+  const { apply } = require('../ingest')
+
+  await apply(
+    'main',
+    item('player.death', {
+      steamId: 'victim',
+      attackerType: 'player',
+      attackerId: 'killer',
+      attackerName: 'Killer',
+    }),
+  )
+
+  const stats = rec.touching('rust_player_wipe_stats')
+  assert.equal(stats.length, 2, 'one row for the victim, one for the attacker')
+
+  // The parameter order is (server, wipe, steam, kills, deaths, suicides, ...).
+  const victim = stats.find((s) => s.params[2] === 'victim')
+  const killer = stats.find((s) => s.params[2] === 'killer')
+
+  assert.ok(victim && killer)
+  assert.equal(victim.params[3], 0, 'the victim scored no kill')
+  assert.equal(victim.params[4], 1, 'the victim died once')
+  assert.equal(killer.params[3], 1, 'the attacker scored one kill')
+  assert.equal(killer.params[4], 0, 'the attacker did not die')
+})
+
+test('a suicide is a death and a suicide, and credits nobody with a kill', async () => {
+  const rec = withRecorder()
+  const { apply } = require('../ingest')
+
+  await apply('main', item('player.death', { steamId: 'victim', attackerType: 'self' }))
+
+  const stats = rec.touching('rust_player_wipe_stats')
+  assert.equal(stats.length, 1, 'nobody is credited with the kill')
+  assert.equal(stats[0].params[4], 1, 'it is still a death')
+  assert.equal(stats[0].params[5], 1, 'and a suicide')
+  assert.equal(stats[0].params[3], 0)
+})
+
+test('an environment or NPC death credits no attacker', async () => {
+  for (const attackerType of ['environment', 'npc']) {
+    const rec = withRecorder()
+    const { apply } = require('../ingest')
+
+    await apply('main', item('player.death', { steamId: 'victim', attackerType }))
+
+    const stats = rec.touching('rust_player_wipe_stats')
+    assert.equal(stats.length, 1, `${attackerType} must credit nobody`)
+    assert.equal(stats[0].params[4], 1)
+  }
+})
+
+test('an absent session length adds no playtime and no session', async () => {
+  const rec = withRecorder()
+  const { apply } = require('../ingest')
+
+  // A player who was already on the server when the plugin loaded: the plugin
+  // omits `sessionSec` rather than sending 0, and the difference has to survive
+  // all the way to the column. Adding a zero would record a session of no
+  // length, which is a different claim from recording no session.
+  await apply('main', item('player.disconnected', { steamId: 'p1', reason: 'quit' }))
+
+  const stats = rec.touching('rust_player_wipe_stats')
+  assert.equal(stats[0].params[8], 0, 'no session counted')
+  assert.equal(stats[0].params[9], 0, 'no playtime added')
+
+  const rec2 = withRecorder()
+  await require('../ingest').apply(
+    'main',
+    item('player.disconnected', { steamId: 'p1', sessionSec: 600 }),
+  )
+
+  const counted = rec2.touching('rust_player_wipe_stats')
+  assert.equal(counted[0].params[8], 1)
+  assert.equal(counted[0].params[9], 600)
+})
+
+test('a tally is added per resource, as a delta', async () => {
+  const rec = withRecorder()
+  const { apply } = require('../ingest')
+
+  await apply(
+    'main',
+    item('player.tally', {
+      steamId: 'p1',
+      gathered: { wood: 1200, stones: 300 },
+      npcKills: 3,
+      structures: 2,
+    }),
+  )
+
+  const gathered = rec.touching('rust_gather_totals')
+  assert.equal(gathered.length, 2)
+  assert.deepEqual(
+    gathered.map((g) => [g.params[3], g.params[4]]),
+    [
+      ['wood', 1200],
+      ['stones', 300],
+    ],
+  )
+
+  const stats = rec.touching('rust_player_wipe_stats')
+  assert.equal(stats[0].params[6], 3, 'npc kills')
+  assert.equal(stats[0].params[7], 2, 'structures')
+
+  // `amount = amount + VALUES(amount)` is what makes a delta correct. A running
+  // total on the wire would double every number here, slowly, looking right.
+  assert.match(gathered[0].sql, /amount = amount \+ VALUES\(amount\)/)
+})
+
+test('a new server starts at the feed tail, not at the beginning of history', async () => {
+  withRecorder()
+
+  const sidecar = require('../sidecarClient')
+  const db = require('../model/events/events.db')
+  const ingest = require('../ingest')
+
+  const originalTail = sidecar.feedTail
+  const originalCursor = db.getCursor
+  const originalSet = db.setCursor
+  const written = []
+
+  db.getCursor = async () => null
+  db.setCursor = async (...args) => written.push(args)
+  sidecar.feedTail = async () => ({ ok: true, status: 'ok', data: { lastId: 4021, items: [] } })
+
+  try {
+    const applied = await ingest.ingestServer({ id: 'main' })
+
+    assert.equal(applied, 0, 'nothing is replayed')
+    assert.deepEqual(written, [['main', 4021, 0]], 'the cursor starts at the end')
+  } finally {
+    sidecar.feedTail = originalTail
+    db.getCursor = originalCursor
+    db.setCursor = originalSet
+  }
+})
+
+test('an unreachable sidecar writes no cursor at all', async () => {
+  withRecorder()
+
+  const sidecar = require('../sidecarClient')
+  const db = require('../model/events/events.db')
+  const ingest = require('../ingest')
+
+  const originalTail = sidecar.feedTail
+  const originalCursor = db.getCursor
+  const originalSet = db.setCursor
+  const written = []
+
+  db.getCursor = async () => null
+  db.setCursor = async (...args) => written.push(args)
+  sidecar.feedTail = async () => ({ ok: false, status: 'transport-error', data: null })
+
+  try {
+    await ingest.ingestServer({ id: 'main' })
+
+    // A cursor of 0 written here would replay the sidecar's whole retained
+    // history the moment it came back — which is the failure that looks like a
+    // working catch-up until somebody reads the leaderboard.
+    assert.deepEqual(written, [])
+  } finally {
+    sidecar.feedTail = originalTail
+    db.getCursor = originalCursor
+    db.setCursor = originalSet
+  }
+})
+
+test('the cursor advances after the batch, and one bad event does not wedge it', async () => {
+  withRecorder()
+
+  const sidecar = require('../sidecarClient')
+  const db = require('../model/events/events.db')
+  const ingest = require('../ingest')
+
+  const originals = {
+    feed: sidecar.feed,
+    getCursor: db.getCursor,
+    setCursor: db.setCursor,
+    insertEvent: db.insertEvent,
+  }
+
+  const order = []
+
+  db.getCursor = async () => ({ lastEventId: 10 })
+  db.setCursor = async (_id, last) => order.push(`cursor:${last}`)
+  db.insertEvent = async (row) => {
+    order.push(`event:${row.kind}`)
+    if (row.kind === 'player.chat') throw new Error('malformed')
+  }
+
+  sidecar.feed = async (_server, since) =>
+    since === 10
+      ? {
+          ok: true,
+          status: 'ok',
+          data: {
+            items: [item('player.chat'), item('player.connected', { steamId: 'p1' })],
+            lastId: 12,
+            more: false,
+          },
+        }
+      : { ok: true, status: 'ok', data: { items: [], lastId: since, more: false } }
+
+  try {
+    const applied = await ingest.ingestServer({ id: 'main' })
+
+    // The bad row is logged and skipped; the good one still counts.
+    assert.equal(applied, 1)
+
+    // And the ordering the whole design rests on: every event is written before
+    // the cursor moves past it.
+    assert.deepEqual(order, ['event:player.chat', 'event:player.connected', 'cursor:12'])
+  } finally {
+    Object.assign(db, {
+      getCursor: originals.getCursor,
+      setCursor: originals.setCursor,
+      insertEvent: originals.insertEvent,
+    })
+    sidecar.feed = originals.feed
+  }
+})
+
+test('a board replaces presence rather than appending to it', async () => {
+  const rec = withRecorder()
+  const ingest = require('../ingest')
+
+  await ingest.applyBoards('main', {
+    'players.online': {
+      kind: 'players.online',
+      type: 'snapshot',
+      count: 1,
+      players: [{ steamId: 'p1', name: 'One', sleeping: false }],
+    },
+  })
+
+  const presence = rec.touching('rust_presence')
+
+  // The DELETE is what makes it a board. Without it a player who left stays
+  // online for ever, which is the exact drift the board exists to correct.
+  assert.match(presence[0].sql, /^DELETE FROM rust_presence/)
+  assert.match(presence[1].sql, /INSERT INTO rust_presence/)
+})

swagger-fragment.json

@@ -195,6 +195,172 @@
           }
         }
       }
+    },
+    "/api/v1/public/rust/servers/{id}/events": {
+      "get": {
+        "tags": [
+          "Public · Rust"
+        ],
+        "summary": "Recent events on one Rust server",
+        "description": "The killfeed and everything else public that happened on a server, newest first. Narrow with `kind` (comma-separated) and `wipe`. Only publicly classified kinds are ever returned — moderation events, login attempts and anything carrying an IP address are stored but never served here.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "The server’s slug"
+          },
+          {
+            "name": "kind",
+            "in": "query",
+            "required": false,
+            "description": "One kind, or several comma-separated",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "wipe",
+            "in": "query",
+            "required": false,
+            "description": "Restrict to one wipe id",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "description": "Rows to return, capped at 200",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Recent events, newest first"
+          },
+          "500": {
+            "description": "Internal Server Error"
+          }
+        }
+      }
+    },
+    "/api/v1/public/rust/servers/{id}/leaderboard": {
+      "get": {
+        "tags": [
+          "Public · Rust"
+        ],
+        "summary": "The leaderboard for one Rust server",
+        "description": "Per-wipe when `wipe` is given, all-time otherwise. All-time is the per-wipe rows summed rather than a second set of counters, so a wipe splits a player’s history without ending it.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "The server’s slug"
+          },
+          {
+            "name": "wipe",
+            "in": "query",
+            "required": false,
+            "description": "Restrict to one wipe id",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "sort",
+            "in": "query",
+            "required": false,
+            "description": "kills, deaths, npcKills or playtime",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "description": "Rows to return, capped at 200",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The leaderboard"
+          },
+          "500": {
+            "description": "Internal Server Error"
+          }
+        }
+      }
+    },
+    "/api/v1/public/rust/servers/{id}/online": {
+      "get": {
+        "tags": [
+          "Public · Rust"
+        ],
+        "summary": "Who is on one Rust server right now",
+        "description": "Read from the presence board the bridge re-sends on every connect and every minute, rather than counted from connect and disconnect events — so it is correct even after the website has missed one.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "The server’s slug"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Who is online"
+          },
+          "500": {
+            "description": "Internal Server Error"
+          }
+        }
+      }
+    },
+    "/api/v1/public/rust/servers/{id}/wipes": {
+      "get": {
+        "tags": [
+          "Public · Rust"
+        ],
+        "summary": "Every wipe this server has had",
+        "description": "Newest first. A wipe id is derived by the bridge plugin from the save’s creation time and stamped on every frame, so it is the same id the events and the leaderboard are filtered by.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "The server’s slug"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The wipes"
+          },
+          "500": {
+            "description": "Internal Server Error"
+          }
+        }
+      }
     }
   },
   "tags": [