Feature request: Ability to programmatically cause `SIGINT` in child node process on Windows

[zenflow]

Is your feature request related to a problem? Please describe.

The problem is that there's no cross-platform way to "gracefully" end a child node process.

By "gracefully" I just mean "not abruptly" and "giving it a chance to finish what it needs to do before exiting" (i.e. what SIGINT & SIGTERM are meant to do on Linux).

I know that Windows itself doesn't support those signals, but Node.js already "offers some emulation with process.kill(), and subprocess.kill()" (reference).

Another way that Node.js emulates signal events on Windows (not documented in the reference, but elsewhere) is by generating a SIGINT event when a ctrl+c is received via stdin (and process.stdin is not in raw mode).

In this event, the SIGINT event is generated, not only in the parent process, but also in child node processes.

Let's call this "non-raw-mode ctrl+c behavior".

See "example script" just below for proof.

example script

Run this script (on Windows or Linux), wait for it to say "child started", then hit ctrl+c.

const child = require('child_process').spawn(
  'node',
  [
    '-e',
    "console.log('child started');" +
      'setInterval(() => {}, 1000);' +
      "process.on('SIGINT', () => {" +
      "console.log('child received SIGINT');" +
      'process.exit();' +
      '})',
  ],
  { stdio: ['ignore', 'inherit', 'inherit'] },
)
child.on('exit', () => console.log('child exited'))
process.on('SIGINT', () => console.log('parent received SIGINT'))

Complete output will look like:

child started
child received SIGINT
parent received SIGINT
child exited

If Node.js is somehow able to generate a SIGINT in child node processes in response to a ctrl+c,
then is it possible for Node.js to generate a SIGINT in a child process when we call childProcess.kill('SIGINT')?
This is my main question. :)

Describe the solution you'd like

In Windows environments, when I have a child process that is another Node.js process, I would like to be able to cause a SIGINT event in the child by calling childProcess.kill('SIGINT') in the parent.

Maybe this could even work by sending a ctrl+c keystroke to the child process's stdin? (This is something I failed to do in userland; see first alternative described below) If it worked this way, then even non-node processes could be gracefully stopped on Windows.

Or maybe it could work by copying from the "non-raw-mode ctrl+c behavior" (whatever Node.js is doing under the hood to cause SIGINT events in child processes on Windows)?

Describe alternatives you've considered

First:

I tried to cause a SIGINT in a child process by writing "\u0003" (utf8 character for ctrl+c) to the child's stdin stream.
Since this is the utf8 character emitted by process.stdin when it receives a ctrl+c in raw mode, I thought it would simulate pressing ctrl+c in the terminal and cause a SIGINT event, but nope.
See "example script" just below for proof.

example script

Run this script (on Windows or Linux), wait for it to say "child started", then hit ctrl+c.

const child = require('child_process').spawn(
  'node',
  [
    '-e',
    "console.log('child started');" +
      'setInterval(() => {}, 1000);' +
      "process.on('SIGINT', () => {" +
      "console.log('child received SIGINT');" +
      'process.exit();' +
      '})',
  ],
  { stdio: ['pipe', 'inherit', 'inherit'] },
)
child.on('exit', () => console.log('child exited'))
process.on('SIGINT', () => console.log('parent received SIGINT'))

// Set `process.stdin` into raw mode so that it emits a buffer containing `"\u0003"` when ctrl+c is pressed
process.stdin.setRawMode(true)

// Pipe parent stdin to child stdin, so child will receive buffer containing `"\u0003"`.
process.stdin.pipe(child.stdin)

// eventually exit example
setTimeout(() => child.kill('SIGKILL'), 5000)

Is this is a bug which could be fixed instead of implementing my suggested new feature?

Second:

We can try to take advantage of the "non-raw-mode ctrl+c behavior" (which will generate SIGINT event in parent & child processes, across platforms), but that has lots of limitations:

1. Only works when shutting down from ctrl+c. It doesn't help when we want our parent script to clean up & exit due to it's own decision. It also doesn't help when we just want to end the child process and keep the parent running. In these cases we are left with childProcess.kill('SIGINT') which kills the process abruptly on Windows.
2. No way to control the timing. We might want to end one child process only after ending another child process. (And actually that would be great, though not strictly necessary, for my library (which currently has slightly inaccurate documentation)).
3. Requires parent process's stdin to not be in "raw mode". This means:
   1. We're constrained to one of two ways to work with input from stdin. IMHO ideally if we had to (or wanted to) switch to raw mode of processing input, we would be able to reproduce the behaviors of non-raw mode (i.e. ctrl+c causing SIGINT in parent & children)
   2. Now we have potential problems shutting down gracefully on Linux:
      Since the parent process doesn't know if a SIGINT event was caused by a ctrl+c in the terminal, or if it was caused by an actual SIGINT signal from another process, it needs to issue a SIGINT (with childProcess.kill('SIGINT')) to be sure that the child received at least one SIGINT event.
      So when shutting down from ctrl+c, child processes will receive 2 SIGINT events, which could uncover bugs in programs that don't handle multiple signals properly.
      On Windows we don't have this problem because we know that if the parent process has a SIGINT event it was from ctrl+c, and in that situation we don't need to issue SIGINT to children.

[zenflow]

Forgot to mention: I would be thrilled to work on this and put together a PR /w tests & documentation if I could get a bit of guidance from someone who is both interested in the issue & able to answer some of the questions above 😀 Thanks so much!

[bnoordhuis]

Node's (well, libuv's) SIGINT emulation works by calling SetConsoleCtrlHandler() and handling CTRL_C_EVENT.

I don't know of a way of artificially inducing a CTRL_C_EVENT in another process. There's GenerateConsoleCtrlEvent() but that signals the process group, not a single process, and its documentation explicitly states CTRL_C_EVENT doesn't work.

Some additional caveats:

• Unlike SIGINT on Unices, there's no default action. The target process needs to explicitly handle the event, otherwise it's simply ignored. Okay for Node.js but it means you can't signal random programs and expect it to work.

• I suspect CTRL_C_EVENT only works for console programs but Node.js doesn't always run as one (electron, system service, etc.)

[zenflow]

@bnoordhuis Thanks so much for the info! This is really really useful to me! =D

The docs for GenerateConsoleCtrlEvent() seem a little confusing, but I believe CTRL_C_EVENT does work, just not when trying to limit the signal to a single process group. I put in a PR to the docs to clarify this.

At the bottom of the description of dwProcessGroupId:

If this parameter is zero, the signal is generated in all processes that share the console of the calling process.

So by calling GenerateConsoleCtrlEvent(CTRL_C_EVENT, 0) we can send the CTRL_C_EVENT signal to "all processes that share the console of the calling process".

I tested this and it works as expected. See "example code" just below.

example code

Copy 2 files below, run node ctrlc-example.js, wait for "child started", press ctrl+c

// ctrlc-example.js

const { spawn } = require('child_process')
const child = spawn(
  'node',
  [
    '-e',
    "console.log('child started');" +
      'setInterval(() => {}, 1000);' +
      "process.on('SIGINT', () => {" +
      "console.log('child received SIGINT');" +
      'process.exit();' +
      '})',
  ],
  { stdio: ['ignore', 'inherit', 'inherit'] },
)
child.on('exit', () => console.log('child exited'))
process.on('SIGINT', () => console.log('parent received SIGINT'))

process.stdin.setRawMode(true)
process.stdin.on('data', data => {
  if (data.toString('utf8') === '\u0003') {
    console.log('parent received ctrl+c')
    process.stdin.destroy() // destroy stdin so process can exit naturally after child processes exit
    spawn('powershell.exe', ['-File', 'generate-ctrlc.ps1'])
  }
})

# generate-ctrlc.ps1

