@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/admin/LogBuffer.js

@@ -0,0 +1,92 @@
+// The recent log lines of one instance (game-server-admin-console D21, DR §6.8): a fixed-size in-memory ring the
+// logger feeds through a sink, redacted at capture, read by the console's live tail and search. Nothing goes to disk.
+import { redactLogFields, redactLogMessage } from "./LogRedaction.js";
+/** Fields that hold a client's address, removed for callers without players.viewAddresses. */
+const ADDRESS_FIELDS = ["clientAddress", "address"];
+/** Severity of each level: an entry matches a level filter when its rank is at most the filter's (error 0 … debug 3). */
+const LEVEL_RANK = { error: 0, warn: 1, info: 2, debug: 3 };
+/** The in-memory log buffer of this instance. */
+export class LogBuffer {
+    /** The logger sink that captures into this buffer (add it with GameServerLogger.addSink). */
+    sink = (level, message, fields) => this.capture(level, message, fields);
+    /** The entries, oldest first. */
+    entries = [];
+    /** How many entries are kept. */
+    capacity;
+    /** The sequence of the newest entry (0 before any). */
+    newestSequence = 0;
+    /**
+     * Creates an empty buffer.
+     * @param capacity How many entries are kept (admin.logBufferEntries); the oldest are dropped first.
+     */
+    constructor(capacity) {
+        this.capacity = Math.max(1, capacity);
+    }
+    /** The sequence of the newest entry, 0 before any. */
+    get latestSequence() {
+        return this.newestSequence;
+    }
+    /**
+     * 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, message, fields) {
+        this.newestSequence += 1;
+        this.entries.push({ sequence: this.newestSequence, time: new Date().toISOString(), level: level, message: redactLogMessage(message), fields: redactLogFields(fields) });
+        if (this.entries.length > this.capacity)
+            this.entries.shift();
+    }
+    /**
+     * 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, afterSequence, limit) {
+        const matches = entryFilter(filter);
+        const found = this.entries.filter((entry) => entry.sequence > afterSequence && matches(entry));
+        const kept = (afterSequence > 0) ? found.slice(0, limit) : found.slice(Math.max(0, found.length - limit));
+        return kept.map((entry) => structuredClone(entry));
+    }
+}
+/**
+ * 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 function toLogEntryView(entry, processId, includeAddresses) {
+    const fields = Object.assign({}, entry.fields);
+    if (!includeAddresses)
+        for (const field of ADDRESS_FIELDS)
+            delete fields[field];
+    return { sequence: entry.sequence, time: entry.time, level: entry.level, message: entry.message, fields: fields, processId: processId };
+}
+/**
+ * The test of a log filter.
+ * @param filter The filter.
+ * @returns True for the entries it keeps.
+ */
+function entryFilter(filter) {
+    const text = (filter.text != null && filter.text !== "") ? filter.text.toLowerCase() : null;
+    return (entry) => {
+        if (filter.level != null && LEVEL_RANK[entry.level] > LEVEL_RANK[filter.level])
+            return false;
+        if (filter.roomId != null && entry.fields.roomId !== filter.roomId)
+            return false;
+        if (filter.sessionName != null && entry.fields.sessionName !== filter.sessionName)
+            return false;
+        if (filter.playerId != null && entry.fields.playerId !== filter.playerId)
+            return false;
+        if (filter.userId != null && entry.fields.userId !== filter.userId)
+            return false;
+        if (text == null)
+            return true;
+        return entry.message.toLowerCase().includes(text) || JSON.stringify(entry.fields).toLowerCase().includes(text);
+    };
+}

package/lib/admin/LogRedaction.d.ts

@@ -0,0 +1,15 @@
+/** The text that replaces a secret. */
+export declare const REDACTED_TEXT: string;
+/**
+ * Removes secrets from a log message.
+ * @param message The message.
+ * @returns The message with every secret pattern replaced by "[redacted]".
+ */
+export declare function redactLogMessage(message: string): string;
+/**
+ * Removes secrets from log fields: a field whose name looks secret becomes "[redacted]" (except the DR §6.8 names),
+ * and text anywhere inside the values is redacted like a message.
+ * @param fields The fields.
+ * @returns A redacted copy.
+ */
+export declare function redactLogFields(fields: Record<string, unknown>): Record<string, unknown>;

package/lib/admin/LogRedaction.js

@@ -0,0 +1,72 @@
+// Redaction of captured log entries (game-server-admin-console D21, DR §6.8): secrets never reach the console's log
+// buffer, whichever code logged them.
+/** The text that replaces a secret. */
+export const REDACTED_TEXT = "[redacted]";
+/** Field names that hold secrets. */
+const SECRET_FIELD_PATTERN = /(token|secret|password|passcode|code|key|authorization|cookie|pem|credential)/i;
+/** Fields whose names look secret but are not (DR §6.8). */
+const SAFE_FIELD_NAMES = new Set(["roomId", "sessionName", "playerId", "userId", "clientAddress", "reasonName", "statusCode"]);
+/** Secret patterns inside text: API keys, bearer credentials and PEM blocks (DR §6.8). */
+const SECRET_TEXT_PATTERNS = [
+    /bgsk_[A-Za-z0-9_-]+/g,
+    /Bearer\s+\S+/gi,
+    /-----BEGIN [^-]+-----[\s\S]*?-----END [^-]+-----/g
+];
+/**
+ * Secret values in URL query or hash parameters (the first-owner setup link carries its token so). The logger still
+ * writes the link to the server's own output; only the console's copy is redacted.
+ */
+const SECRET_URL_PARAMETER_PATTERN = /([?&#](?:token|secret|password|code|key)=)[^&#\s"]+/gi;
+/** How deep nested field values are searched; anything deeper is replaced whole. */
+const MAXIMUM_FIELD_DEPTH = 8;
+/**
+ * Removes secrets from a log message.
+ * @param message The message.
+ * @returns The message with every secret pattern replaced by "[redacted]".
+ */
+export function redactLogMessage(message) {
+    let redacted = message;
+    for (const pattern of SECRET_TEXT_PATTERNS)
+        redacted = redacted.replace(pattern, REDACTED_TEXT);
+    return redacted.replace(SECRET_URL_PARAMETER_PATTERN, "$1" + REDACTED_TEXT);
+}
+/**
+ * Removes secrets from log fields: a field whose name looks secret becomes "[redacted]" (except the DR §6.8 names),
+ * and text anywhere inside the values is redacted like a message.
+ * @param fields The fields.
+ * @returns A redacted copy.
+ */
+export function redactLogFields(fields) {
+    return redactObject(fields, 0);
+}
+/**
+ * Redacts one object's fields.
+ * @param fields The object.
+ * @param depth How deep it sits in the entry.
+ * @returns A redacted copy.
+ */
+function redactObject(fields, depth) {
+    const redacted = {};
+    for (const [name, value] of Object.entries(fields)) {
+        const isSecretName = SECRET_FIELD_PATTERN.test(name) && !SAFE_FIELD_NAMES.has(name);
+        redacted[name] = isSecretName ? REDACTED_TEXT : redactValue(value, depth + 1);
+    }
+    return redacted;
+}
+/**
+ * Redacts one field value.
+ * @param value The value.
+ * @param depth How deep it sits in the entry.
+ * @returns A redacted copy.
+ */
+function redactValue(value, depth) {
+    if (typeof value === "string")
+        return redactLogMessage(value);
+    if (value == null || typeof value !== "object")
+        return value;
+    if (depth > MAXIMUM_FIELD_DEPTH)
+        return REDACTED_TEXT;
+    if (Array.isArray(value))
+        return value.map((item) => redactValue(item, depth + 1));
+    return redactObject(value, depth);
+}

package/lib/admin/LogRoutes.d.ts

@@ -0,0 +1,45 @@
+import { type AdminApiRouter } from "./AdminApiRouter.js";
+import type { AdminLogLevel } from "./AdminApiTypes.js";
+import type { AdminCoreServices, AdminServices } from "./AdminServices.js";
+/** The settings document of a fleet-wide temporary level, which instances that start later apply. */
+export declare const LOG_LEVEL_SETTINGS_ID: string;
+/**
+ * A temporary log level on this instance (D21): it replaces the configured level until a timer puts the configured one
+ * back and logs "log level reverted".
+ */
+export declare class TemporaryLogLevel {
+    /** The shared core services. */
+    private readonly services;
+    /** The pending revert, or null. */
+    private revertTimer;
+    /**
+     * Prepares the control; nothing changes until set() or applyStored().
+     * @param services The shared core services.
+     */
+    constructor(services: AdminCoreServices);
+    /**
+     * Sets a temporary level, replacing any earlier one.
+     * @param level The level.
+     * @param revertAfterMinutes Minutes until the configured level comes back (more than 0).
+     */
+    set(level: AdminLogLevel, revertAfterMinutes: number): void;
+    /** Applies a stored fleet-wide level that has not expired yet (an instance that starts during one). */
+    applyStored(): Promise<void>;
+    /** Cancels the pending revert (the console stops); the level stays as it is. */
+    stop(): void;
+    /** Puts the configured level back and logs it. */
+    private revert;
+    /** Clears the pending revert timer. */
+    private cancelRevert;
+}
+/**
+ * Registers the logs, logs/download and logs/level routes.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export declare function registerLogRoutes(router: AdminApiRouter, services: AdminServices): void;
+/**
+ * Registers this instance's readLogs and setLogLevel fleet commands (R15).
+ * @param services The shared services.
+ */
+export declare function registerLogCommands(services: AdminServices): void;

package/lib/admin/LogRoutes.js

@@ -0,0 +1,307 @@
+// The log routes (game-server-admin-console DR §6.11 logs rows, D21): live tail and search across the fleet with a
+// per-instance cursor, the JSON-lines download and the temporary log level, plus this instance's readLogs and
+// setLogLevel fleet commands (R15) and the timer that puts a temporary level back.
+import { getLogger } from "../GameServerLogger.js";
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { DEFAULT_LOG_LEVEL_REVERT_MINUTES } from "./AdminConstants.js";
+import { bodyObject, numberField, stringField } from "./AdminRequestBodies.js";
+import { toLogEntryView } from "./LogBuffer.js";
+import { canViewAddresses } from "./SessionRoutes.js";
+/** HTTP status of a successful read or change. */
+const HTTP_OK = 200;
+/** HTTP status of an invalid query or body. */
+const HTTP_BAD_REQUEST = 400;
+/** The settings document of a fleet-wide temporary level, which instances that start later apply. */
+export const LOG_LEVEL_SETTINGS_ID = "logLevel";
+/** The levels the API accepts. */
+const LOG_LEVELS = new Set(["error", "warn", "info", "debug"]);
+/** Entries one GET logs answers with when the query does not say. */
+const DEFAULT_PAGE_LIMIT = 200;
+/** The most entries one GET logs answers with. */
+const MAXIMUM_PAGE_LIMIT = 1000;
+/** The scope value of the whole fleet. */
+const FLEET_SCOPE = "fleet";
+/** Milliseconds per minute. */
+const MILLISECONDS_PER_MINUTE = 60000;
+/** The download's content type (one JSON object per line). */
+const JSON_LINES_CONTENT_TYPE = "application/x-ndjson";
+/** The download's file name. */
+const DOWNLOAD_FILE_NAME = "logs.jsonl";
+/**
+ * A temporary log level on this instance (D21): it replaces the configured level until a timer puts the configured one
+ * back and logs "log level reverted".
+ */
+export class TemporaryLogLevel {
+    /** The shared core services. */
+    services;
+    /** The pending revert, or null. */
+    revertTimer = null;
+    /**
+     * Prepares the control; nothing changes until set() or applyStored().
+     * @param services The shared core services.
+     */
+    constructor(services) {
+        this.services = services;
+    }
+    /**
+     * Sets a temporary level, replacing any earlier one.
+     * @param level The level.
+     * @param revertAfterMinutes Minutes until the configured level comes back (more than 0).
+     */
+    set(level, revertAfterMinutes) {
+        this.cancelRevert();
+        getLogger().setLevel(level);
+        this.revertTimer = this.services.clock.setTimeout(() => this.revert(), revertAfterMinutes * MILLISECONDS_PER_MINUTE);
+    }
+    /** Applies a stored fleet-wide level that has not expired yet (an instance that starts during one). */
+    async applyStored() {
+        const stored = await this.services.store.getDocument("settings", LOG_LEVEL_SETTINGS_ID);
+        if (stored == null)
+            return;
+        const remainingMilliseconds = Date.parse(stored.value.until) - this.services.clock.now();
+        if (!(remainingMilliseconds > 0))
+            return;
+        this.cancelRevert();
+        getLogger().setLevel(stored.value.level);
+        this.revertTimer = this.services.clock.setTimeout(() => this.revert(), remainingMilliseconds);
+    }
+    /** Cancels the pending revert (the console stops); the level stays as it is. */
+    stop() {
+        this.cancelRevert();
+    }
+    /** Puts the configured level back and logs it. */
+    revert() {
+        this.revertTimer = null;
+        getLogger().setLevel(this.services.state.config.logLevel);
+        getLogger().info("log level reverted", { level: this.services.state.config.logLevel });
+    }
+    /** Clears the pending revert timer. */
+    cancelRevert() {
+        if (this.revertTimer != null)
+            this.services.clock.clearTimeout(this.revertTimer);
+        this.revertTimer = null;
+    }
+}
+/**
+ * Registers the logs, logs/download and logs/level routes.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export function registerLogRoutes(router, services) {
+    const routes = [
+        { method: "GET", pattern: "logs", permission: "logs.view", requiresStepUp: false, auditAction: null, handler: async (request) => ({ status: HTTP_OK, body: await readLogPage(services, request, MAXIMUM_PAGE_LIMIT) }) },
+        { method: "GET", pattern: "logs/download", permission: "logs.view", requiresStepUp: false, auditAction: "logs.download", handler: async (request) => downloadLogs(services, request) },
+        { method: "PUT", pattern: "logs/level", permission: "logs.manage", requiresStepUp: false, auditAction: "logs.level", handler: async (request) => setLogLevel(services, request) }
+    ];
+    for (const route of routes)
+        router.register(route);
+}
+/**
+ * Registers this instance's readLogs and setLogLevel fleet commands (R15).
+ * @param services The shared services.
+ */
+export function registerLogCommands(services) {
+    services.fleet.handle("readLogs", async (command) => {
+        const entries = services.state.logBuffer?.read(command.filter, command.afterSequence, command.limit) ?? [];
+        return entries.map((entry) => toLogEntryView(entry, services.fleet.localProcessId, true));
+    });
+    services.fleet.handle("setLogLevel", async (command) => {
+        services.temporaryLogLevel.set(command.level, command.revertAfterMinutes);
+        return null;
+    });
+}
+/**
+ * GET logs: the matching entries of one instance or of the fleet, merged by time, with the cursor of the next read.
+ * @param services The shared services.
+ * @param request The request.
+ * @param maximumLimit The most entries the query may ask for.
+ * @returns The page.
+ */
+async function readLogPage(services, request, maximumLimit) {
+    const filter = logFilterOf(request.query);
+    const cursor = cursorOf(request.query.get("after"));
+    const limit = limitOf(request.query.get("limit"), maximumLimit);
+    const processId = request.query.get("processId") ?? FLEET_SCOPE;
+    const entries = (processId === FLEET_SCOPE || processId === "")
+        ? await readFleetLogs(services, filter, cursor, limit)
+        : await services.fleet.runOn(processId, "readLogs", { filter: filter, afterSequence: cursor[processId] ?? 0, limit: limit });
+    entries.sort(compareEntries);
+    // With a cursor the oldest new entries come first, so a tail misses nothing; a first read shows the newest.
+    const hasCursor = Object.keys(cursor).length > 0;
+    const kept = hasCursor ? entries.slice(0, limit) : entries.slice(Math.max(0, entries.length - limit));
+    const includeAddresses = canViewAddresses(request);
+    return { entries: kept.map((entry) => toLogEntryView(entry, entry.processId, includeAddresses)), cursor: encodeCursor(advanceCursor(cursor, kept)) };
+}
+/**
+ * Reads every live instance's matching entries, each after its own cursor; instances that fail are left out.
+ * @param services The shared services.
+ * @param filter What to keep.
+ * @param cursor Each instance's newest sequence seen.
+ * @param limit The most entries per instance.
+ * @returns The entries, unsorted.
+ */
+async function readFleetLogs(services, filter, cursor, limit) {
+    const processIds = [services.fleet.localProcessId];
+    for (const instance of await services.fleet.listInstances())
+        if (instance.status === "up" && !processIds.includes(instance.processId))
+            processIds.push(instance.processId);
+    const pages = await Promise.all(processIds.map(async (processId) => {
+        try {
+            return await services.fleet.runOn(processId, "readLogs", { filter: filter, afterSequence: cursor[processId] ?? 0, limit: limit });
+        }
+        catch (error) {
+            // An instance that does not answer is left out of this read; the next poll asks it again.
+            if (error instanceof AdminRequestError)
+                return [];
+            throw error;
+        }
+    }));
+    return pages.flat();
+}
+/**
+ * GET logs/download: the same read as GET logs, up to the whole buffer, as a JSON-lines file.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The download.
+ */
+async function downloadLogs(services, request) {
+    const page = await readLogPage(services, request, services.config.admin.logBufferEntries);
+    const text = page.entries.map((entry) => JSON.stringify(entry) + "\n").join("");
+    const bytes = new TextEncoder().encode(text);
+    return {
+        status: HTTP_OK,
+        body: null,
+        download: { bytes: bytes, contentType: JSON_LINES_CONTENT_TYPE, fileName: DOWNLOAD_FILE_NAME },
+        audit: { target: request.query.get("processId") ?? FLEET_SCOPE, parameters: { entries: page.entries.length, filter: Object.assign({}, logFilterOf(request.query)) } }
+    };
+}
+/**
+ * PUT logs/level: a temporary level on one instance or the fleet; a fleet level is also stored, so instances that
+ * start before it reverts apply it too.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns ok.
+ * @throws AdminRequestError 400 for an unknown level or a revert time that is not more than 0.
+ */
+async function setLogLevel(services, request) {
+    const body = bodyObject(request.body);
+    const scope = stringField(body, "scope");
+    const level = levelOf(stringField(body, "level"));
+    const revertAfterMinutes = (body.revertAfterMinutes == null) ? DEFAULT_LOG_LEVEL_REVERT_MINUTES : numberField(body, "revertAfterMinutes");
+    if (!(revertAfterMinutes > 0))
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "revertAfterMinutes must be more than 0");
+    const command = { level: level, revertAfterMinutes: revertAfterMinutes };
+    if (scope === FLEET_SCOPE) {
+        const until = new Date(services.clock.now() + revertAfterMinutes * MILLISECONDS_PER_MINUTE).toISOString();
+        await services.store.putDocument("settings", LOG_LEVEL_SETTINGS_ID, { level: level, until: until }, null);
+        const outcome = await services.fleet.runOnAll("setLogLevel", command);
+        return { status: HTTP_OK, body: { ok: true }, audit: { target: FLEET_SCOPE, parameters: { level: level, revertAfterMinutes: revertAfterMinutes, failedInstances: outcome.failures.length } } };
+    }
+    await services.fleet.runOn(scope, "setLogLevel", command);
+    return { status: HTTP_OK, body: { ok: true }, audit: { target: scope, parameters: { level: level, revertAfterMinutes: revertAfterMinutes } } };
+}
+/**
+ * The filter of a logs query (level, roomId, sessionName, playerId, userId, text).
+ * @param query The query.
+ * @returns The filter.
+ * @throws AdminRequestError 400 for an unknown level or a playerId that is not a whole number.
+ */
+function logFilterOf(query) {
+    const filter = {};
+    const level = query.get("level");
+    if (level != null && level !== "")
+        filter.level = levelOf(level);
+    const playerId = query.get("playerId");
+    if (playerId != null && playerId !== "") {
+        const parsedPlayerId = Number(playerId);
+        if (!Number.isInteger(parsedPlayerId))
+            throw new AdminRequestError(HTTP_BAD_REQUEST, "playerId must be a whole number");
+        filter.playerId = parsedPlayerId;
+    }
+    for (const field of ["roomId", "sessionName", "userId", "text"]) {
+        const value = query.get(field);
+        if (value != null && value !== "")
+            filter[field] = value;
+    }
+    return filter;
+}
+/**
+ * A level name of a query or body.
+ * @param text The text.
+ * @returns The level.
+ * @throws AdminRequestError 400 for anything but error, warn, info or debug.
+ */
+function levelOf(text) {
+    if (!LOG_LEVELS.has(text))
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "level must be error, warn, info or debug");
+    return text;
+}
+/**
+ * The entry limit of a query.
+ * @param text The limit query value, or null.
+ * @param maximumLimit The largest limit allowed.
+ * @returns The limit (DEFAULT_PAGE_LIMIT when missing, capped at maximumLimit).
+ * @throws AdminRequestError 400 when it is not a whole number of at least 1.
+ */
+function limitOf(text, maximumLimit) {
+    if (text == null || text === "")
+        return Math.min(DEFAULT_PAGE_LIMIT, maximumLimit);
+    const limit = Number(text);
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "limit must be a whole number of at least 1");
+    return Math.min(limit, maximumLimit);
+}
+/**
+ * Decodes a GET logs cursor.
+ * @param text The after query value, or null.
+ * @returns Each instance's newest sequence seen (empty for a first read).
+ * @throws AdminRequestError 400 when it is not a cursor this API made.
+ */
+function cursorOf(text) {
+    if (text == null || text === "")
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(text, "base64url").toString("utf8"));
+    }
+    catch {
+        parsed = null;
+    }
+    const isCursor = parsed != null && typeof parsed === "object" && !Array.isArray(parsed) && Object.values(parsed).every((value) => Number.isInteger(value));
+    if (!isCursor)
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "after must be the cursor of an earlier answer");
+    return parsed;
+}
+/**
+ * Encodes a GET logs cursor.
+ * @param cursor Each instance's newest sequence seen.
+ * @returns The base64url JSON text.
+ */
+function encodeCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+/**
+ * Moves a cursor past the entries a reader got.
+ * @param cursor The cursor of the read.
+ * @param entries The entries returned.
+ * @returns The new cursor.
+ */
+function advanceCursor(cursor, entries) {
+    const advanced = Object.assign({}, cursor);
+    for (const entry of entries)
+        advanced[entry.processId] = Math.max(advanced[entry.processId] ?? 0, entry.sequence);
+    return advanced;
+}
+/**
+ * Orders entries by time, then instance, then sequence.
+ * @param left The first entry.
+ * @param right The second entry.
+ * @returns Negative, zero or positive.
+ */
+function compareEntries(left, right) {
+    if (left.time !== right.time)
+        return left.time.localeCompare(right.time);
+    if (left.processId !== right.processId)
+        return left.processId.localeCompare(right.processId);
+    return left.sequence - right.sequence;
+}

