@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/admin/ConfigOverrides.d.ts

@@ -0,0 +1,174 @@
+import { type AdminCaller } from "./AdminApiRouter.js";
+import type { ConfigChangeView, ConfigOverridesRequest, ConfigView } from "./AdminApiTypes.js";
+import type { AdminCoreServices } from "./AdminServices.js";
+import type { FleetDirectory } from "./FleetDirectory.js";
+/** The settings document of the overrides. */
+export declare const CONFIG_OVERRIDES_SETTINGS_ID: string;
+/** The export formats of exportSnippet. */
+export type ConfigExportFormat = "mjs" | "env";
+/** The console's live overrides of this instance. */
+export declare class ConfigOverrides {
+    /** The shared core services. */
+    private readonly services;
+    /** Announces a change, so every instance re-applies the overrides. */
+    private readonly fleet;
+    /** The config before any override (R32), which a revert restores. */
+    private baseConfig;
+    /** The overrides as last read from the store. */
+    private stored;
+    /** The revision of the stored document, or null when none is stored. */
+    private revision;
+    /** The paths an override currently replaces on this instance. */
+    private readonly overriddenPaths;
+    /**
+     * Prepares the overrides; nothing changes until applyStored().
+     * @param services The shared core services.
+     * @param fleet The fleet directory (change announcements).
+     */
+    constructor(services: AdminCoreServices, fleet: FleetDirectory);
+    /**
+     * Keeps the config before any override, then applies the stored overrides (at boot, before the server listens;
+     * instance overrides apply once the process id is known, on the next reload).
+     */
+    applyStored(): Promise<void>;
+    /** Reads the stored overrides again and applies them (a settings change announcement). */
+    reload(): Promise<void>;
+    /**
+     * Overrides a live option, fleet-wide or on one instance (D20, DR §9).
+     * @param request The scope, option path, value and the revision the editor read.
+     * @param by Who changes it (recorded in the history).
+     * @returns The config page of the scope's instance (this one for the fleet).
+     * @throws AdminRequestError 400 for an option that needs a restart or an invalid value, 409 for an option set by an
+     *     environment variable or flag; AdminConflictError for a stale expectedRevision.
+     */
+    setOverride(request: ConfigOverridesRequest, by: AdminCaller): Promise<ConfigView>;
+    /**
+     * Removes an override, so the file, environment or default value applies again.
+     * @param scope "fleet" or a process id.
+     * @param path The option path.
+     * @param by Who reverts it (recorded in the history).
+     * @returns The config page of the scope's instance.
+     * @throws AdminRequestError 400 for an option that is not live-editable, 404 when the scope has no override of it.
+     */
+    revert(scope: string, path: string, by: AdminCaller): Promise<ConfigView>;
+    /**
+     * The value an option has for a scope: the scope's override, else the fleet's, else the configured one.
+     * @param scope "fleet" or a process id.
+     * @param path The option path.
+     * @returns The value.
+     */
+    valueAt(scope: string, path: string): unknown;
+    /**
+     * The config page (spec 9): every option with its value (secrets only "set" / "not set"), its source and whether
+     * it can change live, as it applies to an instance.
+     * @param processId The instance (this instance's base config and sources, with the overrides that apply there).
+     * @returns The page data.
+     */
+    describe(processId: string): ConfigView;
+    /**
+     * The change history, newest first.
+     * @returns The last HISTORY_LENGTH changes.
+     */
+    history(): Promise<ConfigChangeView[]>;
+    /**
+     * A config snippet with this instance's current settings, for restart-only options and for keeping live changes:
+     * every value that differs from the default, never a secret value.
+     * @param format "mjs" for babylon-game-server.config.mjs (set secrets read from process.env), "env" for .env lines
+     *     (every secret listed with an empty value).
+     * @returns The file text.
+     */
+    exportSnippet(format: ConfigExportFormat): string;
+    /**
+     * The option of a path, when the console may change it now.
+     * @param path The option path.
+     * @returns The option.
+     * @throws AdminRequestError 400 when it is not live-editable, 409 when an environment variable or flag set it.
+     */
+    private requireEditable;
+    /**
+     * Checks that a scope is the fleet or a live instance.
+     * @param scope "fleet" or a process id.
+     * @throws AdminRequestError 404 for an unknown or lost instance.
+     */
+    private requireKnownScope;
+    /**
+     * Parses a value by the option's type and checks it on a copy of the config.
+     * @param definition The option.
+     * @param value The value given.
+     * @returns The parsed value.
+     * @throws AdminRequestError 400 with the validation problems.
+     */
+    private validatedValue;
+    /**
+     * Stores the overrides, applies them here and announces the change to every instance.
+     * @param next The new overrides.
+     * @param expectedRevision The revision the editor read, or null for no check.
+     * @throws AdminConflictError when expectedRevision is stale.
+     */
+    private save;
+    /**
+     * Appends a change to the configHistory stream.
+     * @param change The change.
+     */
+    private recordChange;
+    /**
+     * Applies the overrides that reach this instance and restores the base value of any that no longer do. Locked
+     * options are never touched, and a value that did not change is not written again (so a settings reload never
+     * resets a temporary log level).
+     */
+    private applyEffective;
+    /**
+     * Writes a value into the running config and applies its side effect (D20): the logger's level, the join rate
+     * limiter; every other live option is read where it is used (maxMessagesPerSecond by new sessions).
+     * @param path The option path.
+     * @param value The value.
+     */
+    private applyValue;
+    /**
+     * The override of a path that reaches an instance: its own, else the fleet's.
+     * @param path The option path.
+     * @param processId The instance, or null for the fleet value only.
+     * @returns The override, or null when none applies.
+     */
+    private overrideFor;
+    /**
+     * Whether an environment variable or a flag set an option (it is then never overridden, D20).
+     * @param path The option path.
+     * @returns True when locked.
+     */
+    private isLocked;
+    /**
+     * One option of the config page.
+     * @param definition The option.
+     * @param processId The instance the page describes.
+     * @returns The row.
+     */
+    private describeOption;
+    /**
+     * The .env export: one line per non-default, non-secret value, then every secret with an empty value.
+     * @returns The text.
+     */
+    private exportEnvironment;
+    /**
+     * The babylon-game-server.config.mjs export: every non-default, non-secret value, the dedicated scenes, and each set
+     * secret read from its environment variable.
+     * @returns The module text.
+     */
+    private exportModule;
+    /**
+     * The non-secret options whose current value differs from the default.
+     * @returns The options.
+     */
+    private changedOptions;
+    /**
+     * The instance a scope's page describes.
+     * @param scope "fleet" or a process id.
+     * @returns The process id (this instance for the fleet).
+     */
+    private processIdOfScope;
+    /**
+     * The current time as ISO text.
+     * @returns The time.
+     */
+    private nowText;
+}

