RunicGateway/Module-Rust
3
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases 4 Wiki Activity

feat: the first pages, and what a browser walk found behind them
All checks were successful
PR Checks / client-build (pull_request) Successful in 15s
Details
PR Checks / frozen-manifest (pull_request) Successful in 36s
Details
PR Checks / server-tests (pull_request) Successful in 7m58s
Details

Browse Source 
Phase 4. `/rust` is the server list and the module's landing page (D12);
`/rust/servers/:id` is one server with four tabs — feed, leaderboard, who is
on, wipes (D13). Everything selectable lives in the URL, so any view of the
page is a link. The feed and the presence list poll every twenty seconds while
the tab is visible and not at all when it is not (D14); the leaderboard and the
wipe list load once. `site.footer.status` is filled with a live server and
player count (D15).

Nothing on these pages calls a game server. Every field comes from this
module's own tables, which is what the phase criterion is about: the site
renders the last thing each server said while every server is off.

Walking that criterion in a browser against a live rig found four defects, two
of them already shipped in phase 3:

  * An unreachable refresh called `putState` — the whole-row write — with two
    fields, so a host that rebooted lost its hostname, map, size, seed and wipe
    id. The list then read "Offline" with nothing beside it, which is not "here
    is what we know" but "we have never heard of it". `markUnreachable` now
    moves three columns and mentions no others.
  * "Last reported" read `updated_at`, which a FAILED poll writes too — so an
    offline server claimed it had reported just now, every thirty seconds, for
    as long as it stayed down. `last_seen_at` is the new column, moved only by a
    frame that arrived.
  * Feed rows showed a bare time of day, so three events from six weeks ago all
    read as this afternoon once the feed was filtered to a past wipe.
  * `/rust/servers/typo` rendered core's ErrorState under its own heading and
    read "No such server / Something went wrong", sending a reader who mistyped
    a URL looking for an outage.

Also: a detail route (`GET …/servers/:id`), because it is the only route under
that path that can say a server does not exist — the other four answer an empty
list for an id nobody configured, and each of those is a good answer to its own
question.

`useAsync` cannot poll: it blanks its data on every dependency change, so a
twenty-second refresh built on it would clear the killfeed and re-fill it four
times a minute. `hooks/usePolled.js` is the module's own, invisible when it
succeeds and keeping the rows when it fails.

The client test fake was *nearly* core — it prefixed routes without stripping
the trailing separator, so the first module to register an index route failed
the nav check for a link that works in a browser. It now copies core's line
character for character.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4
This commit is contained in:
claude
2026-09-16 21:40:28 -05:00
parent 5ce711048c
commit 22fd8c5da7
29 changed files with 2040 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

141
client/src/components/Feed.jsx Normal file
View File

