@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/admin/FleetRoutes.js

@@ -0,0 +1,465 @@
+// The fleet routes (game-server-admin-console DR §6.11 overview, instances and maintenance rows, DR §7.6, §7.7): the
+// overview, the instance list and pages, drain from the console and maintenance mode, plus this instance's handlers of
+// the setMaintenance, clearMaintenance and drain fleet commands (R15).
+import { matchMaker } from "colyseus";
+import { randomUUID } from "node:crypto";
+import { getLogger } from "../GameServerLogger.js";
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { NOTICE_TEXT_MAX_LENGTH } from "./AdminConstants.js";
+import { bodyObject, booleanField, numberField, optionalStringField, stringListField } from "./AdminRequestBodies.js";
+import { computeHealthWarnings } from "./HealthWarnings.js";
+import { MAINTENANCE_SETTINGS_ID } from "./MaintenanceMode.js";
+/** HTTP status of a successful read or change. */
+const HTTP_OK = 200;
+/** HTTP status of an invalid request. */
+const HTTP_BAD_REQUEST = 400;
+/** HTTP status of an unknown instance. */
+const HTTP_NOT_FOUND = 404;
+/** HTTP status of a fleet-only action without Redis (R33). */
+const HTTP_CONFLICT = 409;
+/** The Colyseus room type of sessions. */
+const SESSION_ROOM_NAME = "fusion_session";
+/** The game mode the overview counts a session under before its first join. */
+const PENDING_GAME_MODE = "Pending";
+/** How many refusal reasons the overview lists. */
+const TOP_REFUSAL_REASON_COUNT = 5;
+/** Seconds per minute, for per-minute rates. */
+const SECONDS_PER_MINUTE = 60;
+/** Milliseconds per second. */
+const MILLISECONDS_PER_SECOND = 1000;
+/** The scope value of fleet-wide maintenance and notices. */
+const FLEET_SCOPE = "fleet";
+/** Activity items the overview shows. */
+const OVERVIEW_ACTIVITY_COUNT = 10;
+/** The refusal of a fleet-only action on a single instance (R33). */
+const NEEDS_REDIS_MESSAGE = "needs Redis to reach other instances";
+/**
+ * Registers the overview, instances/* and maintenance routes.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export function registerFleetRoutes(router, services) {
+    const routes = [
+        { method: "GET", pattern: "overview", permission: "fleet.view", requiresStepUp: false, auditAction: null, handler: async (request) => ({ status: HTTP_OK, body: await buildOverview(services, request) }) },
+        { method: "GET", pattern: "instances", permission: "fleet.view", requiresStepUp: false, auditAction: null, handler: async () => ({ status: HTTP_OK, body: await services.fleet.listInstances() }) },
+        { method: "GET", pattern: "instances/:processId", permission: "fleet.view", requiresStepUp: false, auditAction: null, handler: async (request) => ({ status: HTTP_OK, body: await describeInstance(services, request.params.processId) }) },
+        { method: "POST", pattern: "instances/:processId/drain", permission: "fleet.manage", requiresStepUp: true, auditAction: "instance.drain", handler: async (request) => drainInstance(services, request) },
+        { method: "GET", pattern: "maintenance", permission: "fleet.view", requiresStepUp: false, auditAction: null, handler: async () => ({ status: HTTP_OK, body: await buildMaintenanceView(services) }) },
+        { method: "PUT", pattern: "maintenance", permission: "fleet.manage", requiresStepUp: isFleetScope, auditAction: "maintenance.set", handler: async (request) => setMaintenance(services, request) }
+    ];
+    for (const route of routes)
+        router.register(route);
+}
+/**
+ * Registers this instance's handlers of the setMaintenance, clearMaintenance and drain fleet commands (R15).
+ * @param services The shared services.
+ */
+export function registerFleetCommands(services) {
+    services.fleet.handle("setMaintenance", async (maintenance) => {
+        services.maintenance.setInstance(maintenance);
+        services.serverEvents.record("maintenance on (this instance): " + maintenance.message, services.processId());
+        return null;
+    });
+    services.fleet.handle("clearMaintenance", async () => {
+        services.maintenance.setInstance(null);
+        services.serverEvents.record("maintenance off (this instance)", services.processId());
+        return null;
+    });
+    services.fleet.handle("drain", async (request) => drainThisInstance(services, request));
+}
+/**
+ * A notice to players (DR §6.9) with a fresh id and the server's time.
+ * @param services The shared services (the clock).
+ * @param text The text (at most NOTICE_TEXT_MAX_LENGTH characters).
+ * @param severity How prominent it is.
+ * @param countdownSeconds Seconds until the announced event, or null.
+ * @returns The notice.
+ */
+export function createNoticePayload(services, text, severity, countdownSeconds) {
+    return { noticeId: randomUUID(), text: text, severity: severity, countdownSeconds: countdownSeconds, sentAtMilliseconds: services.clock.now() };
+}
+/**
+ * Sends a notice to the sessions of this instance.
+ * @param state The server state.
+ * @param roomId One room, or null for every room of this instance.
+ * @param playerId One player of that room, or 0 for everyone.
+ * @param notice The notice.
+ * @returns How many players were targeted.
+ */
+export function sendLocalNotice(state, roomId, playerId, notice) {
+    const rooms = Array.from(state.sessionRooms).filter((room) => roomId == null || room.roomId === roomId);
+    return rooms.reduce((total, room) => total + room.adminSendNotice(notice, playerId), 0);
+}
+/**
+ * Refuses a fleet-only action on a single instance (DR §9, R33).
+ * @param services The shared services.
+ * @throws AdminRequestError 409 without Redis.
+ */
+export function requireScaledOut(services) {
+    if (!services.fleet.isScaledOut)
+        throw new AdminRequestError(HTTP_CONFLICT, NEEDS_REDIS_MESSAGE);
+}
+/**
+ * An optional notice or maintenance text, at most NOTICE_TEXT_MAX_LENGTH characters.
+ * @param body The body.
+ * @param name The field.
+ * @returns The text, or null.
+ * @throws AdminRequestError 400 when it is not text or too long.
+ */
+export function noticeTextField(body, name) {
+    const value = optionalStringField(body, name);
+    if (value != null && value.length > NOTICE_TEXT_MAX_LENGTH)
+        throw new AdminRequestError(HTTP_BAD_REQUEST, name + " is longer than " + NOTICE_TEXT_MAX_LENGTH + " characters");
+    return value;
+}
+/**
+ * A number field that may not be negative.
+ * @param body The body.
+ * @param name The field.
+ * @returns The number.
+ * @throws AdminRequestError 400 when it is not a number or negative.
+ */
+export function nonNegativeNumberField(body, name) {
+    const value = numberField(body, name);
+    if (value < 0)
+        throw new AdminRequestError(HTTP_BAD_REQUEST, name + " may not be negative");
+    return value;
+}
+/**
+ * Whether a request's body names the fleet scope (step-up applies to fleet maintenance only, R8).
+ * @param request The request.
+ * @returns True for scope "fleet".
+ */
+function isFleetScope(request) {
+    return bodyObject(request.body).scope === FLEET_SCOPE;
+}
+/**
+ * GET overview: the fleet at a glance (spec 2).
+ * @param services The shared services.
+ * @param request The request (its security decides consoleOverHttp).
+ * @returns The overview.
+ */
+async function buildOverview(services, request) {
+    const records = await services.fleet.listInstanceRecords();
+    const instances = records.map((record) => record.view);
+    const upRecords = records.filter((record) => record.view.status === "up");
+    const upInstances = upRecords.map((record) => record.view);
+    const rooms = await matchMaker.query({ name: SESSION_ROOM_NAME });
+    const gameModeTotals = totalsByGameMode(rooms);
+    return {
+        instancesUp: upInstances.length,
+        instancesLost: instances.length - upInstances.length,
+        players: sumOf(upInstances, (instance) => instance.players),
+        sessions: sumOf(upInstances, (instance) => instance.sessions),
+        playersByGameMode: gameModeTotals.players,
+        sessionsByGameMode: gameModeTotals.sessions,
+        dedicatedSessions: sumOf(upInstances, (instance) => instance.dedicatedSessions),
+        joinsPerMinute: sumOf(upRecords, (record) => perMinute(record, "joinsAccepted")),
+        refusalsPerMinute: sumOf(upRecords, (record) => perMinute(record, "joinsRefused")),
+        topRefusalReasons: topRefusalReasons(upRecords),
+        authFailuresPerMinute: sumOf(upRecords, (record) => perMinute(record, "authFailures")),
+        transportShare: transportShare(upInstances),
+        versions: versionsOf(upInstances),
+        certificateDaysLeft: soonestCertificateExpiry(upInstances),
+        redis: await redisStateOf(services),
+        maintenance: maintenanceSummary(upInstances),
+        draining: upInstances.filter((instance) => instance.draining).length,
+        scaledOut: services.fleet.isScaledOut,
+        warnings: computeHealthWarnings(services, instances, request.isSecure),
+        customPanels: services.extensions.panelViews("overview"),
+        activity: await services.audit.activity(OVERVIEW_ACTIVITY_COUNT)
+    };
+}
+/**
+ * GET instances/:processId: the instance, its sessions and its dedicated sessions.
+ * @param services The shared services.
+ * @param processId The instance.
+ * @returns The instance page.
+ * @throws AdminRequestError 404 for an unknown instance.
+ */
+async function describeInstance(services, processId) {
+    const instances = await services.fleet.listInstances();
+    const instance = instances.find((candidate) => candidate.processId === processId);
+    if (instance == null)
+        throw new AdminRequestError(HTTP_NOT_FOUND, "no such instance");
+    const sessions = (instance.status === "up") ? await services.fleet.runOn(processId, "describeSessions", null) : [];
+    // Dedicated session rows arrive with the dedicated sessions page (T9).
+    return { instance: instance, sessions: sessions, dedicated: [] };
+}
+/**
+ * POST instances/:processId/drain (DR §7.7).
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The drain deadline.
+ */
+async function drainInstance(services, request) {
+    const body = bodyObject(request.body);
+    const noticeText = noticeTextField(body, "noticeText");
+    const noticeLeadSeconds = (body.noticeLeadSeconds == null) ? 0 : nonNegativeNumberField(body, "noticeLeadSeconds");
+    const processId = request.params.processId;
+    const started = await services.fleet.runOn(processId, "drain", { noticeText: noticeText, noticeLeadSeconds: noticeLeadSeconds });
+    return { status: HTTP_OK, body: started, audit: { target: processId, parameters: { noticeText: noticeText, noticeLeadSeconds: noticeLeadSeconds } } };
+}
+/**
+ * The drain command on this instance (DR §7.7): the notice goes to every session first, the drain starts after
+ * noticeLeadSeconds, and drain keeps its one-way meaning. A second drain answers the running drain's deadline.
+ * @param services The shared services.
+ * @param request The notice and its lead time.
+ * @returns When the remaining sessions will be closed.
+ */
+async function drainThisInstance(services, request) {
+    const runningDeadline = services.routeContext.drainDeadline();
+    if (runningDeadline != null)
+        return { drainDeadline: runningDeadline };
+    const leadSeconds = Math.max(0, request.noticeLeadSeconds);
+    const closesInSeconds = leadSeconds + services.config.drainSeconds;
+    if (request.noticeText != null && request.noticeText !== "") {
+        sendLocalNotice(services.state, null, 0, createNoticePayload(services, request.noticeText, "warning", closesInSeconds));
+    }
+    if (leadSeconds === 0) {
+        startDrain(services);
+        return { drainDeadline: services.routeContext.drainDeadline() ?? isoAfter(services, closesInSeconds) };
+    }
+    services.clock.setTimeout(() => startDrain(services), leadSeconds * MILLISECONDS_PER_SECOND);
+    return { drainDeadline: isoAfter(services, closesInSeconds) };
+}
+/**
+ * Starts this instance's drain in the background; a failure is logged.
+ * @param services The shared services.
+ */
+function startDrain(services) {
+    services.serverEvents.record("drain started", services.processId());
+    services.routeContext.drain().catch((error) => getLogger().error("drain failed", { error: String(error) }));
+}
+/**
+ * GET maintenance (and the answer of PUT maintenance).
+ * @param services The shared services.
+ * @returns The fleet setting and each instance's maintenance.
+ */
+async function buildMaintenanceView(services) {
+    const stored = await services.store.getDocument("settings", MAINTENANCE_SETTINGS_ID);
+    const instances = await services.fleet.listInstances();
+    const rows = instances.map((instance) => ({
+        processId: instance.processId,
+        // This instance answers with its state now; the others with their last heartbeat.
+        maintenance: instance.isThisInstance ? services.maintenance.current() : instance.maintenance
+    }));
+    return { fleet: stored?.value ?? null, instances: rows, windows: await services.maintenanceWindows.list() };
+}
+/**
+ * PUT maintenance (DR §7.6): fleet scope stores the setting every instance applies (Redis only, after an optional
+ * warning notice); an instance scope sets that instance's own maintenance.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The maintenance view.
+ */
+async function setMaintenance(services, request) {
+    const body = bodyObject(request.body);
+    const scope = requiredText(body, "scope");
+    const enabled = booleanField(body, "enabled");
+    const settings = {
+        enabled: enabled,
+        message: noticeTextField(body, "message") ?? "",
+        allowUserIds: (body.allowUserIds == null) ? [] : stringListField(body, "allowUserIds"),
+        allowAddresses: (body.allowAddresses == null) ? [] : stringListField(body, "allowAddresses"),
+        leaveReadiness: (body.leaveReadiness == null) ? false : booleanField(body, "leaveReadiness")
+    };
+    const noticeSeconds = (body.noticeSeconds == null) ? null : nonNegativeNumberField(body, "noticeSeconds");
+    if (scope === FLEET_SCOPE)
+        await setFleetMaintenance(services, settings, noticeSeconds);
+    else
+        await setInstanceMaintenance(services, scope, settings);
+    const by = request.caller?.name ?? "unknown";
+    services.extensions.callHook("onMaintenanceChanged", { enabled: enabled, scope: scope, message: enabled ? settings.message : null, by: by });
+    const parameters = { ...settings, noticeSeconds: noticeSeconds };
+    return { status: HTTP_OK, body: await buildMaintenanceView(services), audit: { target: scope, parameters: parameters } };
+}
+/**
+ * Turns fleet maintenance on or off: stores (or deletes) settings/maintenance and announces it, so every instance
+ * applies it. This instance applies it at once, so the answer already shows it.
+ * @param services The shared services.
+ * @param settings The setting.
+ * @param noticeSeconds Seconds of warning notice sent to every player first, or null.
+ * @throws AdminRequestError 409 without Redis (R33).
+ */
+async function setFleetMaintenance(services, settings, noticeSeconds) {
+    requireScaledOut(services);
+    if (settings.enabled && noticeSeconds != null && noticeSeconds > 0) {
+        const notice = createNoticePayload(services, settings.message, "warning", noticeSeconds);
+        await services.fleet.runOnAll("sendNotice", { roomId: null, playerId: 0, notice: notice });
+    }
+    if (settings.enabled)
+        await services.store.putDocument("settings", MAINTENANCE_SETTINGS_ID, settings, null);
+    else
+        await services.store.deleteDocument("settings", MAINTENANCE_SETTINGS_ID);
+    await services.maintenance.reloadFleetSetting(services.store);
+    await services.fleet.announceChange("settings");
+    services.serverEvents.record(settings.enabled ? "maintenance on (fleet): " + settings.message : "maintenance off (fleet)", null);
+}
+/**
+ * Turns one instance's own maintenance on or off through the fleet bus.
+ * @param services The shared services.
+ * @param processId The instance.
+ * @param settings The setting.
+ */
+async function setInstanceMaintenance(services, processId, settings) {
+    if (!settings.enabled) {
+        await services.fleet.runOn(processId, "clearMaintenance", null);
+        return;
+    }
+    const maintenance = {
+        message: settings.message,
+        allowUserIds: settings.allowUserIds,
+        allowAddresses: settings.allowAddresses,
+        leaveReadiness: settings.leaveReadiness,
+        scope: "instance",
+        endsAt: null
+    };
+    await services.fleet.runOn(processId, "setMaintenance", maintenance);
+}
+/**
+ * Players and sessions per game mode across the fleet, from the matchmaker's listing.
+ * @param rooms The session rooms of every instance.
+ * @returns The totals, keyed by game mode name.
+ */
+function totalsByGameMode(rooms) {
+    const players = {};
+    const sessions = {};
+    for (const room of rooms) {
+        const gameMode = (typeof room.metadata?.gameMode === "string") ? room.metadata.gameMode : PENDING_GAME_MODE;
+        players[gameMode] = (players[gameMode] ?? 0) + room.clients;
+        sessions[gameMode] = (sessions[gameMode] ?? 0) + 1;
+    }
+    return { players: players, sessions: sessions };
+}
+/**
+ * A counter's per-minute rate between an instance's last two heartbeats (DR §8): never negative.
+ * @param record The instance with its earlier heartbeat.
+ * @param counter The counter.
+ * @returns The rate, or 0 without an earlier heartbeat.
+ */
+function perMinute(record, counter) {
+    return rateBetween(record.previous, record.view, (heartbeat) => heartbeat[counter]);
+}
+/**
+ * The per-minute rate of a value between two heartbeats; a drop (a restart) counts as 0.
+ * @param previous The earlier heartbeat, or null.
+ * @param current The newer heartbeat.
+ * @param read Reads the counter.
+ * @returns The rate per minute.
+ */
+function rateBetween(previous, current, read) {
+    if (previous == null)
+        return 0;
+    const seconds = (Date.parse(current.sentAt) - Date.parse(previous.sentAt)) / MILLISECONDS_PER_SECOND;
+    const growth = read(current) - read(previous);
+    if (seconds <= 0 || growth <= 0)
+        return 0;
+    return (growth / seconds) * SECONDS_PER_MINUTE;
+}
+/**
+ * The refusal reasons with the highest fleet rate.
+ * @param upRecords The live instances.
+ * @returns At most TOP_REFUSAL_REASON_COUNT reasons with a rate above 0, highest first.
+ */
+function topRefusalReasons(upRecords) {
+    const rates = new Map();
+    for (const record of upRecords) {
+        for (const reason of Object.keys(record.view.refusalsByReason)) {
+            const rate = rateBetween(record.previous, record.view, (heartbeat) => heartbeat.refusalsByReason[reason] ?? 0);
+            rates.set(reason, (rates.get(reason) ?? 0) + rate);
+        }
+    }
+    const reasons = Array.from(rates, ([reason, perMinuteRate]) => ({ reason: reason, perMinute: perMinuteRate }));
+    return reasons.filter((entry) => entry.perMinute > 0).sort((left, right) => right.perMinute - left.perMinute).slice(0, TOP_REFUSAL_REASON_COUNT);
+}
+/**
+ * The share of frames per transport across the fleet (fractions that add up to 1, or both 0 before any frame).
+ * @param upInstances The live instances.
+ * @returns The shares.
+ */
+function transportShare(upInstances) {
+    const websocket = sumOf(upInstances, (instance) => instance.framesWebsocket);
+    const webtransport = sumOf(upInstances, (instance) => instance.framesWebtransport);
+    const total = websocket + webtransport;
+    if (total === 0)
+        return { websocket: 0, webtransport: 0 };
+    return { websocket: websocket / total, webtransport: webtransport / total };
+}
+/**
+ * The server and protocol versions the live instances run.
+ * @param upInstances The live instances.
+ * @returns One row per version pair, with its instance count.
+ */
+function versionsOf(upInstances) {
+    const rows = new Map();
+    for (const instance of upInstances) {
+        const key = instance.serverVersion + "/" + instance.protocolVersion;
+        const row = rows.get(key) ?? { serverVersion: instance.serverVersion, protocolVersion: instance.protocolVersion, instances: 0 };
+        row.instances += 1;
+        rows.set(key, row);
+    }
+    return Array.from(rows.values());
+}
+/**
+ * The fewest certificate days left among the live instances.
+ * @param upInstances The live instances.
+ * @returns The days, or null when no instance serves TLS.
+ */
+function soonestCertificateExpiry(upInstances) {
+    const days = upInstances.map((instance) => instance.certificateDaysLeft).filter((value) => value != null);
+    return (days.length > 0) ? Math.min(...days) : null;
+}
+/**
+ * Whether Redis connects the fleet and answers.
+ * @param services The shared services.
+ * @returns "not configured", "reachable" or "unreachable".
+ */
+async function redisStateOf(services) {
+    if (services.config.redis.url == null)
+        return "not configured";
+    return (await services.routeContext.isRedisReachable()) ? "reachable" : "unreachable";
+}
+/**
+ * Which maintenance is in force across the live instances.
+ * @param upInstances The live instances.
+ * @returns "fleet", "some instances" or "off".
+ */
+function maintenanceSummary(upInstances) {
+    if (upInstances.some((instance) => instance.maintenance?.scope === "fleet"))
+        return "fleet";
+    if (upInstances.some((instance) => instance.maintenance != null))
+        return "some instances";
+    return "off";
+}
+/**
+ * Sums a value over items.
+ * @param items The items.
+ * @param read Reads each item's value.
+ * @returns The sum.
+ */
+function sumOf(items, read) {
+    return items.reduce((total, item) => total + read(item), 0);
+}
+/**
+ * An ISO time some seconds from the admin clock's now.
+ * @param services The shared services.
+ * @param seconds Seconds from now.
+ * @returns The ISO time.
+ */
+function isoAfter(services, seconds) {
+    return new Date(services.clock.now() + seconds * MILLISECONDS_PER_SECOND).toISOString();
+}
+/**
+ * A required non-empty text field.
+ * @param body The body.
+ * @param name The field.
+ * @returns The text.
+ * @throws AdminRequestError 400 when it is missing or empty.
+ */
+function requiredText(body, name) {
+    const value = optionalStringField(body, name);
+    if (value == null || value === "")
+        throw new AdminRequestError(HTTP_BAD_REQUEST, name + " must be text");
+    return value;
+}