package/lib/admin/ConfigOverrides.js

@@ -0,0 +1,406 @@
+// Live config overrides from the console (game-server-admin-console D20, DR §9): only LIVE_EDITABLE_OPTION_PATHS, never
+// an option set by an environment variable or a flag, validated on a copy of the config, stored fleet-wide or per
+// instance in settings/configOverrides (so they survive restarts), re-applied by every instance on each change, and
+// kept in the configHistory stream. Nothing is ever written to the config file on disk.
+import { CONFIG_OPTIONS, DEFAULT_GAME_SERVER_CONFIG, parseOptionValue, readPath, validateGameServerConfig, writePath } from "../GameServerConfig.js";
+import { getLogger } from "../GameServerLogger.js";
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { LIVE_EDITABLE_OPTION_PATHS } from "./AdminConstants.js";
+import { dedicatedSceneView } from "./DedicatedRoutes.js";
+/** The settings document of the overrides. */
+export const CONFIG_OVERRIDES_SETTINGS_ID = "configOverrides";
+/** HTTP status of an invalid override. */
+const HTTP_BAD_REQUEST = 400;
+/** HTTP status of a revert with nothing to revert. */
+const HTTP_NOT_FOUND = 404;
+/** HTTP status of an override of a locked option. */
+const HTTP_CONFLICT = 409;
+/** The scope value of the whole fleet. */
+const FLEET_SCOPE = "fleet";
+/** How many config changes the history answers with. */
+const HISTORY_LENGTH = 500;
+/** What a secret that has a value shows. */
+const SECRET_SET = "set";
+/** What a secret without a value shows. */
+const SECRET_NOT_SET = "not set";
+/** Marks a list secret's environment-variable placeholder inside the JSON of a config module export. */
+const LIST_PLACEHOLDER_PATTERN = /"__ENVIRONMENT_LIST_PLACEHOLDER__([A-Z0-9_]+)__"/g;
+/** Marks a text secret's environment-variable placeholder inside the JSON of a config module export. */
+const TEXT_PLACEHOLDER_PATTERN = /"__ENVIRONMENT_PLACEHOLDER__([A-Z0-9_]+)__"/g;
+/** Live options whose change also needs a call besides the config write. */
+const LOG_LEVEL_PATH = "logLevel";
+const JOIN_RATE_PATH = "limits.joinRequestsPerMinutePerAddress";
+/** The console's live overrides of this instance. */
+export class ConfigOverrides {
+    /** The shared core services. */
+    services;
+    /** Announces a change, so every instance re-applies the overrides. */
+    fleet;
+    /** The config before any override (R32), which a revert restores. */
+    baseConfig = null;
+    /** The overrides as last read from the store. */
+    stored = emptyOverrides();
+    /** The revision of the stored document, or null when none is stored. */
+    revision = null;
+    /** The paths an override currently replaces on this instance. */
+    overriddenPaths = new Set();
+    /**
+     * Prepares the overrides; nothing changes until applyStored().
+     * @param services The shared core services.
+     * @param fleet The fleet directory (change announcements).
+     */
+    constructor(services, fleet) {
+        this.services = services;
+        this.fleet = fleet;
+    }
+    /**
+     * Keeps the config before any override, then applies the stored overrides (at boot, before the server listens;
+     * instance overrides apply once the process id is known, on the next reload).
+     */
+    async applyStored() {
+        this.baseConfig ??= structuredClone(this.services.state.config);
+        await this.reload();
+    }
+    /** Reads the stored overrides again and applies them (a settings change announcement). */
+    async reload() {
+        const stored = await this.services.store.getDocument("settings", CONFIG_OVERRIDES_SETTINGS_ID);
+        this.stored = stored?.value ?? emptyOverrides();
+        this.revision = stored?.revision ?? null;
+        this.applyEffective();
+    }
+    /**
+     * Overrides a live option, fleet-wide or on one instance (D20, DR §9).
+     * @param request The scope, option path, value and the revision the editor read.
+     * @param by Who changes it (recorded in the history).
+     * @returns The config page of the scope's instance (this one for the fleet).
+     * @throws AdminRequestError 400 for an option that needs a restart or an invalid value, 409 for an option set by an
+     *     environment variable or flag; AdminConflictError for a stale expectedRevision.
+     */
+    async setOverride(request, by) {
+        const definition = this.requireEditable(request.path);
+        const value = this.validatedValue(definition, request.value);
+        await this.requireKnownScope(request.scope);
+        await this.reload();
+        const before = this.valueAt(request.scope, request.path);
+        const next = structuredClone(this.stored);
+        overridesOfScope(next, request.scope)[request.path] = value;
+        await this.save(next, request.expectedRevision);
+        await this.recordChange({ at: this.nowText(), by: by.name, scope: request.scope, path: request.path, before: before, after: value, reverted: false });
+        return this.describe(this.processIdOfScope(request.scope));
+    }
+    /**
+     * Removes an override, so the file, environment or default value applies again.
+     * @param scope "fleet" or a process id.
+     * @param path The option path.
+     * @param by Who reverts it (recorded in the history).
+     * @returns The config page of the scope's instance.
+     * @throws AdminRequestError 400 for an option that is not live-editable, 404 when the scope has no override of it.
+     */
+    async revert(scope, path, by) {
+        if (!LIVE_EDITABLE_OPTION_PATHS.includes(path))
+            throw new AdminRequestError(HTTP_BAD_REQUEST, "this option needs a restart");
+        await this.reload();
+        const next = structuredClone(this.stored);
+        const scoped = overridesOfScope(next, scope);
+        if (!Object.hasOwn(scoped, path))
+            throw new AdminRequestError(HTTP_NOT_FOUND, "this scope has no override of " + path);
+        const before = this.valueAt(scope, path);
+        delete scoped[path];
+        if (scope !== FLEET_SCOPE && Object.keys(scoped).length === 0)
+            delete next.instances[scope];
+        await this.save(next, this.revision);
+        await this.recordChange({ at: this.nowText(), by: by.name, scope: scope, path: path, before: before, after: this.valueAt(scope, path), reverted: true });
+        return this.describe(this.processIdOfScope(scope));
+    }
+    /**
+     * The value an option has for a scope: the scope's override, else the fleet's, else the configured one.
+     * @param scope "fleet" or a process id.
+     * @param path The option path.
+     * @returns The value.
+     */
+    valueAt(scope, path) {
+        const override = this.overrideFor(path, (scope === FLEET_SCOPE) ? null : scope);
+        if (override != null)
+            return override.value;
+        return readPath(this.baseConfig ?? this.services.state.config, path);
+    }
+    /**
+     * The config page (spec 9): every option with its value (secrets only "set" / "not set"), its source and whether
+     * it can change live, as it applies to an instance.
+     * @param processId The instance (this instance's base config and sources, with the overrides that apply there).
+     * @returns The page data.
+     */
+    describe(processId) {
+        return {
+            processId: processId,
+            revision: this.revision,
+            options: CONFIG_OPTIONS.map((definition) => this.describeOption(definition, processId)),
+            dedicatedScenes: this.services.state.registry.listScenes().map(dedicatedSceneView)
+        };
+    }
+    /**
+     * The change history, newest first.
+     * @returns The last HISTORY_LENGTH changes.
+     */
+    async history() {
+        const records = await this.services.store.readRecords("configHistory", { limit: HISTORY_LENGTH, newestFirst: true });
+        return records.map((record) => record.value);
+    }
+    /**
+     * A config snippet with this instance's current settings, for restart-only options and for keeping live changes:
+     * every value that differs from the default, never a secret value.
+     * @param format "mjs" for babylon-game-server.config.mjs (set secrets read from process.env), "env" for .env lines
+     *     (every secret listed with an empty value).
+     * @returns The file text.
+     */
+    exportSnippet(format) {
+        return (format === "env") ? this.exportEnvironment() : this.exportModule();
+    }
+    /**
+     * The option of a path, when the console may change it now.
+     * @param path The option path.
+     * @returns The option.
+     * @throws AdminRequestError 400 when it is not live-editable, 409 when an environment variable or flag set it.
+     */
+    requireEditable(path) {
+        const definition = CONFIG_OPTIONS.find((candidate) => candidate.path === path);
+        if (definition == null || !LIVE_EDITABLE_OPTION_PATHS.includes(path))
+            throw new AdminRequestError(HTTP_BAD_REQUEST, "this option needs a restart");
+        const source = this.services.state.configSources[path];
+        if (source === "environment")
+            throw new AdminRequestError(HTTP_CONFLICT, "set by " + definition.environmentVariable + "; change it there", path);
+        if (source === "flag")
+            throw new AdminRequestError(HTTP_CONFLICT, "set by --" + (definition.flag ?? path) + "; change it there", path);
+        return definition;
+    }
+    /**
+     * Checks that a scope is the fleet or a live instance.
+     * @param scope "fleet" or a process id.
+     * @throws AdminRequestError 404 for an unknown or lost instance.
+     */
+    async requireKnownScope(scope) {
+        if (scope === FLEET_SCOPE || scope === this.services.processId())
+            return;
+        const isLiveInstance = (await this.fleet.listInstances()).some((instance) => instance.processId === scope && instance.status === "up");
+        if (!isLiveInstance)
+            throw new AdminRequestError(HTTP_NOT_FOUND, "no such instance");
+    }
+    /**
+     * Parses a value by the option's type and checks it on a copy of the config.
+     * @param definition The option.
+     * @param value The value given.
+     * @returns The parsed value.
+     * @throws AdminRequestError 400 with the validation problems.
+     */
+    validatedValue(definition, value) {
+        const parsed = parseOptionValue(definition, value);
+        if (parsed == null)
+            throw new AdminRequestError(HTTP_BAD_REQUEST, definition.path + " cannot be " + JSON.stringify(value));
+        const candidate = structuredClone(this.services.state.config);
+        writePath(candidate, definition.path, parsed.value);
+        const problems = validateGameServerConfig(candidate);
+        if (problems.length > 0)
+            throw new AdminRequestError(HTTP_BAD_REQUEST, problems.join("; "));
+        return parsed.value;
+    }
+    /**
+     * Stores the overrides, applies them here and announces the change to every instance.
+     * @param next The new overrides.
+     * @param expectedRevision The revision the editor read, or null for no check.
+     * @throws AdminConflictError when expectedRevision is stale.
+     */
+    async save(next, expectedRevision) {
+        const saved = await this.services.store.putDocument("settings", CONFIG_OVERRIDES_SETTINGS_ID, next, expectedRevision);
+        this.stored = saved.value;
+        this.revision = saved.revision;
+        this.applyEffective();
+        await this.fleet.announceChange("settings");
+    }
+    /**
+     * Appends a change to the configHistory stream.
+     * @param change The change.
+     */
+    async recordChange(change) {
+        await this.services.store.appendRecord("configHistory", change);
+    }
+    /**
+     * Applies the overrides that reach this instance and restores the base value of any that no longer do. Locked
+     * options are never touched, and a value that did not change is not written again (so a settings reload never
+     * resets a temporary log level).
+     */
+    applyEffective() {
+        const base = this.baseConfig ?? this.services.state.config;
+        for (const path of LIVE_EDITABLE_OPTION_PATHS) {
+            const override = this.isLocked(path) ? null : this.overrideFor(path, this.services.processId() ?? null);
+            if (override != null) {
+                this.applyValue(path, override.value);
+                this.overriddenPaths.add(path);
+            }
+            else if (this.overriddenPaths.delete(path)) {
+                this.applyValue(path, structuredClone(readPath(base, path)));
+            }
+        }
+    }
+    /**
+     * Writes a value into the running config and applies its side effect (D20): the logger's level, the join rate
+     * limiter; every other live option is read where it is used (maxMessagesPerSecond by new sessions).
+     * @param path The option path.
+     * @param value The value.
+     */
+    applyValue(path, value) {
+        const state = this.services.state;
+        if (JSON.stringify(readPath(state.config, path)) === JSON.stringify(value))
+            return;
+        writePath(state.config, path, value);
+        if (path === LOG_LEVEL_PATH)
+            getLogger().setLevel(state.config.logLevel);
+        if (path === JOIN_RATE_PATH)
+            state.rateLimiter.setRequestsPerMinute(state.config.limits.joinRequestsPerMinutePerAddress);
+    }
+    /**
+     * The override of a path that reaches an instance: its own, else the fleet's.
+     * @param path The option path.
+     * @param processId The instance, or null for the fleet value only.
+     * @returns The override, or null when none applies.
+     */
+    overrideFor(path, processId) {
+        const instanceOverrides = (processId != null) ? this.stored.instances[processId] : undefined;
+        if (instanceOverrides != null && Object.hasOwn(instanceOverrides, path))
+            return { value: instanceOverrides[path] };
+        if (Object.hasOwn(this.stored.fleet, path))
+            return { value: this.stored.fleet[path] };
+        return null;
+    }
+    /**
+     * Whether an environment variable or a flag set an option (it is then never overridden, D20).
+     * @param path The option path.
+     * @returns True when locked.
+     */
+    isLocked(path) {
+        const source = this.services.state.configSources[path];
+        return source === "environment" || source === "flag";
+    }
+    /**
+     * One option of the config page.
+     * @param definition The option.
+     * @param processId The instance the page describes.
+     * @returns The row.
+     */
+    describeOption(definition, processId) {
+        const liveEditable = LIVE_EDITABLE_OPTION_PATHS.includes(definition.path);
+        const locked = this.isLocked(definition.path);
+        const override = (liveEditable && !locked) ? this.overrideFor(definition.path, processId) : null;
+        const value = (override != null) ? override.value : readPath(this.baseConfig ?? this.services.state.config, definition.path);
+        return {
+            path: definition.path,
+            environmentVariable: definition.environmentVariable,
+            flag: definition.flag,
+            description: definition.description,
+            isSecret: definition.isSecret,
+            value: definition.isSecret ? (hasValue(value) ? SECRET_SET : SECRET_NOT_SET) : value,
+            source: (override != null) ? "override" : (this.services.state.configSources[definition.path] ?? "code"),
+            liveEditable: liveEditable,
+            locked: locked,
+            needsRestart: !liveEditable
+        };
+    }
+    /**
+     * The .env export: one line per non-default, non-secret value, then every secret with an empty value.
+     * @returns The text.
+     */
+    exportEnvironment() {
+        const lines = ["# Babylon Game Server settings exported from the admin console on " + this.nowText()];
+        for (const definition of this.changedOptions())
+            lines.push(definition.environmentVariable + "=" + environmentText(readPath(this.services.state.config, definition.path)));
+        lines.push("# Secrets are never exported: fill these in where they are needed.");
+        for (const definition of CONFIG_OPTIONS.filter((candidate) => candidate.isSecret))
+            lines.push(definition.environmentVariable + "=");
+        return lines.join("\n") + "\n";
+    }
+    /**
+     * The babylon-game-server.config.mjs export: every non-default, non-secret value, the dedicated scenes, and each set
+     * secret read from its environment variable.
+     * @returns The module text.
+     */
+    exportModule() {
+        const config = this.services.state.config;
+        const exported = {};
+        for (const definition of this.changedOptions())
+            writePath(exported, definition.path, readPath(config, definition.path));
+        for (const definition of CONFIG_OPTIONS.filter((candidate) => candidate.isSecret && hasValue(readPath(config, candidate.path)))) {
+            const placeholderKind = (definition.valueType === "string-list") ? "__ENVIRONMENT_LIST_PLACEHOLDER__" : "__ENVIRONMENT_PLACEHOLDER__";
+            writePath(exported, definition.path, placeholderKind + definition.environmentVariable + "__");
+        }
+        if (config.dedicated.scenes.length > 0 || config.dedicated.boot.length > 0)
+            exported.dedicated = structuredClone(config.dedicated);
+        const body = JSON.stringify(exported, null, 4)
+            .replace(LIST_PLACEHOLDER_PATTERN, "(process.env.$1 ?? \"\").split(\",\")")
+            .replace(TEXT_PLACEHOLDER_PATTERN, "process.env.$1 ?? null");
+        return "// Babylon Game Server settings exported from the admin console on " + this.nowText() + ".\n// Secrets are read from the environment, never written here.\nexport default " + body + ";\n";
+    }
+    /**
+     * The non-secret options whose current value differs from the default.
+     * @returns The options.
+     */
+    changedOptions() {
+        return CONFIG_OPTIONS.filter((definition) => {
+            if (definition.isSecret)
+                return false;
+            return JSON.stringify(readPath(this.services.state.config, definition.path)) !== JSON.stringify(readPath(DEFAULT_GAME_SERVER_CONFIG, definition.path));
+        });
+    }
+    /**
+     * The instance a scope's page describes.
+     * @param scope "fleet" or a process id.
+     * @returns The process id (this instance for the fleet).
+     */
+    processIdOfScope(scope) {
+        return (scope === FLEET_SCOPE) ? this.services.processId() : scope;
+    }
+    /**
+     * The current time as ISO text.
+     * @returns The time.
+     */
+    nowText() {
+        return new Date(this.services.clock.now()).toISOString();
+    }
+}
+/**
+ * No overrides.
+ * @returns An empty overrides document.
+ */
+function emptyOverrides() {
+    return { fleet: {}, instances: {} };
+}
+/**
+ * The override map of a scope, created when missing.
+ * @param overrides The overrides document (changed in place).
+ * @param scope "fleet" or a process id.
+ * @returns The scope's map.
+ */
+function overridesOfScope(overrides, scope) {
+    if (scope === FLEET_SCOPE)
+        return overrides.fleet;
+    overrides.instances[scope] ??= {};
+    return overrides.instances[scope];
+}
+/**
+ * Whether an option has a value (a secret is "set").
+ * @param value The value.
+ * @returns False for null, undefined, "" and an empty list.
+ */
+function hasValue(value) {
+    if (Array.isArray(value))
+        return value.length > 0;
+    return value != null && value !== "";
+}
+/**
+ * A value as .env text: lists comma-separated, null empty.
+ * @param value The value.
+ * @returns The text.
+ */
+function environmentText(value) {
+    if (Array.isArray(value))
+        return value.join(",");
+    return (value == null) ? "" : String(value);
+}