@@ -0,0 +1,141 @@
// ── The feed: what happened on one server ─────────────────────────────────
//
// Rows come from `/public/rust/servers/:id/events`, which serves a default-deny
// ALLOWLIST (`server/catalogue.js`). Everything carrying an IP address, a
// player's report about another player, or the grid square somebody's base is in
// is stored and never answered here — so this component cannot leak one by
// forgetting to filter, which is the point of the boundary living on the server.
//
// It polls (org lead, phase 4): every twenty seconds while the tab is visible,
// paused when it is not. `usePolled` keeps the rows on screen across a refresh —
// see the comment at the top of that file for why core's `useAsync` cannot do
// this job.
import { EmptyState, ErrorState, Loading } from '../core.js'
import { describe, FILTERS, kindsFor } from '../lib/feed.js'
import { ago, clock } from '../lib/format.js'
import usePolled from '../hooks/usePolled.js'
import api from '../api.js'
const TONE = {
kill: 'var(--accent-bright)',
death: 'var(--muted)',
join: 'var(--mode-live, #5fb98a)',
leave: 'var(--dim)',
chat: 'var(--text)',
server: 'var(--mode-maint, #e6c26a)',
other: 'var(--muted)',
}
export default function Feed({ serverId, wipeId, filter, onFilter }) {
const kinds = kindsFor(filter)
const { data, error, loading, at } = usePolled(
() => api.servers.events(serverId, { kinds, wipe: wipeId, limit: 100 }),
// The key is the QUESTION. Changing server, wipe or filter blanks the rows,
// because what is on screen is an answer to a different one; a poll tick
// does not, because it is the same question asked again.
{ key: `${serverId}|${wipeId || ''}|${filter}`, intervalMs: 20_000 },
)
const events = data ? data.events : []
return (
<div>
<div
className="sans"
style={{ display: 'flex', flexWrap: 'wrap', gap: 10, alignItems: 'center', marginBottom: 16 }}
>
<label style={{ color: 'var(--dim)', fontSize: '0.78rem' }}>
Showing{' '}
<select
value={filter}
onChange={(e) => onFilter(e.target.value)}
style={selectStyle}
>
{FILTERS.map((f) => (
<option key={f.id} value={f.id}>{f.label}</option>
))}
</select>
</label>
{/* What a refresh is FOR: saying when the page last managed one. Without
it a feed that stopped updating looks exactly like a quiet server. */}
{at && (
<span style={{ color: 'var(--dim)', fontSize: '0.74rem' }}>updated {ago(at)}</span>
)}
{error && (
<span style={{ color: 'var(--mode-maint, #e6c26a)', fontSize: '0.74rem' }}>
the last refresh failed — showing what we had
</span>
)}
</div>
{loading && <Loading />}
{/* An error with nothing to fall back on is the only case that takes over
the panel. A failed REFRESH keeps the rows and says so in the line
above, because a site whose premise is "it renders while the game is
off" must not blank itself the first time a request does. */}
{error && !data && <ErrorState error={error} />}
{data && events.length === 0 && (
<EmptyState
title="Nothing here yet"
message="Nothing this server has reported matches. A server that has just been added has no history until it says something."
/>
)}
{events.length > 0 && (
<ol style={{ listStyle: 'none', margin: 0, padding: 0 }}>
{events.map((event) => {
const line = describe(event)
return (
<li
key={event.id}
style={{
display: 'flex',
gap: 12,
alignItems: 'baseline',
padding: '7px 0',
borderBottom: '1px solid var(--line-soft, var(--line))',
}}
>
<time
className="sans"
dateTime={new Date(event.t).toISOString()}
title={new Date(event.t).toLocaleString()}
style={{ flex: 'none', color: 'var(--dim)', fontSize: '0.74rem', minWidth: '5.6rem' }}
>
{clock(event.t)}
</time>
<span style={{ color: TONE[line.tone] || 'var(--muted)', fontSize: '0.92rem' }}>
{line.actor && <strong style={{ color: 'var(--ink)' }}>{line.actor}</strong>}
{line.actor && (line.join || ' ')}
{line.verb}
{line.subject && ' '}
{line.subject && <strong style={{ color: 'var(--ink)' }}>{line.subject}</strong>}
{line.detail && (
<span className="sans" style={{ color: 'var(--dim)', fontSize: '0.76rem' }}>
{' · '}
{line.detail}
</span>
)}
</span>
</li>
)
})}
</ol>
)}
</div>
)
}
const selectStyle = {
background: 'var(--panel-flat, transparent)',
color: 'var(--text)',
border: '1px solid var(--line)',
borderRadius: 'var(--radius-input, 6px)',
padding: '3px 8px',
fontSize: '0.78rem',
}

73
client/src/components/FooterStatus.jsx Normal file
View File

