@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/admin/LeaderboardRoutes.js

@@ -0,0 +1,569 @@
+// The leaderboards/* admin routes (game-server-leaderboards T6, DR §6 admin table, D9, D17, D18, D21, D22): boards and
+// seasons, entry moderation, players, rules, activity, status, backups and the server-trust submission. Every change is
+// audited with its reason fields and new scores (never keys); reads are not audited.
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { bodyObject, booleanField, numberField, optionalStringField, stringField } from "./AdminRequestBodies.js";
+import { LEADERBOARD_ALL_VARIANT_KEY, LEADERBOARD_DEFAULT_PAGE_SIZE, LEADERBOARD_MAXIMUM_PAGE_SIZE } from "../leaderboards/LeaderboardConstants.js";
+import { LeaderboardError } from "../leaderboards/LeaderboardError.js";
+import { variantKeyOf, variantValuesOf } from "../leaderboards/LeaderboardRules.js";
+import { exportLeaderboards, exportRankingCsv, importLeaderboards } from "../leaderboards/LeaderboardTransfer.js";
+/** HTTP status of a successful answer. */
+const HTTP_OK = 200;
+/** HTTP status of an invalid request. */
+const HTTP_BAD_REQUEST = 400;
+/** The ok body of an answer with nothing else to say. */
+const OK_BODY = { ok: true };
+/** Longest moderation reason, in characters. */
+const MAXIMUM_REASON_LENGTH = 500;
+/** Activity records one read returns unless the query says otherwise. */
+const DEFAULT_ACTIVITY_LIMIT = 50;
+/** Most activity records one read returns. */
+const MAXIMUM_ACTIVITY_LIMIT = 500;
+/** The activity kinds the activity view can be filtered by. */
+const ACTIVITY_KINDS = new Set(["accepted", "duplicate", "refused"]);
+/** The download of each export format. */
+const EXPORT_CONTENT_TYPES = { json: "application/json; charset=utf-8", csv: "text/csv; charset=utf-8" };
+/** The file name of a JSON backup. */
+const JSON_EXPORT_FILE_NAME = "leaderboards.json";
+/**
+ * Registers every leaderboards/* route (DR §6 admin table).
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export function registerLeaderboardRoutes(router, services) {
+    const leaderboards = services.leaderboards;
+    const routes = [
+        { method: "GET", pattern: "leaderboards/status", permission: "leaderboards.view", requiresStepUp: false, auditAction: null, handler: async () => ok(await leaderboards.status()) },
+        { method: "GET", pattern: "leaderboards/boards", permission: "leaderboards.view", requiresStepUp: false, auditAction: null, handler: async () => listBoards(leaderboards) },
+        { method: "POST", pattern: "leaderboards/boards", permission: "leaderboards.manage", requiresStepUp: false, auditAction: "leaderboard.boardCreate", handler: async (request) => createBoard(leaderboards, request) },
+        { method: "GET", pattern: "leaderboards/boards/:boardId", permission: "leaderboards.view", requiresStepUp: false, auditAction: null, handler: async (request) => ok(await leaderboards.describeBoard(request.params.boardId, seasonQueryOf(request.query))) },
+        { method: "PUT", pattern: "leaderboards/boards/:boardId", permission: "leaderboards.manage", requiresStepUp: false, auditAction: "leaderboard.boardUpdate", handler: async (request) => updateBoard(leaderboards, request) },
+        { method: "POST", pattern: "leaderboards/boards/:boardId/duplicate", permission: "leaderboards.manage", requiresStepUp: false, auditAction: "leaderboard.boardDuplicate", handler: async (request) => duplicateBoard(leaderboards, request) },
+        { method: "DELETE", pattern: "leaderboards/boards/:boardId", permission: "leaderboards.manage", requiresStepUp: true, auditAction: "leaderboard.boardDelete", handler: async (request) => deleteBoard(leaderboards, request) },
+        { method: "GET", pattern: "leaderboards/boards/:boardId/entries", permission: "leaderboards.view", requiresStepUp: false, auditAction: null, handler: async (request) => readEntries(leaderboards, request) },
+        { method: "GET", pattern: "leaderboards/boards/:boardId/removed", permission: "leaderboards.view", requiresStepUp: false, auditAction: null, handler: async (request) => readRemoved(leaderboards, request) },
+        { method: "POST", pattern: "leaderboards/boards/:boardId/entries", permission: "leaderboards.manage", requiresStepUp: false, auditAction: "leaderboard.entryAdd", handler: async (request) => addEntry(leaderboards, request) },
+        { method: "PUT", pattern: "leaderboards/boards/:boardId/entries/:playerId", permission: "leaderboards.manage", requiresStepUp: false, auditAction: "leaderboard.entryCorrect", handler: async (request) => correctEntry(leaderboards, request) },
+        { method: "POST", pattern: "leaderboards/boards/:boardId/entries/:playerId/remove", permission: "leaderboards.manage", requiresStepUp: false, auditAction: "leaderboard.entryRemove", handler: async (request) => removeEntry(leaderboards, request) },
+        { method: "POST", pattern: "leaderboards/boards/:boardId/entries/:playerId/restore", permission: "leaderboards.manage", requiresStepUp: false, auditAction: "leaderboard.entryRestore", handler: async (request) => restoreEntry(leaderboards, request) },
+        { method: "POST", pattern: "leaderboards/boards/:boardId/seasons/reset", permission: "leaderboards.manage", requiresStepUp: true, auditAction: "leaderboard.seasonReset", handler: async (request) => resetSeason(leaderboards, request) },
+        { method: "DELETE", pattern: "leaderboards/boards/:boardId/seasons/:seasonId", permission: "leaderboards.manage", requiresStepUp: true, auditAction: "leaderboard.seasonDelete", handler: async (request) => deleteSeason(leaderboards, request) },
+        { method: "GET", pattern: "leaderboards/players", permission: "leaderboards.view", requiresStepUp: false, auditAction: null, handler: async (request) => ok(await leaderboards.searchPlayers(request.query.get("search") ?? "")) },
+        { method: "GET", pattern: "leaderboards/players/:playerId", permission: "leaderboards.view", requiresStepUp: false, auditAction: null, handler: async (request) => ok(await leaderboards.getPlayerDetail(request.params.playerId)) },
+        { method: "PUT", pattern: "leaderboards/players/:playerId/name", permission: "leaderboards.manage", requiresStepUp: false, auditAction: "leaderboard.playerRename", handler: async (request) => renamePlayer(leaderboards, request) },
+        { method: "POST", pattern: "leaderboards/players/:playerId/hide", permission: "leaderboards.manage", requiresStepUp: false, auditAction: "leaderboard.playerHide", handler: async (request) => hidePlayer(leaderboards, request) },
+        { method: "POST", pattern: "leaderboards/players/:playerId/merge", permission: "leaderboards.manage", requiresStepUp: true, auditAction: "leaderboard.playerMerge", handler: async (request) => mergePlayer(leaderboards, request) },
+        { method: "DELETE", pattern: "leaderboards/players/:playerId", permission: "leaderboards.manage", requiresStepUp: true, auditAction: "leaderboard.playerErase", handler: async (request) => erasePlayer(leaderboards, request) },
+        { method: "GET", pattern: "leaderboards/rules", permission: "leaderboards.view", requiresStepUp: false, auditAction: null, handler: async () => ok(await leaderboards.getRulesView()) },
+        { method: "PUT", pattern: "leaderboards/rules", permission: "leaderboards.manage", requiresStepUp: false, auditAction: "leaderboard.rules", handler: async (request) => updateRules(leaderboards, request) },
+        { method: "GET", pattern: "leaderboards/activity", permission: "leaderboards.view", requiresStepUp: false, auditAction: null, handler: async (request) => readActivity(leaderboards, request) },
+        { method: "GET", pattern: "leaderboards/export", permission: "leaderboards.view", requiresStepUp: false, auditAction: "leaderboard.export", handler: async (request) => exportBoards(services, request) },
+        {
+            method: "POST",
+            pattern: "leaderboards/import",
+            permission: "leaderboards.manage",
+            requiresStepUp: (request) => !isDryRun(request),
+            auditAction: (request) => isDryRun(request) ? "leaderboard.importPreview" : "leaderboard.import",
+            handler: async (request) => importBoards(services, request)
+        },
+        { method: "POST", pattern: "leaderboards/submit", permission: "leaderboards.submit", requiresStepUp: false, auditAction: null, handler: async (request) => submitAtServerTrust(leaderboards, request) }
+    ];
+    for (const route of routes)
+        router.register({ ...route, handler: withLeaderboardErrors(route.handler) });
+}
+/**
+ * Whether an import is a dry run: a missing flag is a dry run, so only an explicit false writes.
+ * @param request The request.
+ * @returns True unless the body sets dryRun to false.
+ */
+function isDryRun(request) {
+    return request.body?.dryRun !== false;
+}
+// ---- Boards and seasons ---------------------------------------------------------------------------------------------
+/**
+ * GET leaderboards/boards: every board's summary, sorted by board id.
+ * @param leaderboards The leaderboard service.
+ * @returns The summaries.
+ */
+async function listBoards(leaderboards) {
+    const records = await leaderboards.listBoardRecords();
+    const summaries = [];
+    for (const stored of records)
+        summaries.push(await leaderboards.summarizeBoard(stored));
+    return ok(summaries);
+}
+/**
+ * POST leaderboards/boards: the body is `{ definition }` (the definition itself is accepted too).
+ * @param leaderboards The leaderboard service.
+ * @param request The request.
+ * @returns The new board's summary.
+ */
+async function createBoard(leaderboards, request) {
+    const body = bodyObject(request.body);
+    const definition = ((body.definition != null) ? body.definition : body);
+    const summary = await leaderboards.createBoard(definition);
+    return { status: HTTP_OK, body: summary, audit: { target: summary.definition.boardId, parameters: { definition: summary.definition } } };
+}
+/**
+ * PUT leaderboards/boards/:boardId `{ definition, revision, startNewSeason }`.
+ * @param leaderboards The leaderboard service.
+ * @param request The request.
+ * @returns The updated summary.
+ */
+async function updateBoard(leaderboards, request) {
+    const body = bodyObject(request.body);
+    const definition = bodyObject(body.definition);
+    const revision = numberField(body, "revision");
+    const startNewSeason = (body.startNewSeason == null) ? false : booleanField(body, "startNewSeason");
+    const boardId = request.params.boardId;
+    const summary = await leaderboards.updateBoard(boardId, definition, revision, startNewSeason);
+    return { status: HTTP_OK, body: summary, audit: { target: boardId, parameters: { definition: summary.definition, startNewSeason: startNewSeason } } };
+}
+/**
+ * POST leaderboards/boards/:boardId/duplicate `{ newBoardId, displayName }`.
+ * @param leaderboards The leaderboard service.
+ * @param request The request.
+ * @returns The new board's summary.
+ */
+async function duplicateBoard(leaderboards, request) {
+    const body = bodyObject(request.body);
+    const newBoardId = stringField(body, "newBoardId");
+    const displayName = stringField(body, "displayName");
+    const boardId = request.params.boardId;
+    const summary = await leaderboards.duplicateBoard(boardId, newBoardId, displayName);
+    return { status: HTTP_OK, body: summary, audit: { target: boardId, parameters: { newBoardId: newBoardId, displayName: displayName } } };
+}
+/**
+ * DELETE leaderboards/boards/:boardId: the board and every ranking of every season (step-up).
+ * @param leaderboards The leaderboard service.
+ * @param request The request.
+ * @returns Ok.
+ */
+async function deleteBoard(leaderboards, request) {
+    const boardId = request.params.boardId;
+    await leaderboards.deleteBoard(boardId);
+    return { status: HTTP_OK, body: OK_BODY, audit: { target: boardId, parameters: {} } };
+}
+/**
+ * POST leaderboards/boards/:boardId/seasons/reset `{ reason }` (step-up).
+ * @param leaderboards The leaderboard service.
+ * @param request The request.
+ * @returns The board's summary with its new season.
+ */
+async function resetSeason(leaderboards, request) {
+    const reason = reasonField(bodyObject(request.body));
+    const boardId = request.params.boardId;
+    const summary = await leaderboards.resetSeason(boardId, "admin");
+    return { status: HTTP_OK, body: summary, audit: { target: boardId, parameters: { reason: reason, newSeasonId: summary.currentSeasonId } } };
+}
+/**
+ * DELETE leaderboards/boards/:boardId/seasons/:seasonId: an archived season's rankings (step-up).
+ * @param leaderboards The leaderboard service.
+ * @param request The request.
+ * @returns `{ deletedEntries }`.
+ */
+async function deleteSeason(leaderboards, request) {
+    const boardId = request.params.boardId;
+    const seasonId = seasonIdOf(request.params.seasonId, "seasonId");
+    const deletedEntries = await leaderboards.deleteSeason(boardId, seasonId);
+    return { status: HTTP_OK, body: { deletedEntries: deletedEntries }, audit: { target: boardId, parameters: { seasonId: seasonId, deletedEntries: deletedEntries } } };
+}
+// ---- Entries --------------------------------------------------------------------------------------------------------
+/**
+ * GET leaderboards/boards/:boardId/entries (`?season=&variantKey=&offset=&limit=&search=`): a page of one ranking, or
+ * the entries matching a search.
+ * @param leaderboards The leaderboard service.
+ * @param request The request.
+ * @returns The page.
+ */
+async function readEntries(leaderboards, request) {
+    const boardId = request.params.boardId;
+    const ranking = await rankingOf(leaderboards, boardId, request.query);
+    const search = textQueryOf(request.query, "search");
+    if (search != null)
+        return ok(await leaderboards.searchEntries(boardId, ranking.variantKey, ranking.seasonId, search));
+    const offset = integerQueryOf(request.query, "offset", 0, 0, Number.MAX_SAFE_INTEGER);
+    const limit = integerQueryOf(request.query, "limit", LEADERBOARD_DEFAULT_PAGE_SIZE, 1, LEADERBOARD_MAXIMUM_PAGE_SIZE);
+    return ok(await leaderboards.readEntries(boardId, variantValuesOf(ranking.variantKey), ranking.seasonId, offset, limit, "admin"));
+}
+/**
+ * GET leaderboards/boards/:boardId/removed (`?season=&variantKey=`).
+ * @param leaderboards The leaderboard service.
+ * @param request The request.
+ * @returns The removed entries.
+ */
+async function readRemoved(leaderboards, request) {
+    const boardId = request.params.boardId;
+    const ranking = await rankingOf(leaderboards, boardId, request.query);
+    return ok(await leaderboards.readRemoved(boardId, ranking.variantKey, ranking.seasonId));
+}
+/**
+ * POST leaderboards/boards/:boardId/entries `{ variant, playerId, displayName, score, reason }`: an entry by hand at
+ * server trust, for a new manual player when playerId is missing.
+ * @param leaderboards The leaderboard service.
+ * @param request The request.
+ * @returns The entry with its rank.
+ */
+async function addEntry(leaderboards, request) {
+    const body = bodyObject(request.body);
+    const variant = variantFieldOf(body);
+    const playerId = optionalStringField(body, "playerId");
+    const displayName = optionalStringField(body, "displayName") ?? "";
+    const score = numberField(body, "score");
+    const reason = reasonField(body);
+    const boardId = request.params.boardId;
+    const entry = await leaderboards.addEntry(boardId, variant, (playerId === "") ? null : playerId, displayName, score);
+    return { status: HTTP_OK, body: entry, audit: { target: boardId, parameters: { playerId: entry.playerId, variant: variant, score: score, reason: reason } } };
+}
+/**
+ * PUT leaderboards/boards/:boardId/entries/:playerId `{ seasonId, variantKey, score, reason }`.
+ * @param leaderboards The leaderboard service.
+ * @param request The request.
+ * @returns The corrected entry.
+ */
+async function correctEntry(leaderboards, request) {
+    const body = bodyObject(request.body);
+    const seasonId = seasonIdField(body);
+    const variantKey = stringField(body, "variantKey");
+    const score = numberField(body, "score");
+    const reason = reasonField(body);
+    const { boardId, playerId } = request.params;
+    const entry = await leaderboards.correctEntry(boardId, variantKey, seasonId, playerId, score);
+    return { status: HTTP_OK, body: entry, audit: { target: boardId, parameters: { playerId: playerId, seasonId: seasonId, variantKey: variantKey, score: score, reason: reason } } };
+}
+/**
+ * POST leaderboards/boards/:boardId/entries/:playerId/remove `{ seasonId, variantKey, reason }`.
+ * @param leaderboards The leaderboard service.
+ * @param request The request.
+ * @returns Ok.
+ */
+async function removeEntry(leaderboards, request) {
+    const body = bodyObject(request.body);
+    const seasonId = seasonIdField(body);
+    const variantKey = stringField(body, "variantKey");
+    const reason = reasonField(body);
+    const { boardId, playerId } = request.params;
+    await leaderboards.removeEntry(boardId, variantKey, seasonId, playerId, reason, callerNameOf(request));
+    return { status: HTTP_OK, body: OK_BODY, audit: { target: boardId, parameters: { playerId: playerId, seasonId: seasonId, variantKey: variantKey, reason: reason } } };
+}
+/**
+ * POST leaderboards/boards/:boardId/entries/:playerId/restore `{ seasonId, variantKey }`.
+ * @param leaderboards The leaderboard service.
+ * @param request The request.
+ * @returns Ok.
+ */
+async function restoreEntry(leaderboards, request) {
+    const body = bodyObject(request.body);
+    const seasonId = seasonIdField(body);
+    const variantKey = stringField(body, "variantKey");
+    const { boardId, playerId } = request.params;
+    await leaderboards.restoreEntry(boardId, variantKey, seasonId, playerId);
+    return { status: HTTP_OK, body: OK_BODY, audit: { target: boardId, parameters: { playerId: playerId, seasonId: seasonId, variantKey: variantKey } } };
+}
+// ---- Players --------------------------------------------------------------------------------------------------------
+/**
+ * PUT leaderboards/players/:playerId/name `{ displayName }`.
+ * @param leaderboards The leaderboard service.
+ * @param request The request.
+ * @returns The player.
+ */
+async function renamePlayer(leaderboards, request) {
+    const displayName = stringField(bodyObject(request.body), "displayName");
+    const playerId = request.params.playerId;
+    const player = await leaderboards.renamePlayer(playerId, displayName);
+    return { status: HTTP_OK, body: player, audit: { target: playerId, parameters: { displayName: player.displayName } } };
+}
+/**
+ * POST leaderboards/players/:playerId/hide `{ hidden }` (D18).
+ * @param leaderboards The leaderboard service.
+ * @param request The request.
+ * @returns The player.
+ */
+async function hidePlayer(leaderboards, request) {
+    const hidden = booleanField(bodyObject(request.body), "hidden");
+    const playerId = request.params.playerId;
+    const player = await leaderboards.hidePlayer(playerId, hidden, callerNameOf(request));
+    return { status: HTTP_OK, body: player, audit: { target: playerId, parameters: { hidden: hidden } } };
+}
+/**
+ * POST leaderboards/players/:playerId/merge `{ intoPlayerId }` (step-up, DR §15).
+ * @param leaderboards The leaderboard service.
+ * @param request The request.
+ * @returns The kept player's detail.
+ */
+async function mergePlayer(leaderboards, request) {
+    const intoPlayerId = stringField(bodyObject(request.body), "intoPlayerId");
+    const playerId = request.params.playerId;
+    const detail = await leaderboards.mergePlayers(playerId, intoPlayerId);
+    return { status: HTTP_OK, body: detail, audit: { target: playerId, parameters: { intoPlayerId: intoPlayerId } } };
+}
+/**
+ * DELETE leaderboards/players/:playerId: every entry and the record (step-up).
+ * @param leaderboards The leaderboard service.
+ * @param request The request.
+ * @returns `{ erasedEntries }`.
+ */
+async function erasePlayer(leaderboards, request) {
+    const playerId = request.params.playerId;
+    const erasedEntries = await leaderboards.erasePlayer(playerId);
+    return { status: HTTP_OK, body: { erasedEntries: erasedEntries }, audit: { target: playerId, parameters: { erasedEntries: erasedEntries } } };
+}
+// ---- Rules, activity, backups and server submissions ----------------------------------------------------------------
+/**
+ * PUT leaderboards/rules `{ rules, revision }`.
+ * @param leaderboards The leaderboard service.
+ * @param request The request.
+ * @returns The new rules view.
+ */
+async function updateRules(leaderboards, request) {
+    const body = bodyObject(request.body);
+    const rules = bodyObject(body.rules);
+    const revision = numberField(body, "revision");
+    const view = await leaderboards.updateRules(rules, revision);
+    return { status: HTTP_OK, body: view, audit: { target: "rules", parameters: { rules: view.rules } } };
+}
+/**
+ * GET leaderboards/activity (`?kind=&boardId=&before=&limit=`): newest first; client addresses only for callers holding
+ * players.viewAddresses (D21).
+ * @param leaderboards The leaderboard service.
+ * @param request The request.
+ * @returns The records.
+ */
+async function readActivity(leaderboards, request) {
+    const kind = textQueryOf(request.query, "kind");
+    if (kind != null && !ACTIVITY_KINDS.has(kind))
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "kind must be accepted, duplicate or refused");
+    const boardId = textQueryOf(request.query, "boardId");
+    const before = (textQueryOf(request.query, "before") != null) ? integerQueryOf(request.query, "before", 0, 0, Number.MAX_SAFE_INTEGER) : null;
+    const limit = integerQueryOf(request.query, "limit", DEFAULT_ACTIVITY_LIMIT, 1, MAXIMUM_ACTIVITY_LIMIT);
+    const includeAddresses = request.caller?.permissions.has("players.viewAddresses") === true;
+    return ok(await leaderboards.readActivity(kind, boardId, before, limit, includeAddresses));
+}
+/**
+ * GET leaderboards/export (`?format=json|csv&boardId=&season=&variantKey=`): a JSON backup (all boards or one) or one
+ * ranking as CSV (boardId required; season and variantKey default to the current season and the first variant).
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The download.
+ */
+async function exportBoards(services, request) {
+    const format = request.query.get("format") ?? "json";
+    if (format !== "json" && format !== "csv")
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "format must be json or csv");
+    const boardId = textQueryOf(request.query, "boardId");
+    if (format === "json") {
+        const seasonId = seasonQueryOf(request.query);
+        const file = await exportLeaderboards(services.leaderboards, boardId, seasonId, services.clock);
+        const audit = { target: boardId ?? "all", parameters: { format: format, boardId: boardId, seasonId: seasonId } };
+        return downloadOf(JSON.stringify(file, null, 2), "json", JSON_EXPORT_FILE_NAME, audit);
+    }
+    if (boardId == null)
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "a CSV export needs boardId");
+    const ranking = await rankingOf(services.leaderboards, boardId, request.query);
+    const csv = await exportRankingCsv(services.leaderboards, boardId, ranking.seasonId, ranking.variantKey);
+    const audit = { target: boardId, parameters: { format: format, boardId: boardId, seasonId: ranking.seasonId, variantKey: ranking.variantKey } };
+    return downloadOf(csv, "csv", boardId + "-season-" + ranking.seasonId + ".csv", audit);
+}
+/**
+ * POST leaderboards/import `LeaderboardImportRequest` (step-up unless a dry run). The audit names the policy and the
+ * result, never the file (it holds key hashes).
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The import result (the preview of a dry run).
+ */
+async function importBoards(services, request) {
+    const body = bodyObject(request.body);
+    const importRequest = {
+        file: bodyObject(body.file),
+        conflictPolicy: stringField(body, "conflictPolicy"),
+        dryRun: isDryRun(request)
+    };
+    const result = await importLeaderboards(services.leaderboards, importRequest, services.clock);
+    return { status: HTTP_OK, body: result, audit: { target: "import", parameters: { conflictPolicy: importRequest.conflictPolicy, ...result } } };
+}
+/**
+ * POST leaderboards/submit: a submission at the server trust level (D9) for the player named by `body.playerId`; an
+ * unknown player with a displayName becomes a manual player.
+ * @param leaderboards The leaderboard service.
+ * @param request The request.
+ * @returns The per-score results.
+ */
+async function submitAtServerTrust(leaderboards, request) {
+    const body = bodyObject(request.body);
+    const caller = { userId: null, userDisplayName: null, userAvatar: null, isNameManaged: false, playerKey: null, clientAddress: request.clientAddress };
+    return ok(await leaderboards.submit(caller, body, "server"));
+}
+// ---- Helpers --------------------------------------------------------------------------------------------------------
+/**
+ * Wraps a handler so a LeaderboardError answers with its status, sentence and reason (as the error detail).
+ * @param handler The handler.
+ * @returns The wrapped handler.
+ */
+function withLeaderboardErrors(handler) {
+    return async (request) => {
+        try {
+            return await handler(request);
+        }
+        catch (error) {
+            if (error instanceof LeaderboardError)
+                throw new AdminRequestError(error.status, error.message, error.reason);
+            throw error;
+        }
+    };
+}
+/**
+ * A 200 answer.
+ * @param body The JSON body.
+ * @returns The result.
+ */
+function ok(body) {
+    return { status: HTTP_OK, body: body };
+}
+/**
+ * A download answer.
+ * @param text The file's text.
+ * @param format "json" or "csv".
+ * @param fileName The file name.
+ * @param audit The audit detail.
+ * @returns The result.
+ */
+function downloadOf(text, format, fileName, audit) {
+    const bytes = new TextEncoder().encode(text);
+    return { status: HTTP_OK, body: null, download: { bytes: bytes, contentType: EXPORT_CONTENT_TYPES[format], fileName: fileName }, audit: audit };
+}
+/**
+ * The ranking a read names: `?season=` (default the current season) and `?variantKey=` (default the season's first
+ * written variant, else the first value of each dimension).
+ * @param leaderboards The leaderboard service.
+ * @param boardId The board.
+ * @param query The query.
+ * @returns The season and variant key.
+ * @throws LeaderboardError 404 for an unknown board or a season it does not keep.
+ */
+async function rankingOf(leaderboards, boardId, query) {
+    const record = (await leaderboards.getBoardRecord(boardId)).value;
+    const seasonId = seasonQueryOf(query) ?? record.currentSeasonId;
+    if (!record.seasons.some((season) => season.seasonId === seasonId)) {
+        throw new LeaderboardError(404, "invalidRequest", "board " + boardId + " has no season " + seasonId);
+    }
+    const variantKey = textQueryOf(query, "variantKey");
+    if (variantKey != null)
+        return { seasonId: seasonId, variantKey: variantKey };
+    return { seasonId: seasonId, variantKey: await defaultVariantKeyOf(leaderboards, record, seasonId) };
+}
+/**
+ * The variant a read shows when none is named: the season's first written variant, else the first value of each
+ * dimension ("all" without dimensions).
+ * @param leaderboards The leaderboard service.
+ * @param record The board.
+ * @param seasonId The season.
+ * @returns The variant key.
+ */
+async function defaultVariantKeyOf(leaderboards, record, seasonId) {
+    const [firstWritten] = await leaderboards.stores.rankStore.listVariantKeys(record.definition.boardId, seasonId);
+    if (firstWritten != null)
+        return firstWritten;
+    const firstValues = {};
+    for (const dimension of record.definition.dimensions)
+        firstValues[dimension.name] = dimension.values[0];
+    return variantKeyOf(record.definition, firstValues).variantKey ?? LEADERBOARD_ALL_VARIANT_KEY;
+}
+/**
+ * The `?season=` of a query.
+ * @param query The query.
+ * @returns The season, or null when absent.
+ * @throws AdminRequestError 400 when it is not a whole number from 1.
+ */
+function seasonQueryOf(query) {
+    const text = textQueryOf(query, "season");
+    return (text != null) ? seasonIdOf(text, "season") : null;
+}
+/**
+ * A season id from text.
+ * @param text The text.
+ * @param name The field name for the error.
+ * @returns The season.
+ * @throws AdminRequestError 400 when it is not a whole number from 1.
+ */
+function seasonIdOf(text, name) {
+    const seasonId = Number(text);
+    if (!Number.isSafeInteger(seasonId) || seasonId < 1)
+        throw new AdminRequestError(HTTP_BAD_REQUEST, name + " must be a whole number from 1");
+    return seasonId;
+}
+/**
+ * A non-empty query value.
+ * @param query The query.
+ * @param name The name.
+ * @returns The value, or null when absent or empty.
+ */
+function textQueryOf(query, name) {
+    const value = query.get(name);
+    return (value == null || value === "") ? null : value;
+}
+/**
+ * A whole-number query value within limits.
+ * @param query The query.
+ * @param name The name.
+ * @param defaultValue The value when absent.
+ * @param minimum The least value.
+ * @param maximum The greatest value.
+ * @returns The value.
+ * @throws AdminRequestError 400 when it is not a whole number within the limits.
+ */
+function integerQueryOf(query, name, defaultValue, minimum, maximum) {
+    const text = textQueryOf(query, name);
+    if (text == null)
+        return defaultValue;
+    const value = Number(text);
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum)
+        throw new AdminRequestError(HTTP_BAD_REQUEST, name + " must be a whole number from " + minimum + " to " + maximum);
+    return value;
+}
+/**
+ * The required `seasonId` of a body.
+ * @param body The body.
+ * @returns The season.
+ * @throws AdminRequestError 400 when it is not a whole number from 1.
+ */
+function seasonIdField(body) {
+    const seasonId = numberField(body, "seasonId");
+    if (!Number.isSafeInteger(seasonId) || seasonId < 1)
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "seasonId must be a whole number from 1");
+    return seasonId;
+}
+/**
+ * The required, non-empty `reason` of a body, trimmed.
+ * @param body The body.
+ * @returns The reason.
+ * @throws AdminRequestError 400 when it is missing, empty or too long.
+ */
+function reasonField(body) {
+    const reason = stringField(body, "reason").trim();
+    if (reason === "" || reason.length > MAXIMUM_REASON_LENGTH)
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "reason must be 1 to " + MAXIMUM_REASON_LENGTH + " characters");
+    return reason;
+}
+/**
+ * The optional `variant` of a body: an object of texts, or null.
+ * @param body The body.
+ * @returns The variant, or null when absent.
+ * @throws AdminRequestError 400 when it is not an object of texts.
+ */
+function variantFieldOf(body) {
+    const variant = body.variant;
+    if (variant == null)
+        return null;
+    const isTextObject = typeof variant === "object" && !Array.isArray(variant) && Object.values(variant).every((value) => typeof value === "string");
+    if (!isTextObject)
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "variant must be an object of texts");
+    return variant;
+}
+/**
+ * The name of the admin making a request, for removedBy fields.
+ * @param request The request.
+ * @returns The caller's name.
+ */
+function callerNameOf(request) {
+    return request.caller?.name ?? "unknown";
+}

