Module-Rust/server/router/public/rust.router.js

// ── 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. Rust’s own world events (protocol 14, PLAN_REDESIGNS §14.3.1) arrive as `world.event` with `event` naming which of 24: they are public, with a `grid` worked out from the map, but a player’s `name` (and the names in `credited`) only for the presence audience, a Steam id and a position only for staff, and a type this build does not know only for staff. A downed patrol helicopter, Chinook or Bradley carries `credited` and `creditedCount` by the server’s `creditRule`.'
  // #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. Each row carries `titles`: the chat titles that player holds now, as `[{ text, color }]` in the order the game shows them, and an empty list for a player with none. Titles rank the CURRENT wipe whichever wipe the page asks for, and are set by the operator’s rules. On a server that reports Economics, and only for one wipe, each row also carries `balance` (its last known coin balance, null when none was reported) and the answer carries `economics: { startingBalance }` (PLAN_REDESIGNS §11.2.2); `economics` is null otherwise. `sort=balance` ranks the richest, and only balances above the starting balance are on it (D336). Each row carries `treasuresWon` (Dangerous Treasures chests emptied, Treasure Hunter’s count, PLAN_REDESIGNS §14.3.4), and the answer carries `dangerousTreasures: true` where the server reports Dangerous Treasures or a row already counts one, which is when a page shows that column. Likewise `guardedWon` (guarded crates cleared, Warden’s count, PLAN_REDESIGNS §14.3.5) and `guardedCrate: true` where the server reports Guarded Crate or a row already counts one.'
  // #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, playtime, cratesHacked, dropsLooted, treasuresWon, guardedWon, or balance (one wipe on a server with Economics)', 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/npc-profiles',
  // #swagger.tags = ['Public · Rust']
  // #swagger.summary = 'The NPC profiles a server’s leaderboard can rank by'
  // #swagger.description = 'The site’s RunicNPC profiles pushed to this server (docs/runicnpc/PLAN.md stage 4, D250): each one’s id, its name, a label (the first of its NPC names), and how its kills are counted (D247) — `server` (this server’s kills of that name), `name` (every server’s kills of that name) or `profile` (this site profile’s, wherever it was pushed). Empty on a site without RunicNPC.'
  // #swagger.parameters['id'] = { in: 'path', required: true, description: 'The server’s slug', schema: { type: 'string' } }
  /* #swagger.responses[200] = { description: 'The profiles', content: { "application/json": { schema: { $ref: "#/components/schemas/RustNpcBoardProfiles" } } } } */
  siteMode,
  servers.listNpcProfiles,
)

rustRouter.get(
  '/servers/:id/npc-leaderboard',
  // #swagger.tags = ['Public · Rust']
  // #swagger.summary = 'Who has killed the most NPCs of one profile'
  // #swagger.description = 'One RunicNPC profile’s kills, most first, counted as the profile says (D247, D250). Per wipe when `wipe` is given, all time otherwise. A profile counted across servers reaches every server’s current wipe when `wipe` is this server’s current one, and only this server’s rows for an older wipe. Each row carries the chat `titles` the player holds now, as the main leaderboard’s do.'
  // #swagger.parameters['id'] = { in: 'path', required: true, description: 'The server’s slug', schema: { type: 'string' } }
  // #swagger.parameters['profile'] = { in: 'query', required: true, description: 'The profile’s id, from npc-profiles', schema: { type: 'integer' } }
  // #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: 'The ranking', content: { "application/json": { schema: { $ref: "#/components/schemas/RustNpcLeaderboard" } } } } */
  /* #swagger.responses[404] = { description: 'No such profile on this server' } */
  siteMode,
  servers.npcLeaderboard,
)

rustRouter.get(
  '/servers/:id/players/:steamId/npc-kills',
  // #swagger.tags = ['Public · Rust']
  // #swagger.summary = 'One player’s kills of each NPC profile on a server'
  // #swagger.description = 'What opening a leaderboard row shows (D252): the player’s kills of RunicNPC’s NPCs by profile on this server, for the wipe the page shows (`wipe`), or all time without it. Counted by profile name on this server, whatever a profile’s leaderboard counts; labelled with the site’s name for the profile where it has one. The same numbers the leaderboard already makes public, split by profile.'
  // #swagger.parameters['id'] = { in: 'path', required: true, description: 'The server’s slug', schema: { type: 'string' } }
  // #swagger.parameters['steamId'] = { in: 'path', required: true, description: 'The player’s Steam id', schema: { type: 'string' } }
  // #swagger.parameters['wipe'] = { in: 'query', required: false, description: 'Restrict to one wipe id', schema: { type: 'string' } }
  /* #swagger.responses[200] = { description: 'The kills', content: { "application/json": { schema: { $ref: "#/components/schemas/RustNpcPlayerKills" } } } } */
  siteMode,
  servers.playerNpcKills,
)

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,
)