@@ -0,0 +1,73 @@
// ── This module's fill for core's `site.footer.status` slot ───────────────
//
// R13, and the contract is MODULE_API.md §3.7. Core owns the position in the
// footer's info row and the separator around it, and passes `linkStyle` so the
// row stays visually one row. **The label, the destination, the data and whether
// anything renders at all are this component's** — that is the whole division,
// and it is why the slot is named for a place rather than for a meaning.
//
// ── The live count, and what it costs ─────────────────────────────────────
//
// The org lead chose a live count ("3 servers · 42 online") over a static link,
// so this fetches. Be clear-eyed about where it fetches from: core renders
// `SiteFooter` inside `PublicLayout`, and every public page renders
// `PublicLayout` ITSELF (§3.3) — so this component mounts once per public page
// view, not once per session. Every public page on the site therefore carries one
// `/public/rust/servers` request, including pages that have nothing to do with
// Rust.
//
// Two things keep that honest rather than merely cheap:
//
// • **It renders NOTHING until it has an answer, and nothing again if the
// request fails.** An unfilled slot renders nothing and core's `wrap` takes
// the separator with it, so a failed fetch degrades to exactly the footer an
// instance with no module installed has. A spinner in a footer would be worse
// than silence on every page of the site.
// • **It never polls.** One request per page view is a cost; a timer in the
// footer of every page would be a different kind of thing entirely.
//
// If that per-page request ever shows up in an operator's logs as a problem, the
// fix is a short-lived module-scope cache here — the decision to keep the number
// live stays intact, and nothing else on the site has to change.
import { useEffect, useState } from 'react'
import { Link } from 'react-router-dom'
import api from '../api.js'
export default function FooterStatus({ linkStyle }) {
const [summary, setSummary] = useState(null)
useEffect(() => {
let live = true
api.servers
.list()
.then(({ servers }) => {
if (!live) return
// `online` already accounts for staleness — the model refuses to let a
// row that has not been written in five minutes claim a server is up —
// so this is a sum, not a judgement.
setSummary({
servers: servers.length,
players: servers.reduce((total, server) => total + (server.online ? server.players : 0), 0),
})
})
// Silence, deliberately. This is the footer of every page on the site; a
// module that cannot reach its own API has nothing to say there.
.catch(() => {})
return () => {
live = false
}
}, [])
if (!summary || summary.servers === 0) return null
return (
<Link to="/rust" style={linkStyle}>
{summary.servers === 1 ? '1 server' : `${summary.servers} servers`}
{' · '}
{summary.players === 1 ? '1 online' : `${summary.players} online`}
</Link>
)
}

110
client/src/components/Leaderboard.jsx Normal file
View File

@@ -0,0 +1,110 @@
// ── The leaderboard ───────────────────────────────────────────────────────
//
// Per wipe when a wipe is selected, all-time when it is not (R12). The two are
// the same rows summed differently rather than two sets of counters, so they can
// never disagree — which is worth knowing here because it means "All time" is
// not a slower or less accurate answer, it is the same table without a WHERE.
//
// It does NOT poll. A leaderboard moves on the scale of a session; a table that
// re-sorted itself under the reader's cursor every twenty seconds would be worse
// than one that is four minutes old, and the page has a `Refresh` on the tab
// strip for anybody who disagrees.
import { EmptyState, ErrorState, Loading, useAsync } from '../core.js'
import { ago, count, duration, shortId } from '../lib/format.js'
import api from '../api.js'
// `sort` is the API's own vocabulary (`kills`, `deaths`, `npcKills`, `playtime`),
// and the column it maps to is this file's. Keeping them in one list is what
// stops a header that sorts by something other than what it says.
const COLUMNS = [
{ key: 'kills', label: 'Kills', sort: 'kills', value: (r) => count(r.kills) },
{ key: 'deaths', label: 'Deaths', sort: 'deaths', value: (r) => count(r.deaths) },
{ key: 'npcKills', label: 'NPC kills', sort: 'npcKills', value: (r) => count(r.npcKills) },
{ key: 'structures', label: 'Structures', sort: null, value: (r) => count(r.structures) },
{ key: 'playtimeSec', label: 'Played', sort: 'playtime', value: (r) => duration(r.playtimeSec) },
]
export default function Leaderboard({ serverId, wipeId, sort, onSort }) {
const { data, loading, error } = useAsync(
() => api.servers.leaderboard(serverId, { wipe: wipeId, sort, limit: 50 }),
[serverId, wipeId, sort],
)
const rows = data ? data.leaderboard : []
if (loading) return <Loading />
if (error) return <ErrorState error={error} />
if (rows.length === 0) {
return (
<EmptyState
title="No scores yet"
message={
wipeId
? 'Nobody has done anything countable on this wipe yet.'
: 'This server has not reported anything countable yet.'
}
/>
)
}
return (
<div style={{ overflowX: 'auto' }}>
<table className="sans" style={{ width: '100%', borderCollapse: 'collapse', fontSize: '0.86rem' }}>
<thead>
<tr style={{ textAlign: 'left', color: 'var(--dim)', fontSize: '0.72rem', letterSpacing: '0.08em' }}>
<th style={{ ...cell, textTransform: 'uppercase' }}>Player</th>
{COLUMNS.map((column) => (
<th key={column.key} style={{ ...cell, textAlign: 'right', textTransform: 'uppercase' }}>
{column.sort ? (
<button
type="button"
onClick={() => onSort(column.sort)}
aria-label={`Sort by ${column.label}`}
style={{
cursor: 'pointer',
background: 'none',
border: 'none',
padding: 0,
font: 'inherit',
letterSpacing: 'inherit',
textTransform: 'inherit',
color: column.sort === sort ? 'var(--accent-bright)' : 'var(--dim)',
}}
>
{column.label}
</button>
) : (
column.label
)}
</th>
))}
<th style={{ ...cell, textAlign: 'right', textTransform: 'uppercase' }}>Last seen</th>
</tr>
</thead>
<tbody>
{rows.map((row, index) => (
<tr key={row.steamId} style={{ borderTop: '1px solid var(--line-soft, var(--line))' }}>
<td style={cell}>
<span style={{ color: 'var(--dim)', marginRight: 8 }}>{index + 1}</span>
{/* A player this module has never seen NAMED is shown by the tail
of their id rather than as a blank: the row is real, and a
nameless one reads as a rendering fault. */}
<strong style={{ color: 'var(--ink)' }}>{row.name || shortId(row.steamId)}</strong>
</td>
{COLUMNS.map((column) => (
<td key={column.key} style={{ ...cell, textAlign: 'right' }}>
{column.value(row)}
</td>
))}
<td style={{ ...cell, textAlign: 'right', color: 'var(--dim)' }}>{ago(row.lastSeen)}</td>
</tr>
))}
</tbody>
</table>
</div>
)
}
const cell = { padding: '8px 10px', whiteSpace: 'nowrap' }

