fix: restore runtime close hook and implement graceful shutdown env vars

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. Available in all presets.
+- `"error", (error, { event? }) => {}` - Called when an error is captured. Available in all presets.
+- `"response", (response, event) => {}` - Called when a response is sent. Available in all presets.
+- `"close", () => {}` - Called when the server receives a shutdown signal (`SIGTERM` or `SIGINT`). Only available in long-running server presets (Node.js, Bun, Deno). Not called in serverless or edge environments.
 
 ## Examples
 
@@ -76,7 +77,32 @@ export default definePlugin((nitro) => {
 
 ### Graceful shutdown
 
-Server will gracefully shutdown and wait for any background pending tasks initiated by event.waitUntil
+On long-running server presets (`node-server`, `node-cluster`, `bun`, `deno-server`), the `close` hook fires when the process receives `SIGTERM` or `SIGINT`, allowing plugins to run async cleanup before exit.
+
+```ts
+import { definePlugin } from "nitro";
+
+export default definePlugin((nitro) => {
+  nitro.hooks.hook("close", async () => {
+    await flushTelemetry();
+    await db.close();
+  });
+})
+```
+
+Serverless and edge runtimes (Cloudflare Workers, AWS Lambda, Vercel, Netlify, Deno Deploy) do not have a shutdown signal–the platform terminates the execution context without notice. The `close` hook will not fire in these environments.
+
+For per-request cleanup that works across all presets, use the `"response"` hook or `request.waitUntil()` instead:
+
+```ts
+import { definePlugin } from "nitro";
+
+export default definePlugin((nitro) => {
+  nitro.hooks.hook("response", async (response, event) => {
+    await flushRequestTelemetry(event);
+  });
+})
+```
 
 ### Request and response lifecycle
 

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

@@ -31,12 +31,10 @@ You can customize server behavior using following environment variables:
 
 - `NITRO_PORT` or `PORT` (defaults to `3000`)
 - `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_UNIX_SOCKET` - if provided (a path to the desired socket file) the service will be served over the provided UNIX socket (Node.js and Bun only).
 - `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'`.
+- `NITRO_SHUTDOWN_TIMEOUT` - Sets the amount of time (in milliseconds) before a forced shutdown occurs. Defaults to `5000` milliseconds.
 
 ## Cluster mode
 

docs/2.deploy/10.runtimes/bun.md

@@ -17,3 +17,14 @@ bun run ./.output/server/index.mjs
 ```
 
 :read-more{to="https://bun.sh"}
+
+### Environment Variables
+
+You can customize server behavior using following environment variables:
+
+- `NITRO_PORT` or `PORT` (defaults to `3000`)
+- `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'`. Defaults to `'false'`.
+- `NITRO_SHUTDOWN_TIMEOUT` - Sets the amount of time (in milliseconds) before a forced shutdown occurs. Defaults to `5000` milliseconds.

docs/2.deploy/10.runtimes/deno.md

@@ -18,6 +18,16 @@ NITRO_PRESET=deno_server npm run build
 deno run --unstable --allow-net --allow-read --allow-env .output/server/index.ts
 ```
 
+### Environment Variables
+
+You can customize server behavior using following environment variables:
+
+- `NITRO_PORT` or `PORT` (defaults to `3000`)
+- `NITRO_HOST` or `HOST`
+- `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'`. Defaults to `'false'`.
+- `NITRO_SHUTDOWN_TIMEOUT` - Sets the amount of time (in milliseconds) before a forced shutdown occurs. Defaults to `5000` milliseconds.
+
 ## Deno Deploy
 
 :read-more{to="/deploy/providers/deno-deploy"}

src/presets/bun/runtime/bun.ts

@@ -6,14 +6,16 @@ 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 { resolveGracefulShutdownConfig, setupShutdownHooks } from "#nitro/runtime/shutdown";
 import { resolveWebsocketHooks } from "#nitro/runtime/app";
 
 const _parsedPort = Number.parseInt(process.env.NITRO_PORT ?? process.env.PORT ?? "");
 const port = Number.isNaN(_parsedPort) ? 3000 : _parsedPort;
 const host = process.env.NITRO_HOST || process.env.HOST;
 const cert = process.env.NITRO_SSL_CERT;
 const key = process.env.NITRO_SSL_KEY;
-// const socketPath = process.env.NITRO_UNIX_SOCKET; // TODO
+const socketPath = process.env.NITRO_UNIX_SOCKET;
+const gracefulShutdown = resolveGracefulShutdownConfig();
 
 const nitroApp = useNitroApp();
 
@@ -35,12 +37,15 @@ serve({
   hostname: host,
   tls: cert && key ? { cert, key } : undefined,
   fetch: _fetch,
+  gracefulShutdown,
   bun: {
+    unix: socketPath,
     websocket: import.meta._websocket ? ws?.websocket : undefined,
   },
 });
 
 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 { resolveGracefulShutdownConfig, setupShutdownHooks } from "#nitro/runtime/shutdown";
 import { resolveWebsocketHooks } from "#nitro/runtime/app";
 
 const _parsedPort = Number.parseInt(process.env.NITRO_PORT ?? process.env.PORT ?? "");
@@ -14,7 +15,7 @@ const port = Number.isNaN(_parsedPort) ? 3000 : _parsedPort;
 const host = process.env.NITRO_HOST || process.env.HOST;
 const cert = process.env.NITRO_SSL_CERT;
 const key = process.env.NITRO_SSL_KEY;
-// const socketPath = process.env.NITRO_UNIX_SOCKET; // TODO
+const gracefulShutdown = resolveGracefulShutdownConfig();
 
 const nitroApp = useNitroApp();
 
@@ -35,9 +36,11 @@ serve({
   hostname: host,
   tls: cert && key ? { cert, key } : undefined,
   fetch: _fetch,
+  gracefulShutdown,
 });
 
 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 { resolveGracefulShutdownConfig, setupShutdownHooks } from "#nitro/runtime/shutdown";
 import { resolveWebsocketHooks } from "#nitro/runtime/app";
 
 const _parsedPort = Number.parseInt(process.env.NITRO_PORT ?? process.env.PORT ?? "");
@@ -13,7 +14,8 @@ const port = Number.isNaN(_parsedPort) ? 3000 : _parsedPort;
 const host = process.env.NITRO_HOST || process.env.HOST;
 const cert = process.env.NITRO_SSL_CERT;
 const key = process.env.NITRO_SSL_KEY;
-// const socketPath = process.env.NITRO_UNIX_SOCKET; // TODO
+const socketPath = process.env.NITRO_UNIX_SOCKET;
+const gracefulShutdown = resolveGracefulShutdownConfig();
 
 const nitroApp = useNitroApp();
 
@@ -22,6 +24,8 @@ const server = serve({
   hostname: host,
   tls: cert && key ? { cert, key } : undefined,
   fetch: nitroApp.fetch,
+  gracefulShutdown,
+  node: socketPath ? { path: socketPath } : undefined,
 });
 
 if (import.meta._websocket) {
@@ -38,6 +42,7 @@ if (import.meta._websocket) {
 }
 
 trapUnhandledErrors();
+setupShutdownHooks();
 
 // Scheduled tasks
 if (import.meta._tasks) {

src/runtime/internal/shutdown.ts

@@ -0,0 +1,32 @@
+import { useNitroApp } from "../app.ts";
+import type { ServerOptions } from "srvx";
+
+export function resolveGracefulShutdownConfig(): ServerOptions["gracefulShutdown"] {
+  if (process.env.NITRO_SHUTDOWN_DISABLED === "true") {
+    return false;
+  }
+
+  const timeoutMs = Number.parseInt(process.env.NITRO_SHUTDOWN_TIMEOUT ?? "", 10);
+
+  if (timeoutMs > 0) {
+    // srvx expects timeout in seconds
+    return { gracefulTimeout: timeoutMs / 1000 };
+  }
+
+  return undefined;
+}
+
+async function _shutdownHandler() {
+  try {
+    await useNitroApp().hooks?.callHook("close");
+  } catch (error) {
+    console.error("[nitro] Error running close hook:", error);
+  }
+}
+
+export function setupShutdownHooks() {
+  if (typeof process !== "undefined" && process.on) {
+    process.on("SIGTERM", _shutdownHandler);
+    process.on("SIGINT", _shutdownHandler);
+  }
+}

test/unit/shutdown.test.ts

@@ -0,0 +1,133 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const callHook = vi.fn().mockResolvedValue(undefined);
+
+vi.mock("../../src/runtime/internal/app.ts", () => ({
+  useNitroApp: () => ({
+    hooks: { callHook },
+  }),
+}));
+
+import {
+  resolveGracefulShutdownConfig,
+  setupShutdownHooks,
+} from "../../src/runtime/internal/shutdown.ts";
+
+describe("resolveGracefulShutdownConfig", () => {
+  const env = process.env;
+
+  afterEach(() => {
+    process.env = env;
+  });
+
+  it("returns undefined by default", () => {
+    process.env = { ...env };
+    delete process.env.NITRO_SHUTDOWN_DISABLED;
+    delete process.env.NITRO_SHUTDOWN_TIMEOUT;
+    expect(resolveGracefulShutdownConfig()).toBeUndefined();
+  });
+
+  it.each([
+    { value: "true", expected: false },
+    { value: "false", expected: undefined },
+    { value: "", expected: undefined },
+    { value: "1", expected: undefined },
+    { value: "yes", expected: undefined },
+  ])("NITRO_SHUTDOWN_DISABLED=$value returns $expected", ({ value, expected }) => {
+    process.env = { ...env, NITRO_SHUTDOWN_DISABLED: value };
+    delete process.env.NITRO_SHUTDOWN_TIMEOUT;
+    expect(resolveGracefulShutdownConfig()).toBe(expected);
+  });
+
+  it("returns gracefulTimeout in seconds from NITRO_SHUTDOWN_TIMEOUT ms", () => {
+    process.env = { ...env, NITRO_SHUTDOWN_TIMEOUT: "10000" };
+    delete process.env.NITRO_SHUTDOWN_DISABLED;
+    expect(resolveGracefulShutdownConfig()).toEqual({ gracefulTimeout: 10 });
+  });
+
+  it("disabled takes priority over timeout", () => {
+    process.env = {
+      ...env,
+      NITRO_SHUTDOWN_DISABLED: "true",
+      NITRO_SHUTDOWN_TIMEOUT: "10000",
+    };
+    expect(resolveGracefulShutdownConfig()).toBe(false);
+  });
+
+  it("ignores non-numeric timeout", () => {
+    process.env = { ...env, NITRO_SHUTDOWN_TIMEOUT: "abc" };
+    delete process.env.NITRO_SHUTDOWN_DISABLED;
+    expect(resolveGracefulShutdownConfig()).toBeUndefined();
+  });
+});
+
+describe("setupShutdownHooks", () => {
+  let savedSIGTERM: Function[];
+  let savedSIGINT: Function[];
+
+  beforeEach(() => {
+    savedSIGTERM = process.listeners("SIGTERM").slice();
+    savedSIGINT = process.listeners("SIGINT").slice();
+    callHook.mockClear();
+    callHook.mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    process.removeAllListeners("SIGTERM");
+    process.removeAllListeners("SIGINT");
+    for (const fn of savedSIGTERM) process.on("SIGTERM", fn as () => void);
+    for (const fn of savedSIGINT) process.on("SIGINT", fn as () => void);
+  });
+
+  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", async () => {
+    setupShutdownHooks();
+    process.emit("SIGTERM", "SIGTERM");
+    await vi.waitFor(() => {
+      expect(callHook).toHaveBeenCalledWith("close");
+    });
+  });
+
+  it("calls close hook on SIGINT", async () => {
+    setupShutdownHooks();
+    process.emit("SIGINT", "SIGINT");
+    await vi.waitFor(() => {
+      expect(callHook).toHaveBeenCalledWith("close");
+    });
+  });
+
+  it("awaits the close hook promise", async () => {
+    let resolved = false;
+    callHook.mockImplementation(
+      () =>
+        new Promise<void>((r) => {
+          setTimeout(() => {
+            resolved = true;
+            r();
+          }, 50);
+        })
+    );
+    setupShutdownHooks();
+    process.emit("SIGTERM", "SIGTERM");
+    await vi.waitFor(() => expect(resolved).toBe(true));
+  });
+
+  it("logs error if close hook throws", async () => {
+    const error = new Error("cleanup failed");
+    callHook.mockRejectedValueOnce(error);
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    setupShutdownHooks();
+    process.emit("SIGTERM", "SIGTERM");
+    await vi.waitFor(() => {
+      expect(consoleSpy).toHaveBeenCalledWith("[nitro] Error running close hook:", error);
+    });
+    consoleSpy.mockRestore();
+  });
+});