@colyseus/tools 0.16.16 → 0.16.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/tools",
-  "version": "0.16.16",
+  "version": "0.16.18",
   "description": "Simplify the development and production settings for your Colyseus project.",
   "input": "./src/index.ts",
   "main": "./build/index.js",
@@ -49,13 +49,15 @@
   "devDependencies": {
     "@types/cors": "^2.8.10",
     "@types/dotenv": "^8.2.0",
+    "pm2": "^6.0.14",
+    "mocha": "^11.7.5",
     "uwebsockets-express": "^1.1.10",
-    "@colyseus/redis-presence": "^0.16.4",
     "@colyseus/redis-driver": "^0.16.1",
+    "@colyseus/ws-transport": "^0.16.5",
     "@colyseus/core": "^0.16.24",
-    "@colyseus/bun-websockets": "^0.16.5",
     "@colyseus/uwebsockets-transport": "^0.16.10",
-    "@colyseus/ws-transport": "^0.16.5"
+    "@colyseus/bun-websockets": "^0.16.5",
+    "@colyseus/redis-presence": "^0.16.4"
   },
   "peerDependencies": {
     "@colyseus/core": "0.16.x",
@@ -73,6 +75,7 @@
     }
   ],
   "scripts": {
-    "start": "tsx example/app.ts"
+    "start": "tsx example/app.ts",
+    "test": "mocha --require tsx test/pm2-deployment.test.ts"
   }
 }

package/pm2/ActionMethods.js

@@ -0,0 +1,47 @@
+/**
+ * Monkey-patch for PM2's ActionMethods.js
+ * Adds custom methods like updateProcessConfig without modifying the original file.
+ */
+'use strict';
+
+const Utility = require('../Utility');
+
+// Import the original ActionMethods module
+const originalActionMethods = require('./ActionMethods_orig.js');
+
+module.exports = function(God) {
+  // Apply original ActionMethods
+  originalActionMethods(God);
+
+  /**
+   * Update process configuration without restart.
+   * Merges opts.env.current_conf into proc.pm2_env.
+   * @method updateProcessConfig
+   * @param {Object} opts - { id: pm_id, env: { current_conf: { ... } } }
+   * @param {Function} cb
+   */
+  God.updateProcessConfig = function updateProcessConfig(opts, cb) {
+    var id = opts.id;
+
+    if (typeof(id) === 'undefined')
+      return cb(God.logAndGenerateError('opts.id not passed to updateProcessConfig', opts));
+    if (!(id in God.clusters_db))
+      return cb(God.logAndGenerateError('Process id unknown'), {});
+
+    const proc = God.clusters_db[id];
+
+    if (!proc || !proc.pm2_env)
+      return cb(God.logAndGenerateError('Process not found or missing pm2_env'), {});
+
+    // Merge env into pm2_env.env
+    if (opts.env) {
+      Utility.extend(proc.pm2_env, opts.env);
+      Utility.extend(proc.pm2_env.env, opts.env); // why both?
+    }
+
+    // Merge current_conf directly into pm2_env
+    Utility.extendExtraConfig(proc, opts);
+
+    return cb(null, Utility.clone(proc.pm2_env));
+  };
+};

package/pm2/post-deploy-agent.js

@@ -14,8 +14,7 @@ const io = require('@pm2/io');
 const path = require('path');
 const shared = require('./shared');
 
