@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/GameServerConfig.d.ts

@@ -0,0 +1,387 @@
+/** Every setting of a Babylon Game Server (D3). Defaults are DEFAULT_GAME_SERVER_CONFIG. */
+export interface GameServerConfig {
+    /** TCP (and UDP) port. Default 2567; env GAME_SERVER_PORT, else PORT. */
+    port: number;
+    /** Address to bind. Default "0.0.0.0". */
+    host: string;
+    /** Public ws(s):// URL players use, shown in logs and docs (null: derived from host/port/TLS). */
+    publicUrl: string | null;
+    /** host[:port] each instance advertises for seat reservations when scaled out (D18), or null. */
+    publicAddress: string | null;
+    /** Trust x-forwarded-for / x-real-ip for the client address (D11). Default false. */
+    trustProxy: boolean;
+    /** "auto" (JSON when NODE_ENV=production), "json" or "text". */
+    logFormat: "auto" | "json" | "text";
+    /** Least severe level logged. Default "info". */
+    logLevel: GameServerLogLevel;
+    /** TLS on the server itself. */
+    tls: TlsConfig;
+    /** HTTP/3 WebTransport. */
+    udp: UdpConfig;
+    /** Player authentication. */
+    auth: AuthConfig;
+    /** Discord sign-in for players (discord-sign-in). */
+    discordSignIn: DiscordSignInConfig;
+    /** Admin API, console and their data. */
+    admin: AdminConfig;
+    /** Prometheus endpoint. */
+    metrics: MetricsConfig;
+    /** Abuse limits. */
+    limits: LimitsConfig;
+    /** Multi-instance scaling. */
+    redis: RedisConfig;
+    /** Dedicated Server-mode sessions. */
+    dedicated: DedicatedConfig;
+    /** Leaderboards (game-server-leaderboards). */
+    leaderboards: LeaderboardsConfig;
+    /** Seconds running sessions may continue after SIGTERM (D17). Default 30. */
+    drainSeconds: number;
+}
+/** Log levels, most severe first. */
+export type GameServerLogLevel = "error" | "warn" | "info" | "debug";
+/** TLS on the server itself (D2, D9). */
+export interface TlsConfig {
+    /** Serve https:// and wss:// (and HTTP/3 when UDP is on). Default false. */
+    enabled: boolean;
+    /** Path of the PEM certificate chain file, or null. */
+    certFile: string | null;
+    /** Path of the PEM private key file, or null. */
+    keyFile: string | null;
+    /** PEM certificate chain text (container secrets), or null. */
+    certPem: string | null;
+    /** PEM private key text (container secrets), or null. */
+    keyPem: string | null;
+    /** Make a local development certificate (refused when NODE_ENV=production). Default false. */
+    developmentCertificate: boolean;
+}
+/** HTTP/3 WebTransport (D2, D8). */
+export interface UdpConfig {
+    /** Also accept WebTransport over HTTP/3 (UDP) on the same port. Needs TLS. Default false. */
+    enabled: boolean;
+}
+/** How player tokens are verified. */
+export type AuthMode = "shared-secret" | "jwt" | "webhook" | "custom";
+/** Player authentication (D2, D13). */
+export interface AuthConfig {
+    /** Require a valid token on every join. Default false. */
+    enabled: boolean;
+    /** The verifier. Default "shared-secret". */
+    mode: AuthMode;
+    /** Shared-secret mode: the accepted tokens. */
+    sharedSecret: {
+        tokens: string[];
+    };
+    /** JWT mode: an HMAC secret or a JWKS URL, plus the expected claims. */
+    jwt: {
+        secret: string | null;
+        jwksUrl: string | null;
+        issuer: string | null;
+        audience: string | null;
+        algorithms: string[];
+    };
+    /** Webhook mode: the URL that approves players, and its timeout in milliseconds. */
+    webhook: {
+        url: string | null;
+        timeoutMs: number;
+    };
+}
+/** Discord sign-in for players (discord-sign-in D12): website OAuth2 with PKCE, scope identify; off by default. */
+export interface DiscordSignInConfig {
+    /** Let players sign in with Discord. Default false. */
+    enabled: boolean;
+    /** The Discord application's client id. */
+    clientId: string | null;
+    /** The Discord application's client secret (from the environment; never logged or shown). */
+    clientSecret: string | null;
+    /** This server's callback address exactly as registered with Discord, ending in /game-server/discord/callback. */
+    redirectUri: string | null;
+    /** Game origins (scheme://host[:port]) a sign-in may return to. */
+    returnOrigins: string[];
+    /** Days a sign-in lasts before the player signs in again (1–365). Default 30. */
+    sessionDays: number;
+}
+/** Admin API, console and their data (D15; game-server-admin-console D7, D30). */
+export interface AdminConfig {
+    /** Bearer token of the legacy admin endpoints and a full-access API key (null: legacy API off). Secret. */
+    token: string | null;
+    /** Serve the web console when an admin account exists or a setup is pending. Default true. */
+    console: boolean;
+    /** Folder of the file data store when Redis is not configured. Default "./babylon-game-server-data". */
+    dataDir: string;
+    /** Console sign-out after this many idle minutes. Default 30. */
+    sessionIdleMinutes: number;
+    /** Console sign-out after this many hours in all. Default 12. */
+    sessionMaxHours: number;
+    /** Addresses or CIDR ranges that may reach the console and its API (empty: any). */
+    allowedNetworks: string[];
+    /** Log entries each instance keeps for the console. Default 10000. */
+    logBufferEntries: number;
+    /** Hours of metrics history kept for the charts. Default 24. */
+    metricsHistoryHours: number;
+    /** An external Grafana dashboard URL the console links to (null: none). */
+    grafanaUrl: string | null;
+    /** A region or label shown beside this instance (null: none). */
+    instanceLabel: string | null;
+    /** OpenID Connect single sign-on (game-server-admin-console D26). */
+    oidc: AdminOpenIdConfig;
+    /** Passkeys (game-server-admin-console D31). */
+    passkeys: AdminPasskeyConfig;
+    /** The console's Colyseus Cloud page (colyseus-cloud-console). */
+    colyseusCloud: AdminColyseusCloudConfig;
+}
+/** OpenID Connect settings of the admin console (D26); enabled needs issuer and clientId. */
+export interface AdminOpenIdConfig {
+    /** Offer single sign-on. Default false. */
+    enabled: boolean;
+    /** Issuer URL with a /.well-known/openid-configuration (null: none). */
+    issuer: string | null;
+    /** The console's client id at the provider (null: none). */
+    clientId: string | null;
+    /** The console's client secret (null: a public client). Secret. */
+    clientSecret: string | null;
+    /** Sign-in button label. Default "Single sign-on". */
+    label: string;
+    /** Claim that carries groups or roles. Default "groups". */
+    roleClaim: string;
+    /** Claim value → role, as "value=role" pairs. Default none. */
+    roleMapping: string[];
+    /** Allow username and password sign-in too. Default true. */
+    allowLocalSignIn: boolean;
+}
+/** Passkey settings of the admin console (D31). */
+export interface AdminPasskeyConfig {
+    /** Offer passkeys. Default true. */
+    enabled: boolean;
+    /** Relying party id (null: the console host). */
+    rpId: string | null;
+}
+/** The console's Colyseus Cloud page: the read-only Cloud API it reads (colyseus-cloud-console). */
+export interface AdminColyseusCloudConfig {
+    /** Team API token from the Colyseus Cloud dashboard (API tokens); null turns the page off. Secret. */
+    apiToken: string | null;
+    /** Slug of the application the page shows, e.g. "1234-my-game"; null uses the team's only application. */
+    application: string | null;
+    /** Base URL of the Cloud API, without a trailing slash. */
+    apiUrl: string;
+}
+/** Prometheus endpoint (D16). */
+export interface MetricsConfig {
+    /** Serve GET /metrics. Default true. */
+    enabled: boolean;
+    /** Require the admin token on /metrics. Default false. */
+    requireAdminToken: boolean;
+}
+/** Abuse limits (D14). */
+export interface LimitsConfig {
+    /** Browser origins allowed to join (empty: any). */
+    allowedOrigins: string[];
+    /** Accept joins that send no Origin header (native clients, tests). Default true. */
+    allowMissingOrigin: boolean;
+    /** Join requests one client address may make per minute. Default 120. */
+    joinRequestsPerMinutePerAddress: number;
+    /** Sessions one process hosts. Default 1000. */
+    maxSessions: number;
+    /** Players one session accepts; larger requests are clamped. Default 255. */
+    maxPlayersPerSession: number;
+    /** Dedicated sessions one process runs. Default 4. */
+    maxDedicatedSessions: number;
+    /** Largest WebSocket message in bytes. Default 65536. */
+    maxMessageBytes: number;
+    /** Messages one client may send per second before it is disconnected. Default 2000. */
+    maxMessagesPerSecond: number;
+    /** Longest session name in characters. Default 128. */
+    maxSessionNameLength: number;
+}
+/** Multi-instance scaling (D18). */
+export interface RedisConfig {
+    /** redis:// URL shared by every instance, or null for one process. */
+    url: string | null;
+}
+/** Dedicated Server-mode sessions (D19). */
+export interface DedicatedConfig {
+    /** The scenes dedicated sessions may run. */
+    scenes: DedicatedSceneConfig[];
+    /** Dedicated sessions started with the server. */
+    boot: DedicatedBootSession[];
+}
+/** Leaderboards (game-server-leaderboards D11): on by default, with boards created from an optional definitions file. */
+export interface LeaderboardsConfig {
+    /**
+     * JSON file of boards created on start when missing (game-server-leaderboards D11), relative to the working
+     * directory; null for none.
+     */
+    definitionsFile: string | null;
+    /**
+     * true: only callers whose verified auth identity has a user id may submit; anonymous players' existing entries are
+     * moved to the removed list on start (leaderboard-signed-in-only D1). Default false.
+     */
+    signedInPlayersOnly: boolean;
+}
+/** One scene a dedicated session may run. */
+export interface DedicatedSceneConfig {
+    /** Name clients and the admin API use. */
+    name: string;
+    /** http(s):// URL or folder of the exported scene. */
+    sceneRoot: string;
+    /** Exported scene file. */
+    sceneFile: string;
+    /** Extra script bundles loaded before the scene. */
+    projectScripts: string[];
+    /** Most players. Default 8. */
+    maxPlayers: number;
+    /** True when a Client join may start it. Default false. */
+    onDemand: boolean;
+    /** Seconds an on-demand session stays up empty. Default 60. */
+    idleSeconds: number;
+}
+/** A dedicated session started with the server. */
+export interface DedicatedBootSession {
+    /** The session name clients join. */
+    sessionName: string;
+    /** The DedicatedSceneConfig name it runs. */
+    sceneName: string;
+}
+/** A recursive partial, for config files and API overrides. */
+export type DeepPartial<Value> = {
+    [Key in keyof Value]?: Value[Key] extends Array<infer Item> ? Item[] : Value[Key] extends object | null ? DeepPartial<Value[Key]> : Value[Key];
+};
+/** One leaf option: where it lives and how flags and env vars spell it (D3). */
+export interface ConfigOptionDefinition {
+    /** Dotted path in GameServerConfig, e.g. "tls.certFile". */
+    path: string;
+    /** Environment variable, e.g. "GAME_SERVER_TLS_CERT_FILE". */
+    environmentVariable: string;
+    /** CLI flag without dashes, e.g. "tls-cert-file", or null. */
+    flag: string | null;
+    /** How text values parse. */
+    valueType: "string" | "nullable-string" | "number" | "boolean" | "string-list" | "enum";
+    /** Allowed values of an enum option. */
+    allowedValues?: string[];
+    /** One sentence for README, .env.example and --help. */
+    description: string;
+    /** True for secrets: redacted in logs. */
+    isSecret: boolean;
+}
+/**
+ * Where an option's value came from (game-server-admin-console D20); "platform" is a default of the host the server
+ * runs on (Colyseus Cloud), "code" is a value given to createGameServer.
+ */
+export type ConfigSource = "default" | "platform" | "file" | "environment" | "flag" | "code";
+/** The source of each CONFIG_OPTIONS path, keyed by dotted path. */
+export type ConfigSourceMap = Record<string, ConfigSource>;
+/** Where loadGameServerConfig reads from. */
+export interface GameServerConfigSources {
+    /** Command-line arguments after the subcommand. */
+    argv: string[];
+    /** Environment variables. */
+    environment: NodeJS.ProcessEnv;
+    /** Folder the config file is looked for in, and relative paths resolve against. */
+    workingDirectory: string;
+    /** CPUs on this machine (default: the real count). More than one means Colyseus Cloud runs on Redis. */
+    processorCount?: number;
+    /** The user's home folder (default: the real one), which holds the admin data on Colyseus Cloud. */
+    homeDirectory?: string;
+}
+/** Thrown when the config is invalid; lists every problem. */
+export declare class GameServerConfigError extends Error {
+    /** Every problem, one readable sentence each. */
+    readonly problems: string[];
+    /**
+     * Creates the error.
+     * @param problems Every problem found.
+     */
+    constructor(problems: string[]);
+}
+/** The settings a server uses when nothing overrides them (D2: TLS, UDP and auth off). */
+export declare const DEFAULT_GAME_SERVER_CONFIG: GameServerConfig;
+/** Every leaf option, once (D3). Flag parsing, env parsing, redaction and the docs all derive from it. */
+export declare const CONFIG_OPTIONS: ConfigOptionDefinition[];
+/**
+ * Tells whether this process runs on Colyseus Cloud.
+ * @param environment The process environment.
+ * @returns True on Colyseus Cloud.
+ */
+export declare function isColyseusCloud(environment: NodeJS.ProcessEnv): boolean;
+/**
+ * Loads the CLI config: defaults < platform < config file < environment < flags (D3), plus the legacy dedicated flags (D19).
+ * @param sources The arguments, environment and working directory.
+ * @returns The validated config.
+ * @throws GameServerConfigError listing every problem.
+ */
+export declare function loadGameServerConfig(sources: GameServerConfigSources): Promise<GameServerConfig>;
+/**
+ * Loads the CLI config like loadGameServerConfig and records where each option came from (game-server-admin-console
+ * D20): the last layer that set it, else "default".
+ * @param sources The arguments, environment and working directory.
+ * @returns The validated config and the source of every CONFIG_OPTIONS path.
+ * @throws GameServerConfigError listing every problem.
+ */
+export declare function loadGameServerConfigWithSources(sources: GameServerConfigSources): Promise<{
+    config: GameServerConfig;
+    sources: ConfigSourceMap;
+}>;
+/**
+ * Parses a value given for an option by its value type (the console's live overrides, game-server-admin-console
+ * D20): text parses as it would from an environment variable (so a string-list takes a comma-separated string), any
+ * other value is kept as it is for validateGameServerConfig to check.
+ * @param definition The option.
+ * @param value The value given.
+ * @returns The value, or null when text does not parse.
+ */
+export declare function parseOptionValue(definition: ConfigOptionDefinition, value: unknown): {
+    value: unknown;
+} | null;
+/**
+ * The defaults deep-merged with overrides (objects merge, arrays and scalars replace), then validated.
+ * @param overrides The values to apply (a full config is fine).
+ * @param environment The environment validation checks (NODE_ENV); the process environment when omitted.
+ * @returns The validated config.
+ * @throws GameServerConfigError listing every problem.
+ */
+export declare function resolveGameServerConfig(overrides: DeepPartial<GameServerConfig>, environment?: NodeJS.ProcessEnv): GameServerConfig;
+/**
+ * The problems of a config (empty when valid): wrong value types, out-of-range numbers and incomplete opt-ins (D2).
+ * @param config The config.
+ * @param environment The environment (NODE_ENV); the process environment when omitted.
+ * @returns One sentence per problem, each naming the option and its environment variable.
+ */
+export declare function validateGameServerConfig(config: GameServerConfig, environment?: NodeJS.ProcessEnv): string[];
+/**
+ * A copy safe to log: every isSecret option replaced by "[redacted]" (when set) or null (D4).
+ * @param config The config.
+ * @returns The redacted copy.
+ */
+export declare function describeConfig(config: GameServerConfig): Record<string, unknown>;
+/**
+ * The log format a config means here: "auto" is JSON under NODE_ENV=production, else text (D4).
+ * @param config The config.
+ * @param environment The environment (NODE_ENV); the process environment when omitted.
+ * @returns "json" or "text".
+ */
+export declare function effectiveLogFormat(config: GameServerConfig, environment?: NodeJS.ProcessEnv): "json" | "text";
+/**
+ * Whether NODE_ENV says production.
+ * @param environment The environment.
+ * @returns True when NODE_ENV is "production".
+ */
+export declare function isProductionEnvironment(environment: NodeJS.ProcessEnv): boolean;
+/**
+ * Reads a dotted path of an object.
+ * @param target The object.
+ * @param dottedPath E.g. "tls.certFile".
+ * @returns The value, or undefined when a step is missing.
+ */
+export declare function readPath(target: object, dottedPath: string): unknown;
+/**
+ * Writes a dotted path of an object, creating the objects on the way.
+ * @param target The object.
+ * @param dottedPath E.g. "tls.certFile".
+ * @param value The value.
+ */
+export declare function writePath(target: object, dottedPath: string, value: unknown): void;
+/**
+ * Whether a text is a bare origin: http(s), a host, an optional port, and nothing else.
+ * @param origin The text.
+ * @returns True for "https://game.example.com" or "http://localhost:6178".
+ */
+export declare function isPlainOrigin(origin: string): boolean;