94
client/src/components/Online.jsx Normal file
View File

@@ -0,0 +1,94 @@
// ── Who is on the server right now ────────────────────────────────────────
//
// Read from the presence BOARD, not counted from connect and disconnect events:
// the bridge re-sends the whole board on every connect and every sixty seconds,
// so this is right even after the website has missed something (PROTOCOL.md
// §8.3). Counting transitions instead would drift, and drift in the direction
// people notice — players who never left.
//
// It polls with the feed, because "who is on" is the one thing on this page that
// is a live question.
import { EmptyState, ErrorState, Loading } from '../core.js'
import { duration, shortId } from '../lib/format.js'
import usePolled from '../hooks/usePolled.js'
import api from '../api.js'
export default function Online({ serverId, online }) {
const { data, error, loading } = usePolled(() => api.servers.online(serverId), {
key: serverId,
intervalMs: 20_000,
})
const players = data ? data.players : []
if (loading) return <Loading />
if (error && !data) return <ErrorState error={error} />
if (players.length === 0) {
return (
<EmptyState
title={online ? 'Nobody is on' : 'The server is offline'}
message={
online
? 'The server is up and the island is empty. Somebody has to be first.'
: 'Presence is the one thing on this page that cannot be answered from the record — it is who is connected now, and nothing is.'
}
/>
)
}
return (
<>
{/* A board is the last one that ARRIVED, and an unreachable sidecar does not
clear it — deliberately, because the rows are still the best answer
anybody has. But presented bare they read as "these people are on right
now", which is the one thing an offline server cannot be saying. The
page walk found this with a fixture server whose header said Offline
above three apparently-connected players. */}
{!online && (
<p className="sans" style={{ color: 'var(--dim)', fontSize: '0.8rem', marginTop: 0 }}>
This server is offline. Below is the last board it sent, not who is on it now.
</p>
)}
<ul style={{ listStyle: 'none', margin: 0, padding: 0 }}>
{players.map((player) => (
<li
key={player.steamId}
style={{
display: 'flex',
justifyContent: 'space-between',
alignItems: 'baseline',
gap: 12,
padding: '8px 0',
borderBottom: '1px solid var(--line-soft, var(--line))',
}}
>
<span>
<strong style={{ color: 'var(--ink)' }}>{player.name || shortId(player.steamId)}</strong>
{/* Sleeping is not idle and not offline — a sleeping player's body is
in the world and can be killed, which is why the board carries the
flag at all. */}
{player.sleeping && (
<span className="sans" style={{ color: 'var(--dim)', fontSize: '0.76rem' }}> · sleeping</span>
)}
</span>
{/* `connectedAt` is absent for a player who was already on when the
plugin loaded — an unknown session length, which is not a session of
no length. Saying nothing is the honest render of that. */}
<span className="sans" style={{ color: 'var(--dim)', fontSize: '0.78rem', whiteSpace: 'nowrap' }}>
{player.connectedAt ? `on for ${sessionSoFar(player.connectedAt)}` : ''}
</span>
</li>
))}
</ul>
</>
)
}
/** How long a player has been on, from the DATETIME the board reported. */
function sessionSoFar(connectedAt) {
const since = Date.parse(connectedAt)
if (Number.isNaN(since)) return ''
return duration((Date.now() - since) / 1000)
}

