@babylonjs-toolkit/server 0.0.0-stage → 9.35.0

package/lib/DualTransport.d.ts

@@ -0,0 +1,112 @@
+import type { Transport } from "colyseus";
+import type { IncomingMessage, ServerResponse } from "node:http";
+/** The members of an Express application the HTTP/3 transport uses (its matchmaking routes and the request handler). */
+export interface ExpressApplication {
+    /** Handles one HTTPS request. */
+    (request: IncomingMessage, response: ServerResponse): void;
+    /** Adds middleware. */
+    use(handler: unknown): unknown;
+    /** Adds a POST route. */
+    post(path: string, handler: unknown): unknown;
+}
+/** The options of @colyseus/h3-transport's H3Transport (local shape: no type import of the optional package, D8). */
+export interface H3TransportOptions {
+    /** The Express application serving HTTPS. */
+    app: ExpressApplication;
+    /** The certificate (PEM); omitted to let the transport make a development one. */
+    cert?: string;
+    /** The private key (PEM); omitted with cert. */
+    key?: string;
+}
+/** A bidirectional stream of a WebTransport session (the part the probe guard wraps). */
+export interface Http3BidirectionalStream {
+    /** Bytes from the peer. */
+    readable: ReadableStream<Uint8Array>;
+}
+/** A WebTransport session as the HTTP/3 server hands it out (the part the probe guard wraps). */
+export interface Http3Session {
+    /** Opens a bidirectional stream to the peer. */
+    createBidirectionalStream(): Promise<Http3BidirectionalStream>;
+}
+/** The HTTP/3 server of @fails-components/webtransport (the part the probe guard wraps). */
+export interface Http3ServerInstance {
+    /**
+     * The incoming sessions of a path.
+     * @param path The path, e.g. "/".
+     * @returns The stream of sessions.
+     */
+    sessionStream(path: string): Promise<ReadableStream<Http3Session>>;
+}
+/** An H3Transport instance (local shape). Its inherited `server` is the HTTPS server, set once it listens. */
+export interface H3TransportInstance extends Transport {
+    /** The HTTP/3 server, set once it listens. */
+    h3Server: Http3ServerInstance;
+    /** Accepts WebTransport sessions until shutdown; H3Transport.listen starts it. */
+    acceptIncomingSessions(): Promise<void>;
+    /**
+     * Listens for HTTPS (TCP) and HTTP/3 (UDP) on one port.
+     * @param port The port.
+     * @param hostname The bind address.
+     * @param backlog The TCP backlog.
+     * @param listeningListener Called once the HTTPS server listens.
+     * @returns The transport.
+     */
+    listen(port: number, hostname?: string, backlog?: number, listeningListener?: () => void): this;
+    /** Stops HTTPS and HTTP/3. */
+    shutdown(): void;
+    /**
+     * Delays every frame (Colyseus' latency simulation).
+     * @param milliseconds The added one-way latency.
+     */
+    simulateLatency(milliseconds: number): void;
+}
+/** The H3Transport class (local shape). */
+export type H3TransportConstructor = new (options: H3TransportOptions) => H3TransportInstance;
+/** A certificate generated by the optional package for WebTransport hash pinning (local shape). */
+export interface GeneratedWebTransportCertificate {
+    /** The certificate (PEM). */
+    cert: string;
+    /** The private key (PEM). */
+    private: string;
+    /** The SHA-256 hash, as colon-separated hex pairs ("AB:CD:…"). */
+    fingerprint: string;
+}
+/** The optional package's exports the server uses (local shape). */
+export interface H3TransportModule {
+    /** The HTTP/3 WebTransport transport. */
+    H3Transport: H3TransportConstructor;
+    /**
+     * Makes a short-lived ECDSA P-256 certificate that browsers accept by hash (serverCertificateHashes).
+     * @param attributes The subject attributes.
+     * @param options The validity.
+     * @returns The certificate, its key and hash.
+     */
+    generateWebTransportCertificate(attributes: {
+        shortName: string;
+        value: string;
+    }[], options: {
+        days: number;
+    }): Promise<GeneratedWebTransportCertificate>;
+}
+/** What createDualTransport needs. */
+export interface DualTransportOptions {
+    /** The HTTPS/WSS certificate (PEM), or null to use the HTTP/3 one for HTTPS too. */
+    cert: string | null;
+    /** The private key (PEM), or null with cert. */
+    key: string | null;
+    /**
+     * True (development certificate) to give HTTP/3 its own short-lived self-signed certificate, pinned by hash: browsers
+     * refuse WebTransport to locally trusted roots such as mkcert's, but accept a pinned certificate. HTTPS keeps cert.
+     */
+    pinHttp3Certificate: boolean;
+    /** Largest WebSocket message, in bytes (limits.maxMessageBytes). */
+    maxPayload: number;
+}
+/**
+ * The transport of a server with UDP on (D8): HTTP/3 WebTransport and HTTPS from @colyseus/h3-transport, plus WebSocket
+ * upgrades on the same HTTPS server, so WebTransport and WebSocket players share one port and one session.
+ * @param options The certificate, key, HTTP/3 pinning and WebSocket message limit.
+ * @returns The transport.
+ * @throws Error(H3_MISSING_MESSAGE) when the optional package cannot be loaded.
+ */
+export declare function createDualTransport(options: DualTransportOptions): Promise<Transport>;

