fix: gracefully shutdown server

- 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

fixes: vercel#53661

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

@@ -34,17 +34,20 @@ import {
 } from '../lib/helpers/get-reserved-port'
 import os from 'os'
 
+type Child = ReturnType<typeof fork>
+type ExitCode = Parameters<Child['kill']>[0]
+
 let dir: string
-let child: undefined | ReturnType<typeof fork>
+let child: undefined | Child
 let config: NextConfigComplete
 let isTurboSession = false
 let traceUploadUrl: string
 let sessionStopHandled = false
 let sessionStarted = Date.now()
 
-const handleSessionStop = async (signal: string | null) => {
+const handleSessionStop = async (signal: ExitCode | null) => {
   if (child) {
-    child.kill((signal as any) || 0)
+    child.kill(signal ?? 0)
   }
   if (sessionStopHandled) return
   sessionStopHandled = true
@@ -108,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']) {
@@ -333,16 +339,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/lib/next-test-utils.ts

@@ -523,10 +523,28 @@ export async function killProcess(
   })
 }
 
+export function isAppRunning(instance: ChildProcess) {
+  if (!instance?.pid) {
+    return false
+  }
+
+  try {
+    process.kill(instance.pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
 // Kill a launched app
 export async function killApp(instance: ChildProcess) {
   if (instance && instance.pid) {
     await killProcess(instance.pid)
+    try {
+      await waitForCondition(2000, () => !isAppRunning(instance))
+    } catch {
+      await killProcess(instance.pid, 'SIGKILL')
+    }
   }
 }
 
@@ -559,6 +577,18 @@ export function waitFor(millis: number) {
   return new Promise((resolve) => setTimeout(resolve, millis))
 }
 
+export async function waitForCondition(
+  timeout: number,
+  condition: () => boolean
+) {
+  const start = Date.now()
+  while (Date.now() - start < timeout) {
+    if (condition()) return
+    await waitFor(100)
+  }
+  throw new Error(`Timed out after ${timeout}ms`)
+}
+
 export async function startStaticServer(
   dir: string,
   notFoundFile?: string,