63
client/src/components/Tabs.jsx Normal file
View File

@@ -0,0 +1,63 @@
// ── Tabs, bundled rather than borrowed ────────────────────────────────────
//
// The shared kit is nine members and it is CLOSED (MODULE_API.md §3.4): layout,
// headings, the three data-page states, the fetch hook, the session, the site
// and `Slot`. A tab strip is not in it, so it is here — which is the kit working
// as designed rather than a gap in it. What the kit guarantees is that a module
// page looks like the site while it loads and while it fails; everything a page
// builds on top of that is the module's own.
//
// It is styled with core's CSS VARIABLES and its `.pill` class rather than with
// colours of its own, so it re-themes with the instance (THEMING_AND_NAV.md).
// The one class this module must never write by hand is the shell wrapper —
// `PublicLayout`'s `shell` prop exists precisely so that one stays core's.
//
// **The selected tab lives in the URL, not in this component.** A tab strip that
// owned its own state would make every panel on this page unlinkable: "look at
// the leaderboard for this server" would be a sentence rather than a link, back
// would leave the page entirely, and a refresh would land on the first tab. So
// this is a controlled component and `ServerDetail` keeps the state in a search
// parameter.
export default function Tabs({ tabs, active, onSelect, label = 'Sections' }) {
return (
<div
role="tablist"
aria-label={label}
className="sans"
style={{
display: 'flex',
flexWrap: 'wrap',
gap: 8,
borderBottom: '1px solid var(--line)',
paddingBottom: 12,
marginBottom: 20,
}}
>
{tabs.map((tab) => {
const selected = tab.id === active
return (
<button
key={tab.id}
type="button"
role="tab"
aria-selected={selected}
onClick={() => onSelect(tab.id)}
style={{
cursor: 'pointer',
padding: '6px 14px',
borderRadius: 'var(--radius-pill, 999px)',
fontSize: '0.82rem',
letterSpacing: '0.04em',
border: `1px solid ${selected ? 'var(--accent)' : 'var(--line)'}`,
background: selected ? 'var(--blue)' : 'transparent',
color: selected ? 'var(--accent-bright)' : 'var(--muted)',
}}
>
{tab.label}
</button>
)
})}
</div>
)
}

54
client/src/components/WipeSelect.jsx Normal file
View File