package/lib/admin/MaintenanceMode.d.ts

@@ -0,0 +1,41 @@
+import type { GameServerStateValues } from "../GameServerState.js";
+import type { MaintenanceSettings, MaintenanceState } from "./AdminApiTypes.js";
+import type { AdminStore } from "./AdminStore.js";
+/** The settings document that holds the fleet maintenance (collection "settings"). */
+export declare const MAINTENANCE_SETTINGS_ID: string;
+/** Decides which maintenance is in force on this instance and publishes it to the server state. */
+export declare class MaintenanceMode {
+    /** The server state whose maintenance field this class owns. */
+    private readonly state;
+    /** The stored fleet setting while it is enabled, else null. */
+    private fleetSetting;
+    /** Maintenance set for this instance only, else null. */
+    private instanceState;
+    /**
+     * Starts with no maintenance in force.
+     * @param state The server state the join gate reads.
+     */
+    constructor(state: GameServerStateValues);
+    /**
+     * Applies the stored fleet setting; a disabled or missing setting ends fleet maintenance.
+     * @param settings The setting, or null when the document does not exist.
+     */
+    applyFleetSetting(settings: MaintenanceSettings | null): void;
+    /**
+     * Sets or clears this instance's own maintenance. An enabled fleet setting still wins over a clear.
+     * @param maintenance The maintenance, or null to clear it.
+     */
+    setInstance(maintenance: MaintenanceState | null): void;
+    /**
+     * The maintenance in force: the enabled fleet setting, else this instance's own, else none.
+     * @returns The maintenance, or null.
+     */
+    current(): MaintenanceState | null;
+    /**
+     * Reads the stored fleet setting again and applies it (at start, and on every "settings" change announcement).
+     * @param store The admin data store.
+     */
+    reloadFleetSetting(store: AdminStore): Promise<void>;
+    /** Puts the maintenance in force where the join gate and readiness read it. */
+    private publish;
+}

