graceful shutdown (#60059)

- Both the standalone server and the `startServer` function it calls
attempt to stop the server on `SIGINT` and `SIGTERM` in different ways.
This lets `server.js` yield to `startServer`
- The cleanup function in `startServer` was not waiting for the server
to close before calling `process.exit`. This lets it wait for any
in-flight requests to finish processing before exiting the process
- Sends `SIGKILL` to the child process in `next dev`, which should have
the same effect of immediately shutting down the server on `SIGTERM` or
`SIGINT`

fixes: #53661
refs: #59551

------

Previously #59551 attempted to fix #53661, but had broken some tests in
the process. It looks like the final commit was also missing an intended
change to `utils.ts`. This should fix those issues as well as introduce
a new set of tests for the graceful shutdown feature.

In the last PR I was squashing and force-pushing updates along the way
but it made it difficult to track the changes. This time I'm pushing
quite a few commits to make it easier to track the changes and refactors
I've made, with the idea that this should be squashed before being
merged.

<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:

## For Contributors

### Improving Documentation

- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR.
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide

### Adding or Updating Examples

- The "examples guidelines" are followed from our contributing doc
https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md
- Make sure the linting passes by running `pnpm build && pnpm lint`. See
https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md

### Fixing a bug

- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md

### Adding a feature

- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md


## For Maintainers

- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change

### What?

### Why?

### How?

Closes NEXT-
Fixes #

-->

packages/next/src/bin/next.ts

@@ -108,12 +108,11 @@ if (process.env.NODE_ENV) {
 ;(process.env as any).NODE_ENV = process.env.NODE_ENV || defaultEnv
 ;(process.env as any).NEXT_RUNTIME = 'nodejs'
 
-// Make sure commands gracefully respect termination signals (e.g. from Docker)
-// Allow the graceful termination to be manually configurable
-if (!process.env.NEXT_MANUAL_SIG_HANDLE && command !== 'dev') {
+if (command === 'build') {
   process.on('SIGTERM', () => process.exit(0))
   process.on('SIGINT', () => process.exit(0))
 }
+
 async function main() {
   const currentArgsSpec = commandArgs[command]()
   const validatedArgs = getValidatedArgs(currentArgsSpec, forwardedArgs)

packages/next/src/build/utils.ts

@@ -2072,13 +2072,6 @@ const dir = path.join(__dirname)
 process.env.NODE_ENV = 'production'
 process.chdir(__dirname)
 
-// Make sure commands gracefully respect termination signals (e.g. from Docker)
-// Allow the graceful termination to be manually configurable
-if (!process.env.NEXT_MANUAL_SIG_HANDLE) {
-  process.on('SIGTERM', () => process.exit(0))
-  process.on('SIGINT', () => process.exit(0))
-}
-
 const currentPort = parseInt(process.env.PORT, 10) || 3000
 const hostname = process.env.HOSTNAME || '0.0.0.0'
 

packages/next/src/cli/next-dev.ts

@@ -28,27 +28,31 @@ import type { SelfSignedCertificate } from '../lib/mkcert'
 import uploadTrace from '../trace/upload-trace'
 import { initialEnv } from '@next/env'
 import { fork } from 'child_process'
+import type { ChildProcess } from 'child_process'
 import {
   getReservedPortExplanation,
   isPortIsReserved,
 } from '../lib/helpers/get-reserved-port'
 import os from 'os'
+import { once } from 'node:events'
 
 let dir: string
-let child: undefined | ReturnType<typeof fork>
+let child: undefined | ChildProcess
 let config: NextConfigComplete
 let isTurboSession = false
 let traceUploadUrl: string
 let sessionStopHandled = false
 let sessionStarted = Date.now()
 
-const handleSessionStop = async (signal: string | null) => {
-  if (child) {
-    child.kill((signal as any) || 0)
-  }
+const handleSessionStop = async (signal: NodeJS.Signals | number | null) => {
+  if (child?.pid) child.kill(signal ?? 0)
   if (sessionStopHandled) return
   sessionStopHandled = true
 
+  if (child?.pid && child.exitCode === null && child.signalCode === null) {
+    await once(child, 'exit').catch(() => {})
+  }
+
   try {
     const { eventCliSessionStopped } =
       require('../telemetry/events/session-stopped') as typeof import('../telemetry/events/session-stopped')
@@ -107,8 +111,11 @@ const handleSessionStop = async (signal: string | null) => {
   process.exit(0)
 }
 
-process.on('SIGINT', () => handleSessionStop('SIGINT'))
-process.on('SIGTERM', () => handleSessionStop('SIGTERM'))
+process.on('SIGINT', () => handleSessionStop('SIGKILL'))
+process.on('SIGTERM', () => handleSessionStop('SIGKILL'))
+
+// exit event must be synchronous
+process.on('exit', () => child?.kill('SIGKILL'))
 
 const nextDev: CliCommand = async (args) => {
   if (args['--help']) {
@@ -335,16 +342,4 @@ const nextDev: CliCommand = async (args) => {
   await runDevServer(false)
 }
 
-function cleanup() {
-  if (!child) {
-    return
-  }
-
-  child.kill('SIGTERM')
-}
-
-process.on('exit', cleanup)
-process.on('SIGINT', cleanup)
-process.on('SIGTERM', cleanup)
-
 export { nextDev }

packages/next/src/server/lib/start-server.ts

@@ -264,10 +264,9 @@ export async function startServer(
       })
 
       try {
-        const cleanup = (code: number | null) => {
+        const cleanup = () => {
           debug('start-server process cleanup')
-          server.close()
-          process.exit(code ?? 0)
+          server.close(() => process.exit(0))
         }
         const exception = (err: Error) => {
           if (isPostpone(err)) {
@@ -279,11 +278,11 @@ export async function startServer(
           // This is the render worker, we keep the process alive
           console.error(err)
         }
-        process.on('exit', (code) => cleanup(code))
+        // Make sure commands gracefully respect termination signals (e.g. from Docker)
+        // Allow the graceful termination to be manually configurable
         if (!process.env.NEXT_MANUAL_SIG_HANDLE) {
-          // callback value is signal string, exit with 0
-          process.on('SIGINT', () => cleanup(0))
-          process.on('SIGTERM', () => cleanup(0))
+          process.on('SIGINT', cleanup)
+          process.on('SIGTERM', cleanup)
         }
         process.on('rejectionHandled', () => {
           // It is ok to await a Promise late in Next.js as it allows for better

test/integration/telemetry/test/page-features.test.js

@@ -100,7 +100,7 @@ describe('page features telemetry', () => {
         await renderViaHTTP(port, '/hello')
 
         if (app) {
-          await killApp(app)
+          await killApp(app, 'SIGTERM')
         }
         await check(() => stderr, /NEXT_CLI_SESSION_STOPPED/)
 
@@ -141,7 +141,7 @@ describe('page features telemetry', () => {
         await renderViaHTTP(port, '/hello')
 
         if (app) {
-          await killApp(app)
+          await killApp(app, 'SIGTERM')
         }
 
         await check(() => stderr, /NEXT_CLI_SESSION_STOPPED/)

test/lib/next-modes/base.ts

@@ -10,6 +10,7 @@ import { Span } from 'next/src/trace'
 import webdriver from '../next-webdriver'
 import { renderViaHTTP, fetchViaHTTP, waitFor } from 'next-test-utils'
 import cheerio from 'cheerio'
+import { once } from 'events'
 import { BrowserInterface } from '../browsers/base'
 import escapeStringRegexp from 'escape-string-regexp'
 
@@ -59,7 +60,7 @@ export class NextInstance {
   public testDir: string
   protected isStopping: boolean = false
   protected isDestroyed: boolean = false
-  protected childProcess: ChildProcess
+  protected childProcess?: ChildProcess
   protected _url: string
   protected _parsedUrl: URL
   protected packageJson?: PackageJson = {}
@@ -331,13 +332,7 @@ export class NextInstance {
   public async stop(): Promise<void> {
     this.isStopping = true
     if (this.childProcess) {
-      let exitResolve
-      const exitPromise = new Promise((resolve) => {
-        exitResolve = resolve
-      })
-      this.childProcess.addListener('exit', () => {
-        exitResolve()
-      })
+      const exitPromise = once(this.childProcess, 'exit')
       await new Promise<void>((resolve) => {
         treeKill(this.childProcess.pid, 'SIGKILL', (err) => {
           if (err) {

test/lib/next-test-utils.ts

@@ -17,6 +17,7 @@ import { getRandomPort } from 'get-port-please'
 import fetch from 'node-fetch'
 import qs from 'querystring'
 import treeKill from 'tree-kill'
+import { once } from 'events'
 
 import server from 'next/dist/server/next'
 import _pkg from 'next/package.json'
@@ -497,7 +498,7 @@ export function buildTS(
 
 export async function killProcess(
   pid: number,
-  signal: string | number = 'SIGTERM'
+  signal: NodeJS.Signals | number = 'SIGTERM'
 ): Promise<void> {
   return await new Promise((resolve, reject) => {
     treeKill(pid, signal, (err) => {
@@ -524,9 +525,18 @@ export async function killProcess(
 }
 
 // Kill a launched app
-export async function killApp(instance: ChildProcess) {
-  if (instance && instance.pid) {
-    await killProcess(instance.pid)
+export async function killApp(
+  instance?: ChildProcess,
+  signal: NodeJS.Signals | number = 'SIGKILL'
+) {
+  if (
+    instance?.pid &&
+    instance.exitCode === null &&
+    instance.signalCode === null
+  ) {
+    const exitPromise = once(instance, 'exit')
+    await killProcess(instance.pid, signal)
+    await exitPromise
   }
 }