package/lib/DualTransport.js

@@ -0,0 +1,197 @@
+import { WebSocketTransport } from "@colyseus/ws-transport";
+import { createRequire } from "node:module";
+import { networkInterfaces } from "node:os";
+/** The optional HTTP/3 package, imported only when UDP is on (D8). A string-typed specifier keeps tsc from resolving it. */
+const H3_TRANSPORT_PACKAGE = "@colyseus/h3-transport";
+/** The error when UDP is on and the optional package is missing (its native build failed on this platform). */
+const H3_MISSING_MESSAGE = "UDP needs @colyseus/h3-transport, which is not installed on this platform";
+/** Milliseconds between WebSocket keep-alive pings. */
+const PING_INTERVAL_MS = 10000;
+/** Days the pinned HTTP/3 development certificate is valid; browsers accept hash pinning only up to 14 days. */
+const PINNED_CERTIFICATE_DAYS = 10;
+/** Common name of the pinned HTTP/3 development certificate. */
+const PINNED_CERTIFICATE_NAME = "localhost";
+/** The IPv4 "every interface" bind address. */
+const IPV4_WILDCARD_HOST = "0.0.0.0";
+/** The dual-stack "every interface" bind address (IPv6 and, mapped, IPv4). */
+const DUAL_STACK_WILDCARD_HOST = "::";
+/**
+ * The transport of a server with UDP on (D8): HTTP/3 WebTransport and HTTPS from @colyseus/h3-transport, plus WebSocket
+ * upgrades on the same HTTPS server, so WebTransport and WebSocket players share one port and one session.
+ * @param options The certificate, key, HTTP/3 pinning and WebSocket message limit.
+ * @returns The transport.
+ * @throws Error(H3_MISSING_MESSAGE) when the optional package cannot be loaded.
+ */
+export async function createDualTransport(options) {
+    const h3Module = await importH3Transport();
+    const DualTransport = createDualTransportClass(h3Module.H3Transport);
+    const express = createRequire(import.meta.url)("express");
+    const app = express();
+    app.use(express.json());
+    const pinnedCertificate = options.pinHttp3Certificate
+        ? await h3Module.generateWebTransportCertificate([{ shortName: "CN", value: PINNED_CERTIFICATE_NAME }], { days: PINNED_CERTIFICATE_DAYS })
+        : null;
+    const h3Options = { app: app };
+    if (pinnedCertificate != null) {
+        h3Options.cert = pinnedCertificate.cert;
+        h3Options.key = pinnedCertificate.private;
+    }
+    else if (options.cert != null && options.key != null) {
+        h3Options.cert = options.cert;
+        h3Options.key = options.key;
+    }
+    const httpsMaterial = (pinnedCertificate != null && options.cert != null && options.key != null) ? { cert: options.cert, key: options.key } : null;
+    const webSocketTransport = new WebSocketTransport({ noServer: true, pingInterval: PING_INTERVAL_MS, maxPayload: options.maxPayload });
+    const transport = new DualTransport(h3Options, webSocketTransport, httpsMaterial);
+    // Matchmaking answers carry the hash, so the SDK pins it for its WebTransport connection.
+    if (pinnedCertificate != null)
+        transport.fingerprint = fingerprintBytes(pinnedCertificate.fingerprint);
+    return transport;
+}
+/**
+ * The bytes of a colon-separated hex hash.
+ * @param fingerprint The hash, "AB:CD:…".
+ * @returns The bytes.
+ */
+function fingerprintBytes(fingerprint) {
+    return fingerprint.split(":").map((hexPair) => Number.parseInt(hexPair, 16));
+}
+/**
+ * The address the HTTP/3 and HTTPS servers bind. The HTTP/3 (UDP) server listens only on the address family it is
+ * given, and browsers and Node resolve "localhost" to ::1 first, so the IPv4 wildcard becomes the dual-stack wildcard
+ * whenever this machine has IPv6 (containers without IPv6 keep 0.0.0.0, where "::" would fail to bind).
+ * @param hostname The configured bind address.
+ * @returns The address to bind.
+ */
+function http3BindHost(hostname) {
+    if (hostname !== IPV4_WILDCARD_HOST || !hasIpv6Interface())
+        return hostname;
+    return DUAL_STACK_WILDCARD_HOST;
+}
+/**
+ * Whether any network interface (loopback included) has an IPv6 address.
+ * @returns True when IPv6 is available.
+ */
+function hasIpv6Interface() {
+    const interfaces = Object.values(networkInterfaces()).flatMap((addresses) => addresses ?? []);
+    return interfaces.some((address) => address.family === "IPv6");
+}
+/**
+ * Keeps a WebTransport session that ends before it sends its first message from crashing the server. The runtime probes
+ * the server with exactly such a session before it joins (D25). @colyseus/h3-transport reads a session's first message
+ * without a rejection handler, so a probe that closes leaves an unhandled rejection, which ends a Node process. The guard
+ * makes that first read wait forever instead of rejecting; the session's own close handling still cleans up.
+ * @param h3Server The transport's HTTP/3 server.
+ */
+function guardProbeSessions(h3Server) {
+    const openSessionStream = h3Server.sessionStream.bind(h3Server);
+    h3Server.sessionStream = async (path) => {
+        const sessions = await openSessionStream(path);
+        const guard = new TransformStream({
+            transform: (session, controller) => controller.enqueue(guardFirstRead(session))
+        });
+        return sessions.pipeThrough(guard);
+    };
+}
+/**
+ * Makes the first read of a session's first bidirectional stream wait forever when the session ends before any data.
+ * @param session The session.
+ * @returns The same session, guarded.
+ */
+function guardFirstRead(session) {
+    const createStream = session.createBidirectionalStream.bind(session);
+    session.createBidirectionalStream = async () => {
+        const stream = await createStream();
+        const getReader = stream.readable.getReader.bind(stream.readable);
+        stream.readable.getReader = (() => guardReader(getReader()));
+        return stream;
+    };
+    return session;
+}
+/**
+ * A reader whose first read never rejects: it resolves with the first chunk, or stays pending when the stream fails.
+ * Later reads are the reader's own (the transport's read loop handles their failures).
+ * @param reader The stream's reader.
+ * @returns The same reader, guarded.
+ */
+function guardReader(reader) {
+    const read = reader.read.bind(reader);
+    let isFirstRead = true;
+    reader.read = () => {
+        if (!isFirstRead)
+            return read();
+        isFirstRead = false;
+        return new Promise((resolve) => {
+            read().then(resolve, ignoreEndedProbe);
+        });
+    };
+    return reader;
+}
+/** The rejection of a session that ended before its first message: nothing to do, the session cleans itself up. */
+function ignoreEndedProbe() {
+    return;
+}
+/**
+ * Loads the optional HTTP/3 package.
+ * @returns Its module.
+ * @throws Error(H3_MISSING_MESSAGE) when it is not installed or its native part does not load.
+ */
+async function importH3Transport() {
+    try {
+        return await import(H3_TRANSPORT_PACKAGE);
+    }
+    catch {
+        throw new Error(H3_MISSING_MESSAGE);
+    }
+}
+/**
+ * Builds the dual transport class on the loaded H3Transport (D8).
+ * @param h3TransportBase The H3Transport constructor of the optional package.
+ * @returns The DualTransport class.
+ */
+function createDualTransportClass(h3TransportBase) {
+    return class DualTransport extends h3TransportBase {
+        /** The WebSocket transport sharing the HTTPS server (D8). */
+        webSocketTransport;
+        /** The HTTPS certificate when it differs from the HTTP/3 one (pinned development certificate), else null. */
+        httpsMaterial;
+        /**
+         * Creates the transport.
+         * @param h3Options The H3 options.
+         * @param webSocketTransport A noServer WebSocket transport.
+         * @param httpsMaterial The HTTPS certificate when it differs from the HTTP/3 one, else null.
+         */
+        constructor(h3Options, webSocketTransport, httpsMaterial) {
+            super(h3Options);
+            this.webSocketTransport = webSocketTransport;
+            this.httpsMaterial = httpsMaterial;
+        }
+        /**
+         * Listens for HTTPS + HTTP/3, then attaches WebSocket upgrades to the same HTTPS server.
+         * @param port The port (TCP and UDP).
+         * @param hostname The bind address.
+         * @param backlog The TCP backlog.
+         * @param listeningListener Called once both listen.
+         * @returns The transport.
+         */
+        listen(port, hostname, backlog, listeningListener) {
+            return super.listen(port, http3BindHost(hostname), backlog, () => {
+                if (this.httpsMaterial != null)
+                    this.server.setSecureContext(this.httpsMaterial);
+                this.webSocketTransport.attachToServer(this.server);
+                if (listeningListener != null)
+                    listeningListener();
+            });
+        }
+        /** Accepts WebTransport sessions, guarding the ones that end before they join (guardProbeSessions). */
+        acceptIncomingSessions() {
+            guardProbeSessions(this.h3Server);
+            return super.acceptIncomingSessions();
+        }
+        /** Stops WebSocket and HTTP/3. */
+        shutdown() {
+            this.webSocketTransport.shutdown();
+            super.shutdown();
+        }
+    };
+}

