watch: add --watch-kill-signal flag

add the new `--watch-kill-signal` to allow users to customize
what signal is sent to the process on restarts during watch mode

PR-URL: #58719
Reviewed-By: Yagiz Nizipli <[email protected]>

Author: dario-piotrowicz

doc/api/cli.md

@@ -3092,6 +3092,19 @@ mode. If no file is provided, Node.js will exit with status code `9`.
 node --watch index.js
 ```
 
+### `--watch-kill-signal`
+
+<!-- YAML
+added:
+  - REPLACEME
+-->
+
+Customizes the signal sent to the process on watch mode restarts.
+
+```bash
+node --watch --watch-kill-signal SIGINT test.js
+```
+
 ### `--watch-path`
 
 <!-- YAML
@@ -3434,6 +3447,7 @@ one is included in the list below.
 * `--use-openssl-ca`
 * `--use-system-ca`
 * `--v8-pool-size`
+* `--watch-kill-signal`
 * `--watch-path`
 * `--watch-preserve-output`
 * `--watch`

doc/node-config-schema.json

@@ -562,6 +562,9 @@
         "watch": {
           "type": "boolean"
         },
+        "watch-kill-signal": {
+          "type": "string"
+        },
         "watch-path": {
           "oneOf": [
             {

lib/internal/main/watch_mode.js

@@ -20,6 +20,7 @@ const {
 const { getOptionValue } = require('internal/options');
 const { FilesWatcher } = require('internal/watch_mode/files_watcher');
 const { green, blue, red, white, clear } = require('internal/util/colors');
+const { convertToValidSignal } = require('internal/util');
 
 const { spawn } = require('child_process');
 const { inspect } = require('util');
@@ -30,8 +31,7 @@ const { once } = require('events');
 prepareMainThreadExecution(false, false);
 markBootstrapComplete();
 
-// TODO(MoLow): Make kill signal configurable
-const kKillSignal = 'SIGTERM';
+const kKillSignal = convertToValidSignal(getOptionValue('--watch-kill-signal'));
 const kShouldFilterModules = getOptionValue('--watch-path').length === 0;
 const kEnvFile = getOptionValue('--env-file') || getOptionValue('--env-file-if-exists');
 const kWatchedPaths = ArrayPrototypeMap(getOptionValue('--watch-path'), (path) => resolve(path));

src/node_options.cc

@@ -953,6 +953,11 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             "path to watch",
             &EnvironmentOptions::watch_mode_paths,
             kAllowedInEnvvar);
+  AddOption("--watch-kill-signal",
+            "kill signal to send to the process on watch mode restarts"
+            "(default: SIGTERM)",
+            &EnvironmentOptions::watch_mode_kill_signal,
+            kAllowedInEnvvar);
   AddOption("--watch-preserve-output",
             "preserve outputs on watch mode restart",
             &EnvironmentOptions::watch_mode_preserve_output,

src/node_options.h

@@ -231,6 +231,7 @@ class EnvironmentOptions : public Options {
   bool watch_mode = false;
   bool watch_mode_report_to_parent = false;
   bool watch_mode_preserve_output = false;
+  std::string watch_mode_kill_signal = "SIGTERM";
   std::vector<std::string> watch_mode_paths;
 
   bool syntax_check_only = false;

test/parallel/test-runner-watch-mode-kill-signal.mjs

@@ -0,0 +1,122 @@
+import * as common from '../common/index.mjs';
+import { describe, it, beforeEach } from 'node:test';
+import { once } from 'node:events';
+import assert from 'node:assert';
+import { spawn } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import tmpdir from '../common/tmpdir.js';
+
+if (common.isWindows) {
+  common.skip('no signals on Windows');
+}
+
+if (common.isIBMi) {
+  common.skip('IBMi does not support `fs.watch()`');
+}
+
+if (common.isAIX) {
+  common.skip('folder watch capability is limited in AIX.');
+}
+
+const indexContents = `
+  const { setTimeout } = require("timers/promises");
+  (async () => {
+      // Wait a few milliseconds to make sure that the
+      // parent process has time to attach its listeners
+      await setTimeout(200);
+
+      process.on('SIGTERM', () => {
+          console.log('__SIGTERM received__');
+          process.exit(123);
+      });
+
+      process.on('SIGINT', () => {
+          console.log('__SIGINT received__');
+          process.exit(124);
+      });
+
+      console.log('ready!');
+
+      // Wait for a long time (just to keep the process alive)
+      await setTimeout(100_000_000);
+  })();
+`;
+
+let indexPath = '';
+
+function refresh() {
+  tmpdir.refresh();
+  indexPath = tmpdir.resolve('index.js');
+  writeFileSync(indexPath, indexContents);
+}
+
+describe('test runner watch mode with --watch-kill-signal', () => {
+  beforeEach(refresh);
+
+  it('defaults to SIGTERM', async () => {
+    let currentRun = Promise.withResolvers();
+    const child = spawn(process.execPath, ['--watch', indexPath], {
+      cwd: tmpdir.path,
+    });
+
+    let stdout = '';
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+      currentRun.resolve();
+    });
+
+    await currentRun.promise;
+
+    currentRun = Promise.withResolvers();
+    writeFileSync(indexPath, indexContents);
+
+    await currentRun.promise;
+    child.kill();
+    const [exitCode] = await once(child, 'exit');
+    assert.match(stdout, /__SIGTERM received__/);
+    assert.strictEqual(exitCode, 123);
+  });
+
+  it('can be overridden (to SIGINT)', async () => {
+    let currentRun = Promise.withResolvers();
+    const child = spawn(process.execPath, ['--watch', '--watch-kill-signal', 'SIGINT', indexPath], {
+      cwd: tmpdir.path,
+    });
+    let stdout = '';
+
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+      if (stdout.includes('ready!')) {
+        currentRun.resolve();
+      }
+    });
+
+    await currentRun.promise;
+
+    currentRun = Promise.withResolvers();
+    writeFileSync(indexPath, indexContents);
+
+    await currentRun.promise;
+    child.kill();
+    const [exitCode] = await once(child, 'exit');
+    assert.match(stdout, /__SIGINT received__/);
+    assert.strictEqual(exitCode, 124);
+  });
+
+  it('errors if an invalid signal is provided', async () => {
+    const currentRun = Promise.withResolvers();
+    const child = spawn(process.execPath, ['--watch', '--watch-kill-signal', 'invalid_signal', indexPath], {
+      cwd: tmpdir.path,
+    });
+    let stdout = '';
+
+    child.stderr.on('data', (data) => {
+      stdout += data.toString();
+      currentRun.resolve();
+    });
+
+    await currentRun.promise;
+
+    assert.match(stdout, new RegExp(/TypeError \[ERR_UNKNOWN_SIGNAL\]: Unknown signal: invalid_signal/));
+  });
+});