package/lib/admin/LogBuffer.d.ts

@@ -0,0 +1,60 @@
+import type { GameServerLogLevel } from "../GameServerConfig.js";
+import type { LogSink } from "../GameServerLogger.js";
+import type { LogEntry, LogEntryView } from "./AdminApiTypes.js";
+/** What a log read keeps; every field left out matches everything. */
+export interface LogFilter {
+    /** This level or a more severe one. */
+    level?: GameServerLogLevel;
+    /** Entries of this room. */
+    roomId?: string;
+    /** Entries of this session. */
+    sessionName?: string;
+    /** Entries of this player. */
+    playerId?: number;
+    /** Entries of this user. */
+    userId?: string;
+    /** Text in the message or the fields, ignoring case. */
+    text?: string;
+}
+/** The in-memory log buffer of this instance. */
+export declare class LogBuffer {
+    /** The logger sink that captures into this buffer (add it with GameServerLogger.addSink). */
+    readonly sink: LogSink;
+    /** The entries, oldest first. */
+    private readonly entries;
+    /** How many entries are kept. */
+    private readonly capacity;
+    /** The sequence of the newest entry (0 before any). */
+    private newestSequence;
+    /**
+     * Creates an empty buffer.
+     * @param capacity How many entries are kept (admin.logBufferEntries); the oldest are dropped first.
+     */
+    constructor(capacity: number);
+    /** The sequence of the newest entry, 0 before any. */
+    get latestSequence(): number;
+    /**
+     * Adds an entry, redacted (DR §6.8), with the next sequence and the current time.
+     * @param level The entry's level.
+     * @param message What happened.
+     * @param fields The entry's fields.
+     */
+    capture(level: GameServerLogLevel, message: string, fields: Record<string, unknown>): void;
+    /**
+     * Reads matching entries. With a cursor, the oldest entries after it come first, so a live tail misses nothing;
+     * without one (0), the newest entries are returned, so a first look shows what just happened.
+     * @param filter What to keep.
+     * @param afterSequence Only entries with a larger sequence; 0 for the newest.
+     * @param limit The most entries returned.
+     * @returns The entries, oldest first.
+     */
+    read(filter: LogFilter, afterSequence: number, limit: number): LogEntry[];
+}
+/**
+ * A buffered entry as the console shows it.
+ * @param entry The entry.
+ * @param processId The instance it came from.
+ * @param includeAddresses False removes the client address fields (callers without players.viewAddresses).
+ * @returns The view.
+ */
+export declare function toLogEntryView(entry: LogEntry, processId: string, includeAddresses: boolean): LogEntryView;