lib: add trace-sigint APIs

theanarkh · RafaelGSS · commit e0555396042b · 2025-08-12T09:20:04.000-03:00
PR-URL: #59040 Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
diff --git a/doc/api/util.md b/doc/api/util.md
@@ -739,6 +739,16 @@ fs.access('file/that/does/not/exist', (err) => {
 });
 ```
 
+## `util.setTraceSigInt(enable)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `enable` {boolean}
+
+Enable or disable printing a stack trace on `SIGINT`. The API is only available on the main thread.
+
 ## `util.inherits(constructor, superConstructor)`
 
 <!-- YAML
diff --git a/lib/internal/process/pre_execution.js b/lib/internal/process/pre_execution.js
@@ -393,10 +393,7 @@ function setupStacktracePrinterOnSigint() {
   if (!getOptionValue('--trace-sigint')) {
     return;
   }
-  const { SigintWatchdog } = require('internal/watchdog');
-
-  const watchdog = new SigintWatchdog();
-  watchdog.start();
+  require('internal/util/trace_sigint').setTraceSigInt(true);
 }
 
 function initializeReport() {
diff --git a/lib/internal/util/trace_sigint.js b/lib/internal/util/trace_sigint.js
@@ -0,0 +1,29 @@
+'use strict';
+
+const { isMainThread } = require('worker_threads');
+const {
+  ERR_WORKER_UNSUPPORTED_OPERATION,
+} = require('internal/errors').codes;
+
+let sigintWatchdog;
+function getSigintWatchdog() {
+  if (!sigintWatchdog) {
+    const { SigintWatchdog } = require('internal/watchdog');
+    sigintWatchdog = new SigintWatchdog();
+  }
+  return sigintWatchdog;
+}
+
+function setTraceSigInt(enable) {
+  if (!isMainThread)
+    throw new ERR_WORKER_UNSUPPORTED_OPERATION('Calling util.setTraceSigInt');
+  if (enable) {
+    getSigintWatchdog().start();
+  } else {
+    getSigintWatchdog().stop();
+  }
+};
+
+module.exports = {
+  setTraceSigInt,
+};
diff --git a/lib/util.js b/lib/util.js
@@ -535,3 +535,9 @@ defineLazyProperties(
   'internal/util/diff',
   ['diff'],
 );
+
+defineLazyProperties(
+  module.exports,
+  'internal/util/trace_sigint',
+  ['setTraceSigInt'],
+);
diff --git a/test/parallel/test-trace-sigint-in-worker.js b/test/parallel/test-trace-sigint-in-worker.js
@@ -0,0 +1,20 @@
+'use strict';
+
+const common = require('../common');
+
+const assert = require('assert');
+const util = require('util');
+const { Worker, workerData } = require('worker_threads');
+
+if (workerData?.isWorker) {
+  assert.throws(() => {
+    util.setTraceSigInt(true);
+  }, {
+    code: 'ERR_WORKER_UNSUPPORTED_OPERATION',
+  });
+} else {
+  const w = new Worker(__filename, { workerData: { isWorker: true } });
+  w.on('exit', common.mustCall((code) => {
+    assert.strictEqual(code, 0);
+  }));
+}
diff --git a/test/pseudo-tty/test-start-trace-sigint.js b/test/pseudo-tty/test-start-trace-sigint.js
@@ -0,0 +1,32 @@
+'use strict';
+
+const { mustCall } = require('../common');
+const childProcess = require('child_process');
+const assert = require('assert');
+const util = require('util');
+
+if (process.env.CHILD === 'true') {
+  main();
+} else {
+  // Use inherited stdio child process to prevent test tools from determining
+  // the case as crashed from SIGINT
+  const cp = childProcess.spawn(
+    process.execPath,
+    [__filename],
+    {
+      env: { ...process.env, CHILD: 'true' },
+      stdio: 'inherit',
+    });
+  cp.on('exit', mustCall((code, signal) => {
+    assert.strictEqual(signal, 'SIGINT');
+    assert.strictEqual(code, null);
+  }));
+}
+
+function main() {
+  util.setTraceSigInt(true);
+  // Deactivate colors even if the tty does support colors.
+  process.env.NODE_DISABLE_COLORS = '1';
+  process.kill(process.pid, 'SIGINT');
+  while (true);
+}
diff --git a/test/pseudo-tty/test-start-trace-sigint.out b/test/pseudo-tty/test-start-trace-sigint.out
@@ -0,0 +1,11 @@
+KEYBOARD_INTERRUPT: Script execution was interrupted by `SIGINT`
+    at main (*/test-start-trace-sigint.js:*)
+    at */test-start-trace-sigint.js:*
+    at *
+    at *
+    at *
+    at *
+    at *
+    at *
+    at *
+    at *
diff --git a/test/pseudo-tty/test-stop-trace-sigint.js b/test/pseudo-tty/test-stop-trace-sigint.js
@@ -0,0 +1,32 @@
+'use strict';
+
+const { mustCall } = require('../common');
+const childProcess = require('child_process');
+const assert = require('assert');
+const util = require('util');
+
+if (process.env.CHILD === 'true') {
+  main();
+} else {
+  // Use inherited stdio child process to prevent test tools from determining
+  // the case as crashed from SIGINT
+  const cp = childProcess.spawn(
+    process.execPath,
+    ['--trace-sigint', __filename],
+    {
+      env: { ...process.env, CHILD: 'true' },
+      stdio: 'inherit',
+    });
+  cp.on('exit', mustCall((code, signal) => {
+    assert.strictEqual(signal, 'SIGINT');
+    assert.strictEqual(code, null);
+  }));
+}
+
+function main() {
+  util.setTraceSigInt(false);
+  // Deactivate colors even if the tty does support colors.
+  process.env.NODE_DISABLE_COLORS = '1';
+  process.kill(process.pid, 'SIGINT');
+  while (true);
+}
diff --git a/test/pseudo-tty/test-stop-trace-sigint.out b/test/pseudo-tty/test-stop-trace-sigint.out

Original file line number	Diff line number	Diff line change
`@@ -393,10 +393,7 @@ function setupStacktracePrinterOnSigint() {`
`393`	`393`	`if (!getOptionValue('--trace-sigint')) {`
`394`	`394`	`return;`
`395`	`395`	`}`
`396`		`- const { SigintWatchdog } = require('internal/watchdog');`
`397`		`-`
`398`		`- const watchdog = new SigintWatchdog();`
`399`		`- watchdog.start();`
	`396`	`+ require('internal/util/trace_sigint').setTraceSigInt(true);`
`400`	`397`	`}`
`401`	`398`
`402`	`399`	`function initializeReport() {`