From 2cdca4ee0040a97d0b254ea39667774fdd285bcf Mon Sep 17 00:00:00 2001
From: theanarkh <theratliter@gmail.com>
Date: Sat, 12 Jul 2025 16:39:12 +0800
Subject: [PATCH] lib: add trace-sigint APIs

---
 doc/api/util.md                              | 10 ++++++
 lib/internal/process/pre_execution.js        |  5 +--
 lib/internal/util/trace_sigint.js            | 29 ++++++++++++++++++
 lib/util.js                                  |  6 ++++
 test/parallel/test-trace-sigint-in-worker.js | 20 ++++++++++++
 test/pseudo-tty/test-start-trace-sigint.js   | 32 ++++++++++++++++++++
 test/pseudo-tty/test-start-trace-sigint.out  | 11 +++++++
 test/pseudo-tty/test-stop-trace-sigint.js    | 32 ++++++++++++++++++++
 test/pseudo-tty/test-stop-trace-sigint.out   |  0
 9 files changed, 141 insertions(+), 4 deletions(-)
 create mode 100644 lib/internal/util/trace_sigint.js
 create mode 100644 test/parallel/test-trace-sigint-in-worker.js
 create mode 100644 test/pseudo-tty/test-start-trace-sigint.js
 create mode 100644 test/pseudo-tty/test-start-trace-sigint.out
 create mode 100644 test/pseudo-tty/test-stop-trace-sigint.js
 create mode 100644 test/pseudo-tty/test-stop-trace-sigint.out

diff --git a/doc/api/util.md b/doc/api/util.md
index 9b6282fc67945b..9d452311aa7468 100644
--- 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
index 480e150496d2db..fc7a0e206928da 100644
--- 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
new file mode 100644
index 00000000000000..fe946f1486c232
--- /dev/null
+++ 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
index 0884a8d518602d..4b014a290c312f 100644
--- 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
new file mode 100644
index 00000000000000..ed7ca3908e7ca5
--- /dev/null
+++ 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
new file mode 100644
index 00000000000000..bbadae61093061
--- /dev/null
+++ 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
new file mode 100644
index 00000000000000..e5e4911f844080
--- /dev/null
+++ 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
new file mode 100644
index 00000000000000..363a4008371ba6
--- /dev/null
+++ 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
new file mode 100644
index 00000000000000..e69de29bb2d1d6