@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/cli.js

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+import http from "node:http";
+import https from "node:https";
+import { createGameServer } from "./GameServer.js";
+import { GameServerConfigError, isProductionEnvironment, loadGameServerConfig, loadGameServerConfigWithSources } from "./GameServerConfig.js";
+import { getLogger } from "./GameServerLogger.js";
+import { readPackageVersion, writeRecipes } from "./ServerInit.js";
+import { runAdminCommand } from "./admin/AdminCli.js";
+/** Exit code of a configuration problem. */
+const CONFIG_PROBLEM_EXIT_CODE = 2;
+/** Exit code of any other startup failure. */
+const STARTUP_FAILURE_EXIT_CODE = 1;
+/** The default subcommand. */
+const START_COMMAND = "start";
+/** The subcommand that writes the starter folder (config, env, Dockerfile and deployment recipes). */
+const INIT_COMMAND = "init";
+/** The folder `init` writes when none is named. */
+const DEFAULT_INIT_FOLDER = "./babylon-game-server";
+/** The flag that lets `init` overwrite existing files. */
+const FORCE_FLAG = "--force";
+/** Exit code of an `init` that left existing files alone. */
+const FILES_SKIPPED_EXIT_CODE = 1;
+/** The subcommand that manages admin accounts and API keys on the admin data store (game-server-admin-console T3). */
+const ADMIN_COMMAND = "admin";
+/** The subcommand that checks a running server's health (the Docker HEALTHCHECK). */
+const HEALTHCHECK_COMMAND = "healthcheck";
+/** Exit code of a healthy server. */
+const HEALTHY_EXIT_CODE = 0;
+/** Exit code of an unhealthy or unreachable server (Docker reserves 2, so every failure uses 1). */
+const UNHEALTHY_EXIT_CODE = 1;
+/** Milliseconds the health check waits for an answer. */
+const HEALTHCHECK_TIMEOUT_MS = 3000;
+/** The health endpoint the check calls (ServerEndpoints). */
+const HEALTH_PATH = "/game-server/health";
+/** The address the check calls: the server's own loopback interface. */
+const HEALTHCHECK_HOST = "127.0.0.1";
+/** HTTP status of a healthy answer. */
+const HTTP_OK = 200;
+/** Bind addresses that only accept connections from this machine. */
+const LOOPBACK_HOSTS = ["localhost", "127.0.0.1", "::1"];
+/**
+ * How the banner names the TLS setup.
+ * @param tls The TLS settings.
+ * @returns "off", "on (files)", "on (pem)" or "on (development)".
+ */
+function describeTls(tls) {
+    if (!tls.enabled)
+        return "off";
+    if (tls.certFile != null && tls.keyFile != null)
+        return "on (files)";
+    if (tls.certPem != null && tls.keyPem != null)
+        return "on (pem)";
+    return "on (development)";
+}
+/**
+ * Prints the startup banner (§Control flow). It is plain console text in every log format, so platforms show it.
+ * @param running The running server.
+ */
+function printBanner(running) {
+    const config = running.config;
+    const authText = config.auth.enabled ? config.auth.mode : "off";
+    console.log("Babylon Game Server " + readPackageVersion() + " listening on " + running.urls.webSocket);
+    console.log("  HTTP:         " + running.urls.http);
+    console.log("  WebTransport: " + (running.urls.webTransport ?? "off"));
+    console.log("  TLS: " + describeTls(config.tls) + "   UDP: " + describeUdp(running) + "   Auth: " + authText + "   Redis: " + describeRedis(config.redis.url));
+}
+/**
+ * How the banner names the Redis setup, without credentials.
+ * @param redisUrl The configured Redis URL, or null.
+ * @returns "off", or "on (<host>:<port>)".
+ */
+function describeRedis(redisUrl) {
+    if (redisUrl == null)
+        return "off";
+    try {
+        return "on (" + new URL(redisUrl).host + ")";
+    }
+    catch {
+        return "on";
+    }
+}
+/**
+ * How the banner names the UDP setup.
+ * @param running The running server.
+ * @returns "off", or "on (WebTransport on <url>, UDP <port>)".
+ */
+function describeUdp(running) {
+    if (running.urls.webTransport == null)
+        return "off";
+    return "on (WebTransport on " + running.urls.webTransport + ", UDP " + running.port + ")";
+}
+/**
+ * Warns when a production server accepts anyone: auth off on an address other machines can reach (D2).
+ * @param config The config.
+ * @param environment The environment the config was loaded from.
+ */
+function warnWhenOpenInProduction(config, environment) {
+    const isLoopback = LOOPBACK_HOSTS.includes(config.host) || config.host.startsWith("127.");
+    if (!isProductionEnvironment(environment) || config.auth.enabled || isLoopback)
+        return;
+    getLogger().warn("auth is disabled and the server listens on " + config.host + ": anyone who can reach it can join (set GAME_SERVER_AUTH_ENABLED)");
+}
+/**
+ * Prints every configuration problem to stderr.
+ * @param error The configuration error.
+ */
+function printConfigProblems(error) {
+    console.error("Babylon Game Server configuration problems:");
+    for (const problem of error.problems)
+        console.error("  - " + problem);
+}
+/**
+ * `babylon-game-server [start] [flags]`: loads the config (defaults < Colyseus Cloud's defaults on that host < file < env < flags), starts the server (which
+ * starts its boot dedicated sessions), and prints the banner.
+ * @param argumentList The arguments after the subcommand.
+ * @param environment The process environment.
+ */
+async function runStart(argumentList, environment) {
+    const loaded = await loadGameServerConfigWithSources({ argv: argumentList, environment: environment, workingDirectory: process.cwd() });
+    const config = loaded.config;
+    const running = await createGameServer({ config: config, handleSignals: true, configSources: loaded.sources });
+    printBanner(running);
+    warnWhenOpenInProduction(config, environment);
+}
+/**
+ * `babylon-game-server healthcheck [flags]`: loads the same config the server uses and GETs its own
+ * `/game-server/health` on 127.0.0.1 over the configured scheme (TLS certificates are not checked: the call never
+ * leaves the machine). Sets exit code 0 on HTTP 200 and 1 on anything else, including a config problem, so Docker's
+ * HEALTHCHECK can run it.
+ * @param argumentList The arguments after the subcommand.
+ * @param environment The process environment.
+ */
+async function runHealthcheck(argumentList, environment) {
+    let config;
+    try {
+        config = await loadGameServerConfig({ argv: argumentList, environment: environment, workingDirectory: process.cwd() });
+    }
+    catch (error) {
+        if (error instanceof GameServerConfigError)
+            printConfigProblems(error);
+        else
+            console.error(error);
+        process.exitCode = UNHEALTHY_EXIT_CODE;
+        return;
+    }
+    const status = await requestHealthStatus(config.port, config.tls.enabled);
+    process.exitCode = (status === HTTP_OK) ? HEALTHY_EXIT_CODE : UNHEALTHY_EXIT_CODE;
+}
+/**
+ * GETs the health endpoint of the server on this machine.
+ * @param port The server port.
+ * @param secure True for https (certificates are not checked).
+ * @returns The HTTP status, or null when the server did not answer within HEALTHCHECK_TIMEOUT_MS.
+ */
+function requestHealthStatus(port, secure) {
+    return new Promise((resolve) => {
+        const scheme = secure ? "https" : "http";
+        const url = scheme + "://" + HEALTHCHECK_HOST + ":" + port + HEALTH_PATH;
+        const handleResponse = (response) => {
+            response.resume();
+            resolve(response.statusCode ?? null);
+        };
+        const request = secure
+            ? https.get(url, { timeout: HEALTHCHECK_TIMEOUT_MS, rejectUnauthorized: false }, handleResponse)
+            : http.get(url, { timeout: HEALTHCHECK_TIMEOUT_MS }, handleResponse);
+        request.on("timeout", () => request.destroy());
+        request.on("error", () => resolve(null));
+    });
+}
+/**
+ * `babylon-game-server init [folder] [--force]`: writes the starter folder (D27) and prints each file and the next step.
+ * Existing files are kept unless `--force`; each one is listed as `skipped (exists): <path>` and the exit code is 1.
+ * @param argumentList The arguments after the subcommand.
+ */
+async function runInit(argumentList) {
+    const force = argumentList.includes(FORCE_FLAG);
+    const folder = argumentList.find((argument) => !argument.startsWith("--")) ?? DEFAULT_INIT_FOLDER;
+    const result = await writeRecipes(folder, force);
+    for (const filePath of result.written)
+        console.log("wrote " + filePath);
+    for (const filePath of result.skipped)
+        console.log("skipped (exists): " + filePath);
+    if (result.written.length > 0) {
+        console.log("Edit babylon-game-server.config.mjs, then see DEPLOY.md");
+        console.log("Recommended host: Colyseus Cloud. Its deploy repository is colyseus-cloud/; see colyseus-cloud/README.md");
+    }
+    if (result.skipped.length > 0) {
+        console.log("Run again with " + FORCE_FLAG + " to overwrite the skipped files.");
+        process.exitCode = FILES_SKIPPED_EXIT_CODE;
+    }
+}
+/**
+ * Runs the subcommand the command line names (`start` when the first argument is a flag or absent).
+ * @param argumentList The command-line arguments after the script name.
+ * @param environment The process environment.
+ */
+async function main(argumentList, environment) {
+    const command = argumentList[0];
+    if (command === INIT_COMMAND) {
+        await runInit(argumentList.slice(1));
+        return;
+    }
+    if (command === ADMIN_COMMAND) {
+        await runAdminCommand(argumentList.slice(1), environment);
+        return;
+    }
+    if (command === HEALTHCHECK_COMMAND) {
+        await runHealthcheck(argumentList.slice(1), environment);
+        return;
+    }
+    const namesStart = command === START_COMMAND;
+    await runStart(namesStart ? argumentList.slice(1) : argumentList, environment);
+}
+main(process.argv.slice(2), process.env).catch((error) => {
+    if (error instanceof GameServerConfigError) {
+        printConfigProblems(error);
+        process.exit(CONFIG_PROBLEM_EXIT_CODE);
+    }
+    console.error(error);
+    process.exitCode = STARTUP_FAILURE_EXIT_CODE;
+});