test: add Nub loader recipe

Author: colinhacks

examples/using-pm2-and-transpilers/README.md

@@ -13,6 +13,32 @@ $ pm2 install typescript
 $ pm2 start http.ts
 ```
 
+### Node with `@nubjs/loader`
+
+Install the loader in the application. Keep PM2 on its normal Node interpreter. The loader needs Node.js 18.19 or later. PM2's daemon and cluster workers use that Node executable.
+
+```sh
+npm install --save-dev @nubjs/loader@0.8.3
+```
+
+Configure `node_args` as an array so PM2 preloads the loader before its fork and cluster containers start:
+
+```js
+module.exports = {
+  apps: [{
+    name: 'api',
+    script: './src/server.ts',
+    interpreter: 'node',
+    node_args: ['--import', '@nubjs/loader'],
+    instances: 2,
+    exec_mode: 'cluster',
+    wait_ready: true,
+  }],
+};
+```
+
+Start the ecosystem file with `pm2 start ecosystem.config.cjs`. PM2 keeps its Node process containers, IPC readiness, reload behavior, and cluster support. The loader does not provision or select a Node version. Retain the application's TypeScript type-check in CI. Do not set `interpreter` to a launcher executable. PM2 treats it as an arbitrary interpreter instead of using its Node containers.
+
 ## Livescript
 
 

lib/ProcessUtils.js

@@ -35,6 +35,13 @@ module.exports = {
     if (ext === '.ts' && stripping)
       return
 
+    var loader_preload = process.execArgv.some(function (argument, index, args) {
+      return argument === '--import=@nubjs/loader' ||
+        (argument === '--import' && args[index + 1] === '@nubjs/loader')
+    })
+    if (loader_preload)
+      return
+
     // Resolve ts-node from the application dependencies, not from PM2's
     try {
       require(require.resolve('ts-node/register', { paths: [cwd || path.dirname(exec_path)] }))

package.json

@@ -148,6 +148,7 @@
     "debug": "4.4.3"
   },
   "devDependencies": {
+    "@nubjs/loader": "0.8.3",
     "express": "^4.21.0",
     "mocha": "^11.7.0",
     "should": "^13.2.3"

test/e2e.sh

@@ -17,6 +17,7 @@ runTest ./test/e2e/cli/start-app.sh
 runTest ./test/e2e/cli/operate-regex.sh
 #runTest ./test/e2e/cli/bun.sh
 runTest ./test/e2e/cli/typescript.sh
+runTest ./test/e2e/cli/nub-loader.sh
 runTest ./test/e2e/cli/app-configuration.sh
 runTest ./test/e2e/cli/binary.sh
 runTest ./test/e2e/cli/startOrX.sh

test/e2e/cli/nub-loader.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+
+SRC=$(cd $(dirname "$0"); pwd)
+fixture=$(cd "$SRC/../../fixtures/nub-loader"; pwd)
+export PM2_HOME="$fixture/.pm2"
+source "${SRC}/../include.sh"
+
+log_file="$fixture/loader.log"
+
+cleanup() {
+  $pm2 delete all >/dev/null 2>&1 || true
+  $pm2 kill >/dev/null 2>&1 || true
+}
+trap cleanup EXIT
+
+pids_for() {
+  $pm2 jlist | $node -e '
+    let input = "";
+    process.stdin.on("data", (chunk) => input += chunk);
+    process.stdin.on("end", () => {
+      console.log(JSON.parse(input)
+        .filter((app) => app.name === "nub-loader-cluster")
+        .map((app) => app.pid)
+        .sort((left, right) => left - right)
+        .join(" "));
+    });
+  '
+}
+
+probe_reload() {
+  PM2_BIN="$pm2" APP_NAME="$1" PORT="$2" $node <<'NODE'
+const { spawn } = require('child_process');
+const http = require('http');
+
+let failures = 0;
+let pending = 0;
+
+function request() {
+  pending += 1;
+  let settled = false;
+  const complete = () => {
+    if (settled)
+      return;
+    settled = true;
+    pending -= 1;
+  };
+  const request = http.get(`http://127.0.0.1:${process.env.PORT}`, (response) => {
+    if (response.statusCode !== 200)
+      failures += 1;
+    response.resume();
+    response.once('end', complete);
+  });
+  request.setTimeout(1000, () => request.destroy());
+  request.once('error', () => {
+    failures += 1;
+    complete();
+  });
+}
+
+request();
+const reload = spawn(process.env.PM2_BIN, ['reload', process.env.APP_NAME], { stdio: 'inherit' });
+const probes = setInterval(request, 10);
+
+reload.once('close', (code) => {
+  clearInterval(probes);
+  const deadline = Date.now() + 2000;
+  const finish = () => {
+    if (pending > 0 && Date.now() < deadline) {
+      setTimeout(finish, 10);
+      return;
+    }
+    if (code !== 0 || failures > 0 || pending !== 0) {
+      console.error({ code, failures, pending });
+      process.exit(1);
+    }
+  };
+  setTimeout(finish, 50);
+});
+NODE
+}
+
+cd "$fixture"
+> "$log_file"
+
+$pm2 start ecosystem.config.cjs
+should 'should start the TypeScript fork and cluster apps' 'online' 5
+
+expected_node=$($node -p 'process.versions.node')
+! grep -F 'TypeScript support unavailable' "$log_file"
+spec 'Should not request ts-node when the loader is preloaded'
+ready_count=$(grep -Fc '"event":"ready"' "$log_file")
+[ "$ready_count" -eq 3 ]
+spec 'Should receive readiness from every fork and cluster worker'
+grep -F '"mode":"pm2"' "$log_file"
+spec 'Should transform non-erasable TypeScript syntax'
+grep -F "\"cwd\":\"$fixture\"" "$log_file"
+spec 'Should resolve the loader from the application cwd'
+grep -F "\"node\":\"$expected_node\"" "$log_file"
+spec 'Should run workers on the daemon Node version'
+grep -E '"sourceMapFrame":".*service\.ts:7:' "$log_file"
+spec 'Should preserve TypeScript source maps'
+
+old_cluster_pids=$(pids_for)
+[ "$(echo "$old_cluster_pids" | wc -w)" -eq 2 ]
+spec 'Should record both cluster worker PIDs before reload'
+
+probe_reload nub-loader-cluster 45679
+spec 'Should serve requests without interruption during cluster reload'
+
+should 'should keep both TypeScript cluster workers online after reload' 'online' 5
+
+probe_reload plain-js-cluster 45680
+spec 'Should keep a plain JavaScript cluster available during reload'
+
+new_cluster_pids=$(pids_for)
+[ "$old_cluster_pids" != "$new_cluster_pids" ]
+spec 'Should replace cluster workers after readiness reload'
+grep -F '"event":"shutdown"' "$log_file"
+spec 'Should deliver graceful shutdown to replaced workers'
+
+$pm2 delete all
+sleep 1
+remaining_workers=0
+for pid in $old_cluster_pids $new_cluster_pids; do
+  if kill -0 "$pid" 2>/dev/null; then
+    remaining_workers=1
+  fi
+done
+[ "$remaining_workers" -eq 0 ]
+spec 'Should not leave replaced cluster workers running'

