fix(shutdown): exit non-zero on crash-initiated shutdown

uncaughtException/unhandledRejection routed through shutdown(), whose
happy path always exited 0. A crash that drained cleanly therefore
exited 0, which Kubernetes and systemd read as a clean stop — suppressing
OnFailure restarts and non-zero-exit alerting, and reducing crash signal
below Node's own default of 1.

shutdown() now takes an exitCode used on the success path; signals keep 0
and the crash handlers pass 1. Also drop idle keep-alive sockets when
draining: server.close() waits on them, so browser clients holding
connections open could push the drain past SHUTDOWN_TIMEOUT_MS and skip
the trace flush and pool close entirely.

Addresses review feedback on #188.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dkijania

src/index.ts

@@ -24,6 +24,10 @@ const SHUTDOWN_TIMEOUT_MS = Number(process.env.SHUTDOWN_TIMEOUT_MS) || 10000;
       closeServer: () =>
         new Promise<void>((resolve, reject) => {
           server.close((error) => (error ? reject(error) : resolve()));
+          // `close` also waits on idle keep-alive sockets, which browser
+          // clients hold open for keepAliveTimeout; dropping them keeps the
+          // drain prompt so the closers below still run inside the timeout.
+          server.closeIdleConnections();
         }),
       closers: [
         // Flush any buffered OpenTelemetry spans before exit.
@@ -39,13 +43,15 @@ const SHUTDOWN_TIMEOUT_MS = Number(process.env.SHUTDOWN_TIMEOUT_MS) || 10000;
       process.on(signal, () => void shutdown(signal));
     });
 
+    // Crashes exit non-zero: an exit 0 reads as a clean stop to Kubernetes and
+    // systemd, suppressing restarts and non-zero-exit alerting.
     process.on('uncaughtException', (error) => {
       console.error('Uncaught exception:', error);
-      void shutdown('uncaughtException');
+      void shutdown('uncaughtException', 1);
     });
     process.on('unhandledRejection', (reason) => {
       console.error('Unhandled rejection:', reason);
-      void shutdown('unhandledRejection');
+      void shutdown('unhandledRejection', 1);
     });
   } catch (error) {
     console.error('An error occurred:', error);

src/server/graceful-shutdown.ts

@@ -17,8 +17,9 @@ interface GracefulShutdownOptions {
 /**
  * Build an idempotent shutdown handler. On the first invocation it drains the
  * server, runs each closer (a failing closer is logged but doesn't abort the
- * rest), then exits 0. A hard timeout guarantees the process exits even if a
- * connection or teardown step hangs, and `onExit` is invoked at most once.
+ * rest), then exits with the caller's code. A hard timeout guarantees the
+ * process exits even if a connection or teardown step hangs, and `onExit` is
+ * invoked at most once.
  *
  * Subsequent invocations (e.g. a second signal) are ignored.
  */
@@ -34,7 +35,11 @@ function createGracefulShutdown(options: GracefulShutdownOptions) {
 
   let started = false;
 
-  return async function shutdown(reason: string): Promise<void> {
+  /**
+   * `exitCode` is the code used when the drain succeeds; a crash-initiated
+   * shutdown must pass non-zero so supervisors still see a failed exit.
+   */
+  return async function shutdown(reason: string, exitCode = 0): Promise<void> {
     if (started) return;
     started = true;
     log(`Shutting down (${reason})…`);
@@ -61,7 +66,7 @@ function createGracefulShutdown(options: GracefulShutdownOptions) {
           log('Error during shutdown step', error);
         }
       }
-      exitOnce(0);
+      exitOnce(exitCode);
     } catch (error) {
       log('Error closing server', error);
       exitOnce(1);

tests/unit/graceful-shutdown.test.ts

@@ -71,6 +71,29 @@ describe('Graceful shutdown', () => {
     assert.deepStrictEqual(exits, [0]);
   });
 
+  test('a crash-initiated shutdown drains cleanly but still exits non-zero', async () => {
+    const calls: string[] = [];
+    const exits: number[] = [];
+    const shutdown = createGracefulShutdown({
+      closeServer: async () => {
+        calls.push('server');
+      },
+      closers: [
+        async () => {
+          calls.push('traces');
+        },
+      ],
+      timeoutMs: 1000,
+      onExit: (code) => exits.push(code),
+      log: silent,
+    });
+
+    await shutdown('uncaughtException', 1);
+    // The drain still runs in full — only the exit code differs from a signal.
+    assert.deepStrictEqual(calls, ['server', 'traces']);
+    assert.deepStrictEqual(exits, [1]);
+  });
+
   test('exits 1 when draining exceeds the timeout, and only once', async () => {
     const exits: number[] = [];
     const shutdown = createGracefulShutdown({