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 91.86047% with 28 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.28%. Comparing base (87a4efb) to head (823ccda).
⚠️ Report is 82 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_watchdog.cc	90.08%	0 Missing and 24 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.31%   90.28%   -0.03%     
==========================================
  Files         789      789              
  Lines      272878   273229     +351     
  Branches    52112    52183      +71     
==========================================
+ Hits       246444   246695     +251     
- Misses      16909    16963      +54     
- Partials     9525     9571      +46     

Files with missing lines	Coverage Δ
src/env.h	97.33% <100.00%> (+0.07%)	⬆️
src/inspector_agent.cc	81.96% <100.00%> (+0.10%)	⬆️
src/inspector_js_api.cc	77.28% <100.00%> (+0.27%)	⬆️
src/node.cc	77.50% <100.00%> (+0.13%)	⬆️
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.52% <95.83%> (+0.83%)	⬆️
src/node_watchdog.cc	79.82% <90.08%> (+11.07%)	⬆️

... and 39 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

[jasnell]

@nodejs/build ... this is currently blocked by the persistent windows ci failure

[github-actions]

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @jasnell.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment. Otherwise, the commit will be placed in the Other Notable Changes section.

[nodejs-github-bot]

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

[nodejs-github-bot]

Landed in 823d229