allow handler to capture signal exits

Author: isaacs

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 4.1
+
+- Add the ability to capture signal exits by returning `true`
+  from the `onExit` listener.
+
 ## 4.0
 
 - Rewritten in TypeScript

README.md

@@ -40,6 +40,29 @@ If the global `process` object is not suitable for this purpose
 - `alwaysLast`: Run this handler after any other signal or exit
   handlers. This causes `process.emit` to be monkeypatched.
 
+### Capturing Signal Exits
+
+If the handler returns an exact boolean `true`, and the exit is a
+due to signal, then the signal will be considered handled, and
+will _not_ trigger a synthetic `process.kill(process.pid,
+signal)` after firing the `onExit` handlers.
+
+In this case, it your responsibility as the caller to exit with a
+signal (for example, by calling `process.kill()`) if you wish to
+preserve the same exit status that would otherwise have occurred.
+If you do not, then the process will likely exit gracefully with
+status 0 at some point, assuming that no other terminating signal
+or other exit trigger occurs.
+
+Prior to calling handlers, the `onExit` machinery is unloaded, so
+any subsequent exits or signals will not be handled, even if the
+signal is captured and the exit is thus prevented.
+
+Note that numeric code exits may indicate that the process is
+already committed to exiting, for example due to a fatal
+exception or unhandled promise rejection, and so there is no way to
+prevent it safely.
+
 ### Browser Fallback
 
 The `'signal-exit/browser'` module is the same fallback shim that

src/index.ts

@@ -28,16 +28,27 @@ const ObjectDefineProperty = Object.defineProperty.bind(Object)
 
 /**
  * A function that takes an exit code and signal as arguments
+ *
+ * In the case of signal exits *only*, a return value of true
+ * will indicate that the signal is being handled, and we should
+ * not synthetically exit with the signal we received. Regardless
+ * of the handler return value, the handler is unloaded when an
+ * otherwise fatal signal is received, so you get exactly 1 shot
+ * at it, unless you add another onExit handler at that point.
+ *
+ * In the case of numeric code exits, we may already have committed
+ * to exiting the process, for example via a fatal exception or
+ * unhandled promise rejection, so it is impossible to stop safely.
  */
 export type Handler = (
   code: number | null | undefined,
   signal: NodeJS.Signals | null
-) => any
+) => true | void
 type ExitEvent = 'afterExit' | 'exit'
 type Emitted = { [k in ExitEvent]: boolean }
 type Listeners = { [k in ExitEvent]: Handler[] }
 
