@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/NetworkAddresses.js

@@ -0,0 +1,90 @@
+import { BlockList, isIPv4, isIPv6 } from "node:net";
+/** Prefix Node gives an IPv4 address seen on a dual-stack socket. */
+const IPV4_MAPPED_PREFIX = "::ffff:";
+/** Addresses that mean "this machine" (D9). */
+const LOOPBACK_ADDRESSES = ["127.0.0.1", "::1"];
+/** Separator of an address and its prefix length in CIDR notation. */
+const CIDR_SEPARATOR = "/";
+/** Longest IPv4 prefix length. */
+const IPV4_MAX_PREFIX = 32;
+/** Longest IPv6 prefix length. */
+const IPV6_MAX_PREFIX = 128;
+/**
+ * Turns an IPv4-mapped IPv6 address (`::ffff:a.b.c.d`) into its IPv4 form, so lists and checks see one spelling.
+ * @param address The client address.
+ * @returns The normalized address.
+ */
+export function normalizeAddress(address) {
+    const lowerCase = address.trim().toLowerCase();
+    if (lowerCase.startsWith(IPV4_MAPPED_PREFIX) && isIPv4(lowerCase.substring(IPV4_MAPPED_PREFIX.length)))
+        return lowerCase.substring(IPV4_MAPPED_PREFIX.length);
+    return lowerCase;
+}
+/**
+ * Whether an address is this machine's loopback interface (127.0.0.1, ::1 or ::ffff:127.0.0.1).
+ * @param address The client address.
+ * @returns True for a loopback address.
+ */
+export function isLoopbackAddress(address) {
+    return LOOPBACK_ADDRESSES.includes(normalizeAddress(address));
+}
+/**
+ * Adds one address or CIDR range to a block list.
+ * @param blockList The list to add to.
+ * @param entry An address (`a.b.c.d`, IPv6) or a range (`a.b.c.d/n`).
+ * @returns False when the entry is not an address or range.
+ */
+export function addNetworkEntry(blockList, entry) {
+    const separatorIndex = entry.indexOf(CIDR_SEPARATOR);
+    const address = normalizeAddress(separatorIndex >= 0 ? entry.substring(0, separatorIndex) : entry);
+    const family = addressFamily(address);
+    if (family == null)
+        return false;
+    if (separatorIndex < 0) {
+        blockList.addAddress(address, family);
+        return true;
+    }
+    const prefixText = entry.substring(separatorIndex + 1);
+    const prefix = Number(prefixText);
+    const maxPrefix = (family === "ipv4") ? IPV4_MAX_PREFIX : IPV6_MAX_PREFIX;
+    if (prefixText === "" || !Number.isInteger(prefix) || prefix < 0 || prefix > maxPrefix)
+        return false;
+    blockList.addSubnet(address, prefix, family);
+    return true;
+}
+/**
+ * Builds a block list from address and CIDR entries, skipping invalid ones (config validation reports those).
+ * @param entries The addresses and ranges.
+ * @returns The list.
+ */
+export function createNetworkList(entries) {
+    const blockList = new BlockList();
+    for (const entry of entries)
+        addNetworkEntry(blockList, entry);
+    return blockList;
+}
+/**
+ * Whether an address falls inside a block list.
+ * @param blockList The list.
+ * @param address The client address.
+ * @returns True when the address is listed or inside a listed range; false for text that is not an address.
+ */
+export function isAddressInList(blockList, address) {
+    const normalized = normalizeAddress(address);
+    const family = addressFamily(normalized);
+    if (family == null)
+        return false;
+    return blockList.check(normalized, family);
+}
+/**
+ * The IP family of an address.
+ * @param address The normalized address.
+ * @returns "ipv4", "ipv6", or null when it is not an IP address.
+ */
+function addressFamily(address) {
+    if (isIPv4(address))
+        return "ipv4";
+    if (isIPv6(address))
+        return "ipv6";
+    return null;
+}