package/lib/GameServer.d.ts

@@ -0,0 +1,64 @@
+import { type Endpoint } from "colyseus";
+import { type ConfigSourceMap, type DeepPartial, type GameServerConfig } from "./GameServerConfig.js";
+import { type GameServerHooks } from "./GameServerState.js";
+import { type AdminTestingOptions } from "./admin/AdminClock.js";
+import { type AdminExtensions } from "./admin/AdminExtensionsHost.js";
+import { type DiscordTestingOptions } from "./discord/DiscordOAuth.js";
+/** Options of createGameServer. */
+export interface GameServerOptions {
+    /** Overrides of the defaults (D3). */
+    config?: DeepPartial<GameServerConfig>;
+    /** Lifecycle and custom-auth hooks. */
+    hooks?: GameServerHooks;
+    /** Extra HTTP endpoints made with createEndpoint (D15). */
+    routes?: Record<string, Endpoint>;
+    /**
+     * Drain on SIGTERM/SIGINT and exit 0, and drain on an uncaught error and exit 1 (CLI: true; API default false, D17).
+     * The handlers are in place before the boot sessions start, so a stop that arrives while they start still drains.
+     */
+    handleSignals?: boolean;
+    /** Custom admin actions, panels and admin event hooks of the web console (game-server-admin-console D25). */
+    admin?: AdminExtensions;
+    /** For tests only: a manual clock and shorter admin intervals (game-server-admin-console R10). */
+    adminTesting?: AdminTestingOptions;
+    /** For tests only: Discord's base URL (a fake Discord), discord-sign-in D15. */
+    discordTesting?: DiscordTestingOptions;
+    /** Where each option came from (the CLI passes loadGameServerConfigWithSources' map); every path is "code" without it. */
+    configSources?: ConfigSourceMap;
+}
+/** Where players and tools reach a running server. */
+export interface GameServerUrls {
+    /** ws:// or wss:// URL of the SDK endpoint. */
+    webSocket: string;
+    /** http:// or https:// URL of the same endpoint (matchmaking, health). */
+    http: string;
+    /** https:// URL of the WebTransport endpoint, or null when UDP is off. */
+    webTransport: string | null;
+}
+/** A running Babylon Game Server. */
+export interface GameServer {
+    /** The resolved config. */
+    readonly config: GameServerConfig;
+    /** The port it listens on (the free port picked for 0). */
+    readonly port: number;
+    /** Where players and tools reach it. */
+    readonly urls: GameServerUrls;
+    /** Stops at once: disconnects everyone (tests, scripts). */
+    close(): Promise<void>;
+    /** Stops taking players, lets sessions finish, then stops (D17). */
+    drain(): Promise<void>;
+    /** Starts a dedicated session of a configured scene; resolves the room id. */
+    startDedicatedSession(sessionName: string, sceneName: string): Promise<string>;
+}
+/**
+ * Starts the Babylon Game Server: the lobby room "fusion_lobby" and the session room "fusion_session", filtered by
+ * session name and listed in the lobby in real time. The toolkit runtime is loaded first so rooms run the browser's
+ * session logic. Programmatic callers pass overrides of the defaults; the CLI passes its loaded config (D3). Once it
+ * listens, the config's boot dedicated sessions start (D19), and with handleSignals SIGTERM/SIGINT or an uncaught error
+ * drain it (D17). A draining process gets no new rooms from the matchmaker of any process.
+ * @param options The config overrides, hooks, extra routes and signal handling.
+ * @returns The running server.
+ * @throws GameServerConfigError when the config is invalid; Error "admin extension <name>: <problem>" for a bad
+ *     options.admin definition; Error when a boot dedicated session cannot start (the server is stopped again first).
+ */
+export declare function createGameServer(options?: GameServerOptions): Promise<GameServer>;