-// teeny tiny ee
+// teeny special purpose ee
 class Emitter {
   emitted: Emitted = {
     afterExit: false,
@@ -87,14 +98,19 @@ class Emitter {
     ev: ExitEvent,
     code: number | null | undefined,
     signal: NodeJS.Signals | null
-  ) {
+  ): boolean {
     if (this.emitted[ev]) {
-      return
+      return false
     }
     this.emitted[ev] = true
+    let ret: boolean = false
     for (const fn of this.listeners[ev]) {
-      fn(code, signal)
+      ret = fn(code, signal) === true || ret
+    }
+    if (ev === 'exit') {
+      ret = this.emit('afterExit', code, signal) || ret
     }
+    return ret
   }
 }
 
@@ -172,10 +188,10 @@ class SignalExit extends SignalExitBase {
         /* c8 ignore stop */
         if (listeners.length === count) {
           this.unload()
-          this.#emitter.emit('exit', null, sig)
-          this.#emitter.emit('afterExit', null, sig)
+          const ret = this.#emitter.emit('exit', null, sig)
           /* c8 ignore start */
-          process.kill(process.pid, sig === 'SIGHUP' ? this.#hupSig : sig)
+          const s = sig === 'SIGHUP' ? this.#hupSig : sig
+          if (!ret) process.kill(process.pid, s)
           /* c8 ignore stop */
         }
       }
@@ -269,7 +285,6 @@ class SignalExit extends SignalExitBase {
     /* c8 ignore stop */
 
     this.#emitter.emit('exit', this.#process.exitCode, null)
-    this.#emitter.emit('afterExit', this.#process.exitCode, null)
     return this.#originalProcessReallyExit.call(
       this.#process,
       this.#process.exitCode
@@ -287,7 +302,6 @@ class SignalExit extends SignalExitBase {
       const ret = og.call(this.#process, ev, ...args)
       /* c8 ignore start */
       this.#emitter.emit('exit', this.#process.exitCode, null)
-      this.#emitter.emit('afterExit', this.#process.exitCode, null)
       /* c8 ignore stop */
       return ret
     } else {

tap-snapshots/test/signal-capture.ts.test.cjs

@@ -0,0 +1,52 @@
+/* IMPORTANT
+ * This snapshot file is auto-generated, but designed for humans.
+ * It should be checked into source control and tracked carefully.
+ * Re-generate by setting TAP_SNAPSHOT=1 and running tests.
+ * Make sure to inspect the output below.  Do not ignore changes!
+ */
+'use strict'
+exports[`test/signal-capture.ts TAP exit 0 > must match snapshot 1`] = `
+exit handler 0 null
+afterExit handler 0 null
+
+`
+
+exports[`test/signal-capture.ts TAP exit 1 > must match snapshot 1`] = `
+exit handler 1 null
+afterExit handler 1 null
+
+`
+
+exports[`test/signal-capture.ts TAP graceful exit > must match snapshot 1`] = `
+exit handler 0 null
+afterExit handler 0 null
+
+`
+
+exports[`test/signal-capture.ts TAP signal, capture afterExit > must match snapshot 1`] = `
+exit handler null SIGHUP
+afterExit handler null SIGHUP
+afterExit captured signal
+
+`
+
+exports[`test/signal-capture.ts TAP signal, capture both > must match snapshot 1`] = `
+exit handler null SIGHUP
+afterExit handler null SIGHUP
+exit captured signal
+afterExit captured signal
+
+`
+
+exports[`test/signal-capture.ts TAP signal, capture exit > must match snapshot 1`] = `
+exit handler null SIGHUP
+afterExit handler null SIGHUP
+exit captured signal
+
+`
+
+exports[`test/signal-capture.ts TAP signal, no capture > must match snapshot 1`] = `
+exit handler null SIGHUP
+afterExit handler null SIGHUP
+
+`

test/fixtures/signal-capture.js

@@ -0,0 +1,39 @@
+const { onExit } = require('../../dist/cjs/index.js')
+
+const codeOrSignal = process.argv[2] || 'null'
+const [code, signal] = !isNaN(+codeOrSignal)
+  ? [+codeOrSignal, null]
+  : codeOrSignal.startsWith('SIG')
+  ? [null, codeOrSignal]
+  : [null, null]
+
+const capture = process.argv[3] || 'none'
+const captureExit = capture === 'captureExit' || capture === 'capture'
+const captureAfterExit =
+  capture === 'captureAfterExit' || capture === 'capture'
+
+onExit((code, signal) => {
+  console.log('exit handler', code, signal)
+  if (signal && captureExit) {
+    setTimeout(() => console.log('exit captured signal'))
+    return true
+  }
+})
+
+onExit(
+  (code, signal) => {
+    console.log('afterExit handler', code, signal)
+    if (signal && captureAfterExit) {
+      setTimeout(() => console.log('afterExit captured signal'))
+      return true
+    }
+  },
+  { alwaysLast: true }
+)
+
+if (typeof code === 'number') {
+  process.exit(code)
+} else if (typeof signal === 'string') {
+  process.kill(process.pid, signal)
+  setTimeout(() => {}, 200)
+}

test/multi-exit.js

@@ -54,7 +54,9 @@ opts.forEach(function (opt) {
         res.actualSignal = null
       }
       res.stderr = stderr.trim().split('\n')
-      t.same(res, expect[opt])
+      if (!t.same(res, expect[opt], opt)) {
+        console.error([opt, { ...(err || {})}, res, expect[opt]])
+      }
       t.end()
     })
   })

test/signal-capture.ts

@@ -0,0 +1,92 @@
+import { ChildProcessWithoutNullStreams, spawn } from 'node:child_process'
+import { resolve } from 'node:path'
+import t from 'tap'
+
+const f = resolve(__dirname, 'fixtures/signal-capture.js')
+
+const skip = process.platform === 'win32' ? 'skip on windows' : false
+
+type Result = {
+  stdout: string
+  stderr: string
+  code: null | number
+  signal: null | NodeJS.Signals
+}
+
+type PromiseWithProc<T> = Promise<T> & {
+  proc: ChildProcessWithoutNullStreams
+}
+const run = (
+  exit: number | NodeJS.Signals | 'null' = 'null',
+  capture: 'capture' | 'captureExit' | 'captureAfterExit' | 'none' = 'none'
+): PromiseWithProc<Result> => {
+  const args: string[] = [f, String(exit), capture]
+  const proc = spawn(process.execPath, args)
+  const { stdout, stderr } = proc
+  const out: Buffer[] = []
+  const err: Buffer[] = []
+  stdout.on('data', c => out.push(c))
+  stderr.on('data', c => err.push(c))
+  return Object.assign(
+    new Promise<Result>(r => {
+      proc.on('close', (code, signal) => {
+        r({
+          code,
+          signal,
+          stdout: Buffer.concat(out).toString(),
+          stderr: Buffer.concat(err).toString(),
+        })
+      })
+    }),
+    { proc }
+  )
+}
+
+t.test('graceful exit', async t => {
+  const r = await run()
+  t.match(r, { code: 0, signal: null })
+  t.equal(r.stderr, '')
+  t.matchSnapshot(r.stdout)
+})
+
+t.test('exit 0', async t => {
+  const r = await run(0)
+  t.match(r, { code: 0, signal: null })
+  t.equal(r.stderr, '')
+  t.matchSnapshot(r.stdout)
+})
+
+t.test('exit 1', async t => {
+  const r = await run(1)
+  t.match(r, { code: 1, signal: null })
+  t.equal(r.stderr, '')
+  t.matchSnapshot(r.stdout)
+})
+
+t.test('signal, no capture', { skip }, async t => {
+  const r = await run('SIGHUP')
+  t.match(r, { code: null, signal: 'SIGHUP' })
+  t.equal(r.stderr, '')
+  t.matchSnapshot(r.stdout)
+})
+
+t.test('signal, capture exit', { skip }, async t => {
+  const r = await run('SIGHUP', 'captureExit')
+  t.match(r, { code: 0, signal: null })
+  t.equal(r.stderr, '')
+  t.matchSnapshot(r.stdout)
+})
+
+t.test('signal, capture afterExit', { skip }, async t => {
+  const r = await run('SIGHUP', 'captureAfterExit')
+  t.match(r, { code: 0, signal: null })
+  t.equal(r.stderr, '')
+  t.matchSnapshot(r.stdout)
+})
+
+t.test('signal, capture both', { skip }, async t => {
+  const r = await run('SIGHUP', 'capture')
+  t.match(r, { code: 0, signal: null })
+  t.equal(r.stderr, '')
+  t.matchSnapshot(r.stdout)
+})