package/lib/PlayerTokens.d.ts

@@ -0,0 +1,17 @@
+import type { AuthIdentity, AuthRequest } from "./Authentication.js";
+import type { GameServerStateValues } from "./GameServerState.js";
+/**
+ * Verifies a player token: this server's Discord sessions first, then the configured auth (or anonymous when auth is off).
+ * @param state The server state.
+ * @param request The token and what the server knows about the call.
+ * @returns The verified identity, or null for an anonymous player on a server whose auth is off.
+ * @throws AuthRefusal (or whatever the configured verifier throws) when the token is refused.
+ */
+export declare function verifyPlayerToken(state: GameServerStateValues, request: AuthRequest): Promise<AuthIdentity | null>;
+/**
+ * Whether a token goes to a verifier at all (a Discord session always does; anything else only when auth is on).
+ * @param state The server state.
+ * @param token The token ("" when none was sent).
+ * @returns True when the token must be verified.
+ */
+export declare function needsVerification(state: GameServerStateValues, token: string): boolean;

package/lib/PlayerTokens.js

@@ -0,0 +1,24 @@
+// PlayerTokens.ts — the one place that decides which verifier sees a player token (discord-sign-in D10).
+/**
+ * Verifies a player token: this server's Discord sessions first, then the configured auth (or anonymous when auth is off).
+ * @param state The server state.
+ * @param request The token and what the server knows about the call.
+ * @returns The verified identity, or null for an anonymous player on a server whose auth is off.
+ * @throws AuthRefusal (or whatever the configured verifier throws) when the token is refused.
+ */
+export async function verifyPlayerToken(state, request) {
+    if (state.discordSessions != null && state.discordSessions.isSessionToken(request.token))
+        return await state.discordSessions.verify(request.token);
+    if (state.verifier == null)
+        return null;
+    return await state.verifier(request);
+}
+/**
+ * Whether a token goes to a verifier at all (a Discord session always does; anything else only when auth is on).
+ * @param state The server state.
+ * @param token The token ("" when none was sent).
+ * @returns True when the token must be verified.
+ */
+export function needsVerification(state, token) {
+    return (state.discordSessions != null && state.discordSessions.isSessionToken(token)) || state.verifier != null;
+}

package/lib/RoomServerTransport.d.ts

@@ -0,0 +1,73 @@
+import type { FusionConnectRequest, FusionSessionLogicApi, FusionSessionServerEndpoint, FusionWelcome } from "./HeadlessRuntime.js";
+/** Callbacks a transport delivers into, as TOOLKIT.NetworkTransportHandlers. */
+export interface RoomTransportHandlers {
+    /** A simulation frame arrived from a player. */
+    onFrame(sourcePlayerId: number, frame: Uint8Array): void;
+    /** A control message arrived. */
+    onControl(name: string, payload: object): void;
+    /** The connection closed without a disconnect call. */
+    onDisconnected(reason: number): void;
+}
+/**
+ * The dedicated server runner's transport (A17, T13 step 3), as TOOLKIT.INetworkTransport: the runner runs inside the
+ * session room's process, so instead of a socket it talks straight to the room's FusionSessionLogic. It is also the
+ * session's server endpoint: frames clients send to the host reach the runner through receiveFrame.
+ */
+export declare class RoomServerTransport implements FusionSessionServerEndpoint {
+    /** The session rules of the room the server runs in. */
+    private readonly logic;
+    /** Where received frames and control messages go. */
+    private handlers;
+    /** True between connect and disconnect. */
+    private connected;
+    /** The stats overlay's name of this connection. */
+    readonly transportName: string;
+    /**
+     * Creates the transport of a room's dedicated runner.
+     * @param logic The room's session logic.
+     */
+    constructor(logic: FusionSessionLogicApi);
+    /** True between connect and disconnect. */
+    get isConnected(): boolean;
+    /** No latency simulator: the server is in the room's process. */
+    get conditions(): null;
+    /**
+     * Makes the runner the session's dedicated server (player 0).
+     * @param request The runner's connect request.
+     * @returns The runner's welcome.
+     */
+    connect(request: FusionConnectRequest): Promise<FusionWelcome>;
+    /**
+     * Sends a frame from the server: ToPlayer to that client, any other route to every client.
+     * @param route The route.
+     * @param targetPlayerId The target for ToPlayer.
+     * @param frame The frame.
+     * @param channel The TOOLKIT.RpcChannel the runner sends it on; the room keeps it for datagram delivery (D7).
+     */
+    sendFrame(route: number, targetPlayerId: number, frame: Uint8Array, channel?: number): void;
+    /**
+     * Sends a control message from the server (a connect result is applied by the session itself).
+     * @param name The control message name.
+     * @param payload The payload.
+     */
+    sendControl(name: string, payload: object): void;
+    /**
+     * Sets where received frames and control messages go.
+     * @param handlers The callbacks.
+     */
+    setHandlers(handlers: RoomTransportHandlers): void;
+    /** Stops delivering; the room ends with its server. */
+    disconnect(): Promise<void>;
+    /**
+     * A frame a player sent to the server (the session endpoint).
+     * @param sourcePlayerId The sending player.
+     * @param frame The frame.
+     */
+    receiveFrame(sourcePlayerId: number, frame: Uint8Array): void;
+    /**
+     * A control message for the server (connect requests, players joining and leaving).
+     * @param name The control message name.
+     * @param payload The payload.
+     */
+    receiveControl(name: string, payload: object): void;
+}

