@colyseus/tools 0.17.0 → 0.17.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/tools",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "type": "module",
   "description": "Simplify the development and production settings for your Colyseus project.",
   "input": "./src/index.ts",
@@ -39,11 +39,10 @@
     "url": "https://github.com/colyseus/colyseus/issues"
   },
   "files": [
-    "pm2",
-    "html",
     "build",
-    "LICENSE",
-    "README.md"
+    "src",
+    "pm2",
+    "html"
   ],
   "homepage": "https://colyseus.io",
   "dependencies": {
@@ -56,16 +55,16 @@
     "@types/cors": "^2.8.10",
     "@types/dotenv": "^8.2.0",
     "uwebsockets-express": "^1.1.10",
-    "@colyseus/ws-transport": "^0.17.0",
-    "@colyseus/core": "^0.17.0",
-    "@colyseus/bun-websockets": "^0.17.0",
-    "@colyseus/redis-presence": "^0.17.0",
-    "@colyseus/uwebsockets-transport": "^0.17.0",
-    "@colyseus/redis-driver": "^0.17.0"
+    "@colyseus/core": "^0.17.1",
+    "@colyseus/ws-transport": "^0.17.2",
+    "@colyseus/bun-websockets": "^0.17.1",
+    "@colyseus/redis-driver": "^0.17.1",
+    "@colyseus/redis-presence": "^0.17.1",
+    "@colyseus/uwebsockets-transport": "^0.17.2"
   },
   "peerDependencies": {
-    "@colyseus/core": "0.16.x",
-    "@colyseus/ws-transport": "0.16.x"
+    "@colyseus/core": "0.17.x",
+    "@colyseus/ws-transport": "0.17.x"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -0,0 +1,318 @@
+import './loadenv.ts';
+import os from 'os';
+import fs from "fs";
+import net from "net";
+import http from 'http';
+import cors from 'cors';
+import express from 'express';
+import {
+  type ServerOptions,
+  type SDKTypes,
+  type Router,
+  logger,
+  Server,
+  Transport,
+  matchMaker,
+  RegisteredHandler,
+  defineServer,
+  LocalDriver,
+  LocalPresence
+} from '@colyseus/core';
+import { WebSocketTransport } from '@colyseus/ws-transport';
+
+const BunWebSockets = import('@colyseus/bun-websockets'); BunWebSockets.catch(() => {});
+const RedisDriver = import('@colyseus/redis-driver'); RedisDriver.catch(() => {});
+const RedisPresence = import('@colyseus/redis-presence'); RedisPresence.catch(() => {});
+
+export interface ConfigOptions<
+  RoomTypes extends Record<string, RegisteredHandler> = any,
+  Routes extends Router = any
+> extends SDKTypes<RoomTypes, Routes> {
+    options?: ServerOptions,
+    displayLogs?: boolean,
+    rooms?: RoomTypes,
+    routes?: Routes,
+    initializeTransport?: (options: any) => Transport,
+    initializeExpress?: (app: express.Express) => void,
+    initializeGameServer?: (app: Server) => void,
+    beforeListen?: () => void,
+    /**
+     * @deprecated getId() has no effect anymore.
+     */
+    getId?: () => string,
+}
+
+const ALLOWED_KEYS: { [key in keyof Partial<ConfigOptions>]: string } = {
+  'displayLogs': "boolean",
+  'options': "object",
+  'rooms': "object",
+  'routes': "object",
+  'initializeTransport': "function",
+  'initializeExpress': "function",
+  'initializeGameServer': "function",
+  'beforeListen': "function",
+  // deprecated options (will be removed in the next major version)
+  'getId': "function",
+};
+
+export default function <
+  RoomTypes extends Record<string, RegisteredHandler> = any,
+  Routes extends Router = any
+>(options: Omit<ConfigOptions<RoomTypes, Routes>, '~rooms' | '~routes'>) {
+  for (const option in options) {
+    if (!ALLOWED_KEYS[option]) {
+      throw new Error(`❌ Invalid option '${option}'. Allowed options are: ${Object.keys(ALLOWED_KEYS).join(", ")}`);
+    }
+    if(options[option] !== undefined && typeof(options[option]) !== ALLOWED_KEYS[option]) {
+      throw new Error(`❌ Invalid type for ${option}: please provide a ${ALLOWED_KEYS[option]} value.`);
+    }
+  }
+  return options as ConfigOptions<RoomTypes, Routes>;
+}
+
+/**
+ * Expose server instance and listen on the port specified
+ * @param options Application options
+ * @param port Port number to bind Colyseus + Express
+ */
+export async function listen<
+  RoomTypes extends Record<string, RegisteredHandler> = any,
+  Routes extends Router = any
+>(
+    options: ConfigOptions<RoomTypes, Routes>,
+    port?: number,
+): Promise<Server<RoomTypes, Routes>>;
+
+/**
+ * Expose server instance and listen on the port specified
+ * @param server Server instance
+ * @param port Port number to bind Colyseus + Express
+ */
+export async function listen<
+  RoomTypes extends Record<string, RegisteredHandler> = any,
+  Routes extends Router = any
+>(
+    server: Server<RoomTypes, Routes>,
+    port?: number,
+): Promise<Server<RoomTypes, Routes>>;
+
+export async function listen<
+  RoomTypes extends Record<string, RegisteredHandler> = any,
+  Routes extends Router = any
+>(
+    options: ConfigOptions<RoomTypes, Routes> | Server<RoomTypes, Routes>,
+    port: number = Number(process.env.PORT || 2567),
+) {
+    // Force 2567 port on Colyseus Cloud
+    if (process.env.COLYSEUS_CLOUD !== undefined) {
+        port = 2567;
+    }
+
+    //
+    // Handling multiple processes
+    // Use NODE_APP_INSTANCE to play nicely with pm2
+    //
+    const processNumber = Number(process.env.NODE_APP_INSTANCE || "0");
+    port += processNumber;
+
+    let server: Server<RoomTypes, Routes>;
+    let displayLogs = true;
+
+    if (options instanceof Server) {
+        server = options;
+
+        // automatically configure for production under Colyseus Cloud
+        if (process.env.COLYSEUS_CLOUD !== undefined) {
+            // check if local driver/presence are being used (defaults)
+            const isLocalDriver = matchMaker.driver instanceof LocalDriver;
+            const isLocalPresence = matchMaker.presence instanceof LocalPresence;
+
+            const cloudConfig = await getColyseusCloudConfig(
+                port,
+                isLocalDriver ? undefined : matchMaker.driver,
+                isLocalPresence ? undefined : matchMaker.presence,
+            );
+
+            // re-setup matchMaker with Redis driver/presence
+            if (cloudConfig && (isLocalDriver || isLocalPresence)) {
+                await matchMaker.setup(cloudConfig.presence, cloudConfig.driver, cloudConfig.publicAddress);
+            }
+        }
+
+    } else {
+        server = await buildServerFromOptions<RoomTypes, Routes>(options, port);
+        displayLogs = options.displayLogs;
+
+        await options.initializeGameServer?.(server);
+        await matchMaker.onReady;
+        await options.beforeListen?.();
+    }
+
+    if (process.env.COLYSEUS_CLOUD !== undefined) {
+        // listening on socket
+        // const socketPath: any = `/run/colyseus/${port}.sock`;
+        const socketPath: any = `/tmp/${port}.sock`;
+
+        // check if .sock file is active
+        // (fixes "ADDRINUSE" issue when restarting the server)
+        await checkInactiveSocketFile(socketPath);
+
+        await server.listen(socketPath);
+
+    } else {
+        // listening on port
+        await server.listen(port);
+    }
+
+    // notify process manager (production)
+    if (typeof(process.send) === "function") {
+        process.send('ready');
+    }
+
+    if (displayLogs) {
+        logger.info(`⚔️  Listening on http://localhost:${port}`);
+    }
+
+    return server;
+}
+
+async function buildServerFromOptions<
+  RoomTypes extends Record<string, RegisteredHandler> = any,
+  Routes extends Router = any
+>(options: ConfigOptions<RoomTypes, Routes>, port: number) {
+  const serverOptions = options.options || {};
+  options.displayLogs = options.displayLogs ?? true;
+
+  // automatically configure for production under Colyseus Cloud
+  if (process.env.COLYSEUS_CLOUD !== undefined) {
+    const cloudConfig = await getColyseusCloudConfig(port, serverOptions.driver, serverOptions.presence);
+    if (cloudConfig) {
+      serverOptions.driver = cloudConfig.driver;
+      serverOptions.presence = cloudConfig.presence;
+      serverOptions.publicAddress = cloudConfig.publicAddress;
+    }
+  }
+
+  return defineServer<RoomTypes, Routes>(options.rooms || {} as RoomTypes, options.routes, {
+    ...serverOptions,
+    transport: await getTransport(options),
+  });
+}
+
+export async function getTransport(options: ConfigOptions) {
+    let transport: Transport;
+
+    if (!options.initializeTransport) {
+        // @ts-ignore
+        if (typeof Bun !== "undefined") {
+          // @colyseus/bun-websockets
+          BunWebSockets.catch(() => {
+            logger.warn("");
+            logger.warn("❌ could not initialize BunWebSockets.");
+            logger.warn("👉 npm install --save @colyseus/bun-websockets");
+            logger.warn("");
+          })
+          const module = await BunWebSockets;
+          options.initializeTransport = (options: any) => new module.BunWebSockets(options);
+
+        } else {
+          // use WebSocketTransport by default
+          options.initializeTransport = (options: any) => new WebSocketTransport(options);
+        }
+    }
+
+    let app: express.Express | undefined = express();
+    let server = http.createServer(app);
+
+    transport = await options.initializeTransport({ server, app });
+
+    //
+    // TODO: refactor me!
+    // BunWebSockets: There's no need to instantiate "app" and "server" above
+    //
+    if (transport['expressApp']) {
+      app = transport['expressApp'];
+    }
+
+    if (app) {
+      // Enable CORS
+      app.use(cors({ origin: true, credentials: true, }));
+
+      if (options.initializeExpress) {
+          await options.initializeExpress(app);
+      }
+
+      // health check for load balancers
+      app.get("/__healthcheck", (req, res) => {
+        res.status(200).end();
+      });
+
+      if (options.displayLogs) {
+          logger.info("✅ Express initialized");
+      }
+    }
+
+    return transport;
+}
+
+/**
+ * Configure Redis driver/presence for Colyseus Cloud when needed.
+ * Returns configured driver, presence, and publicAddress.
+ */
+async function getColyseusCloudConfig(port: number, currentDriver?: any, currentPresence?: any) {
+  const useRedisConfig = (os.cpus().length > 1) || (process.env.REDIS_URI !== undefined);
+
+  if (!useRedisConfig) {
+    return null;
+  }
+
+  let driver = currentDriver;
+  let presence = currentPresence;
+  const publicAddress = process.env.SUBDOMAIN + "." + process.env.SERVER_NAME + "/" + port;
+
+  if (!driver) {
+    try {
+      const module = await RedisDriver;
+      driver = new module.RedisDriver(process.env.REDIS_URI);
+    } catch (e) {
+      console.error(e);
+      logger.warn("");
+      logger.warn("❌ could not initialize RedisDriver.");
+      logger.warn("👉 npm install --save @colyseus/redis-driver");
+      logger.warn("");
+    }
+  }
+
+  if (!presence) {
+    try {
+      const module = await RedisPresence;
+      presence = new module.RedisPresence(process.env.REDIS_URI);
+    } catch (e) {
+      console.error(e);
+      logger.warn("");
+      logger.warn("❌ could not initialize RedisPresence.");
+      logger.warn("👉 npm install --save @colyseus/redis-presence");
+      logger.warn("");
+    }
+  }
+
+  return { driver, presence, publicAddress };
+}
+
+/**
+ * Check if a socket file is active and remove it if it's not.
+ */
+function checkInactiveSocketFile(sockFilePath: string) {
+  return new Promise((resolve, reject) => {
+    const client = net.createConnection({ path: sockFilePath })
+      .on('connect', () => {
+        // socket file is active, close the connection
+        client.end();
+        throw new Error(`EADDRINUSE: Already listening on '${sockFilePath}'`);
+      })
+      .on('error', () => {
+        // socket file is inactive, remove it
+        fs.unlink(sockFilePath, () => resolve(true));
+      });
+  });
+}

package/src/loadenv.ts

@@ -0,0 +1,67 @@
+import fs from 'fs';
+import path from 'path';
+import dotenv from 'dotenv';
+
+function getEnvFromArgv() {
+  const envIndex = process.argv.indexOf("--env");
+  return (envIndex !== -1) ? process.argv[envIndex + 1] : undefined;
+}
+
+function getNodeEnv() {
+  return process.env.NODE_ENV || getEnvFromArgv() || "development";
+}
+
+function getRegion() {
+  // EU, NA, AS, AF, AU, SA, UNKNOWN
+  return (process.env.REGION || "unknown").toLowerCase();
+}
+
+function loadEnvFile(envFileOptions: string[], log: 'none' | 'success' | 'both'  = 'none') {
+    const envPaths = [];
+    envFileOptions.forEach((envFilename) => {
+      if (envFilename.startsWith("/")) {
+        envPaths.push(envFilename);
+      } else {
+        envPaths.push(path.resolve(path.dirname(typeof(require) !== "undefined" && require?.main?.filename || process.cwd()), "..", envFilename));
+        envPaths.push(path.resolve(process.cwd(), envFilename));
+      }
+    });
+
+    // return the first .env path found
+    const envPath = envPaths.find((envPath) => fs.existsSync(envPath));
+
+    if (envPath) {
+        dotenv.config({ path: envPath });
+
+        if (log !== "none") {
+            console.info(`✅ ${path.basename(envPath)} loaded.`);
+        }
+
+    } else if (log === "both") {
+        console.info(`ℹ️  optional .env file not found: ${envFileOptions.join(", ")}`);
+    }
+}
+
+// reload /etc/environment, if exists
+if (fs.existsSync("/etc/environment")) {
+  dotenv.config({ path: "/etc/environment", override: true })
+}
+
+// load .env.cloud defined on admin panel
+if (process.env.COLYSEUS_CLOUD !== undefined) {
+    const cloudEnvFileNames = [".env.cloud"];
+
+    // prepend .env.cloud file from APP_ROOT_PATH
+    if (process.env.APP_ROOT_PATH) {
+      cloudEnvFileNames.unshift(`${process.env.APP_ROOT_PATH}${(process.env.APP_ROOT_PATH.endsWith("/") ? "" : "/")}.env.cloud`);
+    }
+
+    loadEnvFile(cloudEnvFileNames);
+}
+
+// (overrides previous env configs)
+loadEnvFile([`.env.${getNodeEnv()}`, `.env`], 'both');
+
+if (process.env.REGION !== undefined) {
+  loadEnvFile([`.env.${getRegion()}.${getNodeEnv()}`], 'success');
+}