@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/GameServer.js

@@ -0,0 +1,647 @@
+import { createRouter, defineRoom, defineServer, matchMaker, RedisDriver, RedisPresence } from "colyseus";
+import { WebSocketTransport } from "@colyseus/ws-transport";
+import { Redis } from "ioredis";
+import { createServer as createHttpsServer } from "node:https";
+import { createServer as createNetServer } from "node:net";
+import path from "node:path";
+import { installClientAddressHeaders, JoinRateLimiter } from "./AbuseLimits.js";
+import { createTokenVerifier } from "./Authentication.js";
+import { BOOT_SESSION_LEASE_NAME, BootSessionOwner } from "./BootSessionOwner.js";
+import { DedicatedSceneRegistry } from "./DedicatedSceneRegistry.js";
+import { DedicatedSession, SESSION_ROOM_NAME } from "./DedicatedSession.js";
+import { colyseusLoggerAdapter } from "./ColyseusLoggerAdapter.js";
+import { createDualTransport } from "./DualTransport.js";
+import { CONFIG_OPTIONS, effectiveLogFormat, resolveGameServerConfig } from "./GameServerConfig.js";
+import { GameServerLobbyRoom } from "./GameServerLobbyRoom.js";
+import { GameServerMetrics } from "./GameServerMetrics.js";
+import { GameServerLogger, getLogger, setLogger } from "./GameServerLogger.js";
+import { findGameServerState, setGameServerState } from "./GameServerState.js";
+import { SessionRoom } from "./SessionRoom.js";
+import { allowScriptUrlPrefixes, loadToolkitRuntime, resetScriptUrlAllowList } from "./HeadlessRuntime.js";
+import { createGameServerRoutes } from "./ServerEndpoints.js";
+import { loadTlsMaterial, stopWatchingTlsFiles, watchTlsFiles } from "./TlsCertificates.js";
+import { SYSTEM_CLOCK } from "./admin/AdminClock.js";
+import { AdminExtensionsHost } from "./admin/AdminExtensionsHost.js";
+import { createAdminConsole } from "./admin/AdminConsole.js";
+import { FLEET_HEARTBEAT_INTERVAL_MS, LEADER_TICK_MS, METRICS_SAMPLE_INTERVAL_MS, PAGERDUTY_EVENTS_URL } from "./admin/AdminConstants.js";
+import { openAdminStore } from "./admin/AdminStore.js";
+import { KickBlockList } from "./admin/BanList.js";
+import { LogBuffer } from "./admin/LogBuffer.js";
+import { openLeaderboardRankStore } from "./leaderboards/LeaderboardRankStore.js";
+import { LeaderboardService } from "./leaderboards/LeaderboardService.js";
+import { createLeaderboardRoutes } from "./leaderboards/LeaderboardPublicApi.js";
+import { LEADERBOARD_SCHEDULER_TICK_MS } from "./leaderboards/LeaderboardConstants.js";
+import { DiscordSessions } from "./discord/DiscordSessions.js";
+import { discordEndpoints } from "./discord/DiscordOAuth.js";
+import { DISCORD_API_BASE_URL } from "./discord/DiscordSignInConstants.js";
+import { createDiscordSignInRoutes } from "./discord/DiscordSignInRoutes.js";
+/** Milliseconds between WebSocket keep-alive pings. */
+const PING_INTERVAL_MS = 10000;
+/** Bind addresses that mean "every interface"; URLs show them as localhost. */
+const WILDCARD_HOSTS = ["0.0.0.0", "::"];
+/** Host name the URLs show for a wildcard bind address. */
+const LOCAL_HOST_NAME = "localhost";
+/** CORS header naming the origin allowed to read a response. */
+const ALLOW_ORIGIN_HEADER = "Access-Control-Allow-Origin";
+/** Seconds the drain watchdog allows beyond drainSeconds before it exits with code 1 (D17). */
+const DRAIN_EXIT_MARGIN_SECONDS = 5;
+/** Milliseconds between the drain's checks for remaining session rooms. */
+const DRAIN_POLL_INTERVAL_MS = 250;
+/** Key the readiness probe asks Redis about; it never exists, the answer only proves Redis replies (D18). */
+const READINESS_PROBE_KEY = "babylon-game-server:readiness-probe";
+/** Milliseconds Redis has to answer the readiness probe. */
+const REDIS_PROBE_TIMEOUT_MS = 1000;
+/** Set by PM2 to each process's number. Hosts that do not number their processes run boot sessions directly. */
+const PROCESS_NUMBER_VARIABLE = "NODE_APP_INSTANCE";
+/** Milliseconds per second. */
+const MILLISECONDS_PER_SECOND = 1000;
+/** The name better-call gives the errors an endpoint throws on purpose (answered with their status, not failures). */
+const ROUTER_API_ERROR_NAME = "APIError";
+/** The signals the CLI drains on. */
+const DRAIN_SIGNALS = ["SIGTERM", "SIGINT"];
+/** Exit code after a drain that an uncaught error started, so the process manager records a crash. */
+const CRASH_EXIT_CODE = 1;
+/**
+ * Presence set of the processes that are draining. The matchmaker never creates a room on them, because Colyseus
+ * re-lists a process in its room counts on every room change until its final shutdown, and a drain lasts drainSeconds.
+ */
+const DRAINING_PROCESSES_KEY = "babylon-game-server:draining";
+/** ISO time the running drain closes the remaining sessions, or null while no drain runs (one server per process). */
+let drainDeadline = null;
+/**
+ * Starts the Babylon Game Server: the lobby room "fusion_lobby" and the session room "fusion_session", filtered by
+ * session name and listed in the lobby in real time. The toolkit runtime is loaded first so rooms run the browser's
+ * session logic. Programmatic callers pass overrides of the defaults; the CLI passes its loaded config (D3). Once it
+ * listens, the config's boot dedicated sessions start (D19), and with handleSignals SIGTERM/SIGINT or an uncaught error
+ * drain it (D17). A draining process gets no new rooms from the matchmaker of any process.
+ * @param options The config overrides, hooks, extra routes and signal handling.
+ * @returns The running server.
+ * @throws GameServerConfigError when the config is invalid; Error "admin extension <name>: <problem>" for a bad
+ *     options.admin definition; Error when a boot dedicated session cannot start (the server is stopped again first).
+ */
+export async function createGameServer(options = {}) {
+    if (findGameServerState() != null)
+        throw new Error("a Babylon Game Server is already running in this process");
+    const config = resolveGameServerConfig(options.config ?? {});
+    // Extension definitions are checked before anything starts (D25).
+    const extensions = new AdminExtensionsHost(options.admin ?? {});
+    drainDeadline = null;
+    // Admin tests set their own logger first to read what the server logs (the setup link); only they keep it.
+    if (options.adminTesting == null)
+        setLogger(new GameServerLogger(effectiveLogFormat(config), config.logLevel));
+    if (!config.admin.console)
+        return startConfiguredServer(options, config, extensions, null);
+    // The console's log buffer captures from here on, so every line of this server is in it (D21).
+    const logBuffer = new LogBuffer(config.admin.logBufferEntries);
+    getLogger().addSink(logBuffer.sink);
+    try {
+        return await startConfiguredServer(options, config, extensions, logBuffer);
+    }
+    catch (error) {
+        getLogger().removeSink(logBuffer.sink);
+        throw error;
+    }
+}
+/**
+ * Starts a server of a resolved config (createGameServer's work once the logger and the log buffer are in place).
+ * @param options The options of createGameServer.
+ * @param config The resolved config.
+ * @param extensions The checked admin extensions (D25).
+ * @param logBuffer The console's log buffer (already attached to the logger), or null while the console is off.
+ * @returns The running server.
+ * @throws Error when the server cannot start (see createGameServer).
+ */
+async function startConfiguredServer(options, config, extensions, logBuffer) {
+    const detachLogBuffer = () => {
+        if (logBuffer != null)
+            getLogger().removeSink(logBuffer.sink);
+    };
+    await loadToolkitRuntime();
+    const state = createServerState(config, options.hooks ?? {}, options.configSources ?? codeConfigSources());
+    state.logBuffer = logBuffer;
+    const metrics = config.metrics.enabled ? new GameServerMetrics(() => state) : null;
+    state.metrics = metrics;
+    const requestedPort = await resolveRequestedPort(config);
+    const tlsMaterial = await loadTlsMaterial(config.tls, config.udp.enabled);
+    state.tlsMaterial = tlsMaterial;
+    const transport = await createTransport(config, tlsMaterial);
+    // Only the configured scene roots and scripts may load from now on; close turns the allow-list off again (D19).
+    allowScriptUrlPrefixes(state.registry.allowedUrlPrefixes());
+    let gameServer = null;
+    let listening = false;
+    const requireGameServer = () => {
+        if (gameServer == null)
+            throw new Error("the game server is not listening");
+        return gameServer;
+    };
+    // One ioredis client serves presence and the admin store; RedisPresence.shutdown() quits it (R4).
+    const redisClient = (config.redis.url != null) ? new Redis(config.redis.url) : null;
+    const redisPresence = (redisClient != null) ? new RedisPresence(redisClient) : null;
+    const routeContext = {
+        state: () => state,
+        listeningPort: () => listeningPort(transport, requestedPort),
+        webTransportCertificateHash: () => transport.fingerprint ?? null,
+        isListening: () => listening,
+        urls: () => buildUrls(config, listeningPort(transport, requestedPort)),
+        metrics: () => metrics,
+        isRedisReachable: (redisPresence != null) ? () => isRedisReachable(redisPresence) : async () => true,
+        drain: () => requireGameServer().drain(),
+        drainDeadline: () => drainDeadline,
+        startDedicatedSession: (sessionName, sceneName, startedBy) => startConfiguredDedicatedSession(state.registry, sessionName, sceneName, startedBy)
+    };
+    const adminTesting = options.adminTesting ?? {};
+    const adminStore = await openAdminStore(config, redisClient, adminTesting.clock ?? SYSTEM_CLOCK);
+    state.discordSessions = config.discordSignIn.enabled ? await DiscordSessions.open(adminStore, adminTesting.clock ?? SYSTEM_CLOCK, config.discordSignIn.sessionDays) : null;
+    const leaderboardRankStore = await openLeaderboardRankStore(path.resolve(config.admin.dataDir), redisClient, adminStore.isPersistent);
+    const leaderboards = await LeaderboardService.open({ config: config, state: state, adminStore: adminStore, rankStore: leaderboardRankStore, clock: adminTesting.clock ?? SYSTEM_CLOCK, processId: () => matchMaker.processId, schedulerTickMs: adminTesting.leaderboardSchedulerTickMs ?? LEADERBOARD_SCHEDULER_TICK_MS });
+    const adminConsole = config.admin.console ? await createAdminConsole(createAdminServices(state, adminStore, routeContext, adminTesting, extensions, leaderboards)) : null;
+    const server = defineServer({
+        transport: transport,
+        gracefullyShutdown: false,
+        presence: redisPresence ?? undefined,
+        logger: colyseusLoggerAdapter,
+        driver: (config.redis.url != null) ? new RedisDriver(config.redis.url) : undefined,
+        publicAddress: config.publicAddress ?? undefined,
+        selectProcessIdToCreateRoom: selectProcessForNewRoom,
+        rooms: {
+            fusion_lobby: defineRoom(GameServerLobbyRoom),
+            fusion_session: defineRoom(SessionRoom).filterBy(["sessionName"]).enableRealtimeListing()
+        },
+        routes: createRouter({ ...createGameServerRoutes(routeContext), ...createLeaderboardRoutes(leaderboards, state), ...createDiscordSignInRoutes({ state: () => state, store: adminStore, leaderboards: leaderboards, clock: adminTesting.clock ?? SYSTEM_CLOCK, endpoints: discordEndpoints(options.discordTesting?.apiBaseUrl ?? DISCORD_API_BASE_URL) }), ...(adminConsole?.routes() ?? {}), ...(options.routes ?? {}) }, { onRequest: (request) => adminConsole?.redirectBarePath(request), onError: logRouterError })
+    });
+    const restoreCorsHeaders = installCorsOverride(config.limits);
+    setGameServerState(state);
+    try {
+        await server.listen(requestedPort, config.host);
+    }
+    catch (error) {
+        setGameServerState(null);
+        resetScriptUrlAllowList();
+        restoreCorsHeaders();
+        await leaderboards.stop();
+        throw error;
+    }
+    listening = true;
+    installClientAddressHeaders(transport.server, config.trustProxy);
+    watchTlsFiles(config.tls, (material) => {
+        // The console's certificate expiry reads the served certificate (game-server-admin-console T10).
+        state.tlsMaterial = material;
+        applyRenewedCertificate(transport.server, material, config.udp.enabled);
+        adminConsole?.recordServerEvent("certificate reloaded");
+    });
+    await adminConsole?.start();
+    await leaderboards.start();
+    const port = listeningPort(transport, requestedPort);
+    let removeSignalHandlers = () => undefined;
+    let drainPromise = null;
+    let stopPromise = null;
+    const bootSessionOwner = createBootSessionOwner(config, state, adminStore);
+    const shutDown = async () => {
+        listening = false;
+        removeSignalHandlers();
+        stopWatchingTlsFiles();
+        bootSessionOwner?.stop();
+        // The console stops first, so its timers never touch presence or the store after they close (R4).
+        await adminConsole?.stop();
+        await leaderboards.stop();
+        await forgetDrainingProcess();
+        await server.gracefullyShutdown(false);
+        await adminStore.close();
+        restoreCorsHeaders();
+        resetScriptUrlAllowList();
+        setGameServerState(null);
+        detachLogBuffer();
+    };
+    // close() after (or during) a drain, or a second close(), waits for the one shutdown instead of starting another.
+    const stopServer = () => {
+        stopPromise ??= shutDown();
+        return stopPromise;
+    };
+    gameServer = {
+        config: config,
+        port: port,
+        urls: buildUrls(config, port),
+        close: stopServer,
+        drain: () => {
+            drainPromise ??= drainServer(state, stopServer);
+            return drainPromise;
+        },
+        startDedicatedSession: (sessionName, sceneName) => startConfiguredDedicatedSession(state.registry, sessionName, sceneName, "code")
+    };
+    // Before the boot sessions: on Colyseus Cloud players are routed here as soon as the socket listens.
+    if (options.handleSignals === true)
+        removeSignalHandlers = installProcessHandlers(gameServer);
+    try {
+        if (bootSessionOwner != null)
+            await bootSessionOwner.start();
+        else
+            await startBootSessions(config, state.registry);
+    }
+    catch (error) {
+        await stopServer();
+        throw error;
+    }
+    return gameServer;
+}
+/**
+ * Drains the server (D17): new joins are refused with GameClosed and readiness turns 503 at once; running sessions get
+ * drainSeconds to end by themselves (the deadline is kept for routeContext.drainDeadline, game-server-admin-console
+ * §7.7); the rooms still open then tell their players GameClosed and disconnect with
+ * CloseCode.SERVER_SHUTDOWN; finally the server stops.
+ * @param state The server state.
+ * @param stopServer Stops the transport, presence and driver and clears the state.
+ * @returns Resolves once the server stopped.
+ */
+async function drainServer(state, stopServer) {
+    state.draining = true;
+    await rememberDrainingProcess();
+    getLogger().info("waiting for sessions to end", { sessions: state.sessionRooms.size, drainSeconds: state.config.drainSeconds });
+    const deadline = Date.now() + state.config.drainSeconds * MILLISECONDS_PER_SECOND;
+    drainDeadline = new Date(deadline).toISOString();
+    while (state.sessionRooms.size > 0 && Date.now() < deadline)
+        await delay(DRAIN_POLL_INTERVAL_MS);
+    const remainingRooms = Array.from(state.sessionRooms);
+    await Promise.all(remainingRooms.map((room) => room.closeForShutdown()));
+    await stopServer();
+    getLogger().info("drained", { closedSessions: remainingRooms.length });
+}
+/**
+ * Picks the process a new room is created on: the one with the fewest rooms among those that are not draining, as
+ * Colyseus' default does among all of them. When every process drains, all of them stay candidates, so creating a room
+ * behaves as before (a draining process refuses the join with GameClosed).
+ * @returns The chosen process id.
+ */
+async function selectProcessForNewRoom() {
+    const drainingIds = new Set(await matchMaker.presence.smembers(DRAINING_PROCESSES_KEY));
+    const processes = await matchMaker.stats.fetchAll();
+    const candidates = processes.filter((entry) => !drainingIds.has(entry.processId));
+    const pool = (candidates.length > 0) ? candidates : processes;
+    pool.sort((first, second) => first.roomCount - second.roomCount);
+    return pool[0]?.processId ?? matchMaker.processId;
+}
+/**
+ * Lists this process in DRAINING_PROCESSES_KEY, so no other process creates a room on it. A presence that cannot be
+ * reached is logged and the drain goes on.
+ */
+async function rememberDrainingProcess() {
+    try {
+        await matchMaker.presence.sadd(DRAINING_PROCESSES_KEY, matchMaker.processId);
+    }
+    catch (error) {
+        getLogger().warn("could not mark the process as draining", { error: String(error) });
+    }
+}
+/**
+ * Takes this process out of DRAINING_PROCESSES_KEY at shutdown (process ids are never reused, so this only keeps the
+ * set small). A presence that cannot be reached is ignored.
+ */
+async function forgetDrainingProcess() {
+    try {
+        await matchMaker.presence.srem(DRAINING_PROCESSES_KEY, matchMaker.processId);
+    }
+    catch {
+        // Redis is down or already closed; the stale id matches no live process.
+    }
+}
+/**
+ * Drains on SIGTERM or SIGINT and exits 0, and drains on an uncaught error (an unhandled rejection included) and exits
+ * CRASH_EXIT_CODE (D17). A watchdog exits 1 if the drain takes longer than drainSeconds plus DRAIN_EXIT_MARGIN_SECONDS.
+ * Only the first stop drains; a later uncaught error is logged. Colyseus' own handlers stay off (gracefullyShutdown:
+ * false), which also leaves the process without any uncaught-error handler of Colyseus.
+ * @param gameServer The running server.
+ * @returns Removes the handlers (close).
+ */
+function installProcessHandlers(gameServer) {
+    let stopping = false;
+    const drainAndExit = (exitCode) => {
+        stopping = true;
+        const watchdogMilliseconds = (gameServer.config.drainSeconds + DRAIN_EXIT_MARGIN_SECONDS) * MILLISECONDS_PER_SECOND;
+        setTimeout(() => {
+            getLogger().error("drain did not finish in time");
+            process.exit(1);
+        }, watchdogMilliseconds).unref();
+        gameServer.drain().then(() => process.exit(exitCode), (error) => {
+            getLogger().error("drain failed", { error: String(error) });
+            process.exit(1);
+        });
+    };
+    const onSignal = (signalName) => {
+        getLogger().info("draining", { signal: signalName });
+        if (!stopping)
+            drainAndExit(0);
+    };
+    const onUncaughtError = (error) => {
+        getLogger().error("uncaught error", { error: String(error), stack: error?.stack ?? null, draining: !stopping });
+        if (!stopping)
+            drainAndExit(CRASH_EXIT_CODE);
+    };
+    for (const signalName of DRAIN_SIGNALS)
+        process.once(signalName, onSignal);
+    process.on("uncaughtException", onUncaughtError);
+    return () => {
+        for (const signalName of DRAIN_SIGNALS)
+            process.removeListener(signalName, onSignal);
+        process.removeListener("uncaughtException", onUncaughtError);
+    };
+}
+/**
+ * The router's onError hook (game-server-admin-console D21): a handler that failed is logged, so it reaches the console's
+ * log buffer; errors an endpoint throws on purpose are answered with their status and not logged. The router then
+ * answers 500 as before.
+ * @param error What the handler threw.
+ */
+function logRouterError(error) {
+    if (error?.name === ROUTER_API_ERROR_NAME)
+        return;
+    getLogger().error("router handler failed", { error: String(error) });
+}
+/**
+ * Whether Redis answers within REDIS_PROBE_TIMEOUT_MS (D18).
+ * @param presence The Redis presence.
+ * @returns True when the probe answered in time.
+ */
+async function isRedisReachable(presence) {
+    try {
+        return await Promise.race([presence.exists(READINESS_PROBE_KEY).then(() => true), delay(REDIS_PROBE_TIMEOUT_MS).then(() => false)]);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolves after a while.
+ * @param milliseconds How long to wait.
+ * @returns Resolves after the wait.
+ */
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+/**
+ * The transport of a config (§Control flow): HTTP/3 + HTTPS + WSS on one port when UDP is on, WSS on an HTTPS server
+ * when only TLS is on, else plain WebSocket.
+ * @param config The config.
+ * @param tlsMaterial The HTTPS certificate and key, or null (TLS off, or the pinned HTTP/3 certificate serves HTTPS).
+ * @returns The transport.
+ * @throws Error when UDP is on and @colyseus/h3-transport is missing.
+ */
+async function createTransport(config, tlsMaterial) {
+    const maxPayload = config.limits.maxMessageBytes;
+    if (config.udp.enabled) {
+        return createDualTransport({ cert: tlsMaterial?.cert ?? null, key: tlsMaterial?.key ?? null, pinHttp3Certificate: config.tls.developmentCertificate, maxPayload: maxPayload });
+    }
+    if (tlsMaterial == null)
+        return new WebSocketTransport({ pingInterval: PING_INTERVAL_MS, maxPayload: maxPayload });
+    const httpsServer = createHttpsServer({ cert: tlsMaterial.cert, key: tlsMaterial.key });
+    return new WebSocketTransport({ server: httpsServer, pingInterval: PING_INTERVAL_MS, maxPayload: maxPayload });
+}
+/**
+ * Puts a renewed certificate on the HTTPS server without a restart (D9). HTTP/3 has no reload API, so with UDP on it
+ * keeps the old certificate until the next restart, which is logged.
+ * @param httpsServer The transport's HTTPS server.
+ * @param material The renewed certificate and key.
+ * @param udpEnabled True when HTTP/3 runs.
+ */
+function applyRenewedCertificate(httpsServer, material, udpEnabled) {
+    httpsServer.setSecureContext({ cert: material.cert, key: material.key });
+    getLogger().info("certificate reloaded");
+    if (udpEnabled)
+        getLogger().warn("HTTP/3 uses the new certificate after a restart");
+}
+/**
+ * The port to listen on. TCP and UDP must share one port (D8), so with UDP on, port 0 becomes one free TCP port picked
+ * up front (HTTP/3 would otherwise pick its own, different UDP port).
+ * @param config The config.
+ * @returns The configured port, or the free port picked for 0 with UDP on.
+ */
+async function resolveRequestedPort(config) {
+    if (config.port !== 0 || !config.udp.enabled)
+        return config.port;
+    return new Promise((resolve, reject) => {
+        const probe = createNetServer();
+        probe.once("error", reject);
+        probe.listen(0, config.host, () => {
+            const address = probe.address();
+            const freePort = (address != null && typeof address === "object") ? address.port : 0;
+            probe.close(() => resolve(freePort));
+        });
+    });
+}
+/**
+ * The process state the join gate and the rooms read (D10). createGameServer sets its metrics when they are on (D16).
+ * @param config The resolved config.
+ * @param hooks The server's hooks.
+ * @param configSources Where each option came from.
+ * @returns The state.
+ * @throws GameServerConfigError when auth mode "custom" has no verifyToken hook.
+ */
+function createServerState(config, hooks, configSources) {
+    const customVerifier = (hooks.verifyToken != null) ? hooks.verifyToken.bind(hooks) : null;
+    const verifier = config.auth.enabled ? createTokenVerifier(config.auth, customVerifier) : null;
+    return {
+        config: config,
+        hooks: hooks,
+        verifier: verifier,
+        discordSessions: null,
+        configSources: configSources,
+        rateLimiter: new JoinRateLimiter(config.limits.joinRequestsPerMinutePerAddress),
+        metrics: null,
+        registry: new DedicatedSceneRegistry(config.dedicated.scenes, process.cwd()),
+        draining: false,
+        maintenance: null,
+        sessionRooms: new Set(),
+        lobbyRooms: new Set(),
+        banList: null,
+        kickBlocks: new KickBlockList(() => matchMaker.presence),
+        onPlayerSessionEvent: null,
+        onLeaderboardSessionPresence: null,
+        logBuffer: null,
+        tlsMaterial: null,
+        startedAt: new Date().toISOString()
+    };
+}
+/**
+ * The sources of a server made from code (game-server-admin-console D20): every option counts as "code".
+ * @returns The sources.
+ */
+function codeConfigSources() {
+    return Object.fromEntries(CONFIG_OPTIONS.map((definition) => [definition.path, "code"]));
+}
+/**
+ * The core services of the admin console (game-server-admin-console DR §6.3, R5, R10): the defaults, or the test values
+ * of adminTesting.
+ * @param state The server state.
+ * @param store The admin data store.
+ * @param routeContext What the legacy routes read.
+ * @param adminTesting The test overrides (empty outside tests).
+ * @param extensions The checked admin extensions (D25).
+ * @param leaderboards The leaderboard service.
+ * @returns The services.
+ */
+function createAdminServices(state, store, routeContext, adminTesting, extensions, leaderboards) {
+    return {
+        config: state.config,
+        state: state,
+        store: store,
+        routeContext: routeContext,
+        processId: () => matchMaker.processId,
+        clock: adminTesting.clock ?? SYSTEM_CLOCK,
+        heartbeatIntervalMs: adminTesting.heartbeatIntervalMs ?? FLEET_HEARTBEAT_INTERVAL_MS,
+        metricsSampleIntervalMs: adminTesting.metricsSampleIntervalMs ?? METRICS_SAMPLE_INTERVAL_MS,
+        leaderTickMs: adminTesting.leaderTickMs ?? LEADER_TICK_MS,
+        pagerDutyUrl: adminTesting.pagerDutyUrl ?? PAGERDUTY_EVENTS_URL,
+        colyseusCloudRefreshed: adminTesting.colyseusCloudRefreshed ?? ignoreRefreshPass,
+        extensions: extensions,
+        leaderboards: leaderboards
+    };
+}
+/** The default Colyseus Cloud refresh hook: nothing to report outside tests. */
+function ignoreRefreshPass() {
+    // Nothing to report outside tests (colyseus-cloud-console D17).
+}
+/**
+ * Replaces Colyseus' CORS answer with the origin allow-list (D14). Core merges its defaults (Allow-Origin "*") before
+ * this function's result, so the result always names an origin: the request's when it is allowed, else the first
+ * allowed origin, which a browser on any other origin rejects.
+ * @param limits The limits config.
+ * @returns Puts the original function back (close).
+ */
+function installCorsOverride(limits) {
+    const originalCorsHeaders = matchMaker.controller.getCorsHeaders;
+    matchMaker.controller.getCorsHeaders = (headers) => {
+        const requestHeaders = headers ?? new Headers();
+        const originalAnswer = originalCorsHeaders.call(matchMaker.controller, requestHeaders);
+        if (limits.allowedOrigins.length === 0)
+            return originalAnswer;
+        const origin = requestHeaders.get("origin");
+        const allowedOrigin = (origin != null && limits.allowedOrigins.includes(origin)) ? origin : limits.allowedOrigins[0];
+        return Object.assign({}, originalAnswer, { [ALLOW_ORIGIN_HEADER]: allowedOrigin, Vary: "Origin" });
+    };
+    return () => {
+        matchMaker.controller.getCorsHeaders = originalCorsHeaders;
+    };
+}
+/**
+ * The URLs of a server: the public URL when configured, else derived from the bind address, port and TLS.
+ * @param config The config.
+ * @param port The listening port.
+ * @returns The URLs.
+ */
+function buildUrls(config, port) {
+    const secure = config.tls.enabled;
+    const displayHost = WILDCARD_HOSTS.includes(config.host) ? LOCAL_HOST_NAME : config.host;
+    const derivedHost = (displayHost.includes(":") ? "[" + displayHost + "]" : displayHost) + ":" + port;
+    const webSocket = config.publicUrl ?? (secure ? "wss" : "ws") + "://" + derivedHost;
+    const http = webSocket.replace(/^ws/, "http");
+    // UDP requires TLS, so the HTTP URL is already https:// and names the same host and port as HTTP/3.
+    return { webSocket: webSocket, http: http, webTransport: config.udp.enabled ? http : null };
+}
+/**
+ * Starts a dedicated session of a configured scene (D19).
+ * @param registry The configured dedicated scenes.
+ * @param sessionName The session name clients join.
+ * @param sceneName The configured scene.
+ * @param startedBy Who starts it, as the console shows it (game-server-admin-console T9).
+ * @param createOnThisProcess True creates the room here rather than on the process the matchmaker picks.
+ * @returns The room id.
+ * @throws Error("no dedicated scene named <name>") for an unknown scene; Error when the scene cannot be loaded.
+ */
+function startConfiguredDedicatedSession(registry, sessionName, sceneName, startedBy, createOnThisProcess = false) {
+    const scene = registry.find(sceneName);
+    if (scene == null)
+        return Promise.reject(new Error("no dedicated scene named " + sceneName));
+    return DedicatedSession.start({
+        sessionName: sessionName,
+        sceneRootUrl: scene.sceneRootUrl,
+        sceneFile: scene.sceneFile,
+        playerCount: scene.maxPlayers,
+        projectScripts: scene.projectScripts,
+        sceneName: sceneName,
+        startedBy: startedBy,
+        createOnThisProcess: createOnThisProcess
+    });
+}
+/**
+ * Starts the config's boot dedicated sessions, in order, once the server listens (§Control flow step 9), on a host that
+ * does not number its processes.
+ * @param config The resolved config.
+ * @param registry The configured dedicated scenes.
+ * @throws Error when a boot session cannot start.
+ */
+async function startBootSessions(config, registry) {
+    for (const boot of config.dedicated.boot)
+        await startConfiguredDedicatedSession(registry, boot.sessionName, boot.sceneName, "boot");
+}
+/**
+ * The owner of the boot sessions on a host that numbers its processes, where a rolling deploy can restart any of them.
+ * @param config The resolved config.
+ * @param state The server state.
+ * @param adminStore The store holding the lease.
+ * @returns The owner, not started yet; null when startBootSessions applies or there are no boot sessions.
+ */
+function createBootSessionOwner(config, state, adminStore) {
+    if (process.env[PROCESS_NUMBER_VARIABLE] === undefined || config.dedicated.boot.length === 0)
+        return null;
+    return new BootSessionOwner({
+        tryAcquireLease: (holderId, ttlMilliseconds) => adminStore.tryAcquireLease(BOOT_SESSION_LEASE_NAME, holderId, ttlMilliseconds),
+        startSessions: createLeasedBootStarter(config, state.registry),
+        holderId: () => matchMaker.processId,
+        isDraining: () => state.draining,
+        clock: SYSTEM_CLOCK
+    });
+}
+/**
+ * The start function of a BootSessionOwner. A session whose name already runs waits: during a rolling deploy the draining
+ * process keeps its boot session until it ends, a second room of that name would split its joiners, and the matchmaker
+ * does not refuse one. Each call skips the sessions an earlier call started. Rooms are created on this process, so a
+ * session never lands on a draining process, and it ends with the process that holds the lease, which lets the next
+ * holder start it again.
+ * @param config The resolved config.
+ * @param registry The configured dedicated scenes.
+ * @returns Starts what can start; resolves true when every boot session has started, false when one must wait.
+ */
+function createLeasedBootStarter(config, registry) {
+    const startedSessionNames = new Set();
+    const waitingSessionNames = new Set();
+    return async () => {
+        let mustWait = false;
+        for (const boot of config.dedicated.boot) {
+            if (startedSessionNames.has(boot.sessionName))
+                continue;
+            if (await isSessionRunning(boot.sessionName)) {
+                mustWait = true;
+                // A wait can last the whole drain of the old process, so it logs once rather than on every tick.
+                if (!waitingSessionNames.has(boot.sessionName))
+                    getLogger().info("boot dedicated session \"" + boot.sessionName + "\" waits for the running session of that name to end", { sessionName: boot.sessionName });
+                waitingSessionNames.add(boot.sessionName);
+                continue;
+            }
+            await startConfiguredDedicatedSession(registry, boot.sessionName, boot.sceneName, "boot", true);
+            startedSessionNames.add(boot.sessionName);
+        }
+        return !mustWait;
+    };
+}
+/**
+ * Whether a live process runs a session room of a name. A listing whose process no longer answers is a crash leftover:
+ * the health check removes it, and it must not hold the session back.
+ * @param sessionName The session name.
+ * @returns True when this process or another one that answers lists it, locked or not.
+ */
+async function isSessionRunning(sessionName) {
+    const conditions = { name: SESSION_ROOM_NAME, sessionName: sessionName };
+    for (const room of await matchMaker.query(conditions)) {
+        if (room.processId === matchMaker.processId || await matchMaker.healthCheckProcessId(room.processId) === true)
+            return true;
+    }
+    return false;
+}
+/**
+ * The port the transport actually listens on (the requested one, or the free port picked for 0).
+ * @param transport The transport.
+ * @param requestedPort The port passed to listen.
+ * @returns The listening port.
+ */
+function listeningPort(transport, requestedPort) {
+    const address = transport.server?.address();
+    return (address != null && typeof address === "object") ? address.port : requestedPort;
+}