# --- helpers from https://blog.dantup.com/2013/10/easily-calling-windows-apis-from-powershell/
$script:nativeMethods = @();
function Register-NativeMethod([string]$dll, [string]$methodSignature)
{
    $script:nativeMethods += [PSCustomObject]@{ Dll = $dll; Signature = $methodSignature; }
}
function Add-NativeMethods()
{
    $nativeMethodsCode = $script:nativeMethods | % { "
        [DllImport(`"$($_.Dll)`")]
        public static extern $($_.Signature);
    " }

    Add-Type @"
        using System;
        using System.Runtime.InteropServices;
        public static class NativeMethods {
            $nativeMethodsCode
        }
"@
}
# ---

Register-NativeMethod "Kernel32.dll" "bool GenerateConsoleCtrlEvent(uint dwCtrlEvent, uint dwProcessGroupId)"
Add-NativeMethods

[NativeMethods]::GenerateConsoleCtrlEvent(0, 0) | Out-Null

Output will look like:

child started
parent received ctrl+c
child received SIGINT
parent received SIGINT
child exited

This is great since though we may not have the feature as described exactly in the title, we now have "Ability to programmatically cause SIGINT in all node processes attached to same console on Windows". More specifically we have the ability to programatically send a ctrl+c signal to all processes attached to the same console on Windows. More importantly, if we combine this with sending actual SIGINT signals on Linux, we have a cross-platform way to gracefully end the current process and all of it's children as long as they're all console programs attached to the same console.

It has it's limitations but this could be useful in many of the common situations where we would want to programatically cause a child process to end gracefully, specifically, in a console program, when the parent/main process receives a signal to shut down, or when the parent/main process itself decides to clean up & exit. This does come with the caveat that any other processes attached to the same console will also receive the ctrl+c signal, including a possible additional parent process.

It would be really great if we could expose this system call (GenerateConsoleCtrlEvent(CTRL_C_EVENT, 0) in Node.js, especially since this is what we probably want to do in Windows when process.stdin is in raw mode and we want to reproduce the behavior from non-raw mode (ctrl+c keystroke causes CTRL_C_EVENT for all processes attached to that console).
In Unix (please correct me if I'm wrong) we don't have a way to reproduce the exact behavior of non-raw mode, but we can already approximate it pretty closely in most situations by sending SIGINT to child processes and parent process.

I want to open a new issue for this (probably titled like "Feature request: Add process.generateConsoleCtrlCEvent()"), but I would like to gather some more feedback if possible =)

There are options in userland:

1. Use PowerShell scripting to make the call. But this is verrry slow.
2. Use the ffi-napi package or a custom C++ addon. But these rely node-gyp building an addon during npm install, which is somewhat unreliable on Windows in my experience. Now we have (windows-build-tools)[https://github.com/felixrieseberg/windows-build-tools] to help with this, but it may not be installed, or there may be a problem with it.

@bnoordhuis Is this something you think might be included in core (Node.js)? Thanks for your guidance =)

[zenflow]

@bnoordhuis You said:

Unlike SIGINT on Unices, there's no default action. The target process needs to explicitly handle the event, otherwise it's simply ignored. Okay for Node.js but it means you can't signal random programs and expect it to work.

I'm not sure.. Documentation seems to indicate otherwise (though it could be wrong)..

GenerateConsoleCtrlEvent Remarks says:

All console processes have a default handler function that calls the ExitProcess function

More on this from SetConsoleCtrlHandler Remarks:

Initially, the handler list for each process contains only a default handler function that calls the ExitProcess function. A console process adds or removes additional handler functions by calling the SetConsoleCtrlHandler function, which does not affect the list of handler functions for other processes. When a console process receives any of the control signals, its handler functions are called on a last-registered, first-called basis until one of the handlers returns TRUE. If none of the handlers returns TRUE, the default handler is called.

I tested how python scripts handle the signal by default: Building off my "example code" from #35172 (comment) I replaced the node -e ... command with python -c "import time; print('child started'); time.sleep(999999)" and the python process handled the ctrl+c signal, and in the same way as when I ran the command directly & sent ctrl+c directly. Here is the output:

child started
parent received ctrl+c
Traceback (most recent call last):
  File "<string>", line 1, in <module>
KeyboardInterrupt
parent received SIGINT
child exited

(The 3 lines from "Traceback" to "KeyboardInterrupt" are from the child process)

I can't really think of any naturally long-running Windows console programs to try, but if there are any ideas I would be happy to try them.

[zenflow]

I suspect CTRL_C_EVENT only works for console programs but Node.js doesn't always run as one (electron, system service, etc.)

Yup, that's exactly right. It won't work for programs not attached to the same console as the caller process (which therefore requires those programs to be console programs).

I guess for that reason, and because we can't limit the signal to a single process, we can't use this to implement childProcess.kill('SIGINT') on Windows. :(

[bnoordhuis]

That sounds about right. I'll close this but let me know if there's reason to reopen.

[zenflow]

To whom it may concern, I published generate-ctrl-c-event for generating CTRL_C_EVENT on Windows.

It's a bit inconvenient that it needs ffi-napi to make the system call quickly & efficiently, since that requires the nodegyp toolchain to be set up properly where it's installed (which is frequently not the case on Windows, even when using windows-build-tools). But generate-ctrl-c-event has ffi-napi as an "optional dependency", so if ffi-napi fails to install, it just won't be used, and the system call will be made via a PowerShell script instead (which is really slow).

Still I don't think I'll propose to add this to Node.js core, due to the major caveat:

any other processes attached to the same console will also receive the ctrl+c signal, including a possible additional parent process

I think that would cause a lot of bugs and problems.