// ── The map (phase 14) ────────────────────────────────────────────────────
//
// The picture is public at every setting; what moves on it is not. Each of the
// four layers has its own audience, and a layer the viewer may not see is
// removed on the server — never sent and hidden by the page (PLAN.md §30.2).

rustRouter.get(
  '/servers/:id/map',
  // #swagger.tags = ['Public · Rust']
  // #swagger.summary = 'One Rust server’s map'
  // #swagger.description = 'Where the picture of the current map is, the geometry to draw it with (world size, the picture’s size and ocean margin in pixels, and the game’s own grid), the monuments when the viewer may see the world layer — only the labels drawn on this server, so a hidden label such as Substation is not sent at all (D196) — and which of the five layers — `world`, `events`, `players`, `bases`, `pvp` — this viewer gets. A hidden layer says which audience can see it and never what it holds. The players layer can never be wider than who may see who is online (`cappedByPresence`). `mates` says whether this viewer gets their own position and their online clan mates’. `picture` is null when the game has no picture of its map; `geometry` is null when the server has never described its map.'
  // #swagger.parameters['id'] = { in: 'path', required: true, description: 'The server’s slug', schema: { type: 'string' } }
  /* #swagger.responses[200] = { description: 'The map, as this viewer may see it', content: { "application/json": { schema: { $ref: "#/components/schemas/RustMap" } } } } */
  /* #swagger.responses[404] = { description: 'No such server, or it is disabled' } */
  siteMode,
  servers.getMap,
)

rustRouter.get(
  '/servers/:id/map/image',
  // #swagger.tags = ['Public · Rust']
  // #swagger.summary = 'The picture of one Rust server’s map'
  // #swagger.description = 'The JPEG, cached as immutable for a year because the picture’s SHA-256 is in the URL. A hash that is not the stored picture’s answers 404, so a replaced picture is never served under an old address. Public at every setting: the picture is rendered from the map seed and says nothing about who plays.'
  // #swagger.parameters['id'] = { in: 'path', required: true, description: 'The server’s slug', schema: { type: 'string' } }
  // #swagger.parameters['v'] = { in: 'query', required: true, description: 'The picture’s SHA-256, as the map route names it', schema: { type: 'string' } }
  /* #swagger.responses[200] = { description: 'The picture', content: { "image/jpeg": { schema: { type: "string", format: "binary" } } } } */
  /* #swagger.responses[404] = { description: 'No such server, or no picture with that hash' } */
  siteMode,
  servers.getMapImage,
)

rustRouter.get(
  '/servers/:id/map/live',
  // #swagger.tags = ['Public · Rust']
  // #swagger.summary = 'What moves on one Rust server’s map'
  // #swagger.description = 'The positions this viewer may see, asked of the game while somebody is looking and held for five seconds, so any number of viewers cost one ask. **A layer the viewer may not see is absent from the answer**, not empty: `world` (world events and locked crates), `events` (what the site’s events placed), `players` (online players and sleepers, with names) and `bases` (tool cupboards and vending machines, positions only) and `pvp` (Dynamic PVP’s own PvP zones, where each is now; protocol 14). `mates` is the viewer’s own position and their online first-party clan mates’, for a linked viewer when the server allows it. `live: false` with a `reason` when the game did not answer. Positions are never stored.'
  // #swagger.parameters['id'] = { in: 'path', required: true, description: 'The server’s slug', schema: { type: 'string' } }
  /* #swagger.responses[200] = { description: 'The positions this viewer may see', content: { "application/json": { schema: { $ref: "#/components/schemas/RustMapLive" } } } } */
  /* #swagger.responses[404] = { description: 'No such server, or it is disabled' } */
  siteMode,
  servers.getMapLive,
)

module.exports = rustRouter