fix(devframe): skip ports held on another loopback address

packages/devframe/src/adapters/__tests__/dev.test.ts

@@ -1,5 +1,6 @@
 import type { DevframeNodeContext, DevframeRpcClientFunctions, DevframeRpcServerFunctions } from '../../types'
 import { mkdtempSync, writeFileSync } from 'node:fs'
+import { createServer } from 'node:net'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { defineDevframe } from 'devframe'
@@ -32,6 +33,15 @@ function makeTmpDist(): string {
   return dir
 }
 
+// Holds a port on one address, like an unrelated server already running.
+function listenOn(port: number, host: string): Promise<ReturnType<typeof createServer>> {
+  return new Promise((resolve, reject) => {
+    const server = createServer()
+    server.once('error', reject)
+    server.listen(port, host, () => resolve(server))
+  })
+}
+
 async function connectRaw(url: string, origin?: string): Promise<'open' | 'closed'> {
   return await new Promise((resolve) => {
     const ws = new WebSocket(url, origin ? { headers: { origin } } : undefined)
@@ -763,6 +773,29 @@ describe('adapters/dev', () => {
     expect(port).toBe(override)
   })
 
+  it('createDevServer on the default host does not share a port held on 127.0.0.1', async () => {
+    const taken = await getPort({ port: 19660, host: '127.0.0.1' })
+    const blocker = await listenOn(taken, '127.0.0.1')
+    const devframe = defineDevframe({
+      id: 'devframe-test-port-shared',
+      name: 'Port Shared',
+      version: '0.0.0',
+      packageName: 'devframe-test',
+      homepage: 'https://example.test',
+      description: 'Test devframe.',
+      setup: () => {},
+      cli: { port: taken },
+    })
+    const handle = await createDevServer(devframe, { openBrowser: false, distDir: makeTmpDist() })
+    try {
+      expect(handle.port).not.toBe(taken)
+    }
+    finally {
+      await handle.close()
+      blocker.close()
+    }
+  })
+
   it('registers the instance in the registry and unregisters on close', async () => {
     const registryDir = mkdtempSync(join(tmpdir(), 'devframe-registry-'))
     vi.stubEnv('DEVFRAME_INSTANCES_DIR', registryDir)

patches/get-port-please@3.2.0.patch

@@ -0,0 +1,102 @@
+diff --git a/dist/index.cjs b/dist/index.cjs
+index 31985b25727b3c09416c45d4763d0f83706317b4..fbbbdd63c8126f4f9dfae14a2e486bdd1e1a6b26 100644
+--- a/dist/index.cjs
++++ b/dist/index.cjs
+@@ -211,6 +211,37 @@ function _tryPort(port, host) {
+     });
+   });
+ }
++// Addresses that can answer for `localhost`. They can each hold the same port
++// independently (e.g. `::1` while another process holds `127.0.0.1`), so a
++// port is only free for a loopback or wildcard host if none of them has it.
++const LOOPBACK_HOSTS = ["127.0.0.1", "::1", "0.0.0.0", "::"];
++function _isLoopbackHost(host) {
++  return !host || host === "localhost" || LOOPBACK_HOSTS.includes(host);
++}
++function _isPortInUse(port, host) {
++  return new Promise((resolve) => {
++    const server = node_net.createServer();
++    server.unref();
++    server.on("error", (error) => {
++      resolve(error.code === "EADDRINUSE" || error.code === "EACCES");
++    });
++    server.listen({ port, host }, () => {
++      server.close(() => resolve(false));
++    });
++  });
++}
++async function _tryPortOnLoopback(port, host) {
++  const result = await _tryPort(port, host);
++  if (result === false || !_isLoopbackHost(host)) {
++    return result;
++  }
++  for (const loopbackHost of LOOPBACK_HOSTS) {
++    if (loopbackHost !== host && await _isPortInUse(result, loopbackHost)) {
++      return false;
++    }
++  }
++  return result;
++}
+ function _getLocalHosts(additional) {
+   const hosts = new Set(additional);
+   for (const _interface of Object.values(node_os.networkInterfaces())) {
+@@ -225,7 +256,7 @@ function _getLocalHosts(additional) {
+ }
+ async function _findPort(ports, host) {
+   for (const port of ports) {
+-    const r = await _tryPort(port, host);
++    const r = await _tryPortOnLoopback(port, host);
+     if (r) {
+       return r;
+     }
+diff --git a/dist/index.mjs b/dist/index.mjs
+index d3f84762fa155ffa1119f5bc5e8bb7e0aeb0b114..181a0c588ba9a438a478492f7b0a219e911cc425 100644
+--- a/dist/index.mjs
++++ b/dist/index.mjs
+@@ -209,6 +209,37 @@ function _tryPort(port, host) {
+     });
+   });
+ }
++// Addresses that can answer for `localhost`. They can each hold the same port
++// independently (e.g. `::1` while another process holds `127.0.0.1`), so a
++// port is only free for a loopback or wildcard host if none of them has it.
++const LOOPBACK_HOSTS = ["127.0.0.1", "::1", "0.0.0.0", "::"];
++function _isLoopbackHost(host) {
++  return !host || host === "localhost" || LOOPBACK_HOSTS.includes(host);
++}
++function _isPortInUse(port, host) {
++  return new Promise((resolve) => {
++    const server = createServer();
++    server.unref();
++    server.on("error", (error) => {
++      resolve(error.code === "EADDRINUSE" || error.code === "EACCES");
++    });
++    server.listen({ port, host }, () => {
++      server.close(() => resolve(false));
++    });
++  });
++}
++async function _tryPortOnLoopback(port, host) {
++  const result = await _tryPort(port, host);
++  if (result === false || !_isLoopbackHost(host)) {
++    return result;
++  }
++  for (const loopbackHost of LOOPBACK_HOSTS) {
++    if (loopbackHost !== host && await _isPortInUse(result, loopbackHost)) {
++      return false;
++    }
++  }
++  return result;
++}
+ function _getLocalHosts(additional) {
+   const hosts = new Set(additional);
+   for (const _interface of Object.values(networkInterfaces())) {
+@@ -223,7 +254,7 @@ function _getLocalHosts(additional) {
+ }
+ async function _findPort(ports, host) {
+   for (const port of ports) {
+-    const r = await _tryPort(port, host);
++    const r = await _tryPortOnLoopback(port, host);
+     if (r) {
+       return r;
+     }

pnpm-workspace.yaml

@@ -104,6 +104,7 @@ overrides:
 
 patchedDependencies:
   comark-docs@0.0.1: patches/comark-docs@0.0.1.patch
+  get-port-please@3.2.0: patches/get-port-please@3.2.0.patch
 
 allowBuilds:
   '@parcel/watcher': false