package/lib/RoomServerTransport.js

@@ -0,0 +1,90 @@
+/**
+ * The dedicated server runner's transport (A17, T13 step 3), as TOOLKIT.INetworkTransport: the runner runs inside the
+ * session room's process, so instead of a socket it talks straight to the room's FusionSessionLogic. It is also the
+ * session's server endpoint: frames clients send to the host reach the runner through receiveFrame.
+ */
+export class RoomServerTransport {
+    /** The session rules of the room the server runs in. */
+    logic;
+    /** Where received frames and control messages go. */
+    handlers = null;
+    /** True between connect and disconnect. */
+    connected = false;
+    /** The stats overlay's name of this connection. */
+    transportName = "Room";
+    /**
+     * Creates the transport of a room's dedicated runner.
+     * @param logic The room's session logic.
+     */
+    constructor(logic) {
+        this.logic = logic;
+    }
+    /** True between connect and disconnect. */
+    get isConnected() {
+        return this.connected;
+    }
+    /** No latency simulator: the server is in the room's process. */
+    get conditions() {
+        return null;
+    }
+    /**
+     * Makes the runner the session's dedicated server (player 0).
+     * @param request The runner's connect request.
+     * @returns The runner's welcome.
+     */
+    connect(request) {
+        const welcome = this.logic.attachDedicatedServer(this, request);
+        this.connected = true;
+        return Promise.resolve(welcome);
+    }
+    /**
+     * Sends a frame from the server: ToPlayer to that client, any other route to every client.
+     * @param route The route.
+     * @param targetPlayerId The target for ToPlayer.
+     * @param frame The frame.
+     * @param channel The TOOLKIT.RpcChannel the runner sends it on; the room keeps it for datagram delivery (D7).
+     */
+    sendFrame(route, targetPlayerId, frame, channel) {
+        if (this.connected)
+            this.logic.sendFromServer(route, targetPlayerId, frame, channel);
+    }
+    /**
+     * Sends a control message from the server (a connect result is applied by the session itself).
+     * @param name The control message name.
+     * @param payload The payload.
+     */
+    sendControl(name, payload) {
+        if (this.connected)
+            this.logic.sendControlFromServer(name, payload, 0);
+    }
+    /**
+     * Sets where received frames and control messages go.
+     * @param handlers The callbacks.
+     */
+    setHandlers(handlers) {
+        this.handlers = handlers;
+    }
+    /** Stops delivering; the room ends with its server. */
+    disconnect() {
+        this.connected = false;
+        return Promise.resolve();
+    }
+    /**
+     * A frame a player sent to the server (the session endpoint).
+     * @param sourcePlayerId The sending player.
+     * @param frame The frame.
+     */
+    receiveFrame(sourcePlayerId, frame) {
+        if (this.connected && this.handlers != null)
+            this.handlers.onFrame(sourcePlayerId, frame);
+    }
+    /**
+     * A control message for the server (connect requests, players joining and leaving).
+     * @param name The control message name.
+     * @param payload The payload.
+     */
+    receiveControl(name, payload) {
+        if (this.connected && this.handlers != null)
+            this.handlers.onControl(name, payload);
+    }
+}

