@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/admin/ConsoleSessions.d.ts

@@ -0,0 +1,112 @@
+import type { AdminStore } from "./AdminStore.js";
+import type { AdminClock } from "./AdminClock.js";
+import type { AdminUserRecord, ConsoleSessionRecord } from "./AdminRecords.js";
+/** Where a sign-in comes from. */
+export interface SignInContext {
+    /** The client address. */
+    clientAddress: string;
+    /** The browser's User-Agent header. */
+    userAgent: string;
+}
+/** A live session with its account. */
+export interface ResolvedConsoleSession {
+    /** The session. */
+    record: ConsoleSessionRecord;
+    /** Its account. */
+    user: AdminUserRecord;
+}
+/** The console sessions of the admin store. */
+export declare class ConsoleSessions {
+    /** The admin store. */
+    private readonly store;
+    /** The clock of timeouts. */
+    private readonly clock;
+    /** Idle timeout, in milliseconds (admin.sessionIdleMinutes). */
+    private readonly idleTimeoutMilliseconds;
+    /** Absolute timeout, in milliseconds (admin.sessionMaxHours). */
+    private readonly maximumLifetimeMilliseconds;
+    /**
+     * Creates the session service.
+     * @param store The admin store.
+     * @param clock The clock.
+     * @param sessionIdleMinutes Idle timeout, in minutes.
+     * @param sessionMaxHours Absolute timeout, in hours.
+     */
+    constructor(store: AdminStore, clock: AdminClock, sessionIdleMinutes: number, sessionMaxHours: number);
+    /** How long the browser keeps the cookie, in seconds (the absolute timeout). */
+    get cookieMaxAgeSeconds(): number;
+    /**
+     * Starts a session for an account that has just passed both factors.
+     * @param user The account.
+     * @param context Where the sign-in came from.
+     * @returns The stored session and the cookie value (only its hash is stored).
+     */
+    create(user: AdminUserRecord, context: SignInContext): Promise<{
+        record: ConsoleSessionRecord;
+        cookieValue: string;
+    }>;
+    /**
+     * The live session of a cookie: timeouts applied (an expired session is deleted), lastSeenAt touched at most once
+     * per SESSION_TOUCH_INTERVAL_MS, and null for a disabled or deleted account.
+     * @param cookieValue The cookie value.
+     * @returns The session and its account, or null.
+     */
+    resolve(cookieValue: string): Promise<ResolvedConsoleSession | null>;
+    /**
+     * Records a fresh second-factor check on a session (step-up).
+     * @param sessionId The session's public id.
+     * @returns The updated session, or null when it no longer exists.
+     */
+    markSecondFactor(sessionId: string): Promise<ConsoleSessionRecord | null>;
+    /**
+     * Ends one session.
+     * @param sessionId The session's public id.
+     */
+    end(sessionId: string): Promise<void>;
+    /**
+     * Ends every session of an account.
+     * @param userId The account.
+     * @returns How many were ended.
+     */
+    endAllFor(userId: string): Promise<number>;
+    /**
+     * The live sessions of an account.
+     * @param userId The account.
+     * @returns Its sessions, newest first.
+     */
+    listFor(userId: string): Promise<ConsoleSessionRecord[]>;
+    /**
+     * Deletes expired sessions and expired pending sign-ins (every SESSION_SWEEP_INTERVAL_MS).
+     * @returns How many records were deleted.
+     */
+    sweepExpired(): Promise<number>;
+    /**
+     * When a session ends at the latest.
+     * @param record The session.
+     * @returns ISO time of its absolute timeout.
+     */
+    expiresAt(record: ConsoleSessionRecord): string;
+    /**
+     * Whether a session passed its idle or absolute timeout.
+     * @param record The session.
+     * @param now The current time, in milliseconds.
+     * @returns True when it has expired.
+     */
+    private isExpired;
+    /**
+     * Finds a session by its public id.
+     * @param sessionId The public id.
+     * @returns The stored session, or null.
+     */
+    private findBySessionId;
+    /**
+     * Every stored session of an account.
+     * @param userId The account.
+     * @returns Its session documents.
+     */
+    private documentsOf;
+    /**
+     * @returns The clock's now as an ISO time.
+     */
+    private nowIso;
+}

package/lib/admin/ConsoleSessions.js