package/lib/admin/MaintenanceMode.js

@@ -0,0 +1,74 @@
+// Maintenance mode of one instance (game-server-admin-console D14, DR §7.6): the stored fleet setting every instance
+// applies, and a per-instance state that lives in memory until a restart. The join gate reads the result from
+// state.maintenance.
+/** The settings document that holds the fleet maintenance (collection "settings"). */
+export const MAINTENANCE_SETTINGS_ID = "maintenance";
+/** Decides which maintenance is in force on this instance and publishes it to the server state. */
+export class MaintenanceMode {
+    /** The server state whose maintenance field this class owns. */
+    state;
+    /** The stored fleet setting while it is enabled, else null. */
+    fleetSetting = null;
+    /** Maintenance set for this instance only, else null. */
+    instanceState = null;
+    /**
+     * Starts with no maintenance in force.
+     * @param state The server state the join gate reads.
+     */
+    constructor(state) {
+        this.state = state;
+        this.publish();
+    }
+    /**
+     * Applies the stored fleet setting; a disabled or missing setting ends fleet maintenance.
+     * @param settings The setting, or null when the document does not exist.
+     */
+    applyFleetSetting(settings) {
+        this.fleetSetting = (settings != null && settings.enabled) ? settings : null;
+        this.publish();
+    }
+    /**
+     * Sets or clears this instance's own maintenance. An enabled fleet setting still wins over a clear.
+     * @param maintenance The maintenance, or null to clear it.
+     */
+    setInstance(maintenance) {
+        this.instanceState = (maintenance != null) ? Object.assign({}, maintenance, { scope: "instance" }) : null;
+        this.publish();
+    }
+    /**
+     * The maintenance in force: the enabled fleet setting, else this instance's own, else none.
+     * @returns The maintenance, or null.
+     */
+    current() {
+        if (this.fleetSetting != null)
+            return fleetMaintenanceOf(this.fleetSetting);
+        return this.instanceState;
+    }
+    /**
+     * Reads the stored fleet setting again and applies it (at start, and on every "settings" change announcement).
+     * @param store The admin data store.
+     */
+    async reloadFleetSetting(store) {
+        const stored = await store.getDocument("settings", MAINTENANCE_SETTINGS_ID);
+        this.applyFleetSetting(stored?.value ?? null);
+    }
+    /** Puts the maintenance in force where the join gate and readiness read it. */
+    publish() {
+        this.state.maintenance = this.current();
+    }
+}
+/**
+ * The maintenance state of an enabled fleet setting.
+ * @param settings The stored setting.
+ * @returns The state, scope "fleet".
+ */
+function fleetMaintenanceOf(settings) {
+    return {
+        message: settings.message,
+        allowUserIds: settings.allowUserIds.slice(),
+        allowAddresses: settings.allowAddresses.slice(),
+        leaveReadiness: settings.leaveReadiness,
+        scope: "fleet",
+        endsAt: null
+    };
+}