fix(node): handle EADDRINUSE port conflict on serve (#197)

Co-authored-by: Pooya Parsa <pooya@pi0.io>

Author: nekomeowww

src/adapters/node.ts

@@ -52,6 +52,7 @@ class NodeServer implements Server {
   readonly #isSecure?: boolean;
 
   #listeningPromise?: Promise<void>;
+  #listenError?: Error;
 
   #wait?: ReturnType<typeof createWaitUntil>;
 
@@ -120,20 +121,41 @@ class NodeServer implements Server {
     this.node.server = server;
 
     if (!options.manual) {
-      this.serve();
+      this.serve().catch(() => {});
     }
   }
 
-  serve() {
+  serve(): Promise<this> {
     if (this.#listeningPromise) {
-      return Promise.resolve(this.#listeningPromise).then(() => this);
+      return this.#listeningPromise.then(() => this);
     }
-    this.#listeningPromise = new Promise<void>((resolve) => {
-      this.node!.server!.listen(this.serveOptions, () => {
+
+    const server = this.node?.server;
+    if (!server) {
+      return Promise.reject(new Error("Server not initialized"));
+    }
+
+    this.#listenError = undefined;
+    this.#listeningPromise = new Promise<void>((resolve, reject) => {
+      const onError = (error: Error) => {
+        server.off("listening", onListening);
+        this.#listenError = error;
+        this.#listeningPromise = undefined;
+        reject(error);
+      };
+
+      const onListening = () => {
+        server.off("error", onError);
         printListening(this.options, this.url);
         resolve();
-      });
+      };
+
+      server.once("error", onError);
+      server.once("listening", onListening);
+      server.listen(this.serveOptions);
     });
+
+    return this.#listeningPromise.then(() => this);
   }
 
   get url() {
@@ -148,6 +170,9 @@ class NodeServer implements Server {
   }
 
   ready(): Promise<Server> {
+    if (this.#listenError) {
+      return Promise.reject(this.#listenError);
+    }
     return Promise.resolve(this.#listeningPromise).then(() => this);
   }
 

test/node-adapters.test.ts

@@ -1,3 +1,5 @@
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
 import { describe, expect, test } from "vitest";
 
 import type { NodeHttp1Handler, NodeServerRequest, NodeServerResponse } from "../src/types.ts";
@@ -257,3 +259,45 @@ describe("request signal", () => {
     await server.close(true); // Force close all connections
   });
 });
+
+describe("node server startup", () => {
+  async function withBlockedPort(fn: (port: number) => Promise<void>) {
+    const blocker = createServer((_req, res) => res.end("blocked"));
+    await new Promise<void>((resolve, reject) => {
+      blocker.once("error", reject);
+      blocker.once("listening", () => resolve());
+      blocker.listen(0, "127.0.0.1");
+    });
+    const { port } = blocker.address() as AddressInfo;
+    try {
+      await fn(port);
+    } finally {
+      await new Promise<void>((resolve) => blocker.close(() => resolve()));
+    }
+  }
+
+  test("port conflict rejects with EADDRINUSE", async () => {
+    await withBlockedPort(async (port) => {
+      const server = serve({
+        port,
+        hostname: "127.0.0.1",
+        manual: true,
+        fetch: () => new Response(""),
+      });
+      await expect(server.serve()).rejects.toMatchObject({ code: "EADDRINUSE" });
+      await server.close();
+    });
+  });
+
+  test("auto-serve port conflict surfaces via ready()", async () => {
+    await withBlockedPort(async (port) => {
+      const server = serve({
+        port,
+        hostname: "127.0.0.1",
+        fetch: () => new Response(""),
+      });
+      await expect(server.ready()).rejects.toMatchObject({ code: "EADDRINUSE" });
+      await server.close();
+    });
+  });
+});