@@ -0,0 +1,201 @@
+// Console sessions (game-server-admin-console D10): server-side records keyed by the SHA-256 of a random cookie value,
+// with an idle and an absolute timeout, a CSRF token and the time of the last second-factor check.
+import { SESSION_TOUCH_INTERVAL_MS } from "./AdminConstants.js";
+import { randomToken, sha256Hex } from "./AdminCrypto.js";
+/** Random bytes of a session cookie value. */
+const COOKIE_VALUE_BYTES = 32;
+/** Random bytes of a session's public id. */
+const SESSION_ID_BYTES = 8;
+/** Random bytes of a CSRF token. */
+const CSRF_TOKEN_BYTES = 32;
+/** Milliseconds per second. */
+const MILLISECONDS_PER_SECOND = 1000;
+/** Milliseconds per minute. */
+const MILLISECONDS_PER_MINUTE = 60000;
+/** Milliseconds per hour. */
+const MILLISECONDS_PER_HOUR = 3600000;
+/** The console sessions of the admin store. */
+export class ConsoleSessions {
+    /** The admin store. */
+    store;
+    /** The clock of timeouts. */
+    clock;
+    /** Idle timeout, in milliseconds (admin.sessionIdleMinutes). */
+    idleTimeoutMilliseconds;
+    /** Absolute timeout, in milliseconds (admin.sessionMaxHours). */
+    maximumLifetimeMilliseconds;
+    /**
+     * Creates the session service.
+     * @param store The admin store.
+     * @param clock The clock.
+     * @param sessionIdleMinutes Idle timeout, in minutes.
+     * @param sessionMaxHours Absolute timeout, in hours.
+     */
+    constructor(store, clock, sessionIdleMinutes, sessionMaxHours) {
+        this.store = store;
+        this.clock = clock;
+        this.idleTimeoutMilliseconds = sessionIdleMinutes * MILLISECONDS_PER_MINUTE;
+        this.maximumLifetimeMilliseconds = sessionMaxHours * MILLISECONDS_PER_HOUR;
+    }
+    /** How long the browser keeps the cookie, in seconds (the absolute timeout). */
+    get cookieMaxAgeSeconds() {
+        return Math.floor(this.maximumLifetimeMilliseconds / MILLISECONDS_PER_SECOND);
+    }
+    /**
+     * Starts a session for an account that has just passed both factors.
+     * @param user The account.
+     * @param context Where the sign-in came from.
+     * @returns The stored session and the cookie value (only its hash is stored).
+     */
+    async create(user, context) {
+        const cookieValue = randomToken(COOKIE_VALUE_BYTES);
+        const now = this.nowIso();
+        const record = {
+            sessionId: randomToken(SESSION_ID_BYTES),
+            userId: user.userId,
+            csrfToken: randomToken(CSRF_TOKEN_BYTES),
+            createdAt: now,
+            lastSeenAt: now,
+            secondFactorAt: now,
+            clientAddress: context.clientAddress,
+            userAgent: context.userAgent
+        };
+        await this.store.putDocument("consoleSessions", sha256Hex(cookieValue), record, 0);
+        return { record: record, cookieValue: cookieValue };
+    }
+    /**
+     * The live session of a cookie: timeouts applied (an expired session is deleted), lastSeenAt touched at most once
+     * per SESSION_TOUCH_INTERVAL_MS, and null for a disabled or deleted account.
+     * @param cookieValue The cookie value.
+     * @returns The session and its account, or null.
+     */
+    async resolve(cookieValue) {
+        const documentId = sha256Hex(cookieValue);
+        const stored = await this.store.getDocument("consoleSessions", documentId);
+        if (stored == null)
+            return null;
+        let record = stored.value;
+        const now = this.clock.now();
+        if (this.isExpired(record, now)) {
+            await this.store.deleteDocument("consoleSessions", documentId);
+            return null;
+        }
+        const user = await this.store.getDocument("users", record.userId);
+        if (user == null || user.value.disabled)
+            return null;
+        if (now - Date.parse(record.lastSeenAt) >= SESSION_TOUCH_INTERVAL_MS) {
+            record = Object.assign({}, record, { lastSeenAt: new Date(now).toISOString() });
+            await this.store.putDocument("consoleSessions", documentId, record, null);
+        }
+        return { record: record, user: user.value };
+    }
+    /**
+     * Records a fresh second-factor check on a session (step-up).
+     * @param sessionId The session's public id.
+     * @returns The updated session, or null when it no longer exists.
+     */
+    async markSecondFactor(sessionId) {
+        const stored = await this.findBySessionId(sessionId);
+        if (stored == null)
+            return null;
+        const record = Object.assign({}, stored.value, { secondFactorAt: this.nowIso() });
+        await this.store.putDocument("consoleSessions", stored.id, record, null);
+        return record;
+    }
+    /**
+     * Ends one session.
+     * @param sessionId The session's public id.
+     */
+    async end(sessionId) {
+        const stored = await this.findBySessionId(sessionId);
+        if (stored != null)
+            await this.store.deleteDocument("consoleSessions", stored.id);
+    }
+    /**
+     * Ends every session of an account.
+     * @param userId The account.
+     * @returns How many were ended.
+     */
+    async endAllFor(userId) {
+        const sessions = await this.documentsOf(userId);
+        for (const stored of sessions)
+            await this.store.deleteDocument("consoleSessions", stored.id);
+        return sessions.length;
+    }
+    /**
+     * The live sessions of an account.
+     * @param userId The account.
+     * @returns Its sessions, newest first.
+     */
+    async listFor(userId) {
+        const now = this.clock.now();
+        return (await this.documentsOf(userId))
+            .map((stored) => stored.value)
+            .filter((record) => !this.isExpired(record, now))
+            .sort((left, right) => right.createdAt.localeCompare(left.createdAt));
+    }
+    /**
+     * Deletes expired sessions and expired pending sign-ins (every SESSION_SWEEP_INTERVAL_MS).
+     * @returns How many records were deleted.
+     */
+    async sweepExpired() {
+        const now = this.clock.now();
+        let deletedCount = 0;
+        for (const stored of await this.store.listDocuments("consoleSessions")) {
+            if (!this.isExpired(stored.value, now))
+                continue;
+            if (await this.store.deleteDocument("consoleSessions", stored.id))
+                deletedCount++;
+        }
+        for (const stored of await this.store.listDocuments("pendingSignIns")) {
+            if (Date.parse(stored.value.expiresAt) > now)
+                continue;
+            if (await this.store.deleteDocument("pendingSignIns", stored.id))
+                deletedCount++;
+        }
+        return deletedCount;
+    }
+    /**
+     * When a session ends at the latest.
+     * @param record The session.
+     * @returns ISO time of its absolute timeout.
+     */
+    expiresAt(record) {
+        return new Date(Date.parse(record.createdAt) + this.maximumLifetimeMilliseconds).toISOString();
+    }
+    /**
+     * Whether a session passed its idle or absolute timeout.
+     * @param record The session.
+     * @param now The current time, in milliseconds.
+     * @returns True when it has expired.
+     */
+    isExpired(record, now) {
+        const idleFor = now - Date.parse(record.lastSeenAt);
+        const aliveFor = now - Date.parse(record.createdAt);
+        return idleFor > this.idleTimeoutMilliseconds || aliveFor > this.maximumLifetimeMilliseconds;
+    }
+    /**
+     * Finds a session by its public id.
+     * @param sessionId The public id.
+     * @returns The stored session, or null.
+     */
+    async findBySessionId(sessionId) {
+        const sessions = await this.store.listDocuments("consoleSessions");
+        return sessions.find((stored) => stored.value.sessionId === sessionId) ?? null;
+    }
+    /**
+     * Every stored session of an account.
+     * @param userId The account.
+     * @returns Its session documents.
+     */
+    async documentsOf(userId) {
+        const sessions = await this.store.listDocuments("consoleSessions");
+        return sessions.filter((stored) => stored.value.userId === userId);
+    }
+    /**
+     * @returns The clock's now as an ISO time.
+     */
+    nowIso() {
+        return new Date(this.clock.now()).toISOString();
+    }
+}

