@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/GameServerLobbyRoom.d.ts

@@ -0,0 +1,33 @@
+import { LobbyRoom, type AuthContext } from "colyseus";
+import { type JoinGateResult } from "./JoinGate.js";
+import type { FusionConnectRequest } from "./HeadlessRuntime.js";
+/**
+ * The lobby room ("fusion_lobby"): Colyseus' LobbyRoom behind the same join gate as sessions (D10), so origin, rate and
+ * auth rules apply to session listing too. Live lobby rooms are kept in the server state, so the admin console can
+ * remove a player from the lobby (game-server-admin-console R15).
+ */
+export declare class GameServerLobbyRoom extends LobbyRoom {
+    /**
+     * The join gate of the lobby (kind "lobby": no protocol-version or session-name checks).
+     * @param token The bearer token the client sent.
+     * @param options The join options.
+     * @param context Colyseus' matchmaking context.
+     * @returns The identity and client address, stored as client.auth.
+     * @throws ServerError when the gate refuses the join.
+     */
+    static onAuth(token: string, options: Partial<FusionConnectRequest>, context: AuthContext): Promise<JoinGateResult>;
+    /**
+     * Starts the lobby listing and joins the server's live lobby rooms.
+     * @param options The creation options.
+     */
+    onCreate(options: unknown): Promise<void>;
+    /** Stops the lobby listing and leaves the server's live lobby rooms. */
+    onDispose(): void;
+    /**
+     * Removes the lobby clients that match a user id or an address (lobby kick): each leaves with CloseCode.CONSENTED.
+     * @param userIds User ids to remove.
+     * @param addresses Addresses to remove.
+     * @returns How many clients were removed.
+     */
+    adminKickMatching(userIds: string[], addresses: string[]): number;
+}

package/lib/GameServerLobbyRoom.js

@@ -0,0 +1,56 @@
+import { CloseCode, LobbyRoom } from "colyseus";
+import { findGameServerState, getGameServerState } from "./GameServerState.js";
+import { authorizeJoin } from "./JoinGate.js";
+import { normalizeAddress } from "./NetworkAddresses.js";
+/**
+ * The lobby room ("fusion_lobby"): Colyseus' LobbyRoom behind the same join gate as sessions (D10), so origin, rate and
+ * auth rules apply to session listing too. Live lobby rooms are kept in the server state, so the admin console can
+ * remove a player from the lobby (game-server-admin-console R15).
+ */
+export class GameServerLobbyRoom extends LobbyRoom {
+    /**
+     * The join gate of the lobby (kind "lobby": no protocol-version or session-name checks).
+     * @param token The bearer token the client sent.
+     * @param options The join options.
+     * @param context Colyseus' matchmaking context.
+     * @returns The identity and client address, stored as client.auth.
+     * @throws ServerError when the gate refuses the join.
+     */
+    static async onAuth(token, options, context) {
+        return authorizeJoin(token, options, context, "lobby");
+    }
+    /**
+     * Starts the lobby listing and joins the server's live lobby rooms.
+     * @param options The creation options.
+     */
+    async onCreate(options) {
+        await super.onCreate(options);
+        getGameServerState().lobbyRooms.add(this);
+    }
+    /** Stops the lobby listing and leaves the server's live lobby rooms. */
+    onDispose() {
+        super.onDispose();
+        findGameServerState()?.lobbyRooms.delete(this);
+    }
+    /**
+     * Removes the lobby clients that match a user id or an address (lobby kick): each leaves with CloseCode.CONSENTED.
+     * @param userIds User ids to remove.
+     * @param addresses Addresses to remove.
+     * @returns How many clients were removed.
+     */
+    adminKickMatching(userIds, addresses) {
+        const kickedAddresses = new Set(addresses.map(normalizeAddress));
+        let disconnected = 0;
+        for (const client of Array.from(this.clients)) {
+            const gateResult = client.auth;
+            const userId = gateResult?.identity?.userId ?? null;
+            const address = normalizeAddress(gateResult?.clientAddress ?? "");
+            const matches = (userId != null && userIds.includes(userId)) || kickedAddresses.has(address);
+            if (!matches)
+                continue;
+            client.leave(CloseCode.CONSENTED);
+            disconnected += 1;
+        }
+        return disconnected;
+    }
+}

package/lib/GameServerLogger.d.ts