test/fixtures/nub-loader/ecosystem.config.cjs

@@ -0,0 +1,54 @@
+const path = require('path');
+
+const app = {
+  script: './service.ts',
+  cwd: __dirname,
+  interpreter: 'node',
+  node_args: ['--import', '@nubjs/loader'],
+  wait_ready: true,
+  listen_timeout: 5000,
+  kill_timeout: 1000,
+  env: {
+    PORT: 45678,
+  },
+  merge_logs: true,
+  log_file: path.join(__dirname, 'loader.log'),
+};
+
+const plainApp = {
+  script: './service.js',
+  cwd: __dirname,
+  interpreter: 'node',
+  wait_ready: true,
+  listen_timeout: 5000,
+  kill_timeout: 1000,
+  env: {
+    PORT: 45680,
+  },
+  merge_logs: true,
+  log_file: path.join(__dirname, 'plain.log'),
+};
+
+module.exports = {
+  apps: [
+    {
+      ...app,
+      name: 'nub-loader-fork',
+    },
+    {
+      ...app,
+      name: 'nub-loader-cluster',
+      env: {
+        PORT: 45679,
+      },
+      instances: 2,
+      exec_mode: 'cluster',
+    },
+    {
+      ...plainApp,
+      name: 'plain-js-cluster',
+      instances: 2,
+      exec_mode: 'cluster',
+    },
+  ],
+};

test/fixtures/nub-loader/service.js

