fix(dev): handle a rejected reusePort option and a failed cold restart

Author: danielroe

packages/nuxt-cli/src/commands/dev.ts

@@ -197,7 +197,6 @@ const command = defineCommand({
     })
 
     // On hard restart, use a fork from the pool
-    let cleanupCurrentFork: (() => Promise<void>) | undefined
     // Whatever is serving the app right now: this process, then each fork in turn.
     let closeCurrent = close
     let currentPid = process.pid
@@ -255,8 +254,9 @@ const command = defineCommand({
             : undefined,
           onMessage: (message) => {
             // Handle IPC messages from the fork
-            if (message.type === 'nuxt:internal:dev:ready') {
-              if (startTime) {
+            if (message.type === 'nuxt:internal:dev:ready' || message.type === 'nuxt:internal:dev:loading:error') {
+              serving = true
+              if (message.type === 'nuxt:internal:dev:ready' && startTime) {
                 debug(`Dev server ready for connections in ${Date.now() - startTime}ms`)
               }
             }
@@ -278,19 +278,20 @@ const command = defineCommand({
       catch (error) {
         await fork?.close()
         const detail = error instanceof Error ? error.message : String(error)
-        logger.error(handover
-          ? `Could not restart the dev server, keeping the current one: ${detail}`
-          : `Could not restart the dev server: ${detail}`)
-        if (handover) {
-          onRestart(restart)
+        if (!handover) {
+          // The outgoing server is already closed, so there is nothing left to
+          // serve the app and no watcher left to trigger another attempt.
+          logger.error(`Could not restart the dev server: ${detail}`)
+          process.exit(1)
         }
+        logger.error(`Could not restart the dev server, keeping the current one: ${detail}`)
+        onRestart(restart)
         return
       }
 
       serving = true
       fork.promote()
       const closePrevious = handover ? closeCurrent : undefined
-      cleanupCurrentFork = fork.close
       closeCurrent = fork.close
       currentPid = fork.pid ?? currentPid
       await closePrevious?.()
@@ -303,7 +304,9 @@ const command = defineCommand({
     onRestart(restart)
 
     async function closeAll() {
-      await cleanupCurrentFork?.()
+      if (closeCurrent !== close) {
+        await closeCurrent()
+      }
       await close()
     }
 

packages/nuxt-cli/src/dev/listen.ts

@@ -310,10 +310,18 @@ function bindServer(server: HttpServer, port: number, hostname: string, reusePor
       reject(error)
     }
     server.once('error', onError)
-    server.listen({ port, host: hostname || undefined, reusePort, exclusive: !reusePort }, () => {
+    try {
+      server.listen({ port, host: hostname || undefined, reusePort, exclusive: !reusePort }, () => {
+        server.removeListener('error', onError)
+        resolve()
+      })
+    }
+    catch (error) {
+      // Runtimes that do not know the option reject it before the bind, throwing
+      // rather than emitting `error`.
       server.removeListener('error', onError)
-      resolve()
-    })
+      onError(error as NodeJS.ErrnoException)
+    }
   })
 }
 
@@ -331,7 +339,9 @@ let reusePortSupport: Promise<boolean> | undefined
 /**
  * Whether two sockets can bind the same port at once via `SO_REUSEPORT`, probed
  * on an ephemeral port. A single successful bind is not enough: some platforms
- * accept the option and still reject the second socket. Cached per process.
+ * accept the option and still reject the second socket. Support is a property of
+ * the platform rather than of an address, so the loopback probe stands in for
+ * whichever hostname the dev server ends up binding. Cached per process.
  */
 export function isReusePortSupported(): Promise<boolean> {
   reusePortSupport ??= (async () => {

packages/nuxt-cli/src/dev/pool.ts

@@ -24,7 +24,10 @@ interface PooledFork {
 
 export interface ActiveFork {
   pid?: number
-  /** Resolves once the fork reports it is serving requests, rejects if it dies first. */
+  /**
+   * Resolves once the fork holds the listener, whether the app loaded or the
+   * error page is being served, and rejects if it dies before that.
+   */
   serving: Promise<void>
   /** Promote the fork so that a later crash takes the dev session down. */
   promote: () => void
@@ -119,7 +122,8 @@ export class ForkPool {
 
   /**
    * Resolves when the fork has bound its listener and is answering requests, so
-   * the caller can keep the outgoing server up until then.
+   * the caller can keep the outgoing server up until then. A load failure counts:
+   * the fork is serving an error page and owns the port either way.
    */
   private trackServing(fork: PooledFork): Promise<void> {
     return new Promise<void>((resolve, reject) => {
@@ -170,6 +174,10 @@ export class ForkPool {
     this.pool.push(fork)
   }
 
+  /**
+   * `ready` always settles, rejecting if the fork exits at any point, so every
+   * caller has to keep a rejection handler attached to it.
+   */
   private createFork(): PooledFork {
     const childProc = fork(globalThis.__nuxt_cli__.devEntry!, this.rawArgs, {
       // The inspector is opened by the fork that actually serves the app (see