Support IPv6 local preview servers

- Probe listeners on the loopback address they actually bind to
- Preserve detected server metadata while refreshing preview state
- Cover IPv6 parsing and HTTP probing with tests

Author: badcuban

apps/desktop/src/preview/LocalServers.ts

@@ -43,9 +43,16 @@ export const make = Effect.gen(function* LocalServersMake() {
         const probe =
           cached !== undefined && now - cached.at < PROBE_CACHE_MS
             ? cached.result
-            : await probeHttpServer(entry.port);
+            : await probeHttpServer(entry.port, entry.probeHost);
         probeCache.set(key, { at: now, result: probe });
-        return probe === null ? null : { ...entry, title: probe.title };
+        return probe === null
+          ? null
+          : {
+              port: entry.port,
+              processName: entry.processName,
+              pid: entry.pid,
+              title: probe.title,
+            };
       }),
     );
     for (const [key, value] of probeCache) {

apps/desktop/src/preview/parseListeningPorts.test.ts

@@ -8,15 +8,27 @@ describe("parseListeningPorts", () => {
 
     // Sorted by port, so the lowest listener is first regardless of lsof order.
     expect(parseListeningPorts(output)).toEqual([
-      { port: 5173, processName: "node", pid: 123 },
-      { port: 8000, processName: "Python", pid: 456 },
+      { port: 5173, processName: "node", pid: 123, probeHost: "127.0.0.1" },
+      { port: 8000, processName: "Python", pid: 456, probeHost: "127.0.0.1" },
     ]);
   });
 
-  it("collapses a port listed once per address family", () => {
-    const output = ["p1", "cnode", "n*:3000", "n[::1]:3000"].join("\n");
+  it("collapses a port listed once per address family, preferring IPv4", () => {
+    const output = ["p1", "cnode", "n[::1]:3000", "n*:3000"].join("\n");
 
-    expect(parseListeningPorts(output)).toEqual([{ port: 3000, processName: "node", pid: 1 }]);
+    expect(parseListeningPorts(output)).toEqual([
+      { port: 3000, processName: "node", pid: 1, probeHost: "127.0.0.1" },
+    ]);
+  });
+
+  it("keeps the IPv6 loopback for a listener bound only to ::1", () => {
+    // Node resolving "localhost" to ::1 produces exactly this: a dev server
+    // that refuses 127.0.0.1 but serves [::1] fine.
+    const output = ["p1", "cnode", "n[::1]:4321"].join("\n");
+
+    expect(parseListeningPorts(output)).toEqual([
+      { port: 4321, processName: "node", pid: 1, probeHost: "::1" },
+    ]);
   });
 
   it("ignores addresses this machine's browser cannot reach", () => {
@@ -35,8 +47,8 @@ describe("parseListeningPorts", () => {
     const output = ["p1", "cnode", "n*:3000", "p2", "n*:4000"].join("\n");
 
     expect(parseListeningPorts(output)).toEqual([
-      { port: 3000, processName: "node", pid: 1 },
-      { port: 4000, processName: "", pid: 2 },
+      { port: 3000, processName: "node", pid: 1, probeHost: "127.0.0.1" },
+      { port: 4000, processName: "", pid: 2, probeHost: "127.0.0.1" },
     ]);
   });
 });

apps/desktop/src/preview/parseListeningPorts.ts

@@ -12,21 +12,32 @@ export interface ListeningPort {
   port: number;
   processName: string;
   pid: number;
+  /**
+   * The loopback address the listener actually accepts connections on. A
+   * server bound only to ::1 (Node resolves "localhost" that way on some
+   * machines) refuses 127.0.0.1, so probing the wrong family reports a live
+   * server as absent.
+   */
+  probeHost: "127.0.0.1" | "::1";
 }
 
-/** Addresses that a browser on this machine can actually reach. */
-function isLocallyReachable(address: string): boolean {
+/** Maps a bound address to the loopback it is reachable at, or null for none. */
+function loopbackProbeHost(address: string): "127.0.0.1" | "::1" | null {
   const host = address.slice(0, address.lastIndexOf(":"));
-  return (
-    host === "*" ||
-    host === "" ||
-    host === "127.0.0.1" ||
-    host === "localhost" ||
-    host === "[::1]" ||
-    host === "::1" ||
-    host === "0.0.0.0" ||
-    host === "[::]"
-  );
+  switch (host) {
+    case "*":
+    case "":
+    case "0.0.0.0":
+    case "127.0.0.1":
+    case "localhost":
+      return "127.0.0.1";
+    case "[::1]":
+    case "::1":
+    case "[::]":
+      return "::1";
+    default:
+      return null;
+  }
 }
 
 export function parseListeningPorts(lsofOutput: string): ListeningPort[] {
@@ -54,16 +65,21 @@ export function parseListeningPorts(lsofOutput: string): ListeningPort[] {
     }
     // IPv6 arrives bracketed, and lsof writes "->" for established
     // connections; a listener has no peer.
-    if (value.includes("->") || !isLocallyReachable(value)) {
+    const probeHost = value.includes("->") ? null : loopbackProbeHost(value);
+    if (probeHost === null) {
       continue;
     }
     const port = Number.parseInt(value.slice(value.lastIndexOf(":") + 1), 10);
     if (Number.isNaN(port) || port <= 0) {
       continue;
     }
-    // The same port often appears twice, once per address family. One entry.
-    if (!byPort.has(port)) {
-      byPort.set(port, { port, processName, pid });
+    // The same port often appears twice, once per address family: one entry,
+    // probed over IPv4 when either family accepts it.
+    const existing = byPort.get(port);
+    if (existing === undefined) {
+      byPort.set(port, { port, processName, pid, probeHost });
+    } else if (probeHost === "127.0.0.1") {
+      existing.probeHost = probeHost;
     }
   }
 

apps/desktop/src/preview/probeHttpServer.test.ts

@@ -1,6 +1,7 @@
+import { createServer } from "node:http";
 import { describe, expect, it } from "vite-plus/test";
 
-import { extractHtmlTitle, isHtmlContentType } from "./probeHttpServer.ts";
+import { extractHtmlTitle, isHtmlContentType, probeHttpServer } from "./probeHttpServer.ts";
 
 describe("extractHtmlTitle", () => {
   it("reads a title across attributes and newlines", () => {
@@ -15,6 +16,28 @@ describe("extractHtmlTitle", () => {
   });
 });
 
+describe("probeHttpServer", () => {
+  it("reaches a server bound only to the IPv6 loopback", async () => {
+    // Node resolving "localhost" to ::1 leaves dev servers refusing 127.0.0.1;
+    // the probe must connect to the address the listener is actually on.
+    const server = createServer((_request, response) => {
+      response.writeHead(200, { "content-type": "text/html" });
+      response.end("<html><head><title>Dev App</title></head></html>");
+    });
+    await new Promise<void>((resolve) => server.listen(0, "::1", resolve));
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+      throw new Error("server did not report a port");
+    }
+
+    try {
+      expect(await probeHttpServer(address.port, "::1")).toEqual({ title: "Dev App" });
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+});
+
 describe("isHtmlContentType", () => {
   it("accepts html with a charset", () => {
     expect(isHtmlContentType("text/html; charset=utf-8")).toBe(true);

apps/desktop/src/preview/probeHttpServer.ts

@@ -40,9 +40,15 @@ export interface HttpProbeResult {
   title: string | null;
 }
 
-/** Resolves null for anything that is not an HTML-serving HTTP endpoint. */
+/**
+ * Resolves null for anything that is not an HTML-serving HTTP endpoint.
+ *
+ * The host must be the loopback address the listener is bound to: a server on
+ * ::1 refuses 127.0.0.1, and vice versa.
+ */
 export function probeHttpServer(
   port: number,
+  host: string,
   redirectsLeft = MAX_REDIRECTS,
 ): Promise<HttpProbeResult | null> {
   return new Promise((resolve) => {
@@ -55,7 +61,7 @@ export function probeHttpServer(
     };
 
     const request = get(
-      { host: "127.0.0.1", port, path: "/", timeout: PROBE_TIMEOUT_MS },
+      { host, port, path: "/", timeout: PROBE_TIMEOUT_MS },
       (response: IncomingMessage) => {
         const status = response.statusCode ?? 0;
         const location = response.headers.location;
@@ -68,7 +74,7 @@ export function probeHttpServer(
             finish(null);
             return;
           }
-          void probeHttpServer(port, redirectsLeft - 1).then(finish);
+          void probeHttpServer(port, host, redirectsLeft - 1).then(finish);
           return;
         }
         if (status >= 400 || !isHtmlContentType(response.headers["content-type"])) {