package/lib/ServerEndpoints.d.ts

@@ -0,0 +1,133 @@
+import { type Endpoint } from "colyseus";
+import type { GameServerUrls } from "./GameServer.js";
+import type { GameServerMetrics } from "./GameServerMetrics.js";
+import type { GameServerStateValues } from "./GameServerState.js";
+import type { DedicatedStartedBy } from "./admin/AdminApiTypes.js";
+/** What an endpoint handler reads from its request. */
+export interface EndpointRequestContext {
+    /** Reads a request header. */
+    getHeader(name: string): string | null;
+    /** The path parameters (":roomId"). */
+    params?: Record<string, unknown>;
+    /** The parsed JSON body of a POST. */
+    body?: unknown;
+}
+/** One session of the admin list (D15). */
+export interface AdminSessionSummary {
+    /** The Colyseus room id (the close route's :roomId). */
+    roomId: string;
+    /** The session name players join by. */
+    sessionName: string;
+    /** The session's TOOLKIT.GameMode name, or null when the room has not published one. */
+    gameMode: string | null;
+    /** Clients connected now. */
+    players: number;
+    /** Most clients the room accepts. */
+    maxPlayers: number;
+    /** True when a dedicated Server-mode runner hosts it. */
+    isDedicated: boolean;
+}
+/** The connections a game server accepts, as TOOLKIT.GameServerTransports. */
+export interface GameServerTransports {
+    /** Always true. */
+    webSocket: boolean;
+    /** The HTTP/3 endpoint when UDP is enabled, else null. */
+    webTransport: WebTransportEndpointInfo | null;
+}
+/** The HTTP/3 endpoint of a game server, as TOOLKIT.GameServerWebTransport. */
+export interface WebTransportEndpointInfo {
+    /** The UDP port (the same number as the TCP port). */
+    port: number;
+    /** SHA-256 hash of a pinned development certificate (serverCertificateHashes), or null for a CA-issued one. */
+    certificateHash: number[] | null;
+}
+/** The game server's public description (GET /game-server/info), as TOOLKIT.GameServerInfo. */
+export interface GameServerInfo {
+    /** Always "Babylon Game Server". */
+    serverName: string;
+    /** The server package version. */
+    serverVersion: string;
+    /** The server's TOOLKIT.NETWORK_PROTOCOL_VERSION. */
+    protocolVersion: number;
+    /** The connections the server accepts. */
+    transports: GameServerTransports;
+    /** True when joins need an auth token. */
+    authRequired: boolean;
+    /** True when players can sign in with Discord (discord-sign-in D20). */
+    discordSignIn: boolean;
+}
+/**
+ * What the routes read. The routes are made before the server listens (defineServer takes them), so they read the
+ * server through these closures, which createGameServer fills in after listen.
+ */
+export interface GameServerRouteContext {
+    /** @returns The process's game server state. */
+    state(): GameServerStateValues;
+    /** @returns The port the server listens on (the free port picked for 0). */
+    listeningPort(): number;
+    /** @returns The SHA-256 hash of the pinned HTTP/3 development certificate, or null. */
+    webTransportCertificateHash(): number[] | null;
+    /** @returns True between a successful listen and the end of a drain. */
+    isListening(): boolean;
+    /** @returns Where players and tools reach the server (valid once it listens). */
+    urls(): GameServerUrls;
+    /** @returns The Prometheus metrics, or null when metrics.enabled is false. */
+    metrics(): GameServerMetrics | null;
+    /** @returns True when Redis answers, or when no Redis is configured. */
+    isRedisReachable(): Promise<boolean>;
+    /** Drains the server (D17). */
+    drain(): Promise<void>;
+    /** @returns ISO time a running drain closes the remaining sessions, or null while no drain runs. */
+    drainDeadline(): string | null;
+    /**
+     * Starts a dedicated session of a configured scene.
+     * @param sessionName The session name.
+     * @param sceneName The configured scene.
+     * @param startedBy Who starts it, as the admin console shows it.
+     * @returns The room id.
+     */
+    startDedicatedSession(sessionName: string, sceneName: string, startedBy: DedicatedStartedBy): Promise<string>;
+    /**
+     * Audits a successful legacy admin call as the legacy token; the admin console sets it (game-server-admin-console T3).
+     * @param action "legacy.sessions", "legacy.close", "legacy.dedicated" or "legacy.drain".
+     * @param target The room id or session name it acted on, or null.
+     */
+    auditLegacyAdmin?(action: string, target: string | null): void;
+}
+/** The server package version, read once from package.json. */
+export declare const SERVER_VERSION: string;
+/**
+ * The HTTP endpoints of the game server (D15): health, readiness, info, Prometheus metrics and the admin API. They are
+ * Colyseus router endpoints, so they answer the same on the WebSocket and HTTP/3 transports and get core's CORS.
+ * @param context What the routes read.
+ * @returns The endpoints, keyed by name, for createRouter.
+ */
+export declare function createGameServerRoutes(context: GameServerRouteContext): Record<string, Endpoint>;
+/**
+ * Why the server is not ready, as the readiness endpoint and the fleet heartbeat report it: draining, Redis not
+ * answering, not listening, and maintenance that leaves readiness (game-server-admin-console D14).
+ * @param context What the routes read.
+ * @returns The reasons; empty when ready.
+ */
+export declare function readinessReasons(context: GameServerRouteContext): Promise<string[]>;
+/**
+ * Whether a request carries the admin bearer token (constant-time compare). The admin console also accepts it as a
+ * full-access key (game-server-admin-console D18).
+ * @param state The server state.
+ * @param request The request.
+ * @returns True when an admin token is configured and the request's bearer token equals it.
+ */
+export declare function hasAdminToken(state: GameServerStateValues, request: EndpointRequestContext): boolean;
+/**
+ * A JSON answer.
+ * @param status The HTTP status.
+ * @param body The value sent as JSON.
+ * @returns The response.
+ */
+export declare function jsonResponse(status: number, body: unknown): Response;
+/**
+ * The public description of the running server: name, version, protocol version, transports and whether auth is on.
+ * @param context What the routes read.
+ * @returns The info.
+ */
+export declare function buildServerInfo(context: GameServerRouteContext): GameServerInfo;

