fix: call runtime close hook on shutdown signals

Bridge SIGTERM/SIGINT to `nitroApp.hooks.callHook("close")` so plugins
can run async cleanup (flush telemetry, drain connections, stop queues)
when the server shuts down.

The close hook stopped firing after the srvx migration in #3705 removed
the old `setupGracefulShutdown` machinery. srvx handles HTTP-level
shutdown (connection draining) but never calls Nitro's application-level
close hook.

Adds `setupShutdownHooks()` utility following the same pattern as
`trapUnhandledErrors()` and wires it into node-server, node-cluster,
bun, and deno-server runtime entries.

Resolves #4015
Resolves #2735
Resolves #2566

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: wadefletch

docs/1.docs/50.plugins.md

@@ -54,9 +54,10 @@ export default definePlugin((nitro) => {
 
 ### Available hooks
 
-- `"request", (event) => {}`
-- `"error", (error, { event? }) => {}`
-- `"response", (event, { body }) => {}`
+- `"request", (event) => {}` - Called when a request is received.
+- `"error", (error, { event? }) => {}` - Called when an error is captured.
+- `"response", (response, event) => {}` - Called when a response is sent.
+- `"close", () => {}` - Called when the server receives a shutdown signal (`SIGTERM` or `SIGINT`).
 
 ## Examples
 
@@ -76,7 +77,18 @@ export default definePlugin((nitro) => {
 
 ### Graceful shutdown
 
-Server will gracefully shutdown and wait for any background pending tasks initiated by event.waitUntil
+When the server receives a shutdown signal (`SIGTERM` or `SIGINT`), the `close` hook is called, allowing plugins to run async cleanup before the process exits. This is useful for flushing telemetry, draining database connections, stopping job queues, and other teardown tasks.
+
+```ts
+import { definePlugin } from "nitro";
+
+export default definePlugin((nitro) => {
+  nitro.hooks.hook("close", async () => {
+    await flushTelemetry();
+    await db.close();
+  });
+})
+```
 
 ### Request and response lifecycle
 

docs/2.deploy/10.runtimes/1.node.md

@@ -33,10 +33,7 @@ You can customize server behavior using following environment variables:
 - `NITRO_HOST` or `HOST`
 - `NITRO_UNIX_SOCKET` - if provided (a path to the desired socket file) the service will be served over the provided UNIX socket.
 - `NITRO_SSL_CERT` and `NITRO_SSL_KEY` - if both are present, this will launch the server in HTTPS mode. In the vast majority of cases, this should not be used other than for testing, and the Nitro server should be run behind a reverse proxy like nginx or Cloudflare which terminates SSL.
-- `NITRO_SHUTDOWN_DISABLED` - Disables the graceful shutdown feature when set to `'true'`. If it's set to `'true'`, the graceful shutdown is bypassed to speed up the development process. Defaults to `'false'`.
-- `NITRO_SHUTDOWN_SIGNALS` - Allows you to specify which signals should be handled. Each signal should be separated with a space. Defaults to `'SIGINT SIGTERM'`.
-- `NITRO_SHUTDOWN_TIMEOUT` - Sets the amount of time (in milliseconds) before a forced shutdown occurs. Defaults to `'30000'` milliseconds.
-- `NITRO_SHUTDOWN_FORCE` - When set to true, it triggers `process.exit()` at the end of the shutdown process. If it's set to `'false'`, the process will simply let the event loop clear. Defaults to `'true'`.
+- `NITRO_SHUTDOWN_DISABLED` - Disables the graceful shutdown feature when set to `'true'`. Defaults to `'false'`.
 
 ## Cluster mode
 

src/presets/bun/runtime/bun.ts

@@ -6,6 +6,7 @@ import wsAdapter from "crossws/adapters/bun";
 import { useNitroApp } from "nitro/app";
 import { startScheduleRunner } from "#nitro/runtime/task";
 import { trapUnhandledErrors } from "#nitro/runtime/error/hooks";
+import { setupShutdownHooks } from "#nitro/runtime/shutdown";
 import { resolveWebsocketHooks } from "#nitro/runtime/app";
 
 const _parsedPort = Number.parseInt(process.env.NITRO_PORT ?? process.env.PORT ?? "");
@@ -41,6 +42,7 @@ serve({
 });
 
 trapUnhandledErrors();
+setupShutdownHooks();
 
 // Scheduled tasks
 if (import.meta._tasks) {

src/presets/deno/runtime/deno-server.ts

@@ -6,6 +6,7 @@ import wsAdapter from "crossws/adapters/deno";
 import { useNitroApp } from "nitro/app";
 import { startScheduleRunner } from "#nitro/runtime/task";
 import { trapUnhandledErrors } from "#nitro/runtime/error/hooks";
+import { setupShutdownHooks } from "#nitro/runtime/shutdown";
 import { resolveWebsocketHooks } from "#nitro/runtime/app";
 
 const _parsedPort = Number.parseInt(process.env.NITRO_PORT ?? process.env.PORT ?? "");
@@ -38,6 +39,7 @@ serve({
 });
 
 trapUnhandledErrors();
+setupShutdownHooks();
 
 // Scheduled tasks
 if (import.meta._tasks) {

src/presets/node/runtime/node-cluster.ts

@@ -6,6 +6,7 @@ import wsAdapter from "crossws/adapters/node";
 import { useNitroApp } from "nitro/app";
 import { startScheduleRunner } from "#nitro/runtime/task";
 import { trapUnhandledErrors } from "#nitro/runtime/error/hooks";
+import { setupShutdownHooks } from "#nitro/runtime/shutdown";
 import { resolveWebsocketHooks } from "#nitro/runtime/app";
 
 const _parsedPort = Number.parseInt(process.env.NITRO_PORT ?? process.env.PORT ?? "");
@@ -46,6 +47,7 @@ if (import.meta._websocket) {
 }
 
 trapUnhandledErrors();
+setupShutdownHooks();
 
 // Scheduled tasks
 if (import.meta._tasks) {

src/presets/node/runtime/node-server.ts

@@ -5,6 +5,7 @@ import wsAdapter from "crossws/adapters/node";
 import { useNitroApp } from "nitro/app";
 import { startScheduleRunner } from "#nitro/runtime/task";
 import { trapUnhandledErrors } from "#nitro/runtime/error/hooks";
+import { setupShutdownHooks } from "#nitro/runtime/shutdown";
 import { resolveWebsocketHooks } from "#nitro/runtime/app";
 
 const _parsedPort = Number.parseInt(process.env.NITRO_PORT ?? process.env.PORT ?? "");
@@ -38,6 +39,7 @@ if (import.meta._websocket) {
 }
 
 trapUnhandledErrors();
+setupShutdownHooks();
 
 // Scheduled tasks
 if (import.meta._tasks) {

src/runtime/internal/shutdown.ts

@@ -0,0 +1,10 @@
+import { useNitroApp } from "../app.ts";
+
+export function setupShutdownHooks() {
+  const handler = () => {
+    useNitroApp().hooks?.callHook("close");
+  };
+  for (const sig of ["SIGTERM", "SIGINT"] as const) {
+    process.on(sig, handler);
+  }
+}

test/unit/shutdown.test.ts

@@ -0,0 +1,49 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const callHook = vi.fn();
+
+vi.mock("../../src/runtime/internal/app.ts", () => ({
+  useNitroApp: () => ({
+    hooks: { callHook },
+  }),
+}));
+
+import { setupShutdownHooks } from "../../src/runtime/internal/shutdown.ts";
+
+describe("setupShutdownHooks", () => {
+  let savedSIGTERM: Function[];
+  let savedSIGINT: Function[];
+
+  beforeEach(() => {
+    savedSIGTERM = process.listeners("SIGTERM").slice();
+    savedSIGINT = process.listeners("SIGINT").slice();
+    callHook.mockClear();
+  });
+
+  afterEach(() => {
+    process.removeAllListeners("SIGTERM");
+    process.removeAllListeners("SIGINT");
+    for (const fn of savedSIGTERM) process.on("SIGTERM", fn as NodeJS.SignalsListener);
+    for (const fn of savedSIGINT) process.on("SIGINT", fn as NodeJS.SignalsListener);
+  });
+
+  it("registers SIGTERM and SIGINT handlers", () => {
+    const beforeTERM = process.listenerCount("SIGTERM");
+    const beforeINT = process.listenerCount("SIGINT");
+    setupShutdownHooks();
+    expect(process.listenerCount("SIGTERM")).toBe(beforeTERM + 1);
+    expect(process.listenerCount("SIGINT")).toBe(beforeINT + 1);
+  });
+
+  it("calls close hook on SIGTERM", () => {
+    setupShutdownHooks();
+    process.emit("SIGTERM", "SIGTERM");
+    expect(callHook).toHaveBeenCalledWith("close");
+  });
+
+  it("calls close hook on SIGINT", () => {
+    setupShutdownHooks();
+    process.emit("SIGINT", "SIGINT");
+    expect(callHook).toHaveBeenCalledWith("close");
+  });
+});