wtclaude
c94271104f
A first-party Rust clan is a Team (R5). This module becomes the site's Team provider and answers core from the plugin's `clans` board. Design of record: docs/modules/rust/PLAN.md §24, D47-D58. - The store: rust_clans, rust_clan_members and rust_clan_boards. A clan's identity is <serverId>:<clanId>:<createdMs> (D52), because the game restarts clan ids whenever its clan database version changes. - The provider (D53): getTeams is complete only when every server's board is fresh, supported and untruncated. It is partial when some are, and refuses when none are. Freshness is judged by the website's clock, from when the board's `t` last advanced. - Only a complete board may mark a clan gone. A board at the game's 100-clan ceiling (D55), or one with an unreadable row, proves nothing about what it leaves out. - Leadership is diffed board to board and published (D54). The five clan events are published as team.* kinds, and written to the Team feed as members-only lines (D49). - Core only writes feed items for a Team it already holds. So the last 10 minutes of clan events are re-offered on each board refresh, deduped by a sha1 key: core clamps a dedupeKey to 40 characters, and a readable key would be truncated into collisions. - projectRoster and the clan page share one audience rule (D48): the clan's linked members and staff by default, re-read from the users row. The setting lives on Admin > Rust visibility, which also warns about uMod Clans (D47) and the ceiling. - Public: GET servers/:id/clans (the list is public, D58) and GET clans/:externalId. The client adds a Clans tab and /rust/clans/:externalId, with three module slots for core's notify, activity and forum contributions (D56). - Linking and unlinking an account ask core to reconcile Teams (D57). - The clan kinds are staff-class in the public feed allowlist. - PROTOCOL_VERSION is now 6. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
146 lines
9.9 KiB
JavaScript
146 lines
9.9 KiB
JavaScript
// ── Public · Rust ─────────────────────────────────────────────────────────
|
||
//
|
||
// Mounted at `/api/v1/public/rust` by `index.js`. One express Router, built from
|
||
// CORE's express (`core.express`) — never from a `require('express')` of your
|
||
// own, which would not resolve from here anyway (MODULE_API.md §7.2).
|
||
//
|
||
// **The tier's gate is already on.** This router sits inside core's public tier,
|
||
// which is behind nothing by design. Per-route middleware goes on top, and
|
||
// `siteMode` is the one worth understanding: it is what makes a route respect the
|
||
// operator's maintenance switch. Core applies it to its own content routes and
|
||
// deliberately does not apply it to its status endpoints, because status is
|
||
// exactly what an operator wants visible *during* maintenance.
|
||
//
|
||
// The server list is content, not status — it is the module's landing page — so
|
||
// it takes `siteMode`.
|
||
//
|
||
// ── About the `#swagger` comments ─────────────────────────────────────────
|
||
//
|
||
// They are not documentation *of* the code; they are the source the OpenAPI
|
||
// fragment is generated from (`npm run swagger`, §2.8). swagger-autogen reads
|
||
// them as JavaScript literals it evaluates, so a QUOTE CHARACTER inside a
|
||
// single-quoted description ends the string early — and the failure is silent:
|
||
// the value is truncated at that character while the generator prints success.
|
||
// Use a typographic apostrophe (’) in prose. A backtick is fine.
|
||
|
||
const core = require('../../core')
|
||
|
||
const express = core.express
|
||
const servers = require('./rust.controller')
|
||
const { siteMode } = core.middleware
|
||
|
||
const rustRouter = express.Router()
|
||
|
||
rustRouter.get(
|
||
'/servers',
|
||
// #swagger.tags = ['Public · Rust']
|
||
// #swagger.summary = 'Every Rust server this site follows'
|
||
// #swagger.description = 'The operator’s configured Rust servers and what each one last reported. Answers with `online: false` and `stale: true` rather than failing when a game server or its sidecar is unreachable — the site’s availability does not depend on the game’s.'
|
||
/* #swagger.responses[200] = { description: 'The server list', content: { "application/json": { schema: { $ref: "#/components/schemas/RustServerList" } } } } */
|
||
siteMode,
|
||
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',
|
||
// #swagger.tags = ['Public · Rust']
|
||
// #swagger.summary = 'One Rust server'
|
||
// #swagger.description = 'The same shape the list answers with, for one server, and a `404` when there is no such server or an operator has disabled it. The detail page needs the difference: every other route under this path answers an empty list for an id that does not exist, because an unknown server genuinely has no events and nobody online.'
|
||
// #swagger.parameters['id'] = { in: 'path', required: true, description: 'The server’s slug', schema: { type: 'string' } }
|
||
/* #swagger.responses[200] = { description: 'The server' } */
|
||
/* #swagger.responses[404] = { description: 'No such server, or it is disabled' } */
|
||
siteMode,
|
||
servers.getServer,
|
||
)
|
||
|
||
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. Kinds that name a player who was on the server (connects, respawns, deaths, chat, tallies) are served only to viewers inside the operator’s presence audience, which defaults to staff; `presenceHidden` says when they were withheld.'
|
||
// #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. `lastSeen` is withheld below the operator’s presence audience: a gather tally refreshes it every minute a player is on, so it would name who is online.'
|
||
// #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. **Nothing names who is online by default**: below the operator’s presence audience (staff unless widened) the names are withheld and only `count` is answered.'
|
||
// #swagger.parameters['id'] = { in: 'path', required: true, description: 'The server’s slug', schema: { type: 'string' } }
|
||
/* #swagger.responses[200] = { description: 'Who is online — or, below the operator’s presence audience, only how many', content: { "application/json": { schema: { $ref: "#/components/schemas/RustOnline" } } } } */
|
||
siteMode,
|
||
servers.listOnline,
|
||
)
|
||
|
||
// ── Clans (phase 9) ───────────────────────────────────────────────────────
|
||
//
|
||
// Rust's own clans, which this module also answers core's Team questions from.
|
||
// The list is public (D58); a roster is not (D48).
|
||
|
||
rustRouter.get(
|
||
'/servers/:id/clans',
|
||
// #swagger.tags = ['Public · Rust']
|
||
// #swagger.summary = 'The clans on one Rust server'
|
||
// #swagger.description = 'Every clan on the server’s clan board, best score first: name, colour, score and member count. Public, because none of it names a player. `board` says whether the list is current and complete — a server whose bridge cannot read its clans answers an empty list and the reason, and a server at the game’s 100-clan ceiling says `truncated`.'
|
||
// #swagger.parameters['id'] = { in: 'path', required: true, description: 'The server’s slug', schema: { type: 'string' } }
|
||
/* #swagger.responses[200] = { description: 'The clans', content: { "application/json": { schema: { $ref: "#/components/schemas/RustClanList" } } } } */
|
||
siteMode,
|
||
servers.listClans,
|
||
)
|
||
|
||
rustRouter.get(
|
||
'/clans/:externalId',
|
||
// #swagger.tags = ['Public · Rust']
|
||
// #swagger.summary = 'One Rust clan'
|
||
// #swagger.description = 'A clan and, when the viewer is inside the operator’s clan roster audience, its roster. The audience defaults to the clan’s own members (a website account linked to one of them) and staff. Below it the clan is still described and `roster.visible` is false with no names. The roster never carries a Steam id or a website account id. `externalId` is `<server>:<clan>:<created>`, the same identity the site’s Team pages use.'
|
||
// #swagger.parameters['externalId'] = { in: 'path', required: true, description: 'The clan’s identity: server, clan id and creation time in epoch ms, joined by colons', schema: { type: 'string' } }
|
||
/* #swagger.responses[200] = { description: 'The clan', content: { "application/json": { schema: { $ref: "#/components/schemas/RustClan" } } } } */
|
||
/* #swagger.responses[404] = { description: 'No such clan' } */
|
||
siteMode,
|
||
servers.getClan,
|
||
)
|
||
|
||
module.exports = rustRouter
|