package/lib/ServerEndpoints.js

@@ -0,0 +1,247 @@
+import { CloseCode, createEndpoint, matchMaker } from "colyseus";
+import { createRequire } from "node:module";
+import { secretsMatch } from "./Authentication.js";
+import { getLogger } from "./GameServerLogger.js";
+import { getToolkitRuntime } from "./HeadlessRuntime.js";
+/** The product name the info endpoint reports. */
+const SERVER_NAME = "Babylon Game Server";
+/** Path of the public info endpoint (TOOLKIT.GAME_SERVER_INFO_PATH). */
+const INFO_PATH = "/game-server/info";
+/** Path of the liveness endpoint. */
+const HEALTH_PATH = "/game-server/health";
+/** Path of the readiness endpoint. */
+const READY_PATH = "/game-server/ready";
+/** Path of the Prometheus endpoint. */
+const METRICS_PATH = "/metrics";
+/** Path of the admin session list. */
+const ADMIN_SESSIONS_PATH = "/game-server/admin/sessions";
+/** Path of the admin session close. */
+const ADMIN_CLOSE_SESSION_PATH = "/game-server/admin/sessions/:roomId/close";
+/** Path of the admin dedicated session start. */
+const ADMIN_DEDICATED_PATH = "/game-server/admin/dedicated";
+/** Path of the admin drain. */
+const ADMIN_DRAIN_PATH = "/game-server/admin/drain";
+/** The Colyseus room type of sessions. */
+const SESSION_ROOM_NAME = "fusion_session";
+/** Scheme word of a bearer Authorization header. */
+const BEARER_PREFIX = "Bearer ";
+/** Lowest status that is not a success. */
+const FIRST_FAILURE_STATUS = 400;
+/** HTTP statuses the endpoints answer with. */
+const HTTP_OK = 200;
+const HTTP_CREATED = 201;
+const HTTP_ACCEPTED = 202;
+const HTTP_BAD_REQUEST = 400;
+const HTTP_NOT_FOUND = 404;
+const HTTP_UNAUTHORIZED = 401;
+const HTTP_FORBIDDEN = 403;
+const HTTP_SERVICE_UNAVAILABLE = 503;
+/** The server package version, read once from package.json. */
+export const SERVER_VERSION = createRequire(import.meta.url)("../package.json").version;
+/**
+ * The HTTP endpoints of the game server (D15): health, readiness, info, Prometheus metrics and the admin API. They are
+ * Colyseus router endpoints, so they answer the same on the WebSocket and HTTP/3 transports and get core's CORS.
+ * @param context What the routes read.
+ * @returns The endpoints, keyed by name, for createRouter.
+ */
+export function createGameServerRoutes(context) {
+    return {
+        gameServerHealth: createEndpoint(HEALTH_PATH, { method: "GET" }, async () => jsonResponse(HTTP_OK, { status: "ok" })),
+        gameServerReady: createEndpoint(READY_PATH, { method: "GET" }, async () => readinessResponse(context)),
+        gameServerInfo: createEndpoint(INFO_PATH, { method: "GET" }, async () => jsonResponse(HTTP_OK, buildServerInfo(context))),
+        gameServerMetrics: createEndpoint(METRICS_PATH, { method: "GET" }, async (request) => metricsResponse(context, request)),
+        gameServerAdminSessions: createEndpoint(ADMIN_SESSIONS_PATH, { method: "GET" }, async (request) => requireAdmin(context, request) ?? audited(context, "legacy.sessions", null, jsonResponse(HTTP_OK, await listSessions()))),
+        gameServerAdminCloseSession: createEndpoint(ADMIN_CLOSE_SESSION_PATH, { method: "POST" }, async (request) => requireAdmin(context, request) ?? audited(context, "legacy.close", String(request.params?.roomId ?? ""), await closeSession(String(request.params?.roomId ?? "")))),
+        gameServerAdminDedicated: createEndpoint(ADMIN_DEDICATED_PATH, { method: "POST" }, async (request) => requireAdmin(context, request) ?? audited(context, "legacy.dedicated", dedicatedSessionNameOf(request.body), await startDedicated(context, request.body))),
+        gameServerAdminDrain: createEndpoint(ADMIN_DRAIN_PATH, { method: "POST" }, async (request) => requireAdmin(context, request) ?? audited(context, "legacy.drain", null, startDrain(context)))
+    };
+}
+/**
+ * The readiness answer: ready unless the server drains, Redis does not answer, it is not listening, or maintenance
+ * leaves readiness.
+ * @param context What the routes read.
+ * @returns 200 { ready: true }, or 503 { ready: false, reasons }.
+ */
+async function readinessResponse(context) {
+    const reasons = await readinessReasons(context);
+    if (reasons.length === 0)
+        return jsonResponse(HTTP_OK, { ready: true });
+    return jsonResponse(HTTP_SERVICE_UNAVAILABLE, { ready: false, reasons: reasons });
+}
+/**
+ * Why the server is not ready, as the readiness endpoint and the fleet heartbeat report it: draining, Redis not
+ * answering, not listening, and maintenance that leaves readiness (game-server-admin-console D14).
+ * @param context What the routes read.
+ * @returns The reasons; empty when ready.
+ */
+export async function readinessReasons(context) {
+    const state = context.state();
+    const reasons = [];
+    if (state.draining)
+        reasons.push("draining");
+    if (!(await context.isRedisReachable()))
+        reasons.push("redis unreachable");
+    if (!context.isListening())
+        reasons.push("not listening");
+    if (state.maintenance?.leaveReadiness === true)
+        reasons.push("maintenance");
+    return reasons;
+}
+/**
+ * The Prometheus answer: 404 when metrics are off, 403 without the admin token when metrics.requireAdminToken is on.
+ * @param context What the routes read.
+ * @param request The request.
+ * @returns The exposition text, or an error answer.
+ */
+async function metricsResponse(context, request) {
+    const metrics = context.metrics();
+    if (metrics == null)
+        return jsonResponse(HTTP_NOT_FOUND, { error: "metrics are disabled" });
+    const state = context.state();
+    if (state.config.metrics.requireAdminToken && !hasAdminToken(state, request))
+        return jsonResponse(HTTP_FORBIDDEN, { error: "forbidden" });
+    return new Response(await metrics.render(), { status: HTTP_OK, headers: { "content-type": metrics.contentType } });
+}
+/**
+ * The admin check of an admin route (D15): the admin API exists only with a configured token.
+ * @param context What the routes read.
+ * @param request The request.
+ * @returns 404 when no admin token is configured, 401 on a missing or wrong bearer token, or null to go on.
+ */
+function requireAdmin(context, request) {
+    const state = context.state();
+    if (state.config.admin.token == null)
+        return jsonResponse(HTTP_NOT_FOUND, { error: "not found" });
+    if (!hasAdminToken(state, request))
+        return jsonResponse(HTTP_UNAUTHORIZED, { error: "unauthorized" });
+    return null;
+}
+/**
+ * Passes a legacy admin answer through, auditing it when it succeeded (the answer itself is unchanged).
+ * @param context What the routes read.
+ * @param action The audit action.
+ * @param target The room id or session name, or null.
+ * @param response The answer.
+ * @returns The same answer.
+ */
+function audited(context, action, target, response) {
+    if (response.status < FIRST_FAILURE_STATUS)
+        context.auditLegacyAdmin?.(action, target);
+    return response;
+}
+/**
+ * The session name of a dedicated start body, for the audit target.
+ * @param body The parsed body.
+ * @returns The session name, or null.
+ */
+function dedicatedSessionNameOf(body) {
+    return isDedicatedStartBody(body) ? body.sessionName : null;
+}
+/**
+ * Whether a request carries the admin bearer token (constant-time compare). The admin console also accepts it as a
+ * full-access key (game-server-admin-console D18).
+ * @param state The server state.
+ * @param request The request.
+ * @returns True when an admin token is configured and the request's bearer token equals it.
+ */
+export function hasAdminToken(state, request) {
+    const adminToken = state.config.admin.token;
+    const authorization = request.getHeader("authorization");
+    if (adminToken == null || authorization == null || !authorization.startsWith(BEARER_PREFIX))
+        return false;
+    return secretsMatch(authorization.substring(BEARER_PREFIX.length).trim(), adminToken);
+}
+/**
+ * Every session room the matchmaker knows (every instance when scaled out through Redis).
+ * @returns The sessions.
+ */
+async function listSessions() {
+    const rooms = await matchMaker.query({ name: SESSION_ROOM_NAME });
+    return rooms.map((room) => ({
+        roomId: room.roomId,
+        sessionName: String(room.metadata?.sessionName ?? ""),
+        gameMode: room.metadata?.gameMode ?? null,
+        players: room.clients,
+        maxPlayers: room.maxClients,
+        isDedicated: room.metadata?.isDedicated === true
+    }));
+}
+/**
+ * Starts a dedicated session of a configured scene (D19).
+ * @param context What the routes read.
+ * @param body The request body.
+ * @returns 201 { roomId }; 400 without string sceneName and sessionName; 404 for an unknown scene; 503 when the scene
+ *     fails to start (logged).
+ */
+async function startDedicated(context, body) {
+    if (!isDedicatedStartBody(body))
+        return jsonResponse(HTTP_BAD_REQUEST, { error: "the body needs string sceneName and sessionName" });
+    if (context.state().registry.find(body.sceneName) == null)
+        return jsonResponse(HTTP_NOT_FOUND, { error: "no dedicated scene named " + body.sceneName });
+    try {
+        const roomId = await context.startDedicatedSession(body.sessionName, body.sceneName, "admin");
+        return jsonResponse(HTTP_CREATED, { roomId: roomId });
+    }
+    catch (error) {
+        getLogger().error("the dedicated session did not start", { sessionName: body.sessionName, sceneName: body.sceneName, error: String(error) });
+        return jsonResponse(HTTP_SERVICE_UNAVAILABLE, { error: "the dedicated session did not start: " + String(error) });
+    }
+}
+/**
+ * Whether a request body names a scene and a session.
+ * @param body The parsed body.
+ * @returns True when sceneName and sessionName are both text.
+ */
+function isDedicatedStartBody(body) {
+    if (body == null || typeof body !== "object")
+        return false;
+    const fields = body;
+    return typeof fields.sceneName === "string" && typeof fields.sessionName === "string";
+}
+/**
+ * Starts a drain without exiting the process (the CLI's signal handlers exit; the admin route does not).
+ * @param context What the routes read.
+ * @returns 202 { draining: true } at once; the drain goes on in the background.
+ */
+function startDrain(context) {
+    context.drain().catch((error) => getLogger().error("drain failed", { error: String(error) }));
+    return jsonResponse(HTTP_ACCEPTED, { draining: true });
+}
+/**
+ * Closes a session room: its clients are disconnected with CloseCode.CONSENTED.
+ * @param roomId The room id.
+ * @returns 200 { closed: roomId }, or 404 when no such room exists.
+ */
+async function closeSession(roomId) {
+    const room = await matchMaker.getRoomById(roomId);
+    if (room == null)
+        return jsonResponse(HTTP_NOT_FOUND, { error: "no such session" });
+    await matchMaker.remoteRoomCall(roomId, "disconnect", [CloseCode.CONSENTED]);
+    return jsonResponse(HTTP_OK, { closed: roomId });
+}
+/**
+ * A JSON answer.
+ * @param status The HTTP status.
+ * @param body The value sent as JSON.
+ * @returns The response.
+ */
+export function jsonResponse(status, body) {
+    return new Response(JSON.stringify(body), { status: status, headers: { "content-type": "application/json" } });
+}
+/**
+ * The public description of the running server: name, version, protocol version, transports and whether auth is on.
+ * @param context What the routes read.
+ * @returns The info.
+ */
+export function buildServerInfo(context) {
+    const state = context.state();
+    const webTransport = state.config.udp.enabled ? { port: context.listeningPort(), certificateHash: context.webTransportCertificateHash() } : null;
+    return {
+        serverName: SERVER_NAME,
+        serverVersion: SERVER_VERSION,
+        protocolVersion: getToolkitRuntime().TOOLKIT.NETWORK_PROTOCOL_VERSION,
+        transports: { webSocket: true, webTransport: webTransport },
+        authRequired: state.config.auth.enabled,
+        discordSignIn: state.discordSessions != null
+    };
+}