package/lib/admin/DedicatedRoutes.d.ts

@@ -0,0 +1,21 @@
+import type { ResolvedDedicatedScene } from "../DedicatedSceneRegistry.js";
+import { type AdminApiRouter } from "./AdminApiRouter.js";
+import type { DedicatedSceneView } from "./AdminApiTypes.js";
+import type { AdminServices } from "./AdminServices.js";
+/**
+ * Registers the dedicated/* routes.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export declare function registerDedicatedRoutes(router: AdminApiRouter, services: AdminServices): void;
+/**
+ * Registers this instance's checkDedicatedScene and startDedicated fleet commands (R15).
+ * @param services The shared services.
+ */
+export declare function registerDedicatedCommands(services: AdminServices): void;
+/**
+ * A configured scene as the console lists it.
+ * @param scene The resolved scene.
+ * @returns The row.
+ */
+export declare function dedicatedSceneView(scene: ResolvedDedicatedScene): DedicatedSceneView;

package/lib/admin/DedicatedRoutes.js

@@ -0,0 +1,254 @@
+// The dedicated session routes (game-server-admin-console DR §6.11 dedicated rows, D23, R17): the configured scenes and
+// the running dedicated sessions of the fleet, start on a chosen instance, stop, restart under the same name and the
+// scene check, plus this instance's checkDedicatedScene and startDedicated fleet commands (R15).
+import { matchMaker } from "colyseus";
+import { stat } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { getLogger } from "../GameServerLogger.js";
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { ROOM_STOP_TIMEOUT_MS } from "./AdminConstants.js";
+import { bodyObject, optionalStringField, stringField } from "./AdminRequestBodies.js";
+import { noticeTextField } from "./FleetRoutes.js";
+import { describeFleetSessions } from "./SessionRoutes.js";
+/** HTTP status of a successful read or change. */
+const HTTP_OK = 200;
+/** HTTP status of an unknown scene or dedicated session. */
+const HTTP_NOT_FOUND = 404;
+/** HTTP status of a session name already in use, or a session that cannot be restarted. */
+const HTTP_CONFLICT = 409;
+/** HTTP status of a scene that failed to start. */
+const HTTP_SERVICE_UNAVAILABLE = 503;
+/** HTTP status of a stopped session that did not close in time. */
+const HTTP_GATEWAY_TIMEOUT = 504;
+/** How long one scene check request may take, in milliseconds. */
+const SCENE_CHECK_TIMEOUT_MS = 10000;
+/** Milliseconds between checks for a stopped room's disposal during a restart. */
+const ROOM_DISPOSAL_POLL_MS = 100;
+/** The URL scheme the scene check reads from disk. */
+const FILE_URL_SCHEME = "file:";
+/** Who the console's starts and restarts are recorded as. */
+const ADMIN_STARTER = "admin";
+/**
+ * Registers the dedicated/* routes.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export function registerDedicatedRoutes(router, services) {
+    const routes = [
+        { method: "GET", pattern: "dedicated", permission: "dedicated.view", requiresStepUp: false, auditAction: null, handler: async () => ({ status: HTTP_OK, body: await buildDedicatedView(services) }) },
+        { method: "POST", pattern: "dedicated/start", permission: "dedicated.manage", requiresStepUp: false, auditAction: "dedicated.start", handler: async (request) => startDedicated(services, request) },
+        { method: "POST", pattern: "dedicated/:roomId/stop", permission: "dedicated.manage", requiresStepUp: false, auditAction: "dedicated.stop", handler: async (request) => stopDedicated(services, request) },
+        { method: "POST", pattern: "dedicated/:roomId/restart", permission: "dedicated.manage", requiresStepUp: false, auditAction: "dedicated.restart", handler: async (request) => restartDedicated(services, request) },
+        { method: "POST", pattern: "dedicated/scenes/:sceneName/check", permission: "dedicated.view", requiresStepUp: false, auditAction: null, handler: async (request) => checkSceneOn(services, request) }
+    ];
+    for (const route of routes)
+        router.register(route);
+}
+/**
+ * Registers this instance's checkDedicatedScene and startDedicated fleet commands (R15).
+ * @param services The shared services.
+ */
+export function registerDedicatedCommands(services) {
+    services.fleet.handle("checkDedicatedScene", async (command) => checkDedicatedScene(services, command.sceneName));
+    services.fleet.handle("startDedicated", async (command) => startOnThisInstance(services, command.sceneName, command.sessionName, command.startedBy));
+}
+/**
+ * A configured scene as the console lists it.
+ * @param scene The resolved scene.
+ * @returns The row.
+ */
+export function dedicatedSceneView(scene) {
+    return {
+        name: scene.name,
+        sceneRoot: scene.sceneRoot,
+        sceneFile: scene.sceneFile,
+        projectScripts: scene.projectScripts.slice(),
+        maxPlayers: scene.maxPlayers,
+        onDemand: scene.onDemand,
+        idleSeconds: scene.idleSeconds,
+        source: "config"
+    };
+}
+/**
+ * GET dedicated: this instance's configured scenes and every dedicated session of the fleet.
+ * @param services The shared services.
+ * @returns The page data.
+ */
+async function buildDedicatedView(services) {
+    const scenes = services.state.registry.listScenes().map(dedicatedSceneView);
+    const dedicatedSummaries = (await describeFleetSessions(services)).filter((session) => session.dedicatedScene != null);
+    const sessions = await Promise.all(dedicatedSummaries.map((summary) => describeDedicatedSession(services, summary)));
+    return { scenes: scenes, sessions: sessions.filter((session) => session != null) };
+}
+/**
+ * One running dedicated session with its frame history.
+ * @param services The shared services.
+ * @param summary The session's list row.
+ * @returns The row, or null when the session ended meanwhile or its instance did not answer.
+ */
+async function describeDedicatedSession(services, summary) {
+    let detail;
+    try {
+        detail = await services.roomClient.describe(summary.roomId, false);
+    }
+    catch (error) {
+        if (error instanceof AdminRequestError)
+            return null;
+        throw error;
+    }
+    if (detail.dedicated == null)
+        return null;
+    return {
+        roomId: detail.roomId,
+        sessionName: detail.sessionName,
+        sceneName: detail.dedicated.sceneName,
+        processId: detail.processId,
+        players: detail.players,
+        maxPlayers: detail.maxPlayers,
+        startedBy: detail.dedicated.startedBy,
+        frameStatistics: detail.dedicated.frameStatistics
+    };
+}
+/**
+ * POST dedicated/start: starts a configured scene under a session name on a chosen instance (this one for null).
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The new room id.
+ * @throws AdminRequestError 409 when a session of that name runs anywhere in the fleet.
+ */
+async function startDedicated(services, request) {
+    const body = bodyObject(request.body);
+    const sceneName = stringField(body, "sceneName");
+    const sessionName = stringField(body, "sessionName");
+    const processId = optionalStringField(body, "processId") ?? services.fleet.localProcessId;
+    const sessions = await describeFleetSessions(services);
+    if (sessions.some((session) => session.sessionName === sessionName))
+        throw new AdminRequestError(HTTP_CONFLICT, "a session with this name is running");
+    const started = await services.fleet.runOn(processId, "startDedicated", { sceneName: sceneName, sessionName: sessionName, startedBy: ADMIN_STARTER });
+    return { status: HTTP_OK, body: started, audit: { target: sessionName, parameters: { sceneName: sceneName, processId: processId, roomId: started.roomId } } };
+}
+/**
+ * POST dedicated/:roomId/stop: the players are told GameClosed with the message; nothing restarts the session.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns ok.
+ */
+async function stopDedicated(services, request) {
+    const message = noticeTextField(bodyObject(request.body), "message") ?? "";
+    await services.roomClient.stopDedicated(request.params.roomId, message);
+    return { status: HTTP_OK, body: { ok: true }, audit: { target: request.params.roomId, parameters: { message: message } } };
+}
+/**
+ * POST dedicated/:roomId/restart (R17): stops the session, waits until its room is gone, then starts the same scene
+ * under the same session name on the same instance.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The new room id.
+ * @throws AdminRequestError 404 for a session without a dedicated runner, 409 when its scene is not configured here.
+ */
+async function restartDedicated(services, request) {
+    const roomId = request.params.roomId;
+    const message = noticeTextField(bodyObject(request.body), "message") ?? "";
+    const detail = await services.roomClient.describe(roomId, false);
+    if (detail.dedicated == null)
+        throw new AdminRequestError(HTTP_NOT_FOUND, "no such dedicated session");
+    if (services.state.registry.find(detail.dedicated.sceneName) == null)
+        throw new AdminRequestError(HTTP_CONFLICT, "this session's scene is not configured, so it cannot be restarted");
+    const restartOptions = await services.roomClient.stopDedicated(roomId, message);
+    await waitForRoomDisposal(services, roomId);
+    const started = await services.fleet.runOn(restartOptions.processId, "startDedicated", { sceneName: restartOptions.sceneName, sessionName: restartOptions.sessionName, startedBy: ADMIN_STARTER });
+    return { status: HTTP_OK, body: started, audit: { target: roomId, parameters: { message: message, sessionName: restartOptions.sessionName, roomId: started.roomId } } };
+}
+/**
+ * Waits until a stopped room has left the matchmaker, at most ROOM_STOP_TIMEOUT_MS.
+ * @param services The shared services (the clock).
+ * @param roomId The room.
+ * @throws AdminRequestError 504 when it is still there after ROOM_STOP_TIMEOUT_MS.
+ */
+async function waitForRoomDisposal(services, roomId) {
+    const deadline = services.clock.now() + ROOM_STOP_TIMEOUT_MS;
+    while (await matchMaker.getRoomById(roomId) != null) {
+        if (services.clock.now() >= deadline)
+            throw new AdminRequestError(HTTP_GATEWAY_TIMEOUT, "the dedicated session did not stop in time");
+        await new Promise((resolve) => services.clock.setTimeout(resolve, ROOM_DISPOSAL_POLL_MS));
+    }
+}
+/**
+ * POST dedicated/scenes/:sceneName/check: checks the scene's files on a chosen instance (this one for null).
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The check.
+ */
+async function checkSceneOn(services, request) {
+    const processId = optionalStringField(bodyObject(request.body), "processId") ?? services.fleet.localProcessId;
+    const check = await services.fleet.runOn(processId, "checkDedicatedScene", { sceneName: request.params.sceneName });
+    return { status: HTTP_OK, body: check };
+}
+/**
+ * Starts a configured scene on this instance (the startDedicated command).
+ * @param services The shared services.
+ * @param sceneName The configured scene.
+ * @param sessionName The session name clients join.
+ * @param startedBy Who starts it.
+ * @returns The new room id.
+ * @throws AdminRequestError 404 for an unknown scene, 503 when the scene does not start (logged).
+ */
+async function startOnThisInstance(services, sceneName, sessionName, startedBy) {
+    if (services.state.registry.find(sceneName) == null)
+        throw new AdminRequestError(HTTP_NOT_FOUND, "no dedicated scene named " + sceneName);
+    try {
+        return { roomId: await services.routeContext.startDedicatedSession(sessionName, sceneName, startedBy) };
+    }
+    catch (error) {
+        getLogger().error("the dedicated session did not start", { sessionName: sessionName, sceneName: sceneName, error: String(error) });
+        throw new AdminRequestError(HTTP_SERVICE_UNAVAILABLE, "the dedicated session did not start: " + String(error));
+    }
+}
+/**
+ * Checks that a configured scene's files load, without running any of them (the checkDedicatedScene command): the
+ * scene file and each project script, fetched over http(s) or read from disk for file:// URLs.
+ * @param services The shared services.
+ * @param sceneName The configured scene.
+ * @returns The check.
+ * @throws AdminRequestError 404 for an unknown scene.
+ */
+async function checkDedicatedScene(services, sceneName) {
+    const scene = services.state.registry.find(sceneName);
+    if (scene == null)
+        throw new AdminRequestError(HTTP_NOT_FOUND, "no dedicated scene named " + sceneName);
+    const urls = [scene.sceneRootUrl + scene.sceneFile, ...scene.projectScripts];
+    const files = await Promise.all(urls.map((url) => checkSceneFile(url)));
+    return { sceneName: sceneName, ok: files.every((file) => file.ok), files: files };
+}
+/**
+ * Checks one file of a scene.
+ * @param url An http(s):// or file:// URL.
+ * @returns Whether it loads, with its HTTP status (null for files on disk and failed requests) and the error.
+ */
+async function checkSceneFile(url) {
+    if (url.startsWith(FILE_URL_SCHEME))
+        return checkFileOnDisk(url);
+    try {
+        const response = await fetch(url, { method: "GET", signal: AbortSignal.timeout(SCENE_CHECK_TIMEOUT_MS) });
+        // Only the status matters; the body is never read, so nothing of it runs or stays in memory.
+        await response.body?.cancel();
+        return { url: url, ok: response.ok, status: response.status, error: response.ok ? null : "the server answered " + response.status };
+    }
+    catch (error) {
+        return { url: url, ok: false, status: null, error: (error instanceof Error) ? error.message : String(error) };
+    }
+}
+/**
+ * Checks that a file:// URL names a readable file.
+ * @param url The file:// URL.
+ * @returns Whether it is a file, with the error when it is not.
+ */
+async function checkFileOnDisk(url) {
+    try {
+        const isFile = (await stat(fileURLToPath(url))).isFile();
+        return { url: url, ok: isFile, status: null, error: isFile ? null : "not a file" };
+    }
+    catch (error) {
+        return { url: url, ok: false, status: null, error: (error instanceof Error) ? error.message : String(error) };
+    }
+}

package/lib/admin/ExtensionRoutes.d.ts

@@ -0,0 +1,8 @@
+import { type AdminApiRouter } from "./AdminApiRouter.js";
+import type { AdminServices } from "./AdminServices.js";
+/**
+ * Registers the extensions/* and docs routes.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export declare function registerExtensionRoutes(router: AdminApiRouter, services: AdminServices): void;