@@ -0,0 +1,18 @@
+const { createServer } = require('node:http');
+
+const server = createServer((_request, response) => {
+  response.end('ok');
+});
+
+let shuttingDown = false;
+
+process.on('SIGINT', () => {
+  if (shuttingDown)
+    return;
+  shuttingDown = true;
+  console.log(JSON.stringify({ event: 'shutdown', pid: process.pid }));
+  process.disconnect?.();
+  server.close();
+});
+
+server.listen(Number(process.env.PORT), () => process.send?.('ready'));

test/fixtures/nub-loader/service.ts

@@ -0,0 +1,32 @@
+const { createServer } = require('node:http');
+
+enum ContainerMode {
+  Pm2 = 'pm2',
+}
+
+const sourceMapFrame = new Error('source map check').stack?.split('\n')[1]?.trim();
+
+console.log(JSON.stringify({
+  event: 'ready',
+  mode: ContainerMode.Pm2,
+  cwd: process.cwd(),
+  node: process.versions.node,
+  sourceMapFrame,
+}));
+
+const server = createServer((_request, response) => {
+  response.end('ok');
+});
+
+let shuttingDown = false;
+
+process.on('SIGINT', () => {
+  if (shuttingDown)
+    return;
+  shuttingDown = true;
+  console.log(JSON.stringify({ event: 'shutdown', pid: process.pid }));
+  process.disconnect?.();
+  server.close();
+});
+
+server.listen(Number(process.env.PORT), () => process.send?.('ready'));

test/programmatic/interpreter_resolution.mocha.js

@@ -138,6 +138,9 @@ describe('TypeScript interpreter resolution', function () {
   describe('ProcessUtils.enableTypeScript', function () {
     var ProcessUtils = require('../../lib/ProcessUtils');
     var fake_app_dir;
+    var empty_app_dir;
+    var saved_exec_argv;
+    var real_console_error;
 
     before(function () {
       // Fake app with ts-node in its own node_modules, to prove ts-node is
@@ -149,15 +152,23 @@ describe('TypeScript interpreter resolution', function () {
         JSON.stringify({ name: 'ts-node', version: '0.0.0', main: 'register.js' }));
       fs.writeFileSync(path.join(ts_node_dir, 'register.js'),
         'global.__fake_ts_node_loaded = true;');
+      empty_app_dir = fs.mkdtempSync(path.join(os.tmpdir(), 'pm2-empty-ts-app-'));
+      saved_exec_argv = process.execArgv;
+      real_console_error = console.error;
     });
 
     after(function () {
+      process.execArgv = saved_exec_argv;
+      console.error = real_console_error;
       fs.rmSync(fake_app_dir, { recursive: true, force: true });
+      fs.rmSync(empty_app_dir, { recursive: true, force: true });
       delete global.__fake_ts_node_loaded;
     });
 
     beforeEach(function () {
       delete global.__fake_ts_node_loaded;
+      process.execArgv = [];
+      console.error = real_console_error;
     });
 
     it('should be a no-op for non-TypeScript files', function () {
@@ -176,6 +187,30 @@ describe('TypeScript interpreter resolution', function () {
       ProcessUtils.enableTypeScript(path.join(fake_app_dir, 'app.tsx'), fake_app_dir);
       should(global.__fake_ts_node_loaded).eql(true);
     });
+
+    it('should not request ts-node when @nubjs/loader is preloaded', function () {
+      if (process.features && process.features.typescript)
+        this.skip();
+
+      var warnings = [];
+      process.execArgv = ['--import', '@nubjs/loader'];
+      console.error = function () { warnings.push(Array.prototype.join.call(arguments, ' ')); };
+
+      ProcessUtils.enableTypeScript(path.join(empty_app_dir, 'app.ts'), empty_app_dir);
+      should(warnings).be.empty();
+    });
+
+    it('should retain the ts-node fallback without the loader preload', function () {
+      if (process.features && process.features.typescript)
+        this.skip();
+
+      var warnings = [];
+      console.error = function () { warnings.push(Array.prototype.join.call(arguments, ' ')); };
+
+      ProcessUtils.enableTypeScript(path.join(empty_app_dir, 'app.ts'), empty_app_dir);
+      should(warnings).have.length(1);
+      should(warnings[0]).match(/TypeScript support unavailable/);
+    });
   });
 
   describe('God.nodeApp daemon-side strip flag (cluster)', function () {