src: add --process-timeout=N

[jasnell]

Putting a time limit on a Node.js process is common in many use cases, but each of the common approaches are generally flawed.

OS and CI timeouts are inconsistent and blind. Every OS flavor handles process timeouts in different ways. Stock macOS and Windows do not ship coreutils timeout, etc. None of the options can explain why the process was still running or what exactly was interrupted. Using setTimeout only fires when the event loop is free so it misses busy loops and thread blocks and cannot see the stack. Diagnostics triggered by signal have the same problem.

This introduces a --process-timeout that should work consistently across all runtimes. A native watchdog thread interrupts the main thread, even in the middle of running code. It prints the JavaScript stack (if any) and resources keeping the event loop alive (if any), and can optionally print a full diagnostic report. The process exits with a distinct code (124). If the main thread is stuck in native code, the process still exits.

$ node --process-timeout=10s -e "while(true) {}"
(node:483970) Process timed out after 10s (--process-timeout). Exiting with code 124.
Main thread was executing JavaScript:
    at [eval]:1:1
    at runScriptInThisContext (node:internal/vm:219:10)
    at node:internal/process/execution:485:12
    at [eval]-wrapper:6:24
    at runScriptInContext (node:internal/process/execution:483:60)
    at evalFunction (node:internal/process/execution:317:30)
    at evalTypeScript (node:internal/process/execution:329:3)
    at node:internal/main/eval_string:71:3
No resources keeping the event loop alive were found.

Compare with using timeout which produces no diagnostic output:

$ timeout -v 10s ./node -e "while(true) {}"
timeout: sending signal TERM to command ‘./node’

This needs careful review and evaluation before considering landing. There are ways that the timeout can interplay with various other options (like --watch, and --inspect). I've made some preliminary decisions on it but they need to be reviewed.

We will need to evaluate flakiness of the tests... there are a couple risks to look out for:

• There is a 2 second grace: this is a fixed constant. If the main thread gets no CPU for over 2 seconds after the deadline, it exits without the stack, and the busy, idle, worker and report checks fail.
• Tiny windows: a deadline landing in the microseconds after the ready signal, e.g. between writing ready and calling spin(), would still fail.
• Windows: wait-for-parent.js can only check whether the parent's pid is alive, so a reused pid could keep it running until the 60 second cap.
• Very slow machines: above roughly 5 seconds per startup, the blocked-thread test's retries can exceed the harness timeout. It would then be reported as a timeout, not a clear assertion.

[nodejs-github-bot]

Review requested:

• @nodejs/config
• @nodejs/inspector
• @nodejs/startup

[codecov]

Codecov Report

❌ Patch coverage is 75.00000% with 95 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.25%. Comparing base (357ba2f) to head (f0d5d08).
⚠️ Report is 12 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_watchdog.cc	67.26%	59 Missing and 32 partials ⚠️
src/node_options.cc	95.83%	0 Missing and 3 partials ⚠️
src/node_main_instance.cc	80.00%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #66138      +/-   ##
==========================================
- Coverage   90.29%   90.25%   -0.04%     
==========================================
  Files         790      790              
  Lines      271882   272369     +487     
  Branches    51899    52004     +105     
==========================================
+ Hits       245485   245836     +351     
- Misses      16888    16996     +108     
- Partials     9509     9537      +28     

Files with missing lines	Coverage Δ
src/env.h	97.33% <100.00%> (+0.07%)	⬆️
src/inspector_agent.cc	82.09% <100.00%> (+0.36%)	⬆️
src/inspector_js_api.cc	77.28% <100.00%> (+0.27%)	⬆️
src/node.cc	77.03% <100.00%> (+0.26%)	⬆️
src/node_options.h	95.67% <100.00%> (+0.03%)	⬆️
src/node_watchdog.h	44.44% <ø> (ø)
src/node_worker.h	92.85% <100.00%> (+1.19%)	⬆️
src/node_main_instance.cc	89.47% <80.00%> (-0.67%)	⬇️
src/node_options.cc	81.57% <95.83%> (+0.84%)	⬆️
src/node_watchdog.cc	67.92% <67.26%> (-0.83%)	⬇️

... and 32 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[mcollina]

lgtm

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/77667/

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/77679/