@@ -0,0 +1,111 @@
+import type { GameServerLogLevel } from "./GameServerConfig.js";
+/** Context fields of a log entry; the known ones are added whenever the caller has them (D4). */
+export interface LogFields {
+    /** The session name. */
+    sessionName?: string;
+    /** The Colyseus room id. */
+    roomId?: string;
+    /** The player id in the session. */
+    playerId?: number;
+    /** The verified user id, or null when the player is anonymous. */
+    userId?: string | null;
+    /** The client's address (D11). */
+    clientAddress?: string;
+    /** Any other field. Never put tokens, secrets or PEM text here. */
+    [field: string]: unknown;
+}
+/** The format of the lines a logger writes. */
+export type LogLineFormat = "json" | "text";
+/**
+ * Receives every entry that passes the logger's level, before it is written (the admin console's log buffer, D21).
+ * @param level The entry's level.
+ * @param message What happened.
+ * @param fields The entry's fields, undefined ones dropped and errors turned into their messages.
+ */
+export type LogSink = (level: GameServerLogLevel, message: string, fields: Record<string, unknown>) => void;
+/**
+ * Structured logs without a dependency (D4): one JSON object per line in production, else one readable line per entry,
+ * `<ISO time> <LEVEL> [GameServer] <message> key=value ...`.
+ */
+export declare class GameServerLogger {
+    /** The line format. */
+    private readonly format;
+    /** The least severe level written; the console can change it while the server runs (D21). */
+    private currentLevelValue;
+    /** Where lines go, or null for the console (errors and warnings to stderr, the rest to stdout). */
+    private readonly write;
+    /** Listeners of every logged entry. */
+    private readonly sinks;
+    /**
+     * Creates a logger.
+     * @param format "json" or "text".
+     * @param level The least severe level written.
+     * @param write Receives each finished line (no trailing newline); the console when omitted.
+     */
+    constructor(format: LogLineFormat, level: GameServerLogLevel, write?: (line: string) => void);
+    /** The least severe level logged now. */
+    get currentLevel(): GameServerLogLevel;
+    /**
+     * Changes the least severe level logged, from the next entry on.
+     * @param level The new level.
+     */
+    setLevel(level: GameServerLogLevel): void;
+    /**
+     * Adds a listener that receives every entry that passes the level, before it is written.
+     * @param sink The listener; one that throws is ignored, so it can never stop a log line.
+     */
+    addSink(sink: LogSink): void;
+    /**
+     * Removes a listener added with addSink.
+     * @param sink The listener.
+     */
+    removeSink(sink: LogSink): void;
+    /**
+     * Logs a failure that needs attention.
+     * @param message What happened.
+     * @param fields Context fields.
+     */
+    error(message: string, fields?: LogFields): void;
+    /**
+     * Logs something unexpected that the server worked around.
+     * @param message What happened.
+     * @param fields Context fields.
+     */
+    warn(message: string, fields?: LogFields): void;
+    /**
+     * Logs a normal lifecycle event.
+     * @param message What happened.
+     * @param fields Context fields.
+     */
+    info(message: string, fields?: LogFields): void;
+    /**
+     * Logs detail useful when diagnosing.
+     * @param message What happened.
+     * @param fields Context fields.
+     */
+    debug(message: string, fields?: LogFields): void;
+    /**
+     * Hands one entry to the sinks and writes it, when its level is enabled.
+     * @param level The entry's level.
+     * @param message What happened.
+     * @param fields Context fields.
+     */
+    private log;
+    /**
+     * Calls every sink with a copy of the fields; a sink that throws is ignored.
+     * @param level The entry's level.
+     * @param message What happened.
+     * @param fields The cleaned fields.
+     */
+    private notifySinks;
+}
+/**
+ * The process logger.
+ * @returns The logger createGameServer configured, or a text/info logger before that.
+ */
+export declare function getLogger(): GameServerLogger;
+/**
+ * Replaces the process logger (createGameServer calls it with the configured format and level).
+ * @param logger The new logger.
+ */
+export declare function setLogger(logger: GameServerLogger): void;

package/lib/GameServerLogger.js

