wtclaude
f211969ee1
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
111 lines
4.1 KiB
JavaScript
111 lines
4.1 KiB
JavaScript
// ── 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())
|
|
})
|