package/lib/admin/HealthWarnings.d.ts

@@ -0,0 +1,10 @@
+import type { HealthWarningView, InstanceView } from "./AdminApiTypes.js";
+import type { AdminServices } from "./AdminServices.js";
+/**
+ * The health warnings of the fleet as the requesting console sees it.
+ * @param services The shared services.
+ * @param instances Every known instance.
+ * @param requestIsSecure True when the console request arrived over TLS (R9).
+ * @returns The warnings, most severe first.
+ */
+export declare function computeHealthWarnings(services: AdminServices, instances: InstanceView[], requestIsSecure: boolean): HealthWarningView[];

package/lib/admin/HealthWarnings.js

@@ -0,0 +1,95 @@
+// The overview's health warnings (game-server-admin-console spec 2, DR §6.11 HealthWarningView, DR §9): each names a
+// risky setting or a fleet problem and the console page that fixes it.
+import { isProductionEnvironment } from "../GameServerConfig.js";
+/** Fewer days than this before a certificate expires raises certificateExpiring (DR §8 alert default). */
+const CERTIFICATE_WARNING_DAYS = 14;
+/** Console route of the instances page. */
+const INSTANCES_ROUTE = "#/instances";
+/**
+ * The health warnings of the fleet as the requesting console sees it.
+ * @param services The shared services.
+ * @param instances Every known instance.
+ * @param requestIsSecure True when the console request arrived over TLS (R9).
+ * @returns The warnings, most severe first.
+ */
+export function computeHealthWarnings(services, instances, requestIsSecure) {
+    const upInstances = instances.filter((instance) => instance.status === "up");
+    const candidates = [
+        authOffWarning(services),
+        lostInstanceWarning(instances),
+        originsOpenWarning(services),
+        metricsWarning(services),
+        requestIsSecure ? null : { code: "consoleOverHttp", severity: "warning", message: "this console is open over plain HTTP; serve it over HTTPS", fixRoute: "#/config?path=tls.enabled" },
+        certificateWarning(upInstances),
+        mixedVersionsWarning(upInstances),
+        services.store.isPersistent ? null : { code: "storeNotPersistent", severity: "warning", message: "admin data is stored inside the container and will be lost on restart", fixRoute: "#/config?path=admin.dataDir" }
+    ];
+    return candidates.filter((warning) => warning != null);
+}
+/**
+ * authOffInProduction: NODE_ENV=production with player authentication off.
+ * @param services The shared services.
+ * @returns The warning, or null.
+ */
+function authOffWarning(services) {
+    if (!isProductionEnvironment(process.env) || services.config.auth.enabled)
+        return null;
+    return { code: "authOffInProduction", severity: "critical", message: "player authentication is off on a production server", fixRoute: "#/config?path=auth.enabled" };
+}
+/**
+ * instanceLost: an instance stopped sending heartbeats.
+ * @param instances Every known instance.
+ * @returns The warning, or null.
+ */
+function lostInstanceWarning(instances) {
+    const lostCount = instances.filter((instance) => instance.status === "lost").length;
+    if (lostCount === 0)
+        return null;
+    return { code: "instanceLost", severity: "critical", message: lostCount + " instance(s) stopped sending heartbeats", fixRoute: INSTANCES_ROUTE };
+}
+/**
+ * originsOpen: limits.allowedOrigins is empty, so any website can connect players.
+ * @param services The shared services.
+ * @returns The warning, or null.
+ */
+function originsOpenWarning(services) {
+    if (services.config.limits.allowedOrigins.length > 0)
+        return null;
+    return { code: "originsOpen", severity: "warning", message: "any website can connect players to this server; list your game's origins", fixRoute: "#/config?path=limits.allowedOrigins" };
+}
+/**
+ * metricsUnprotected: the Prometheus endpoint is on and needs no admin token.
+ * @param services The shared services.
+ * @returns The warning, or null.
+ */
+function metricsWarning(services) {
+    if (!services.config.metrics.enabled || services.config.metrics.requireAdminToken)
+        return null;
+    return { code: "metricsUnprotected", severity: "warning", message: "the Prometheus metrics at /metrics are open to anyone", fixRoute: "#/config?path=metrics.requireAdminToken" };
+}
+/**
+ * certificateExpiring: an up instance's certificate has fewer than CERTIFICATE_WARNING_DAYS days left.
+ * @param upInstances The live instances.
+ * @returns The warning, or null.
+ */
+function certificateWarning(upInstances) {
+    const daysLeft = upInstances.map((instance) => instance.certificateDaysLeft).filter((days) => days != null);
+    if (daysLeft.length === 0)
+        return null;
+    const soonest = Math.min(...daysLeft);
+    if (soonest >= CERTIFICATE_WARNING_DAYS)
+        return null;
+    const message = (soonest < 0) ? "a TLS certificate has expired" : "a TLS certificate expires in " + soonest + " day(s)";
+    return { code: "certificateExpiring", severity: (soonest < 0) ? "critical" : "warning", message: message, fixRoute: INSTANCES_ROUTE };
+}
+/**
+ * mixedVersions: the live instances run more than one server version.
+ * @param upInstances The live instances.
+ * @returns The warning, or null.
+ */
+function mixedVersionsWarning(upInstances) {
+    const versions = new Set(upInstances.map((instance) => instance.serverVersion));
+    if (versions.size <= 1)
+        return null;
+    return { code: "mixedVersions", severity: "warning", message: "instances run different server versions: " + Array.from(versions).join(", "), fixRoute: INSTANCES_ROUTE };
+}

package/lib/admin/LeaderboardRoutes.d.ts

@@ -0,0 +1,8 @@
+import type { AdminApiRouter } from "./AdminApiRouter.js";
+import type { AdminServices } from "./AdminServices.js";
+/**
+ * Registers every leaderboards/* route (DR §6 admin table).
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export declare function registerLeaderboardRoutes(router: AdminApiRouter, services: AdminServices): void;