@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/admin/AdminResponses.js

@@ -0,0 +1,164 @@
+// Response building of the console and its API (game-server-admin-console D5, D9, DR §7.3). The router's Node writer
+// ends after the first chunk, so every answer is one in-memory buffer with content-length and connection: close.
+/** Session cookie name over TLS (D10): the __Host- prefix pins it to this host, path / and Secure. */
+export const SECURE_SESSION_COOKIE_NAME = "__Host-bgs-admin";
+/** Session cookie name on loopback HTTP (D10). */
+export const SESSION_COOKIE_NAME = "bgs-admin";
+/** HTTP status of a served file. */
+const HTTP_OK = 200;
+/** HTTP status of an API redirect (SSO). */
+const HTTP_FOUND = 302;
+/** HTTP status of the console's trailing-slash redirect. */
+const HTTP_PERMANENT_REDIRECT = 308;
+/** Content type of every JSON answer. */
+const JSON_CONTENT_TYPE = "application/json; charset=utf-8";
+/** Content type of every plain-text answer. */
+const TEXT_CONTENT_TYPE = "text/plain; charset=utf-8";
+/** Headers on every console response (D9). */
+export const SECURITY_HEADERS = {
+    "content-security-policy": "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self'; font-src 'self'; object-src 'none'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'",
+    "x-frame-options": "DENY",
+    "x-content-type-options": "nosniff",
+    "referrer-policy": "no-referrer",
+    "cross-origin-opener-policy": "same-origin"
+};
+/**
+ * Builds the single-buffer answer of an API call (DR §7.3): JSON, a download, or a redirect, with the D9 headers, the
+ * console origin as the only CORS origin (credentials off, overriding the router's CORS answer) and each cookie.
+ * @param result The handler's result.
+ * @param request The console origin of the request.
+ * @returns The response.
+ */
+export function buildAdminResponse(result, request) {
+    const headers = new Headers();
+    let bytes;
+    let status = result.status;
+    if (result.redirectTo != null) {
+        status = HTTP_FOUND;
+        bytes = new Uint8Array(0);
+        headers.set("location", result.redirectTo);
+    }
+    else if (result.download != null) {
+        bytes = result.download.bytes;
+        headers.set("content-type", result.download.contentType);
+        headers.set("content-disposition", "attachment; filename=\"" + result.download.fileName.replace(/["\\\r\n]/g, "_") + "\"");
+    }
+    else {
+        bytes = new TextEncoder().encode(JSON.stringify(result.body));
+        headers.set("content-type", JSON_CONTENT_TYPE);
+    }
+    applyCommonHeaders(headers, bytes.byteLength, "no-store");
+    headers.set("access-control-allow-origin", request.consoleOrigin);
+    headers.set("access-control-allow-credentials", "false");
+    headers.set("vary", "Origin");
+    for (const cookie of result.setCookies ?? [])
+        headers.append("set-cookie", cookie);
+    return new Response(responseBody(bytes), { status: status, headers: headers });
+}
+/**
+ * A JSON answer outside the API pipeline (static-path refusals), with the same single-buffer headers.
+ * @param status HTTP status.
+ * @param body The JSON body.
+ * @param consoleOrigin The console origin of the request.
+ * @returns The response.
+ */
+export function adminJsonResponse(status, body, consoleOrigin) {
+    return buildAdminResponse({ status: status, body: body }, { consoleOrigin: consoleOrigin });
+}
+/**
+ * A plain-text console answer (missing asset, console not built).
+ * @param status HTTP status.
+ * @param text The text.
+ * @returns The response.
+ */
+export function adminTextResponse(status, text) {
+    const bytes = new TextEncoder().encode(text);
+    const headers = new Headers({ "content-type": TEXT_CONTENT_TYPE });
+    applyCommonHeaders(headers, bytes.byteLength, "no-store");
+    headers.set("access-control-allow-credentials", "false");
+    return new Response(bytes, { status: status, headers: headers });
+}
+/**
+ * A static file answer.
+ * @param bytes The file.
+ * @param contentType Its content type.
+ * @param cacheControl Its cache-control value.
+ * @returns The response.
+ */
+export function staticFileResponse(bytes, contentType, cacheControl) {
+    const headers = new Headers({ "content-type": contentType });
+    applyCommonHeaders(headers, bytes.byteLength, cacheControl);
+    headers.set("access-control-allow-credentials", "false");
+    return new Response(responseBody(bytes), { status: HTTP_OK, headers: headers });
+}
+/**
+ * A permanent redirect (GET /game-server/admin → /game-server/admin/).
+ * @param location The target path.
+ * @returns The 308 response.
+ */
+export function redirectResponse(location) {
+    const headers = new Headers({ location: location });
+    applyCommonHeaders(headers, 0, "no-store");
+    headers.set("access-control-allow-credentials", "false");
+    return new Response(null, { status: HTTP_PERMANENT_REDIRECT, headers: headers });
+}
+/**
+ * The name of the session cookie for a request (R9).
+ * @param secure True for a secure request (TLS, or HTTPS at a trusted proxy).
+ * @returns `__Host-bgs-admin` or `bgs-admin`.
+ */
+export function sessionCookieName(secure) {
+    return secure ? SECURE_SESSION_COOKIE_NAME : SESSION_COOKIE_NAME;
+}
+/**
+ * The Set-Cookie value of a console session (D10).
+ * @param value The cookie value (a random session id).
+ * @param secure True for a secure request: adds Secure and uses the __Host- name.
+ * @param maxAgeSeconds How long the browser keeps it, in seconds.
+ * @returns The Set-Cookie value.
+ */
+export function buildSessionCookie(value, secure, maxAgeSeconds) {
+    const attributes = [sessionCookieName(secure) + "=" + value, "HttpOnly", "SameSite=Strict", "Path=/", "Max-Age=" + Math.max(0, Math.floor(maxAgeSeconds))];
+    if (secure)
+        attributes.push("Secure");
+    return attributes.join("; ");
+}
+/**
+ * The Set-Cookie value that removes the session cookie (sign-out).
+ * @param secure True for a secure request.
+ * @returns The Set-Cookie value.
+ */
+export function buildClearingCookie(secure) {
+    return buildSessionCookie("", secure, 0);
+}
+/**
+ * The console's own origin, from the Host header and the D9 scheme rule.
+ * @param headers The request headers.
+ * @param secure True for a secure request.
+ * @returns scheme://host.
+ */
+export function consoleOriginOf(headers, secure) {
+    return (secure ? "https" : "http") + "://" + (headers.get("host") ?? "localhost");
+}
+/**
+ * The body of a single-buffer answer. The router's Node writer never ends a stream that yields no chunk, so an empty
+ * body must be null.
+ * @param bytes The body bytes.
+ * @returns The bytes, or null when empty.
+ */
+function responseBody(bytes) {
+    return (bytes.byteLength > 0) ? bytes : null;
+}
+/**
+ * Sets the headers every console answer carries: length, connection: close, caching and the D9 headers.
+ * @param headers The headers to fill.
+ * @param byteLength The body length in bytes.
+ * @param cacheControl The cache-control value.
+ */
+function applyCommonHeaders(headers, byteLength, cacheControl) {
+    headers.set("content-length", String(byteLength));
+    headers.set("connection", "close");
+    headers.set("cache-control", cacheControl);
+    for (const [name, value] of Object.entries(SECURITY_HEADERS))
+        headers.set(name, value);
+}

package/lib/admin/AdminServices.d.ts

@@ -0,0 +1,99 @@
+import type { GameServerConfig } from "../GameServerConfig.js";
+import type { GameServerStateValues } from "../GameServerState.js";
+import type { GameServerRouteContext } from "../ServerEndpoints.js";
+import type { AdminAccounts } from "./AdminAccounts.js";
+import type { AdminAudit } from "./AdminAudit.js";
+import type { ApiKeys } from "./ApiKeys.js";
+import type { AdminClock } from "./AdminClock.js";
+import type { AdminExtensionsHost } from "./AdminExtensionsHost.js";
+import type { AdminStore } from "./AdminStore.js";
+import type { ConsoleSessions } from "./ConsoleSessions.js";
+import type { FleetDirectory } from "./FleetDirectory.js";
+import type { MaintenanceMode } from "./MaintenanceMode.js";
+import type { MetricsSampler } from "./MetricsSampler.js";
+import type { TemporaryLogLevel } from "./LogRoutes.js";
+import type { ConfigOverrides } from "./ConfigOverrides.js";
+import type { BanList } from "./BanList.js";
+import type { RoomAdminClient } from "./SessionRoutes.js";
+import type { ServerEvents } from "./ServerEvents.js";
+import type { FleetLeader } from "./FleetLeader.js";
+import type { AlertEngine } from "./AlertEngine.js";
+import type { MaintenanceWindows } from "./MaintenanceWindows.js";
+import type { RolloutCoordinator } from "./RolloutCoordinator.js";
+import type { Passkeys } from "./Passkeys.js";
+import type { OpenIdConnectClient } from "./OpenIdConnect.js";
+import type { ColyseusCloudService } from "./ColyseusCloudService.js";
+import type { LeaderboardService } from "../leaderboards/LeaderboardService.js";
+/** What GameServer.ts hands the console: the server's parts and the test-injectable values (R10). */
+export interface AdminCoreServices {
+    /** The resolved config. */
+    config: GameServerConfig;
+    /** The process's game server state. */
+    state: GameServerStateValues;
+    /** The admin data store (D7). */
+    store: AdminStore;
+    /** What the legacy routes read (listening port, drain, dedicated sessions). */
+    routeContext: GameServerRouteContext;
+    /**
+     * This instance's process id (matchMaker.processId, R5). Call it only from start() onward: Colyseus sets it in listen.
+     * @returns The process id.
+     */
+    processId(): string;
+    /** The clock of every admin timer and every "now" (R10). */
+    clock: AdminClock;
+    /** Milliseconds between fleet heartbeats (FLEET_HEARTBEAT_INTERVAL_MS unless a test overrides it). */
+    heartbeatIntervalMs: number;
+    /** Milliseconds between metrics samples (METRICS_SAMPLE_INTERVAL_MS unless a test overrides it). */
+    metricsSampleIntervalMs: number;
+    /** Milliseconds between leader ticks (LEADER_TICK_MS unless a test overrides it). */
+    leaderTickMs: number;
+    /** The PagerDuty Events v2 URL alert channels post to. */
+    pagerDutyUrl: string;
+    /** Called after each Colyseus Cloud refresh pass (a no-op outside tests, D17). */
+    colyseusCloudRefreshed: (nowMilliseconds: number) => void;
+    /** The custom actions, panels and admin event hooks of GameServerOptions.admin (D25). */
+    extensions: AdminExtensionsHost;
+    /** The leaderboard service (game-server-leaderboards D4). */
+    leaderboards: LeaderboardService;
+}
+/** What the admin routes and services share: the core plus the services createAdminConsole builds. */
+export interface AdminServices extends AdminCoreServices {
+    /** Console sessions (D10). */
+    sessions: ConsoleSessions;
+    /** Admin accounts, sign-in and the setup link (D8, D30). */
+    accounts: AdminAccounts;
+    /** Scoped API keys and the legacy token caller (D18). */
+    apiKeys: ApiKeys;
+    /** The hash-chained audit log (D19). */
+    audit: AdminAudit;
+    /** Heartbeats, fleet commands and change announcements (D16). */
+    fleet: FleetDirectory;
+    /** The maintenance in force on this instance (D14). */
+    maintenance: MaintenanceMode;
+    /** Every room action of the API, on whichever instance owns the room (D11, R17). */
+    roomClient: RoomAdminClient;
+    /** This instance's bans, which the join gate checks (D15); the console puts it on state.banList while it runs. */
+    banList: BanList;
+    /** This instance's metrics history (D22). */
+    metricsSampler: MetricsSampler;
+    /** This instance's temporary log level and its revert timer (D21). */
+    temporaryLogLevel: TemporaryLogLevel;
+    /** The console's live config overrides (D20). */
+    configOverrides: ConfigOverrides;
+    /** Server events of the activity feed, under the record-keeping rule (R3). */
+    serverEvents: ServerEvents;
+    /** The fleet leader lease and its tick (D24). */
+    leader: FleetLeader;
+    /** Alert rules, channels and history (D24). */
+    alerts: AlertEngine;
+    /** Scheduled maintenance windows. */
+    maintenanceWindows: MaintenanceWindows;
+    /** Rolling updates (DR §7.8). */
+    rollouts: RolloutCoordinator;
+    /** Passkey registration and sign-in (D31). */
+    passkeys: Passkeys;
+    /** OpenID Connect single sign-on (D26). */
+    openId: OpenIdConnectClient;
+    /** The Colyseus Cloud page's cache of the Cloud API (colyseus-cloud-console). */
+    colyseusCloud: ColyseusCloudService;
+}

package/lib/admin/AdminServices.js

@@ -0,0 +1,4 @@
+// The services bag handed to every admin route file (game-server-admin-console DR §6.3, §13 R5 and R10). It is the
+// console's composition root: GameServer.ts fills it, AdminConsole.ts adds the services it builds.
+// Each task that adds an admin service adds its field here, documented, and builds it in createAdminConsole.
+export {};

package/lib/admin/AdminStaticFiles.d.ts

@@ -0,0 +1,29 @@
+/** The console app's files, held in memory. */
+export declare class AdminStaticFiles {
+    /** The folder Vite builds into. */
+    private readonly rootFolder;
+    /** Relative URL path (forward slashes) → file bytes. */
+    private readonly files;
+    /**
+     * Prepares serving from a folder; call load() before respond().
+     * @param rootFolder The built console folder (lib/console/).
+     */
+    constructor(rootFolder: string);
+    /** True once index.html has been loaded. */
+    get isAvailable(): boolean;
+    /** Reads every file under the root folder into memory; a missing folder leaves the app unavailable. */
+    load(): Promise<void>;
+    /**
+     * Answers one console path: the file, index.html for extensionless paths (hash routing), 404 text for a missing
+     * file with an extension, or 503 text while the app is not built.
+     * @param assetPath The path after /game-server/admin/ ("" for the app itself).
+     * @returns The response.
+     */
+    respond(assetPath: string): Response;
+    /**
+     * The file a console path names: index.html for "" and for paths without an extension.
+     * @param assetPath The path after /game-server/admin/.
+     * @returns The relative file path.
+     */
+    private resolveFilePath;
+}

package/lib/admin/AdminStaticFiles.js

@@ -0,0 +1,97 @@
+// Static serving of the built console app (game-server-admin-console D1, D3). Vite writes it to lib/console/; every file
+// is read into memory at startup, so each answer is one buffer (D5).
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { adminTextResponse, staticFileResponse } from "./AdminResponses.js";
+/** The app's entry page; extensionless paths serve it too (hash routing, D2). */
+const INDEX_FILE = "index.html";
+/** Folder of Vite's hashed assets. */
+const ASSETS_FOLDER_PREFIX = "assets/";
+/** Cache policy of hashed assets: their names change with their content. */
+const IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
+/** Cache policy of the entry page and other files. */
+const REVALIDATE_CACHE_CONTROL = "no-cache";
+/** Status of a missing asset. */
+const HTTP_NOT_FOUND = 404;
+/** Status while the app is not built. */
+const HTTP_SERVICE_UNAVAILABLE = 503;
+/** The text answered while the app is not built. */
+const NOT_BUILT_TEXT = "the console files are not built (run npm run build in SVR)";
+/** Content type of a file whose extension is not listed. */
+const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+/** Content types by file extension. */
+const CONTENT_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".map": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".ico": "image/x-icon",
+    ".webp": "image/webp",
+    ".woff2": "font/woff2",
+    ".txt": "text/plain; charset=utf-8"
+};
+/** The console app's files, held in memory. */
+export class AdminStaticFiles {
+    /** The folder Vite builds into. */
+    rootFolder;
+    /** Relative URL path (forward slashes) → file bytes. */
+    files = new Map();
+    /**
+     * Prepares serving from a folder; call load() before respond().
+     * @param rootFolder The built console folder (lib/console/).
+     */
+    constructor(rootFolder) {
+        this.rootFolder = rootFolder;
+    }
+    /** True once index.html has been loaded. */
+    get isAvailable() {
+        return this.files.has(INDEX_FILE);
+    }
+    /** Reads every file under the root folder into memory; a missing folder leaves the app unavailable. */
+    async load() {
+        this.files.clear();
+        if (!existsSync(this.rootFolder))
+            return;
+        const entries = await readdir(this.rootFolder, { recursive: true });
+        for (const relativePath of entries) {
+            const absolutePath = path.join(this.rootFolder, relativePath);
+            const bytes = await readFile(absolutePath).catch(() => null);
+            if (bytes == null)
+                continue;
+            this.files.set(relativePath.split(path.sep).join("/"), new Uint8Array(bytes));
+        }
+    }
+    /**
+     * Answers one console path: the file, index.html for extensionless paths (hash routing), 404 text for a missing
+     * file with an extension, or 503 text while the app is not built.
+     * @param assetPath The path after /game-server/admin/ ("" for the app itself).
+     * @returns The response.
+     */
+    respond(assetPath) {
+        if (!this.isAvailable)
+            return adminTextResponse(HTTP_SERVICE_UNAVAILABLE, NOT_BUILT_TEXT);
+        const filePath = this.resolveFilePath(assetPath);
+        const bytes = this.files.get(filePath);
+        if (bytes == null)
+            return adminTextResponse(HTTP_NOT_FOUND, "not found");
+        const cacheControl = filePath.startsWith(ASSETS_FOLDER_PREFIX) ? IMMUTABLE_CACHE_CONTROL : REVALIDATE_CACHE_CONTROL;
+        const contentType = CONTENT_TYPES[path.extname(filePath).toLowerCase()] ?? DEFAULT_CONTENT_TYPE;
+        return staticFileResponse(bytes, contentType, cacheControl);
+    }
+    /**
+     * The file a console path names: index.html for "" and for paths without an extension.
+     * @param assetPath The path after /game-server/admin/.
+     * @returns The relative file path.
+     */
+    resolveFilePath(assetPath) {
+        const cleanPath = assetPath.replace(/^\/+/, "");
+        if (cleanPath === "" || path.posix.extname(cleanPath) === "")
+            return INDEX_FILE;
+        return cleanPath;
+    }
+}

package/lib/admin/AdminStore.d.ts

@@ -0,0 +1,152 @@
+import type { Redis } from "ioredis";
+import type { GameServerConfig } from "../GameServerConfig.js";
+import { type AdminClock } from "./AdminClock.js";
+/** The document collections of the admin store (D7). */
+export type AdminCollection = "users" | "consoleSessions" | "pendingSignIns" | "apiKeys" | "bans" | "playerNotes" | "settings" | "alertRules" | "alertChannels" | "maintenanceWindows" | "rollouts" | "passkeys" | "signInFailures" | "setupLinks" | "colyseusCloud" | "leaderboards" | "leaderboardSettings" | "discordSignIn";
+/** The append-only streams of the admin store (D7). `metrics:<processId>` streams are Redis-only (D22). */
+export type AdminStream = "audit" | "events" | "alertHistory" | "configHistory" | "playerHistory" | "leaderboardActivity" | `metrics:${string}`;
+/** A stored document with its optimistic revision. */
+export interface StoredDocument<Value> {
+    /** The document id within its collection. */
+    id: string;
+    /** Starts at 1 and grows by one per write. */
+    revision: number;
+    /** ISO time of the last write. */
+    updatedAt: string;
+    /** The document. */
+    value: Value;
+}
+/** A stored stream record. */
+export interface StoredRecord<Value> {
+    /** Starts at 1 and grows by one per append, per stream. */
+    sequence: number;
+    /** ISO time of the append. */
+    at: string;
+    /** The record. */
+    value: Value;
+}
+/** A stream read. */
+export interface RecordQuery {
+    /** Only records with a larger sequence. */
+    afterSequence?: number;
+    /** Only records with a smaller sequence. */
+    beforeSequence?: number;
+    /** Most records returned (1–5000). */
+    limit: number;
+    /** Newest first when true. */
+    newestFirst: boolean;
+}
+/** Smallest RecordQuery.limit. */
+export declare const RECORD_QUERY_MIN_LIMIT: number;
+/** Largest RecordQuery.limit. */
+export declare const RECORD_QUERY_MAX_LIMIT: number;
+/** Builds a chained record from the stream's newest record and the new record's sequence and ISO time. */
+export type ChainedRecordBuilder<Value> = (previous: StoredRecord<Value> | null, sequence: number, at: string) => Value;
+/** Thrown when a write's expected revision is not the stored one (spec edge case: two admins edit at once). */
+export declare class AdminConflictError extends Error {
+    /** The document as it is now, or null when it was deleted. */
+    readonly current: StoredDocument<unknown> | null;
+    /**
+     * Creates the error.
+     * @param current The document as it is now.
+     */
+    constructor(current: StoredDocument<unknown> | null);
+}
+/** Persistent admin data, shared by the fleet when Redis is used (D7). */
+export interface AdminStore {
+    /** "redis" or "file". */
+    readonly kind: "redis" | "file";
+    /** False for a file store whose folder is not on a mounted volume inside a container (see HealthWarnings). */
+    readonly isPersistent: boolean;
+    /**
+     * Reads one document.
+     * @param collection The collection.
+     * @param documentId The document id.
+     * @returns The document, or null when it does not exist.
+     */
+    getDocument<Value>(collection: AdminCollection, documentId: string): Promise<StoredDocument<Value> | null>;
+    /**
+     * Reads every document of a collection.
+     * @param collection The collection.
+     * @returns The documents, in no particular order.
+     */
+    listDocuments<Value>(collection: AdminCollection): Promise<StoredDocument<Value>[]>;
+    /**
+     * Writes a document; its revision grows by one.
+     * @param collection The collection.
+     * @param documentId The document id.
+     * @param value The document.
+     * @param expectedRevision The revision the writer read (0 for "must not exist yet"), or null for no check.
+     * @returns The stored document.
+     * @throws AdminConflictError when expectedRevision is a number that differs from the stored revision.
+     */
+    putDocument<Value>(collection: AdminCollection, documentId: string, value: Value, expectedRevision: number | null): Promise<StoredDocument<Value>>;
+    /**
+     * Deletes a document.
+     * @param collection The collection.
+     * @param documentId The document id.
+     * @returns True when it existed.
+     */
+    deleteDocument(collection: AdminCollection, documentId: string): Promise<boolean>;
+    /**
+     * Appends a record to a stream.
+     * @param stream The stream.
+     * @param value The record.
+     * @returns The stored record with its sequence.
+     */
+    appendRecord<Value>(stream: AdminStream, value: Value): Promise<StoredRecord<Value>>;
+    /**
+     * Appends a record built from the stream's newest record, atomically across the fleet (the audit hash chain, R21).
+     * @param stream The stream.
+     * @param build Builds the value from the newest record (null for an empty stream) and the new record's sequence
+     *     and time, which the value may include (the audit hash covers them).
+     * @returns The stored record.
+     */
+    appendChainedRecord<Value>(stream: AdminStream, build: ChainedRecordBuilder<Value>): Promise<StoredRecord<Value>>;
+    /**
+     * Reads records of a stream.
+     * @param stream The stream.
+     * @param query The range, limit and order.
+     * @returns The records.
+     */
+    readRecords<Value>(stream: AdminStream, query: RecordQuery): Promise<StoredRecord<Value>[]>;
+    /**
+     * Removes records appended before the cutoff.
+     * @param stream The stream.
+     * @param cutoff Records whose `at` is earlier are removed.
+     * @returns How many were removed.
+     */
+    trimRecordsBefore(stream: AdminStream, cutoff: Date): Promise<number>;
+    /**
+     * Keeps only the newest records.
+     * @param stream The stream.
+     * @param keepCount How many to keep.
+     * @returns How many were removed.
+     */
+    trimRecordsToCount(stream: AdminStream, keepCount: number): Promise<number>;
+    /**
+     * Takes or renews a lease (the fleet leader, D24). File store: always true (one instance).
+     * @param leaseName The lease.
+     * @param holderId Who wants it (a process id).
+     * @param ttlMilliseconds How long it lasts without renewal.
+     * @returns True when this holder now holds the lease.
+     */
+    tryAcquireLease(leaseName: string, holderId: string, ttlMilliseconds: number): Promise<boolean>;
+    /** Releases what the store holds (the shared Redis client is left to RedisPresence, R4). */
+    close(): Promise<void>;
+}
+/**
+ * Opens the store the config calls for: Redis when a client is given, otherwise the file store in admin.dataDir. The file
+ * store creates nothing until its first write (R3).
+ * @param config The resolved config.
+ * @param redisClient The shared ioredis client, or null without Redis.
+ * @param clock The clock of stored times (tests pass a manual one, R10).
+ * @returns The open store.
+ */
+export declare function openAdminStore(config: GameServerConfig, redisClient: Redis | null, clock?: AdminClock): Promise<AdminStore>;
+/**
+ * Clamps a query limit to RECORD_QUERY_MIN_LIMIT … RECORD_QUERY_MAX_LIMIT.
+ * @param limit The requested limit.
+ * @returns The limit used.
+ */
+export declare function clampRecordLimit(limit: number): number;

package/lib/admin/AdminStore.js

@@ -0,0 +1,46 @@
+// The admin data store (game-server-admin-console D7, DR §6.1): Redis when redis.url is set, otherwise JSON files in
+// admin.dataDir. Documents carry optimistic revisions; streams are append-only with per-stream sequences.
+import { SYSTEM_CLOCK } from "./AdminClock.js";
+import { FileAdminStore } from "./FileAdminStore.js";
+import { RedisAdminStore } from "./RedisAdminStore.js";
+/** Smallest RecordQuery.limit. */
+export const RECORD_QUERY_MIN_LIMIT = 1;
+/** Largest RecordQuery.limit. */
+export const RECORD_QUERY_MAX_LIMIT = 5000;
+/** Thrown when a write's expected revision is not the stored one (spec edge case: two admins edit at once). */
+export class AdminConflictError extends Error {
+    /** The document as it is now, or null when it was deleted. */
+    current;
+    /**
+     * Creates the error.
+     * @param current The document as it is now.
+     */
+    constructor(current) {
+        super("the document changed since it was read");
+        this.name = "AdminConflictError";
+        this.current = current;
+    }
+}
+/**
+ * Opens the store the config calls for: Redis when a client is given, otherwise the file store in admin.dataDir. The file
+ * store creates nothing until its first write (R3).
+ * @param config The resolved config.
+ * @param redisClient The shared ioredis client, or null without Redis.
+ * @param clock The clock of stored times (tests pass a manual one, R10).
+ * @returns The open store.
+ */
+export async function openAdminStore(config, redisClient, clock = SYSTEM_CLOCK) {
+    if (redisClient != null)
+        return new RedisAdminStore(redisClient, clock);
+    return new FileAdminStore(config.admin.dataDir, clock);
+}
+/**
+ * Clamps a query limit to RECORD_QUERY_MIN_LIMIT … RECORD_QUERY_MAX_LIMIT.
+ * @param limit The requested limit.
+ * @returns The limit used.
+ */
+export function clampRecordLimit(limit) {
+    if (!Number.isFinite(limit))
+        return RECORD_QUERY_MAX_LIMIT;
+    return Math.min(RECORD_QUERY_MAX_LIMIT, Math.max(RECORD_QUERY_MIN_LIMIT, Math.floor(limit)));
+}

package/lib/admin/AlertChannels.d.ts

@@ -0,0 +1,43 @@
+import type { AlertChannelView, AlertView } from "./AdminApiTypes.js";
+import type { AlertChannelRecord } from "./AdminRecords.js";
+/** Whether an alert delivery announces a firing or a resolved alert. */
+export type AlertDeliveryState = "firing" | "resolved";
+/** The outcome of one delivery. */
+export interface AlertDeliveryOutcome {
+    ok: boolean;
+    error: string | null;
+}
+/** Delivers alerts to their channels. */
+export declare class AlertChannels {
+    /** Request timeout of a delivery, in milliseconds. */
+    private readonly timeoutMs;
+    /**
+     * Creates the deliverer.
+     * @param timeoutMs Request timeout, in milliseconds. Default ALERT_CHANNEL_TIMEOUT_MS.
+     */
+    constructor(timeoutMs?: number);
+    /**
+     * Posts an alert to a channel with its DR §8 payload. A network failure, a timeout or a non-2xx answer is an
+     * outcome, never a throw.
+     * @param channel The channel with its secrets.
+     * @param alert The alert.
+     * @param state Whether it fired or resolved.
+     * @param pagerDutyUrl The PagerDuty Events v2 URL (tests replace it, R10).
+     * @returns Whether it was delivered, and why not.
+     */
+    deliver(channel: AlertChannelRecord, alert: AlertView, state: AlertDeliveryState, pagerDutyUrl: string): Promise<AlertDeliveryOutcome>;
+}
+/**
+ * The JSON body a channel receives (DR §8).
+ * @param channel The channel.
+ * @param alert The alert.
+ * @param state Whether it fired or resolved.
+ * @returns The payload.
+ */
+export declare function alertPayloadOf(channel: AlertChannelRecord, alert: AlertView, state: AlertDeliveryState): Record<string, unknown>;
+/**
+ * A channel as the console sees it: the url without its path, the routing key as set / not set.
+ * @param channel The stored channel.
+ * @returns The view.
+ */
+export declare function alertChannelView(channel: AlertChannelRecord): AlertChannelView;