package/lib/admin/ConfigRoutes.d.ts

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

package/lib/admin/ConfigRoutes.js

@@ -0,0 +1,91 @@
+// The config routes (game-server-admin-console DR §6.11 config rows, D20): the config page with every option's source,
+// live overrides and their revert, the change history and the export of a config file or .env snippet.
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { bodyObject, stringField } from "./AdminRequestBodies.js";
+/** HTTP status of a successful read or change. */
+const HTTP_OK = 200;
+/** HTTP status of an invalid request. */
+const HTTP_BAD_REQUEST = 400;
+/** The download of each export format. */
+const EXPORT_FILES = {
+    mjs: { fileName: "babylon-game-server.config.mjs", contentType: "text/javascript; charset=utf-8" },
+    env: { fileName: ".env", contentType: "text/plain; charset=utf-8" }
+};
+/**
+ * Registers the config/* routes.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export function registerConfigRoutes(router, services) {
+    const routes = [
+        { method: "GET", pattern: "config", permission: "config.view", requiresStepUp: false, auditAction: null, handler: async (request) => ({ status: HTTP_OK, body: services.configOverrides.describe(request.query.get("processId") || services.fleet.localProcessId) }) },
+        { method: "PUT", pattern: "config/overrides", permission: "config.manage", requiresStepUp: false, auditAction: "config.override", handler: async (request) => setOverride(services, request) },
+        { method: "DELETE", pattern: "config/overrides", permission: "config.manage", requiresStepUp: false, auditAction: "config.revert", handler: async (request) => revertOverride(services, request) },
+        { method: "GET", pattern: "config/history", permission: "config.view", requiresStepUp: false, auditAction: null, handler: async () => ({ status: HTTP_OK, body: await services.configOverrides.history() }) },
+        { method: "GET", pattern: "config/export", permission: "config.view", requiresStepUp: false, auditAction: null, handler: async (request) => exportConfig(services, request) }
+    ];
+    for (const route of routes)
+        router.register(route);
+}
+/**
+ * PUT config/overrides: overrides a live option, audited with its value before and after.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The config page.
+ * @throws AdminRequestError 400 for a bad body (and the ConfigOverrides refusals).
+ */
+async function setOverride(services, request) {
+    const body = bodyObject(request.body);
+    const expectedRevision = body.expectedRevision ?? null;
+    if (expectedRevision !== null && !Number.isInteger(expectedRevision))
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "expectedRevision must be a whole number or null");
+    if (!Object.hasOwn(body, "value"))
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "value is missing");
+    const change = { scope: stringField(body, "scope"), path: stringField(body, "path"), value: body.value, expectedRevision: expectedRevision };
+    const before = services.configOverrides.valueAt(change.scope, change.path);
+    const view = await services.configOverrides.setOverride(change, requireCaller(request));
+    const after = services.configOverrides.valueAt(change.scope, change.path);
+    return { status: HTTP_OK, body: view, audit: { target: change.path, parameters: { scope: change.scope, before: before, after: after } } };
+}
+/**
+ * DELETE config/overrides?scope=&path=: removes an override, audited with its value before and after.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The config page.
+ * @throws AdminRequestError 400 without scope or path.
+ */
+async function revertOverride(services, request) {
+    const scope = request.query.get("scope");
+    const path = request.query.get("path");
+    if (scope == null || scope === "" || path == null || path === "")
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "scope and path are required");
+    const before = services.configOverrides.valueAt(scope, path);
+    const view = await services.configOverrides.revert(scope, path, requireCaller(request));
+    return { status: HTTP_OK, body: view, audit: { target: path, parameters: { scope: scope, before: before, after: services.configOverrides.valueAt(scope, path) } } };
+}
+/**
+ * GET config/export?format=mjs|env: this instance's settings as a config file or .env lines, without secret values.
+ * @param services The shared services.
+ * @param request The request.
+ * @returns The download.
+ * @throws AdminRequestError 400 for an unknown format.
+ */
+async function exportConfig(services, request) {
+    const format = request.query.get("format") ?? "mjs";
+    if (!Object.hasOwn(EXPORT_FILES, format))
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "format must be mjs or env");
+    const exportFormat = format;
+    const bytes = new TextEncoder().encode(services.configOverrides.exportSnippet(exportFormat));
+    return { status: HTTP_OK, body: null, download: { bytes: bytes, contentType: EXPORT_FILES[exportFormat].contentType, fileName: EXPORT_FILES[exportFormat].fileName } };
+}
+/**
+ * The caller of an authorized request (the pipeline always sets it for permission routes).
+ * @param request The request.
+ * @returns The caller.
+ * @throws Error when the pipeline left the caller unset (a programming error).
+ */
+function requireCaller(request) {
+    if (request.caller == null)
+        throw new Error("an authorized admin route ran without a caller");
+    return request.caller;
+}