@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/GameServerMetrics.js

@@ -0,0 +1,276 @@
+import { collectDefaultMetrics, Counter, Gauge, Histogram, Registry } from "prom-client";
+/** Prefix of every metric name (D16). */
+const METRIC_PREFIX = "babylon_game_server_";
+/**
+ * Bucket bounds of the dedicated frame histogram, in seconds: from well under a 60 Hz tick (16.7 ms) to frames long
+ * enough to stall a session.
+ */
+const DEDICATED_FRAME_BUCKETS_SECONDS = [0.001, 0.0025, 0.005, 0.01, 0.0167, 0.025, 0.05, 0.1, 0.25, 0.5, 1];
+/**
+ * How long a counter snapshot is reused, in milliseconds (game-server-admin-console R22): just under one metrics sample
+ * interval, so the registry's JSON is built about once per sample however many readers there are.
+ */
+const SNAPSHOT_CACHE_MS = 14000;
+/**
+ * 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 class GameServerMetrics {
+    /** The registry every metric of this server is on. */
+    registry = new Registry();
+    /** Reads the running server's state at scrape time. */
+    readState;
+    /** Join decisions by result. */
+    joinsTotal;
+    /** Refused joins by ShutdownReason name. */
+    refusalsTotal;
+    /** Failed token checks by auth mode. */
+    authFailuresTotal;
+    /** Simulation frames by direction, transport and channel. */
+    framesTotal;
+    /** Simulation frame bytes by direction and transport. */
+    bytesTotal;
+    /** Room messages (frames and controls) by direction: the room message rate. */
+    messagesTotal;
+    /** Leaderboard scores by result (game-server-leaderboards D21). */
+    leaderboardScoresTotal;
+    /** Refused leaderboard scores and requests by reason (game-server-leaderboards D19). */
+    leaderboardRefusalsTotal;
+    /** Dedicated frames that took longer than one simulation tick. */
+    dedicatedTickOverrunsTotal;
+    /** How long dedicated runners' frames take. */
+    dedicatedFrameSeconds;
+    /** The last counter snapshot, reused for SNAPSHOT_CACHE_MS. */
+    cachedSnapshot = null;
+    /**
+     * 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) {
+        this.readState = state;
+        collectDefaultMetrics({ register: this.registry, prefix: METRIC_PREFIX });
+        this.registerGauges();
+        const registers = [this.registry];
+        this.joinsTotal = new Counter({ name: METRIC_PREFIX + "joins_total", help: "Session and lobby join decisions, by result.", labelNames: ["result"], registers: registers });
+        this.refusalsTotal = new Counter({ name: METRIC_PREFIX + "refusals_total", help: "Refused joins, by ShutdownReason name.", labelNames: ["reason"], registers: registers });
+        this.authFailuresTotal = new Counter({ name: METRIC_PREFIX + "auth_failures_total", help: "Failed token checks, by auth mode.", labelNames: ["mode"], registers: registers });
+        this.framesTotal = new Counter({ name: METRIC_PREFIX + "frames_total", help: "Simulation frames, by direction, transport and channel.", labelNames: ["direction", "transport", "channel"], registers: registers });
+        this.bytesTotal = new Counter({ name: METRIC_PREFIX + "bytes_total", help: "Simulation frame bytes, by direction and transport.", labelNames: ["direction", "transport"], registers: registers });
+        this.messagesTotal = new Counter({ name: METRIC_PREFIX + "messages_total", help: "Room messages (simulation frames and controls), by direction.", labelNames: ["direction"], registers: registers });
+        this.dedicatedTickOverrunsTotal = new Counter({ name: METRIC_PREFIX + "dedicated_tick_overruns_total", help: "Dedicated runner frames longer than one simulation tick.", registers: registers });
+        this.leaderboardScoresTotal = new Counter({ name: METRIC_PREFIX + "leaderboard_scores_total", help: "Leaderboard scores, by result.", labelNames: ["result"], registers: registers });
+        this.leaderboardRefusalsTotal = new Counter({ name: METRIC_PREFIX + "leaderboard_refusals_total", help: "Refused leaderboard scores and requests, by reason.", labelNames: ["reason"], registers: registers });
+        this.dedicatedFrameSeconds = new Histogram({ name: METRIC_PREFIX + "dedicated_frame_seconds", help: "Duration of dedicated runner frames, in seconds.", buckets: DEDICATED_FRAME_BUCKETS_SECONDS, registers: registers });
+    }
+    /** The Content-Type of the Prometheus text the metrics endpoint answers with. */
+    get contentType() {
+        return this.registry.contentType;
+    }
+    /**
+     * 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, reasonName) {
+        this.joinsTotal.inc({ result: result });
+        if (result === "refused" && reasonName != null)
+            this.refusalsTotal.inc({ reason: reasonName });
+    }
+    /**
+     * Counts a failed token check.
+     * @param mode The auth mode that refused it.
+     */
+    countAuthFailure(mode) {
+        this.authFailuresTotal.inc({ mode: mode });
+    }
+    /**
+     * 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, transport, channel, byteLength) {
+        this.framesTotal.inc({ direction: direction, transport: transport, channel: channel });
+        this.bytesTotal.inc({ direction: direction, transport: transport }, byteLength);
+    }
+    /**
+     * Counts one room message (a simulation frame or a control).
+     * @param direction "in" from a client, "out" to a client.
+     */
+    countMessage(direction) {
+        this.messagesTotal.inc({ direction: direction });
+    }
+    /**
+     * 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, reason) {
+        this.leaderboardScoresTotal.inc({ result: result });
+        if (reason != null)
+            this.leaderboardRefusalsTotal.inc({ reason: reason });
+    }
+    /**
+     * Counts one refused leaderboard request (rate limit, auth, ban, bad request; game-server-leaderboards D19).
+     * @param reason The refusal reason.
+     */
+    countLeaderboardRequestRefusal(reason) {
+        this.leaderboardRefusalsTotal.inc({ reason: reason });
+    }
+    /**
+     * 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, tickSeconds) {
+        this.dedicatedFrameSeconds.observe(seconds);
+        if (seconds > tickSeconds)
+            this.dedicatedTickOverrunsTotal.inc();
+    }
+    /**
+     * Renders every metric as Prometheus text (computing the gauges from the live session rooms).
+     * @returns The exposition text.
+     */
+    render() {
+        return this.registry.metrics();
+    }
+    /**
+     * 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.
+     */
+    async snapshot(maxAgeMilliseconds = SNAPSHOT_CACHE_MS) {
+        const now = Date.now();
+        if (this.cachedSnapshot != null && now - this.cachedSnapshot.takenAt < maxAgeMilliseconds)
+            return this.cachedSnapshot.snapshot;
+        const metrics = await this.registry.getMetricsAsJSON();
+        const snapshot = buildCounterSnapshot(metrics);
+        this.cachedSnapshot = { takenAt: now, snapshot: snapshot };
+        return snapshot;
+    }
+    /**
+     * Registers the scrape-time gauges: players and sessions by game mode, and dedicated sessions.
+     */
+    registerGauges() {
+        const metrics = this;
+        const registers = [this.registry];
+        new Gauge({
+            name: METRIC_PREFIX + "players",
+            help: "Players connected to sessions, by game mode.",
+            labelNames: ["game_mode"],
+            registers: registers,
+            collect() {
+                this.reset();
+                for (const [gameMode, totals] of metrics.totalsByGameMode())
+                    this.set({ game_mode: gameMode }, totals.players);
+            }
+        });
+        new Gauge({
+            name: METRIC_PREFIX + "sessions",
+            help: "Live sessions, by game mode.",
+            labelNames: ["game_mode"],
+            registers: registers,
+            collect() {
+                this.reset();
+                for (const [gameMode, totals] of metrics.totalsByGameMode())
+                    this.set({ game_mode: gameMode }, totals.sessions);
+            }
+        });
+        new Gauge({
+            name: METRIC_PREFIX + "dedicated_sessions",
+            help: "Live sessions a dedicated Server-mode runner hosts.",
+            registers: registers,
+            collect() {
+                this.set(metrics.liveRooms().filter((room) => room.isDedicated).length);
+            }
+        });
+    }
+    /**
+     * 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).
+     */
+    totalsByGameMode() {
+        const totals = new Map();
+        for (const room of this.liveRooms()) {
+            const modeTotals = totals.get(room.gameModeName) ?? { players: 0, sessions: 0 };
+            modeTotals.players += room.playerCount;
+            modeTotals.sessions += 1;
+            totals.set(room.gameModeName, modeTotals);
+        }
+        return totals;
+    }
+    /**
+     * The live session rooms of the running server.
+     * @returns The rooms.
+     */
+    liveRooms() {
+        return Array.from(this.readState().sessionRooms);
+    }
+}
+/**
+ * Sums the registry's JSON into the counter snapshot (DR §6.7).
+ * @param metrics The registry's metrics as JSON.
+ * @returns The snapshot.
+ */
+function buildCounterSnapshot(metrics) {
+    const sum = (name, filter = () => true) => sumMetric(metrics, METRIC_PREFIX + name, filter);
+    const withLabel = (label, expected) => (value) => value.labels[label] === expected;
+    const named = (metricName) => (value) => value.metricName === METRIC_PREFIX + metricName;
+    return {
+        joinsAccepted: sum("joins_total", withLabel("result", "accepted")),
+        joinsRefused: sum("joins_total", withLabel("result", "refused")),
+        refusalsByReason: sumByLabel(metrics, METRIC_PREFIX + "refusals_total", "reason"),
+        authFailures: sum("auth_failures_total"),
+        framesIn: sum("frames_total", withLabel("direction", "in")),
+        framesOut: sum("frames_total", withLabel("direction", "out")),
+        bytesIn: sum("bytes_total", withLabel("direction", "in")),
+        bytesOut: sum("bytes_total", withLabel("direction", "out")),
+        framesByTransport: { websocket: sum("frames_total", withLabel("transport", "websocket")), webtransport: sum("frames_total", withLabel("transport", "webtransport")) },
+        messagesIn: sum("messages_total", withLabel("direction", "in")),
+        messagesOut: sum("messages_total", withLabel("direction", "out")),
+        dedicatedTickOverruns: sum("dedicated_tick_overruns_total"),
+        dedicatedFrameSecondsSum: sum("dedicated_frame_seconds", named("dedicated_frame_seconds_sum")),
+        dedicatedFrameCount: sum("dedicated_frame_seconds", named("dedicated_frame_seconds_count")),
+        cpuSecondsTotal: sum("process_cpu_seconds_total"),
+        residentMemoryBytes: sum("process_resident_memory_bytes"),
+        heapUsedBytes: sum("nodejs_heap_size_used_bytes"),
+        gcSecondsTotal: sum("nodejs_gc_duration_seconds", named("nodejs_gc_duration_seconds_sum")),
+        leaderboardScoresAccepted: sum("leaderboard_scores_total", withLabel("result", "accepted")),
+        leaderboardScoresRefused: sum("leaderboard_scores_total", withLabel("result", "refused"))
+    };
+}
+/**
+ * Sums the values of one metric that pass a filter.
+ * @param metrics The registry's metrics as JSON.
+ * @param name The full metric name.
+ * @param filter Picks the values to add.
+ * @returns The sum, or 0 when the metric is missing.
+ */
+function sumMetric(metrics, name, filter) {
+    const metric = metrics.find((candidate) => candidate.name === name);
+    if (metric == null)
+        return 0;
+    return metric.values.filter(filter).reduce((total, value) => total + value.value, 0);
+}
+/**
+ * Sums the values of one metric per value of a label.
+ * @param metrics The registry's metrics as JSON.
+ * @param name The full metric name.
+ * @param label The label to group by.
+ * @returns The sums, keyed by label value.
+ */
+function sumByLabel(metrics, name, label) {
+    const totals = {};
+    const metric = metrics.find((candidate) => candidate.name === name);
+    for (const value of metric?.values ?? []) {
+        const key = String(value.labels[label] ?? "");
+        totals[key] = (totals[key] ?? 0) + value.value;
+    }
+    return totals;
+}