-const opts = { env: process.env.NODE_ENV || "production", };
-let config = undefined;
+let appConfig = undefined;
 
 io.initModule({
   pid: path.resolve('/var/run/colyseus-agent.pid'),
@@ -52,9 +51,11 @@ pm2.connect(function(err) {
     }
 
     try {
-      config = await shared.getAppConfig(ecosystemFilePath);
-      opts.cwd = cwd;
-      postDeploy(cwd, onReply);
+      const config = await shared.getAppConfig(ecosystemFilePath);
+
+      appConfig = { ...config.apps[0], cwd };
+
+      postDeploy(appConfig, onReply);
 
     } catch (err) {
       onReply({ success: false, message: err?.message });
@@ -64,7 +65,7 @@ pm2.connect(function(err) {
 
 const restartingAppIds = new Set();
 
-function postDeploy(cwd, reply) {
+function postDeploy(config, reply) {
   shared.listApps(function(err, apps) {
     if (err) {
       console.error(err);
@@ -73,7 +74,7 @@ function postDeploy(cwd, reply) {
 
     // first deploy, start all processes
     if (apps.length === 0) {
-      return pm2.start(config, {...opts}, (err, result) => {
+      return pm2.start(config, (err, result) => {
         reply({ success: !err, message: err?.message });
         updateAndSave(err, result);
       });
@@ -82,7 +83,7 @@ function postDeploy(cwd, reply) {
     //
     // detect if cwd has changed, and restart PM2 if it has
     //
-    if (apps[0].pm2_env.pm_cwd !== cwd) {
+    if (apps[0].pm2_env.pm_cwd !== config.cwd) {
       console.log("App Root Directory changed. Restarting may take a bit longer...");
 
       //
@@ -92,7 +93,7 @@ function postDeploy(cwd, reply) {
         logIfError(err);
 
         // start again
-        pm2.start(config, { ...opts }, (err, result) => {
+        pm2.start(config, (err, result) => {
           reply({ success: !err, message: err?.message });
           updateAndSave(err, result);
         });
@@ -140,6 +141,20 @@ function postDeploy(cwd, reply) {
       if (err) { return console.error(err); }
 
       let numActiveApps = initialApps.length + restartingAppIds.size;
+      const maxActiveProcesses = config.instances;
+
+      // update config of newly spawned processes (memory limit, etc)
+      shared.listApps(function(err, apps) {
+        logIfError(err);
+
+        // get new processes excluding initialApps 
+        const new_app_envs = shared.filterActiveApps(apps)
+          .map((app) => app.pm2_env)
+          .filter(app_env => !initialApps.find(init_app => init_app.pm_id === app_env.pm_id)); 
+
+        new_app_envs.forEach((app_env) => 
+          shared.updateProcessConfig(app_env.pm_id, appConfig, logIfError));
+      });
 
       /**
        * - Write NGINX config to expose only the new active process
@@ -157,7 +172,7 @@ function postDeploy(cwd, reply) {
       // (They make take from minutes up to hours to stop)
       //
       appsToStop.forEach((app_env) => {
-        if (numActiveApps < shared.MAX_ACTIVE_PROCESSES) {
+        if (numActiveApps < maxActiveProcesses) {
           numActiveApps++;
 
           restartingAppIds.add(app_env.pm_id);
@@ -167,6 +182,9 @@ function postDeploy(cwd, reply) {
 
             // reset counter stats (restart_time=0)
             pm2.reset(app_env.pm_id, logIfError);
+
+            // update process config (memory limit, etc)
+            shared.updateProcessConfig(app_env.pm_id, config, logIfError);
           });
 
         } else {
@@ -174,8 +192,8 @@ function postDeploy(cwd, reply) {
         }
       });
 
-      if (numActiveApps < shared.MAX_ACTIVE_PROCESSES) {
-        const missingOnlineApps = shared.MAX_ACTIVE_PROCESSES - numActiveApps;
+      if (numActiveApps < maxActiveProcesses) {
+        const missingOnlineApps = maxActiveProcesses - numActiveApps;
 
         // console.log("Active apps is lower than MAX_ACTIVE_PROCESSES, will SCALE again =>", {
         //   missingOnlineApps,
@@ -183,11 +201,12 @@ function postDeploy(cwd, reply) {
         //   newNumTotalApps: numTotalApps + missingOnlineApps
         // });
 
+        console.log("Scale up to", numTotalApps + missingOnlineApps);
         pm2.scale(apps[0].name, numTotalApps + missingOnlineApps, updateAndSaveIfAllRunning);
       }
     };
 
-    const numHalfMaxActiveProcesses = Math.ceil(shared.MAX_ACTIVE_PROCESSES / 2);
+    const numHalfMaxActiveProcesses = Math.ceil(config.instances / 2);
 
     /**
      * Re-use previously stopped apps if available
@@ -206,6 +225,7 @@ function postDeploy(cwd, reply) {
 
           // reset counter stats (restart_time=0)
           pm2.reset(app_env.pm_id, logIfError);
+          shared.updateProcessConfig(app_env.pm_id, config, logIfError);
 
           // TODO: set timeout here to exit if some processes are not restarting
 
@@ -229,6 +249,8 @@ function postDeploy(cwd, reply) {
 
       numTotalApps = apps.length + numHalfMaxActiveProcesses;
 
+      console.log("Starting first half of new apps... pm2.scale(app, ", numTotalApps, ")");
+
       // Ensure to scale to a number of processes where `numHalfMaxActiveProcesses` can start immediately.
       pm2.scale(apps[0].name, numTotalApps, onFirstAppsStart.bind(undefined, initialApps));
     }
@@ -244,12 +266,12 @@ function updateAndSaveIfAllRunning(err) {
   if (err) { return console.error(err); }
 
   updateAndReloadNginx((app_envs) => {
-    // console.log("updateAndExitIfAllRunning, app_ids (", app_envs.map(app_env => app_env.NODE_APP_INSTANCE) ,") => ", app_envs.length, "/", shared.MAX_ACTIVE_PROCESSES);
+    // console.log("updateAndExitIfAllRunning, app_ids (", app_envs.map(app_env => app_env.NODE_APP_INSTANCE) ,") => ", app_envs.length, "/", config.instances);
 
     //
     // TODO: add timeout to exit here, in case some processes are not starting
     //
-    if (app_envs.length === shared.MAX_ACTIVE_PROCESSES) {
+    if (app_envs.length === appConfig.instances) {
       complete();
     }
   });
@@ -272,18 +294,24 @@ function updateAndReloadNginx(cb) {
     if (apps.length === 0) { err = "no apps running."; }
     if (err) { return console.error(err); }
 
-    const app_envs = apps
-      .filter(app => app.pm2_env.status !== cst.STOPPING_STATUS && app.pm2_env.status !== cst.STOPPED_STATUS)
-      .map((app) => app.pm2_env);
+    const app_envs = shared.filterActiveApps(apps).map((app) => app.pm2_env);
 
     writeNginxConfig(app_envs);
 
+    // update processes config (memory limit, etc)
+    app_envs.forEach((app_env) => 
+      shared.updateProcessConfig(app_env.pm_id, appConfig, logIfError));
+
     cb?.(app_envs);
   });
 }
 
 function writeNginxConfig(app_envs) {
   // console.log("writeNginxConfig: ", app_envs.map(app_env => app_env.NODE_APP_INSTANCE));
+  if (!fs.existsSync(shared.NGINX_SERVERS_CONFIG_FILE)) {
+    console.warn(`NGINX config file not found at ${shared.NGINX_SERVERS_CONFIG_FILE}, skipping NGINX config update.`);
+    return;
+  }
 
   const port = 2567;
   const addresses = [];

package/pm2/shared.js

@@ -1,12 +1,25 @@
 const pm2 = require('pm2');
+const cst = require('pm2/constants');
 const os = require('os');
 
 const NAMESPACE = 'cloud';
-const MAX_ACTIVE_PROCESSES = os.cpus().length;
+const MAX_ACTIVE_PROCESSES = Number(process.env.MAX_ACTIVE_PROCESSES || os.cpus().length);
+
+const CONFIG_KEYS = [
+  'max_memory_restart',
+  'kill_timeout',
+  'kill_retry_time',
+  'wait_ready',
+  'merge_logs',
+  'cron_restart',
+  'autorestart',
+  'exp_backoff_restart_delay',
+  'restart_delay',
+];
 
 function listApps(callback) {
   pm2.list((err, apps) => {
-    if (err) { return callback(err);; }
+    if (err) { return callback(err); }
 
     // Filter out @colyseus/tools module (PM2 post-deploy agent)
     apps = apps.filter(app => app.name !== '@colyseus/tools');
@@ -16,8 +29,10 @@ function listApps(callback) {
 }
 
 async function getAppConfig(ecosystemFilePath) {
-  const module = await import(ecosystemFilePath);
-  const config = module.default;
+  // Clear require cache to force reload of the config file
+  const resolvedPath = require.resolve(ecosystemFilePath);
+  delete require.cache[resolvedPath];
+  const config = require(ecosystemFilePath);
 
   /**
    * Tune PM2 app config
@@ -29,10 +44,16 @@ async function getAppConfig(ecosystemFilePath) {
     app.namespace = NAMESPACE;
     app.exec_mode = "fork";
 
+    // default: number of CPU cores
     if (app.instances === undefined) {
       app.instances = MAX_ACTIVE_PROCESSES;
     }
 
+    // default: restart if memory exceeds 512M
+    if (app.max_memory_restart === undefined) {
+      app.max_memory_restart = '512M';
+    }
+
     app.time = true;
     app.wait_ready = true;
     app.watch = false;
@@ -52,17 +73,74 @@ async function getAppConfig(ecosystemFilePath) {
     if (!app.kill_retry_time) {
       app.kill_retry_time = 5000;
     }
+
+    // Ensure these config values are also set in app.env so they take priority
+    // over inherited environment variables during PM2's Utility.extend() merge.
+    // This prevents the parent process's environment (e.g., @colyseus/tools agent)
+    // from overwriting the app's config values like max_memory_restart.
+    if (!app.env) {
+      app.env = {};
+    }
+
+    CONFIG_KEYS.forEach((key) => {
+      if (app[key] !== undefined) {
+        app.env[key] = convertValue(app[key]);
+      }
+    });
   }
 
   return config;
 }
 
+function convertValue(value) {
+  if (typeof value === 'string') {
+    const conversionUnit = {
+      // bytes
+      'G': 1024 * 1024 * 1024,
+      'M': 1024 * 1024,
+      'K': 1024,
+      // milliseconds
+      'h': 60 * 60 * 1000,
+      'm': 60 * 1000,
+      's': 1000
+    };
+
+    if (!conversionUnit[value.slice(-1)]) {
+      return parseInt(value, 10);
+
+    } else {
+      return parseFloat(value.slice(0, -1)) * (conversionUnit[value.slice(-1)]);
+    }
+  }
+  return value;
+}
+
+/**
+ * Update process configuration without restart.
+ * This patches pm2_env directly via a custom God method.
+ * @param {number|string} pm_id - Process ID to update
+ * @param {Object} config - Configuration object (e.g., { max_memory_restart: '512M', kill_timeout: 30000 })
+ * @param {Function} cb - Callback(err, updatedEnv)
+ */
+function updateProcessConfig(pm_id, config, cb) {
+  const env = {};
+
+  CONFIG_KEYS.forEach((key) => {
+    if (config[key] !== undefined) {
+      env[key] = convertValue(config[key]);
+    }
+  });
+
+  const opts = { id: pm_id, env, };
+  pm2.Client.executeRemote('updateProcessConfig', opts, cb);
+}
+
 module.exports = {
   /**
    * Constants
    */
-  NGINX_SERVERS_CONFIG_FILE: '/etc/nginx/colyseus_servers.conf',
-  PROCESS_UNIX_SOCK_PATH: '/run/colyseus/',
+  NGINX_SERVERS_CONFIG_FILE: process.env.NGINX_CONFIG_FILE || '/etc/nginx/colyseus_servers.conf',
+  PROCESS_UNIX_SOCK_PATH: process.env.UNIX_SOCK_PATH || '/run/colyseus/',
 
   MAX_ACTIVE_PROCESSES,
   NAMESPACE,
@@ -72,4 +150,11 @@ module.exports = {
    */
   listApps,
   getAppConfig,
+
+  updateProcessConfig,
+
+  filterActiveApps: (apps) => apps.filter(app =>
+    app.pm2_env.status !== cst.STOPPING_STATUS &&
+    app.pm2_env.status !== cst.STOPPED_STATUS
+  ),
 }

package/post-deploy.js

@@ -90,7 +90,11 @@ function restartAll () {
   });
 }
 
-function reloadAll(retry = 0) {
+async function reloadAll(retry = 0) {
+  // Read user's ecosystem config to get the desired number of instances
+  const config = await shared.getAppConfig(CONFIG_FILE_PATH);
+  const desiredInstances = config.apps?.[0]?.instances || shared.MAX_ACTIVE_PROCESSES;
+
   pm2.reload(CONFIG_FILE_PATH, { ...opts }, function (err, apps) {
     if (err) {
       //
@@ -110,9 +114,9 @@ function reloadAll(retry = 0) {
     const name = apps[0].name;
     const reloadedAppIds = apps.map(app => app.pm_id);
 
-    // scale app to use all CPUs available
-    if (apps.length !== shared.MAX_ACTIVE_PROCESSES) {
-      pm2.scale(name, shared.MAX_ACTIVE_PROCESSES, () => onAppRunning(reloadedAppIds));
+    // scale app to the number of instances specified in user's config
+    if (apps.length !== desiredInstances) {
+      pm2.scale(name, desiredInstances, () => onAppRunning(reloadedAppIds));
 
     } else {
       onAppRunning(reloadedAppIds);

package/system-boot.js

@@ -2,8 +2,88 @@
 
 const os = require('os');
 const fs = require('fs');
+const path = require('path');
 const { execSync } = require('child_process');
 
+/**
+ * Apply PM2 monkey-patch for custom functionality (e.g., updateProcessConfig)
+ * This patches the globally installed PM2 used by the system.
+ *
+ * Strategy: Rename ActionMethods.js -> ActionMethods_orig.js and replace with
+ * our wrapper that imports the original and adds custom methods.
+ */
+function applyPM2Patches() {
+  try {
+    // Find global PM2 installation
+    const globalPM2Path = execSync('npm root -g', { encoding: 'utf8' }).trim() + '/pm2';
+
+    if (!fs.existsSync(globalPM2Path)) {
+      console.log('[PM2 Patch] Global PM2 not found, skipping...');
+      return;
+    }
+
+    const godPath = path.join(globalPM2Path, 'lib/God');
+    const actionMethodsPath = path.join(godPath, 'ActionMethods.js');
+    const actionMethodsOrigPath = path.join(godPath, 'ActionMethods_orig.js');
+    const ourActionMethodsPath = path.join(__dirname, 'pm2', 'ActionMethods.js');
+
+    // Check if our patch file exists
+    if (!fs.existsSync(ourActionMethodsPath)) {
+      console.log('[PM2 Patch] Custom ActionMethods.js not found, skipping...');
+      return;
+    }
+
+    // Check if already patched (ActionMethods_orig.js exists)
+    if (!fs.existsSync(actionMethodsOrigPath)) {
+      // Rename original ActionMethods.js -> ActionMethods_orig.js
+      console.log('[PM2 Patch] Renaming original ActionMethods.js -> ActionMethods_orig.js');
+      fs.renameSync(actionMethodsPath, actionMethodsOrigPath);
+
+    } else {
+      console.log('[PM2 Patch] Already patched, skipping...');
+    }
+
+    // Copy our ActionMethods.js wrapper
+    console.log(`[PM2 Patch] Installing custom ActionMethods.js wrapper (${actionMethodsPath})`);
+    fs.copyFileSync(ourActionMethodsPath, actionMethodsPath);
+
+    // Patch Daemon.js to expose "updateProcessConfig" method
+    const daemonPath = path.join(globalPM2Path, 'lib/Daemon.js');
+    console.log(`[PM2 Patch] Patching Daemon.js to expose updateProcessConfig (${daemonPath})`);
+    if (fs.existsSync(daemonPath)) {
+      let daemonContent = fs.readFileSync(daemonPath, 'utf8');
+
+      // Check if updateProcessConfig is already exposed
+      if (!daemonContent.includes('updateProcessConfig')) {
+        // Find server.expose({ and add updateProcessConfig after it
+        const exposePattern = 'server.expose({';
+        const exposeIndex = daemonContent.indexOf(exposePattern);
+
+        if (exposeIndex !== -1) {
+          const insertPos = exposeIndex + exposePattern.length;
+          daemonContent = daemonContent.slice(0, insertPos) +
+            '\n    updateProcessConfig     : God.updateProcessConfig,' +
+            daemonContent.slice(insertPos);
+          fs.writeFileSync(daemonPath, daemonContent);
+          console.log(`[PM2 Patch] Daemon.js patched successfully.`);
+        } else {
+          console.warn('[PM2 Patch] Could not find server.expose pattern in Daemon.js');
+        }
+      } else {
+        console.log('[PM2 Patch] Daemon.js already has updateProcessConfig exposed.');
+      }
+    } else {
+      console.warn('[PM2 Patch] Daemon.js not found at', daemonPath);
+    }
+
+    console.log('[PM2 Patch] PM2 patches applied successfully.');
+
+  } catch (error) {
+    console.warn('[PM2 Patch] Failed to apply PM2 patches:', error.message);
+    // Don't exit - patches are optional enhancements
+  }
+}
+
 const NGINX_LIMITS_CONFIG_FILE = '/etc/nginx/colyseus_limits.conf';
 const LIMITS_CONF_FILE = '/etc/security/limits.d/colyseus.conf';
 const SYSCTL_FILE = '/etc/sysctl.d/local.conf';
@@ -117,4 +197,7 @@ net.ipv4.tcp_keepalive_probes = 3
   }
 }
 
+// Apply PM2 patches before configuring system limits
+applyPM2Patches();
+
 configureSystemLimits();