@@ -0,0 +1,54 @@
// ── "This wipe" or "All time" ─────────────────────────────────────────────
//
// One control, used by two panels, because the wipe is a property of the PAGE
// rather than of the feed or the leaderboard — a reader who has chosen last
// month's map means it for both, and two selects that could disagree is a page
// that shows one wipe's kills next to another's leaderboard.
//
// It loads the wipe list itself. That is a second request for the same list the
// Wipes tab fetches, and it is the right trade: the alternative is the page
// fetching it on mount for a control most visitors never touch, on every visit,
// for every server.
import { useAsync } from '../core.js'
import { day } from '../lib/format.js'
import api from '../api.js'
/** The value that means "no wipe filter at all". Never the empty string — see `api.js`'s `query`. */
export const ALL_TIME = 'all'
export default function WipeSelect({ serverId, value, onChange, currentWipeId }) {
const { data } = useAsync(() => api.servers.wipes(serverId), [serverId])
const wipes = data ? data.wipes : []
// A server with one wipe has nothing to choose between, so the control is not
// offered. "All time" and "this wipe" are the same answer there, and a select
// with one real option is furniture that invites a question with no answer.
if (wipes.length < 2) return null
return (
<label className="sans" style={{ color: 'var(--dim)', fontSize: '0.78rem' }}>
Wipe{' '}
<select
value={value || ALL_TIME}
onChange={(event) => onChange(event.target.value)}
style={{
background: 'var(--panel-flat, transparent)',
color: 'var(--text)',
border: '1px solid var(--line)',
borderRadius: 'var(--radius-input, 6px)',
padding: '3px 8px',
fontSize: '0.78rem',
}}
>
<option value={ALL_TIME}>All time</option>
{wipes.map((wipe) => (
<option key={wipe.wipeId} value={wipe.wipeId}>
{day(wipe.saveCreatedAt || wipe.firstSeen)}
{wipe.wipeId === currentWipeId ? ' (current)' : ''}
</option>
))}
</select>
</label>
)
}

85
client/src/components/Wipes.jsx Normal file
View File

@@ -0,0 +1,85 @@
// ── Every wipe this server has had ────────────────────────────────────────
//
// The list is what makes the rest of the page navigable — picking a wipe here
// filters the feed and the leaderboard — and it is also the proof R12 asks for:
// a wipe that ended is still here, with its record still attached. A Rust server
// wipes monthly, and a community site that forgot the previous map every time
// would throw away most of what it knows about its own players.
//
// `wipeId` is derived by the bridge PLUGIN from the save's creation time and
// stamped on every frame (PROTOCOL.md §8.2), so the id in this list is the same
// id the events and the leaderboard filter by. There is no second derivation
// anywhere that could disagree.
import { EmptyState, ErrorState, Loading, useAsync } from '../core.js'
import { ago, day } from '../lib/format.js'
import api from '../api.js'
export default function Wipes({ serverId, currentWipeId, selected, onSelect }) {
const { data, loading, error } = useAsync(() => api.servers.wipes(serverId), [serverId])
const wipes = data ? data.wipes : []
if (loading) return <Loading />
if (error) return <ErrorState error={error} />
if (wipes.length === 0) {
return (
<EmptyState
title="No wipes recorded"
message="A wipe appears here once this server has reported something during it."
/>
)
}
return (
<ul style={{ listStyle: 'none', margin: 0, padding: 0 }}>
{wipes.map((wipe) => {
const current = wipe.wipeId === currentWipeId
const active = wipe.wipeId === selected
return (
<li key={wipe.wipeId} style={{ borderBottom: '1px solid var(--line-soft, var(--line))' }}>
<button
type="button"
onClick={() => onSelect(wipe.wipeId)}
style={{
display: 'flex',
width: '100%',
gap: 12,
alignItems: 'baseline',
justifyContent: 'space-between',
padding: '10px 6px',
cursor: 'pointer',
background: active ? 'var(--blue)' : 'transparent',
border: 'none',
color: 'inherit',
font: 'inherit',
textAlign: 'left',
}}
>
<span>
<strong style={{ color: 'var(--ink)' }}>
{/* The save's creation time is the wipe's own date; `firstSeen`
is when THIS website first heard about it, and they differ
by however long the module was not installed. The first is
the wipe, so it leads. */}
{day(wipe.saveCreatedAt || wipe.firstSeen)}
</strong>
{current && (
<span className="sans" style={{ color: 'var(--mode-live, #5fb98a)', fontSize: '0.74rem' }}>
{' · current'}
</span>
)}
<span className="sans" style={{ display: 'block', color: 'var(--dim)', fontSize: '0.74rem' }}>
{wipe.wipeId}
</span>
</span>
<span className="sans" style={{ color: 'var(--dim)', fontSize: '0.78rem', whiteSpace: 'nowrap' }}>
last heard {ago(wipe.lastSeen)}
</span>
</button>
</li>
)
})}
</ul>
)
}