@@ -0,0 +1,190 @@
+/** Rank of each level: an entry is written when its rank is at most the logger's (error 0 … debug 3). */
+const LOG_LEVEL_RANK = { error: 0, warn: 1, info: 2, debug: 3 };
+/** Width the level is padded to in text lines, so messages line up. */
+const TEXT_LEVEL_WIDTH = 5;
+/** Tag of every text line. */
+const TEXT_LINE_TAG = "[GameServer]";
+/**
+ * Structured logs without a dependency (D4): one JSON object per line in production, else one readable line per entry,
+ * `<ISO time> <LEVEL> [GameServer] <message> key=value ...`.
+ */
+export class GameServerLogger {
+    /** The line format. */
+    format;
+    /** The least severe level written; the console can change it while the server runs (D21). */
+    currentLevelValue;
+    /** Where lines go, or null for the console (errors and warnings to stderr, the rest to stdout). */
+    write;
+    /** Listeners of every logged entry. */
+    sinks = [];
+    /**
+     * Creates a logger.
+     * @param format "json" or "text".
+     * @param level The least severe level written.
+     * @param write Receives each finished line (no trailing newline); the console when omitted.
+     */
+    constructor(format, level, write) {
+        this.format = format;
+        this.currentLevelValue = level;
+        this.write = write ?? null;
+    }
+    /** The least severe level logged now. */
+    get currentLevel() {
+        return this.currentLevelValue;
+    }
+    /**
+     * Changes the least severe level logged, from the next entry on.
+     * @param level The new level.
+     */
+    setLevel(level) {
+        this.currentLevelValue = level;
+    }
+    /**
+     * Adds a listener that receives every entry that passes the level, before it is written.
+     * @param sink The listener; one that throws is ignored, so it can never stop a log line.
+     */
+    addSink(sink) {
+        this.sinks.push(sink);
+    }
+    /**
+     * Removes a listener added with addSink.
+     * @param sink The listener.
+     */
+    removeSink(sink) {
+        const index = this.sinks.indexOf(sink);
+        if (index >= 0)
+            this.sinks.splice(index, 1);
+    }
+    /**
+     * Logs a failure that needs attention.
+     * @param message What happened.
+     * @param fields Context fields.
+     */
+    error(message, fields) {
+        this.log("error", message, fields);
+    }
+    /**
+     * Logs something unexpected that the server worked around.
+     * @param message What happened.
+     * @param fields Context fields.
+     */
+    warn(message, fields) {
+        this.log("warn", message, fields);
+    }
+    /**
+     * Logs a normal lifecycle event.
+     * @param message What happened.
+     * @param fields Context fields.
+     */
+    info(message, fields) {
+        this.log("info", message, fields);
+    }
+    /**
+     * Logs detail useful when diagnosing.
+     * @param message What happened.
+     * @param fields Context fields.
+     */
+    debug(message, fields) {
+        this.log("debug", message, fields);
+    }
+    /**
+     * Hands one entry to the sinks and writes it, when its level is enabled.
+     * @param level The entry's level.
+     * @param message What happened.
+     * @param fields Context fields.
+     */
+    log(level, message, fields) {
+        if (LOG_LEVEL_RANK[level] > LOG_LEVEL_RANK[this.currentLevelValue])
+            return;
+        const entryFields = cleanFields(fields);
+        this.notifySinks(level, message, entryFields);
+        const line = (this.format === "json") ? jsonLine(level, message, entryFields) : textLine(level, message, entryFields);
+        if (this.write != null)
+            this.write(line);
+        else if (LOG_LEVEL_RANK[level] <= LOG_LEVEL_RANK.warn)
+            process.stderr.write(line + "\n");
+        else
+            process.stdout.write(line + "\n");
+    }
+    /**
+     * Calls every sink with a copy of the fields; a sink that throws is ignored.
+     * @param level The entry's level.
+     * @param message What happened.
+     * @param fields The cleaned fields.
+     */
+    notifySinks(level, message, fields) {
+        for (const sink of this.sinks) {
+            try {
+                sink(level, message, Object.assign({}, fields));
+            }
+            catch {
+                // A failing listener must never stop the line itself from being written.
+            }
+        }
+    }
+}
+/** The process logger (text/info until createGameServer configures it). */
+let processLogger = new GameServerLogger("text", "info");
+/**
+ * The process logger.
+ * @returns The logger createGameServer configured, or a text/info logger before that.
+ */
+export function getLogger() {
+    return processLogger;
+}
+/**
+ * Replaces the process logger (createGameServer calls it with the configured format and level).
+ * @param logger The new logger.
+ */
+export function setLogger(logger) {
+    processLogger = logger;
+}
+/**
+ * Drops undefined fields and turns errors into their messages (JSON.stringify writes an Error as {}).
+ * @param fields The caller's fields.
+ * @returns Fields ready to write.
+ */
+function cleanFields(fields) {
+    const cleaned = {};
+    if (fields == null)
+        return cleaned;
+    for (const [name, value] of Object.entries(fields)) {
+        if (value === undefined)
+            continue;
+        cleaned[name] = (value instanceof Error) ? value.message : value;
+    }
+    return cleaned;
+}
+/**
+ * A JSON log line.
+ * @param level The level.
+ * @param message The message.
+ * @param fields The fields.
+ * @returns `{"time":…,"level":…,"message":…,…fields}`.
+ */
+function jsonLine(level, message, fields) {
+    return JSON.stringify(Object.assign({ time: new Date().toISOString(), level: level, message: message }, fields));
+}
+/**
+ * A readable log line.
+ * @param level The level.
+ * @param message The message.
+ * @param fields The fields.
+ * @returns `<ISO time> <LEVEL> [GameServer] <message> key=value ...`.
+ */
+function textLine(level, message, fields) {
+    const fieldText = Object.entries(fields).map(([name, value]) => " " + name + "=" + textFieldValue(value)).join("");
+    return new Date().toISOString() + " " + level.toUpperCase().padEnd(TEXT_LEVEL_WIDTH) + " " + TEXT_LINE_TAG + " " + message + fieldText;
+}
+/**
+ * How a field value reads in a text line: strings with spaces quoted, objects as JSON.
+ * @param value The value.
+ * @returns The text.
+ */
+function textFieldValue(value) {
+    if (typeof value === "string")
+        return /\s/.test(value) ? JSON.stringify(value) : value;
+    if (value !== null && typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}

package/lib/GameServerMetrics.d.ts

@@ -0,0 +1,158 @@
+import type { AuthMode } from "./GameServerConfig.js";
+import type { GameServerMetricsSink, GameServerStateValues } from "./GameServerState.js";
+/** Counter totals since start, summed over their labels (game-server-admin-console R22, DR §6.7). */
+export interface MetricsCounterSnapshot {
+    /** Accepted joins. */
+    joinsAccepted: number;
+    /** Refused joins. */
+    joinsRefused: number;
+    /** Refused joins by ShutdownReason name. */
+    refusalsByReason: Record<string, number>;
+    /** Failed token checks. */
+    authFailures: number;
+    /** Frames from clients. */
+    framesIn: number;
+    /** Frames to clients. */
+    framesOut: number;
+    /** Frame bytes from clients. */
+    bytesIn: number;
+    /** Frame bytes to clients. */
+    bytesOut: number;
+    /** Frames (both directions) by the client's transport. */
+    framesByTransport: {
+        websocket: number;
+        webtransport: number;
+    };
+    /** Room messages (frames and controls) from clients. */
+    messagesIn: number;
+    /** Room messages (frames and controls) to clients. */
+    messagesOut: number;
+    /** Dedicated frames longer than one tick. */
+    dedicatedTickOverruns: number;
+    /** Sum of dedicated frame durations, in seconds. */
+    dedicatedFrameSecondsSum: number;
+    /** Dedicated frames observed. */
+    dedicatedFrameCount: number;
+    /** Process CPU time, in seconds. */
+    cpuSecondsTotal: number;
+    /** Resident memory, in bytes. */
+    residentMemoryBytes: number;
+    /** Used V8 heap, in bytes. */
+    heapUsedBytes: number;
+    /** Time spent in garbage collection, in seconds. */
+    gcSecondsTotal: number;
+    /** Accepted leaderboard scores (game-server-leaderboards D21). */
+    leaderboardScoresAccepted: number;
+    /** Refused leaderboard scores (game-server-leaderboards D21). */
+    leaderboardScoresRefused: number;
+}
+/**
+ * The Prometheus metrics of a game server (D16), on a private registry with the process defaults (event-loop lag,
+ * memory). The player, session and dedicated-session gauges are computed when Prometheus scrapes, from the live session
+ * rooms, so nothing polls; the counters and the frame histogram are fed by the rooms and the join gate through
+ * GameServerMetricsSink.
+ */
+export declare class GameServerMetrics implements GameServerMetricsSink {
+    /** The registry every metric of this server is on. */
+    private readonly registry;
+    /** Reads the running server's state at scrape time. */
+    private readonly readState;
+    /** Join decisions by result. */
+    private readonly joinsTotal;
+    /** Refused joins by ShutdownReason name. */
+    private readonly refusalsTotal;
+    /** Failed token checks by auth mode. */
+    private readonly authFailuresTotal;
+    /** Simulation frames by direction, transport and channel. */
+    private readonly framesTotal;
+    /** Simulation frame bytes by direction and transport. */
+    private readonly bytesTotal;
+    /** Room messages (frames and controls) by direction: the room message rate. */
+    private readonly messagesTotal;
+    /** Leaderboard scores by result (game-server-leaderboards D21). */
+    private readonly leaderboardScoresTotal;
+    /** Refused leaderboard scores and requests by reason (game-server-leaderboards D19). */
+    private readonly leaderboardRefusalsTotal;
+    /** Dedicated frames that took longer than one simulation tick. */
+    private readonly dedicatedTickOverrunsTotal;
+    /** How long dedicated runners' frames take. */
+    private readonly dedicatedFrameSeconds;
+    /** The last counter snapshot, reused for SNAPSHOT_CACHE_MS. */
+    private cachedSnapshot;
+    /**
+     * Creates the metrics and registers the process defaults.
+     * @param state Reads the running server's state (the gauges read its session rooms at scrape time).
+     */
+    constructor(state: () => GameServerStateValues);
+    /** The Content-Type of the Prometheus text the metrics endpoint answers with. */
+    get contentType(): string;
+    /**
+     * Counts a join decision; a refusal is also counted by its reason.
+     * @param result "accepted" or "refused".
+     * @param reasonName The ShutdownReason name of a refusal, or null.
+     */
+    countJoin(result: "accepted" | "refused", reasonName: string | null): void;
+    /**
+     * Counts a failed token check.
+     * @param mode The auth mode that refused it.
+     */
+    countAuthFailure(mode: AuthMode): void;
+    /**
+     * Counts one simulation frame and its bytes.
+     * @param direction "in" from a client, "out" to a client.
+     * @param transport The client's connection.
+     * @param channel The delivery channel.
+     * @param byteLength The frame size in bytes.
+     */
+    countFrame(direction: "in" | "out", transport: "websocket" | "webtransport", channel: "reliable" | "unreliable", byteLength: number): void;
+    /**
+     * Counts one room message (a simulation frame or a control).
+     * @param direction "in" from a client, "out" to a client.
+     */
+    countMessage(direction: "in" | "out"): void;
+    /**
+     * Counts one leaderboard score; a refused score is also counted by its reason (game-server-leaderboards D19).
+     * @param result What happened to the score.
+     * @param reason The refusal reason, or null.
+     */
+    countLeaderboardScore(result: "accepted" | "duplicate" | "refused", reason: string | null): void;
+    /**
+     * Counts one refused leaderboard request (rate limit, auth, ban, bad request; game-server-leaderboards D19).
+     * @param reason The refusal reason.
+     */
+    countLeaderboardRequestRefusal(reason: string): void;
+    /**
+     * Records how long a dedicated runner's frame took, counting an overrun when it did not fit in one tick.
+     * @param seconds The frame's duration, in seconds.
+     * @param tickSeconds The simulation tick length, in seconds.
+     */
+    observeDedicatedFrame(seconds: number, tickSeconds: number): void;
+    /**
+     * Renders every metric as Prometheus text (computing the gauges from the live session rooms).
+     * @returns The exposition text.
+     */
+    render(): Promise<string>;
+    /**
+     * The counter totals the admin console reads (game-server-admin-console R22): a snapshot younger than the allowed
+     * age is returned as it is, so the registry's JSON is built at most about once per metrics sample (building it also
+     * restarts the event-loop histogram of the process defaults).
+     * @param maxAgeMilliseconds The oldest cached snapshot accepted (default SNAPSHOT_CACHE_MS; the metrics sampler
+     *     passes less, so each of its samples reads fresh counters).
+     * @returns The totals since start.
+     */
+    snapshot(maxAgeMilliseconds?: number): Promise<MetricsCounterSnapshot>;
+    /**
+     * Registers the scrape-time gauges: players and sessions by game mode, and dedicated sessions.
+     */
+    private registerGauges;
+    /**
+     * Sums players and sessions of the live session rooms by game mode name.
+     * @returns The totals, keyed by game mode name ("Pending" before a session's first join).
+     */
+    private totalsByGameMode;
+    /**
+     * The live session rooms of the running server.
+     * @returns The rooms.
+     */
+    private liveRooms;
+}