package/lib/GameServerState.d.ts

@@ -0,0 +1,164 @@
+import type { JoinRateLimiter } from "./AbuseLimits.js";
+import type { AuthIdentity, AuthRequest, ManagedTokenVerifier } from "./Authentication.js";
+import type { DedicatedSceneRegistry } from "./DedicatedSceneRegistry.js";
+import type { AuthMode, ConfigSourceMap, GameServerConfig } from "./GameServerConfig.js";
+import type { SessionRoom } from "./SessionRoom.js";
+import type { DiscordSessions } from "./discord/DiscordSessions.js";
+import type { TlsMaterial } from "./TlsCertificates.js";
+import type { GameServerLobbyRoom } from "./GameServerLobbyRoom.js";
+import type { MaintenanceState } from "./admin/AdminApiTypes.js";
+import type { BanList, KickBlockList } from "./admin/BanList.js";
+import type { LogBuffer } from "./admin/LogBuffer.js";
+import type { PlayerSessionEvent } from "./admin/AdminRecords.js";
+/** A session's description, passed to the session hooks. */
+export interface SessionEvent {
+    /** The Colyseus room id. */
+    roomId: string;
+    /** The session name players join by. */
+    sessionName: string;
+    /** The TOOLKIT.GameMode of the joiner that created the session (Server for a dedicated session), or null. */
+    gameMode: number | null;
+    /** True when a dedicated Server-mode runner hosts the session. */
+    isDedicated: boolean;
+}
+/** A player of a session, passed to the player hooks. */
+export interface PlayerEvent extends SessionEvent {
+    /** The player id in the session. */
+    playerId: number;
+    /** The identity the server verified from the player's token, or null when auth is off. */
+    identity: AuthIdentity | null;
+}
+/**
+ * Lifecycle and custom-auth hooks of a game server. A hook that throws is logged with its name and the server carries on.
+ */
+export interface GameServerHooks {
+    /**
+     * The verifier of auth mode "custom" (D13).
+     * @param request The token and what the server knows about the join.
+     * @returns The verified identity, or null to refuse with CustomAuthenticationFailed.
+     */
+    verifyToken?(request: AuthRequest): Promise<AuthIdentity | null>;
+    /**
+     * A session room was created.
+     * @param event The session.
+     */
+    onSessionCreated?(event: SessionEvent): void;
+    /**
+     * A player was admitted to a session.
+     * @param event The player and its session.
+     */
+    onPlayerJoined?(event: PlayerEvent): void;
+    /**
+     * A player left a session for good.
+     * @param event The player and its session.
+     */
+    onPlayerLeft?(event: PlayerEvent): void;
+    /**
+     * A session room closed.
+     * @param event The session.
+     */
+    onSessionClosed?(event: SessionEvent): void;
+}
+/** What the rooms and the gate record; GameServerMetrics (T7) implements it. */
+export interface GameServerMetricsSink {
+    /**
+     * Counts a join decision.
+     * @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.
+     * @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;
+    /**
+     * Records how long a dedicated runner's frame took.
+     * @param seconds The frame's duration.
+     * @param tickSeconds The simulation tick length the frame must fit in.
+     */
+    observeDedicatedFrame(seconds: number, tickSeconds: number): void;
+    /**
+     * Counts one room message, frame or control (the room message rate, game-server-admin-console T10). Optional, so
+     * custom sinks written before it keep compiling.
+     * @param direction "in" from a client, "out" to a client.
+     */
+    countMessage?(direction: "in" | "out"): void;
+    /**
+     * Counts one leaderboard score or refused request (game-server-leaderboards D21). Optional, so older custom sinks
+     * keep compiling.
+     * @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;
+}
+/** The process-wide state of the running game server, which the static join gate and the rooms read (D10). */
+export interface GameServerStateValues {
+    /** The resolved config. */
+    config: GameServerConfig;
+    /** The hooks the server was created with (possibly none). */
+    hooks: GameServerHooks;
+    /** The token verifier, or null when auth is off. */
+    verifier: ManagedTokenVerifier | null;
+    /** This server's Discord player sessions, or null while Discord sign-in is off (discord-sign-in D10). */
+    discordSessions: DiscordSessions | null;
+    /** Where each option's value came from (game-server-admin-console D20); every path is "code" for a server made from code. */
+    configSources: ConfigSourceMap;
+    /** The per-address join rate limiter (D14). */
+    rateLimiter: JoinRateLimiter;
+    /** The Prometheus metrics, or null when metrics.enabled is false (D16). */
+    metrics: GameServerMetricsSink | null;
+    /** The dedicated scenes this server may run (D19). */
+    registry: DedicatedSceneRegistry;
+    /** True once a drain started: the gate refuses new joins with GameClosed (D17). */
+    draining: boolean;
+    /** Maintenance in force on this instance, or null; the admin console sets it (game-server-admin-console D14). */
+    maintenance: MaintenanceState | null;
+    /** Live session rooms of this process. */
+    sessionRooms: Set<SessionRoom>;
+    /** Live lobby rooms of this process (lobby kick, game-server-admin-console R15). */
+    lobbyRooms: Set<GameServerLobbyRoom>;
+    /** Bans enforced by the join gate, or null while the console is off (game-server-admin-console D15). */
+    banList: BanList | null;
+    /** Recently kicked players per session name, kept in presence (game-server-admin-console D12, R19). */
+    kickBlocks: KickBlockList;
+    /** Receives every player join and leave of a session; the admin console sets it to keep player history, else null. */
+    onPlayerSessionEvent: ((event: PlayerSessionEvent) => void) | null;
+    /** Called with every session join and leave for leaderboard session presence (game-server-leaderboards D10), or null. */
+    onLeaderboardSessionPresence: ((event: PlayerSessionEvent) => void) | null;
+    /** The recent log lines the console tails and searches, or null while the console is off (game-server-admin-console D21). */
+    logBuffer: LogBuffer | null;
+    /** The TLS material served now, for certificate expiry (null without TLS). */
+    tlsMaterial: TlsMaterial | null;
+    /** ISO time the process started. */
+    startedAt: string;
+}
+/**
+ * The running game server's state.
+ * @returns The state.
+ * @throws Error("no Babylon Game Server is running in this process") before createGameServer or after close.
+ */
+export declare function getGameServerState(): GameServerStateValues;
+/**
+ * The running game server's state, for code that also runs without one (DedicatedSession, HeadlessRuntime).
+ * @returns The state, or null when no game server runs.
+ */
+export declare function findGameServerState(): GameServerStateValues | null;
+/**
+ * Sets or clears the process's game server state. createGameServer sets it; close and the end of a drain clear it.
+ * @param state The state, or null.
+ */
+export declare function setGameServerState(state: GameServerStateValues | null): void;

package/lib/GameServerState.js

@@ -0,0 +1,26 @@
+/** The running game server's state, or null when none runs in this process. */
+let currentState = null;
+/**
+ * The running game server's state.
+ * @returns The state.
+ * @throws Error("no Babylon Game Server is running in this process") before createGameServer or after close.
+ */
+export function getGameServerState() {
+    if (currentState == null)
+        throw new Error("no Babylon Game Server is running in this process");
+    return currentState;
+}
+/**
+ * The running game server's state, for code that also runs without one (DedicatedSession, HeadlessRuntime).
+ * @returns The state, or null when no game server runs.
+ */
+export function findGameServerState() {
+    return currentState;
+}
+/**
+ * Sets or clears the process's game server state. createGameServer sets it; close and the end of a drain clear it.
+ * @param state The state, or null.
+ */
+export function setGameServerState(state) {
+    currentState = state;
+}