Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(harness): keep the loopback test bind synchronous

Alfredo Lopez7181b3af4145
diff --git a/codex-llm-proxy/test/bindLoopbackSetup.test.ts b/codex-llm-proxy/test/bindLoopbackSetup.test.ts
index 525695e2d..6fca61fc6 100644
--- a/codex-llm-proxy/test/bindLoopbackSetup.test.ts
+++ b/codex-llm-proxy/test/bindLoopbackSetup.test.ts
@@ -1,18 +1,20 @@
import { afterEach, expect, it } from 'vitest'
+import dns from 'node:dns'
import { type Server, createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
-// this package's vitest `setupFiles`.
+// this package's vitest `setupFiles`. A package that forgets to register it
+// keeps the defect and says nothing: every test still passes while its ephemeral
+// binds go back to the dual-stack wildcard, where another process holding the
+// same port on `127.0.0.1` receives the test's own requests.
//
-// That setup file makes a host-less `listen(0)` bind the IPv4 loopback instead
-// of the dual-stack wildcard, which is what stops a test server from being
-// handed an ephemeral port another process already holds on 127.0.0.1. A
-// package that forgets to register it keeps the defect and says nothing: every
-// test still passes, and the collision resurfaces later as a parse error, a
-// bogus status code or a socket hang up that reads as flakiness.
-//
-// So this file is the signal. It fails the moment the registration is dropped,
-// renamed or moved.
+// The synchronous reads below are the point, not incidental. supertest calls
+// `app.listen(0)` and reads `app.address().port` on the next line
+// (`supertest/lib/test.js:63-67`), so a setup file that reaches loopback through
+// an asynchronous host resolution satisfies a witness that awaits `listening`
+// and still breaks every supertest suite. That revision shipped once; these
+// assertions are what would have stopped it.
const servers: Server[] = []
afterEach(async () => {
@@ -21,40 +23,43 @@ afterEach(async () => {
)
})
-function boundAddress(server: Server): string {
+function track(server: Server): Server {
+ servers.push(server)
+ return server
+}
+
+function boundAddress(server: Server): AddressInfo {
const address = server.address()
if (address === null || typeof address === 'string') {
throw new Error(`expected a bound TCP address, got ${JSON.stringify(address)}`)
}
- return address.address
+ return address
}
-function track(server: Server): Server {
- servers.push(server)
- return server
-}
-
-it('binds an ephemeral port on the IPv4 loopback when the caller gives no host', async () => {
+it('binds an ephemeral port on the IPv4 loopback, readably, before listen() returns', () => {
const numeric = track(createServer())
- await new Promise<void>(resolve => {
- numeric.listen(0, () => resolve())
- })
- expect(boundAddress(numeric)).toBe('127.0.0.1')
+ numeric.listen(0)
+ const numericAddress = boundAddress(numeric)
+ expect(numericAddress.address).toBe('127.0.0.1')
+ expect(numericAddress.port).toBeGreaterThan(0)
- // The options form reaches the same kernel default and needs the same fix.
const options = track(createServer())
- await new Promise<void>(resolve => {
- options.listen({ port: 0 }, () => resolve())
- })
- expect(boundAddress(options)).toBe('127.0.0.1')
+ options.listen({ port: 0 })
+ const optionsAddress = boundAddress(options)
+ expect(optionsAddress.address).toBe('127.0.0.1')
+ expect(optionsAddress.port).toBeGreaterThan(0)
})
it('leaves a host the caller asked for alone', async () => {
- // The setup file rewrites only the case where the caller expressed no
- // preference. A test that wants the wildcard still gets it.
const explicit = track(createServer())
await new Promise<void>(resolve => {
explicit.listen(0, '0.0.0.0', () => resolve())
})
- expect(boundAddress(explicit)).toBe('0.0.0.0')
+ expect(boundAddress(explicit).address).toBe('0.0.0.0')
+})
+
+it('leaves node:dns as it found it once listen() has returned', () => {
+ const beforeListen = dns.lookup
+ track(createServer()).listen(0)
+ expect(dns.lookup).toBe(beforeListen)
})
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index c76225829..461945ecf 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.588",
+ "version": "0.1.589",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.588",
+ "version": "0.1.589",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",
diff --git a/control-api/package.json b/control-api/package.json
index d3cc0edd9..a518fab2a 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.588",
+ "version": "0.1.589",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/test/bindLoopbackSetup.test.ts b/control-api/test/bindLoopbackSetup.test.ts
index 525695e2d..6fca61fc6 100644
--- a/control-api/test/bindLoopbackSetup.test.ts
+++ b/control-api/test/bindLoopbackSetup.test.ts
@@ -1,18 +1,20 @@
import { afterEach, expect, it } from 'vitest'
+import dns from 'node:dns'
import { type Server, createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
-// this package's vitest `setupFiles`.
+// this package's vitest `setupFiles`. A package that forgets to register it
+// keeps the defect and says nothing: every test still passes while its ephemeral
+// binds go back to the dual-stack wildcard, where another process holding the
+// same port on `127.0.0.1` receives the test's own requests.
//
-// That setup file makes a host-less `listen(0)` bind the IPv4 loopback instead
-// of the dual-stack wildcard, which is what stops a test server from being
-// handed an ephemeral port another process already holds on 127.0.0.1. A
-// package that forgets to register it keeps the defect and says nothing: every
-// test still passes, and the collision resurfaces later as a parse error, a
-// bogus status code or a socket hang up that reads as flakiness.
-//
-// So this file is the signal. It fails the moment the registration is dropped,
-// renamed or moved.
+// The synchronous reads below are the point, not incidental. supertest calls
+// `app.listen(0)` and reads `app.address().port` on the next line
+// (`supertest/lib/test.js:63-67`), so a setup file that reaches loopback through
+// an asynchronous host resolution satisfies a witness that awaits `listening`
+// and still breaks every supertest suite. That revision shipped once; these
+// assertions are what would have stopped it.
const servers: Server[] = []
afterEach(async () => {
@@ -21,40 +23,43 @@ afterEach(async () => {
)
})
-function boundAddress(server: Server): string {
+function track(server: Server): Server {
+ servers.push(server)
+ return server
+}
+
+function boundAddress(server: Server): AddressInfo {
const address = server.address()
if (address === null || typeof address === 'string') {
throw new Error(`expected a bound TCP address, got ${JSON.stringify(address)}`)
}
- return address.address
+ return address
}
-function track(server: Server): Server {
- servers.push(server)
- return server
-}
-
-it('binds an ephemeral port on the IPv4 loopback when the caller gives no host', async () => {
+it('binds an ephemeral port on the IPv4 loopback, readably, before listen() returns', () => {
const numeric = track(createServer())
- await new Promise<void>(resolve => {
- numeric.listen(0, () => resolve())
- })
- expect(boundAddress(numeric)).toBe('127.0.0.1')
+ numeric.listen(0)
+ const numericAddress = boundAddress(numeric)
+ expect(numericAddress.address).toBe('127.0.0.1')
+ expect(numericAddress.port).toBeGreaterThan(0)
- // The options form reaches the same kernel default and needs the same fix.
const options = track(createServer())
- await new Promise<void>(resolve => {
- options.listen({ port: 0 }, () => resolve())
- })
- expect(boundAddress(options)).toBe('127.0.0.1')
+ options.listen({ port: 0 })
+ const optionsAddress = boundAddress(options)
+ expect(optionsAddress.address).toBe('127.0.0.1')
+ expect(optionsAddress.port).toBeGreaterThan(0)
})
it('leaves a host the caller asked for alone', async () => {
- // The setup file rewrites only the case where the caller expressed no
- // preference. A test that wants the wildcard still gets it.
const explicit = track(createServer())
await new Promise<void>(resolve => {
explicit.listen(0, '0.0.0.0', () => resolve())
})
- expect(boundAddress(explicit)).toBe('0.0.0.0')
+ expect(boundAddress(explicit).address).toBe('0.0.0.0')
+})
+
+it('leaves node:dns as it found it once listen() has returned', () => {
+ const beforeListen = dns.lookup
+ track(createServer()).listen(0)
+ expect(dns.lookup).toBe(beforeListen)
})
diff --git a/external-rest-api/package-lock.json b/external-rest-api/package-lock.json
index 80cbdb3f0..e1e4e2674 100644
--- a/external-rest-api/package-lock.json
+++ b/external-rest-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-external-rest-api",
- "version": "0.1.83",
+ "version": "0.1.84",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-external-rest-api",
- "version": "0.1.83",
+ "version": "0.1.84",
"dependencies": {
"cors": "^2.8.5",
"express": "^4.21.2",
diff --git a/external-rest-api/package.json b/external-rest-api/package.json
index 00d5f1326..fd127fe32 100644
--- a/external-rest-api/package.json
+++ b/external-rest-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-external-rest-api",
- "version": "0.1.83",
+ "version": "0.1.84",
"description": "External REST API for profile, team management, and RPC token brokerage",
"main": "dist/main.js",
"engines": {
diff --git a/external-rest-api/src/releaseManifest.ts b/external-rest-api/src/releaseManifest.ts
index 1495a56ae..b0706df8e 100644
--- a/external-rest-api/src/releaseManifest.ts
+++ b/external-rest-api/src/releaseManifest.ts
@@ -8,8 +8,8 @@ export type ReleaseManifest = {
export const releaseManifest: ReleaseManifest = {
releaseId: 'v0.8.1',
- externalRestApiVersion: '0.1.83',
- rpcProxyVersion: '0.1.83',
+ externalRestApiVersion: '0.1.84',
+ rpcProxyVersion: '0.1.84',
desktopVersion: '0.8.1',
minimumDesktopVersion: '0.1.252',
}
diff --git a/external-rest-api/test/bindLoopbackSetup.test.ts b/external-rest-api/test/bindLoopbackSetup.test.ts
index 525695e2d..6fca61fc6 100644
--- a/external-rest-api/test/bindLoopbackSetup.test.ts
+++ b/external-rest-api/test/bindLoopbackSetup.test.ts
@@ -1,18 +1,20 @@
import { afterEach, expect, it } from 'vitest'
+import dns from 'node:dns'
import { type Server, createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
-// this package's vitest `setupFiles`.
+// this package's vitest `setupFiles`. A package that forgets to register it
+// keeps the defect and says nothing: every test still passes while its ephemeral
+// binds go back to the dual-stack wildcard, where another process holding the
+// same port on `127.0.0.1` receives the test's own requests.
//
-// That setup file makes a host-less `listen(0)` bind the IPv4 loopback instead
-// of the dual-stack wildcard, which is what stops a test server from being
-// handed an ephemeral port another process already holds on 127.0.0.1. A
-// package that forgets to register it keeps the defect and says nothing: every
-// test still passes, and the collision resurfaces later as a parse error, a
-// bogus status code or a socket hang up that reads as flakiness.
-//
-// So this file is the signal. It fails the moment the registration is dropped,
-// renamed or moved.
+// The synchronous reads below are the point, not incidental. supertest calls
+// `app.listen(0)` and reads `app.address().port` on the next line
+// (`supertest/lib/test.js:63-67`), so a setup file that reaches loopback through
+// an asynchronous host resolution satisfies a witness that awaits `listening`
+// and still breaks every supertest suite. That revision shipped once; these
+// assertions are what would have stopped it.
const servers: Server[] = []
afterEach(async () => {
@@ -21,40 +23,43 @@ afterEach(async () => {
)
})
-function boundAddress(server: Server): string {
+function track(server: Server): Server {
+ servers.push(server)
+ return server
+}
+
+function boundAddress(server: Server): AddressInfo {
const address = server.address()
if (address === null || typeof address === 'string') {
throw new Error(`expected a bound TCP address, got ${JSON.stringify(address)}`)
}
- return address.address
+ return address
}
-function track(server: Server): Server {
- servers.push(server)
- return server
-}
-
-it('binds an ephemeral port on the IPv4 loopback when the caller gives no host', async () => {
+it('binds an ephemeral port on the IPv4 loopback, readably, before listen() returns', () => {
const numeric = track(createServer())
- await new Promise<void>(resolve => {
- numeric.listen(0, () => resolve())
- })
- expect(boundAddress(numeric)).toBe('127.0.0.1')
+ numeric.listen(0)
+ const numericAddress = boundAddress(numeric)
+ expect(numericAddress.address).toBe('127.0.0.1')
+ expect(numericAddress.port).toBeGreaterThan(0)
- // The options form reaches the same kernel default and needs the same fix.
const options = track(createServer())
- await new Promise<void>(resolve => {
- options.listen({ port: 0 }, () => resolve())
- })
- expect(boundAddress(options)).toBe('127.0.0.1')
+ options.listen({ port: 0 })
+ const optionsAddress = boundAddress(options)
+ expect(optionsAddress.address).toBe('127.0.0.1')
+ expect(optionsAddress.port).toBeGreaterThan(0)
})
it('leaves a host the caller asked for alone', async () => {
- // The setup file rewrites only the case where the caller expressed no
- // preference. A test that wants the wildcard still gets it.
const explicit = track(createServer())
await new Promise<void>(resolve => {
explicit.listen(0, '0.0.0.0', () => resolve())
})
- expect(boundAddress(explicit)).toBe('0.0.0.0')
+ expect(boundAddress(explicit).address).toBe('0.0.0.0')
+})
+
+it('leaves node:dns as it found it once listen() has returned', () => {
+ const beforeListen = dns.lookup
+ track(createServer()).listen(0)
+ expect(dns.lookup).toBe(beforeListen)
})
diff --git a/grok-llm-proxy/test/bindLoopbackSetup.test.ts b/grok-llm-proxy/test/bindLoopbackSetup.test.ts
index 525695e2d..6fca61fc6 100644
--- a/grok-llm-proxy/test/bindLoopbackSetup.test.ts
+++ b/grok-llm-proxy/test/bindLoopbackSetup.test.ts
@@ -1,18 +1,20 @@
import { afterEach, expect, it } from 'vitest'
+import dns from 'node:dns'
import { type Server, createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
-// this package's vitest `setupFiles`.
+// this package's vitest `setupFiles`. A package that forgets to register it
+// keeps the defect and says nothing: every test still passes while its ephemeral
+// binds go back to the dual-stack wildcard, where another process holding the
+// same port on `127.0.0.1` receives the test's own requests.
//
-// That setup file makes a host-less `listen(0)` bind the IPv4 loopback instead
-// of the dual-stack wildcard, which is what stops a test server from being
-// handed an ephemeral port another process already holds on 127.0.0.1. A
-// package that forgets to register it keeps the defect and says nothing: every
-// test still passes, and the collision resurfaces later as a parse error, a
-// bogus status code or a socket hang up that reads as flakiness.
-//
-// So this file is the signal. It fails the moment the registration is dropped,
-// renamed or moved.
+// The synchronous reads below are the point, not incidental. supertest calls
+// `app.listen(0)` and reads `app.address().port` on the next line
+// (`supertest/lib/test.js:63-67`), so a setup file that reaches loopback through
+// an asynchronous host resolution satisfies a witness that awaits `listening`
+// and still breaks every supertest suite. That revision shipped once; these
+// assertions are what would have stopped it.
const servers: Server[] = []
afterEach(async () => {
@@ -21,40 +23,43 @@ afterEach(async () => {
)
})
-function boundAddress(server: Server): string {
+function track(server: Server): Server {
+ servers.push(server)
+ return server
+}
+
+function boundAddress(server: Server): AddressInfo {
const address = server.address()
if (address === null || typeof address === 'string') {
throw new Error(`expected a bound TCP address, got ${JSON.stringify(address)}`)
}
- return address.address
+ return address
}
-function track(server: Server): Server {
- servers.push(server)
- return server
-}
-
-it('binds an ephemeral port on the IPv4 loopback when the caller gives no host', async () => {
+it('binds an ephemeral port on the IPv4 loopback, readably, before listen() returns', () => {
const numeric = track(createServer())
- await new Promise<void>(resolve => {
- numeric.listen(0, () => resolve())
- })
- expect(boundAddress(numeric)).toBe('127.0.0.1')
+ numeric.listen(0)
+ const numericAddress = boundAddress(numeric)
+ expect(numericAddress.address).toBe('127.0.0.1')
+ expect(numericAddress.port).toBeGreaterThan(0)
- // The options form reaches the same kernel default and needs the same fix.
const options = track(createServer())
- await new Promise<void>(resolve => {
- options.listen({ port: 0 }, () => resolve())
- })
- expect(boundAddress(options)).toBe('127.0.0.1')
+ options.listen({ port: 0 })
+ const optionsAddress = boundAddress(options)
+ expect(optionsAddress.address).toBe('127.0.0.1')
+ expect(optionsAddress.port).toBeGreaterThan(0)
})
it('leaves a host the caller asked for alone', async () => {
- // The setup file rewrites only the case where the caller expressed no
- // preference. A test that wants the wildcard still gets it.
const explicit = track(createServer())
await new Promise<void>(resolve => {
explicit.listen(0, '0.0.0.0', () => resolve())
})
- expect(boundAddress(explicit)).toBe('0.0.0.0')
+ expect(boundAddress(explicit).address).toBe('0.0.0.0')
+})
+
+it('leaves node:dns as it found it once listen() has returned', () => {
+ const beforeListen = dns.lookup
+ track(createServer()).listen(0)
+ expect(dns.lookup).toBe(beforeListen)
})
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index 4e3bd9218..23bfbfa52 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.361",
+ "version": "0.1.362",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.361",
+ "version": "0.1.362",
"license": "SEE LICENSE IN LICENSE",
"dependencies": {
"@anthropic-ai/sdk": "^0.32.0",
diff --git a/mcp-host/package.json b/mcp-host/package.json
index 7780e022f..f91b6d21e 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.361",
+ "version": "0.1.362",
"description": "MCP Host - reads Host CRD and provides LLM access via OpenAI/Claude",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-host/src/bindLoopbackSetup.test.ts b/mcp-host/src/bindLoopbackSetup.test.ts
index 525695e2d..6fca61fc6 100644
--- a/mcp-host/src/bindLoopbackSetup.test.ts
+++ b/mcp-host/src/bindLoopbackSetup.test.ts
@@ -1,18 +1,20 @@
import { afterEach, expect, it } from 'vitest'
+import dns from 'node:dns'
import { type Server, createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
-// this package's vitest `setupFiles`.
+// this package's vitest `setupFiles`. A package that forgets to register it
+// keeps the defect and says nothing: every test still passes while its ephemeral
+// binds go back to the dual-stack wildcard, where another process holding the
+// same port on `127.0.0.1` receives the test's own requests.
//
-// That setup file makes a host-less `listen(0)` bind the IPv4 loopback instead
-// of the dual-stack wildcard, which is what stops a test server from being
-// handed an ephemeral port another process already holds on 127.0.0.1. A
-// package that forgets to register it keeps the defect and says nothing: every
-// test still passes, and the collision resurfaces later as a parse error, a
-// bogus status code or a socket hang up that reads as flakiness.
-//
-// So this file is the signal. It fails the moment the registration is dropped,
-// renamed or moved.
+// The synchronous reads below are the point, not incidental. supertest calls
+// `app.listen(0)` and reads `app.address().port` on the next line
+// (`supertest/lib/test.js:63-67`), so a setup file that reaches loopback through
+// an asynchronous host resolution satisfies a witness that awaits `listening`
+// and still breaks every supertest suite. That revision shipped once; these
+// assertions are what would have stopped it.
const servers: Server[] = []
afterEach(async () => {
@@ -21,40 +23,43 @@ afterEach(async () => {
)
})
-function boundAddress(server: Server): string {
+function track(server: Server): Server {
+ servers.push(server)
+ return server
+}
+
+function boundAddress(server: Server): AddressInfo {
const address = server.address()
if (address === null || typeof address === 'string') {
throw new Error(`expected a bound TCP address, got ${JSON.stringify(address)}`)
}
- return address.address
+ return address
}
-function track(server: Server): Server {
- servers.push(server)
- return server
-}
-
-it('binds an ephemeral port on the IPv4 loopback when the caller gives no host', async () => {
+it('binds an ephemeral port on the IPv4 loopback, readably, before listen() returns', () => {
const numeric = track(createServer())
- await new Promise<void>(resolve => {
- numeric.listen(0, () => resolve())
- })
- expect(boundAddress(numeric)).toBe('127.0.0.1')
+ numeric.listen(0)
+ const numericAddress = boundAddress(numeric)
+ expect(numericAddress.address).toBe('127.0.0.1')
+ expect(numericAddress.port).toBeGreaterThan(0)
- // The options form reaches the same kernel default and needs the same fix.
const options = track(createServer())
- await new Promise<void>(resolve => {
- options.listen({ port: 0 }, () => resolve())
- })
- expect(boundAddress(options)).toBe('127.0.0.1')
+ options.listen({ port: 0 })
+ const optionsAddress = boundAddress(options)
+ expect(optionsAddress.address).toBe('127.0.0.1')
+ expect(optionsAddress.port).toBeGreaterThan(0)
})
it('leaves a host the caller asked for alone', async () => {
- // The setup file rewrites only the case where the caller expressed no
- // preference. A test that wants the wildcard still gets it.
const explicit = track(createServer())
await new Promise<void>(resolve => {
explicit.listen(0, '0.0.0.0', () => resolve())
})
- expect(boundAddress(explicit)).toBe('0.0.0.0')
+ expect(boundAddress(explicit).address).toBe('0.0.0.0')
+})
+
+it('leaves node:dns as it found it once listen() has returned', () => {
+ const beforeListen = dns.lookup
+ track(createServer()).listen(0)
+ expect(dns.lookup).toBe(beforeListen)
})
diff --git a/mcp-proxy/package-lock.json b/mcp-proxy/package-lock.json
index 96dc862c0..addd86e52 100644
--- a/mcp-proxy/package-lock.json
+++ b/mcp-proxy/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-proxy",
- "version": "0.1.6",
+ "version": "0.1.7",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-proxy",
- "version": "0.1.6",
+ "version": "0.1.7",
"license": "SEE LICENSE IN LICENSE",
"devDependencies": {
"@types/node": "^20.10.0",
diff --git a/mcp-proxy/package.json b/mcp-proxy/package.json
index 6c91322fe..e76f0296a 100644
--- a/mcp-proxy/package.json
+++ b/mcp-proxy/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-proxy",
- "version": "0.1.6",
+ "version": "0.1.7",
"description": "MCP Proxy - centralized HTTP router for MCP servers",
"main": "dist/main.js",
"engines": {
diff --git a/mcp-proxy/test/bindLoopbackSetup.test.ts b/mcp-proxy/test/bindLoopbackSetup.test.ts
index 525695e2d..6fca61fc6 100644
--- a/mcp-proxy/test/bindLoopbackSetup.test.ts
+++ b/mcp-proxy/test/bindLoopbackSetup.test.ts
@@ -1,18 +1,20 @@
import { afterEach, expect, it } from 'vitest'
+import dns from 'node:dns'
import { type Server, createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
-// this package's vitest `setupFiles`.
+// this package's vitest `setupFiles`. A package that forgets to register it
+// keeps the defect and says nothing: every test still passes while its ephemeral
+// binds go back to the dual-stack wildcard, where another process holding the
+// same port on `127.0.0.1` receives the test's own requests.
//
-// That setup file makes a host-less `listen(0)` bind the IPv4 loopback instead
-// of the dual-stack wildcard, which is what stops a test server from being
-// handed an ephemeral port another process already holds on 127.0.0.1. A
-// package that forgets to register it keeps the defect and says nothing: every
-// test still passes, and the collision resurfaces later as a parse error, a
-// bogus status code or a socket hang up that reads as flakiness.
-//
-// So this file is the signal. It fails the moment the registration is dropped,
-// renamed or moved.
+// The synchronous reads below are the point, not incidental. supertest calls
+// `app.listen(0)` and reads `app.address().port` on the next line
+// (`supertest/lib/test.js:63-67`), so a setup file that reaches loopback through
+// an asynchronous host resolution satisfies a witness that awaits `listening`
+// and still breaks every supertest suite. That revision shipped once; these
+// assertions are what would have stopped it.
const servers: Server[] = []
afterEach(async () => {
@@ -21,40 +23,43 @@ afterEach(async () => {
)
})
-function boundAddress(server: Server): string {
+function track(server: Server): Server {
+ servers.push(server)
+ return server
+}
+
+function boundAddress(server: Server): AddressInfo {
const address = server.address()
if (address === null || typeof address === 'string') {
throw new Error(`expected a bound TCP address, got ${JSON.stringify(address)}`)
}
- return address.address
+ return address
}
-function track(server: Server): Server {
- servers.push(server)
- return server
-}
-
-it('binds an ephemeral port on the IPv4 loopback when the caller gives no host', async () => {
+it('binds an ephemeral port on the IPv4 loopback, readably, before listen() returns', () => {
const numeric = track(createServer())
- await new Promise<void>(resolve => {
- numeric.listen(0, () => resolve())
- })
- expect(boundAddress(numeric)).toBe('127.0.0.1')
+ numeric.listen(0)
+ const numericAddress = boundAddress(numeric)
+ expect(numericAddress.address).toBe('127.0.0.1')
+ expect(numericAddress.port).toBeGreaterThan(0)
- // The options form reaches the same kernel default and needs the same fix.
const options = track(createServer())
- await new Promise<void>(resolve => {
- options.listen({ port: 0 }, () => resolve())
- })
- expect(boundAddress(options)).toBe('127.0.0.1')
+ options.listen({ port: 0 })
+ const optionsAddress = boundAddress(options)
+ expect(optionsAddress.address).toBe('127.0.0.1')
+ expect(optionsAddress.port).toBeGreaterThan(0)
})
it('leaves a host the caller asked for alone', async () => {
- // The setup file rewrites only the case where the caller expressed no
- // preference. A test that wants the wildcard still gets it.
const explicit = track(createServer())
await new Promise<void>(resolve => {
explicit.listen(0, '0.0.0.0', () => resolve())
})
- expect(boundAddress(explicit)).toBe('0.0.0.0')
+ expect(boundAddress(explicit).address).toBe('0.0.0.0')
+})
+
+it('leaves node:dns as it found it once listen() has returned', () => {
+ const beforeListen = dns.lookup
+ track(createServer()).listen(0)
+ expect(dns.lookup).toBe(beforeListen)
})
diff --git a/rpc-proxy/package-lock.json b/rpc-proxy/package-lock.json
index fe8605a6e..b9042e3d9 100644
--- a/rpc-proxy/package-lock.json
+++ b/rpc-proxy/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-rpc-proxy",
- "version": "0.1.83",
+ "version": "0.1.84",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-rpc-proxy",
- "version": "0.1.83",
+ "version": "0.1.84",
"dependencies": {
"cors": "^2.8.5",
"express": "^4.21.2",
diff --git a/rpc-proxy/package.json b/rpc-proxy/package.json
index 7415bc5fe..dd8684b18 100644
--- a/rpc-proxy/package.json
+++ b/rpc-proxy/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-rpc-proxy",
- "version": "0.1.83",
+ "version": "0.1.84",
"description": "External-facing RPC proxy for tenant-scoped MCP access",
"main": "dist/main.js",
"engines": {
diff --git a/rpc-proxy/test/bindLoopbackSetup.test.ts b/rpc-proxy/test/bindLoopbackSetup.test.ts
index 525695e2d..6fca61fc6 100644
--- a/rpc-proxy/test/bindLoopbackSetup.test.ts
+++ b/rpc-proxy/test/bindLoopbackSetup.test.ts
@@ -1,18 +1,20 @@
import { afterEach, expect, it } from 'vitest'
+import dns from 'node:dns'
import { type Server, createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
-// this package's vitest `setupFiles`.
+// this package's vitest `setupFiles`. A package that forgets to register it
+// keeps the defect and says nothing: every test still passes while its ephemeral
+// binds go back to the dual-stack wildcard, where another process holding the
+// same port on `127.0.0.1` receives the test's own requests.
//
-// That setup file makes a host-less `listen(0)` bind the IPv4 loopback instead
-// of the dual-stack wildcard, which is what stops a test server from being
-// handed an ephemeral port another process already holds on 127.0.0.1. A
-// package that forgets to register it keeps the defect and says nothing: every
-// test still passes, and the collision resurfaces later as a parse error, a
-// bogus status code or a socket hang up that reads as flakiness.
-//
-// So this file is the signal. It fails the moment the registration is dropped,
-// renamed or moved.
+// The synchronous reads below are the point, not incidental. supertest calls
+// `app.listen(0)` and reads `app.address().port` on the next line
+// (`supertest/lib/test.js:63-67`), so a setup file that reaches loopback through
+// an asynchronous host resolution satisfies a witness that awaits `listening`
+// and still breaks every supertest suite. That revision shipped once; these
+// assertions are what would have stopped it.
const servers: Server[] = []
afterEach(async () => {
@@ -21,40 +23,43 @@ afterEach(async () => {
)
})
-function boundAddress(server: Server): string {
+function track(server: Server): Server {
+ servers.push(server)
+ return server
+}
+
+function boundAddress(server: Server): AddressInfo {
const address = server.address()
if (address === null || typeof address === 'string') {
throw new Error(`expected a bound TCP address, got ${JSON.stringify(address)}`)
}
- return address.address
+ return address
}
-function track(server: Server): Server {
- servers.push(server)
- return server
-}
-
-it('binds an ephemeral port on the IPv4 loopback when the caller gives no host', async () => {
+it('binds an ephemeral port on the IPv4 loopback, readably, before listen() returns', () => {
const numeric = track(createServer())
- await new Promise<void>(resolve => {
- numeric.listen(0, () => resolve())
- })
- expect(boundAddress(numeric)).toBe('127.0.0.1')
+ numeric.listen(0)
+ const numericAddress = boundAddress(numeric)
+ expect(numericAddress.address).toBe('127.0.0.1')
+ expect(numericAddress.port).toBeGreaterThan(0)
- // The options form reaches the same kernel default and needs the same fix.
const options = track(createServer())
- await new Promise<void>(resolve => {
- options.listen({ port: 0 }, () => resolve())
- })
- expect(boundAddress(options)).toBe('127.0.0.1')
+ options.listen({ port: 0 })
+ const optionsAddress = boundAddress(options)
+ expect(optionsAddress.address).toBe('127.0.0.1')
+ expect(optionsAddress.port).toBeGreaterThan(0)
})
it('leaves a host the caller asked for alone', async () => {
- // The setup file rewrites only the case where the caller expressed no
- // preference. A test that wants the wildcard still gets it.
const explicit = track(createServer())
await new Promise<void>(resolve => {
explicit.listen(0, '0.0.0.0', () => resolve())
})
- expect(boundAddress(explicit)).toBe('0.0.0.0')
+ expect(boundAddress(explicit).address).toBe('0.0.0.0')
+})
+
+it('leaves node:dns as it found it once listen() has returned', () => {
+ const beforeListen = dns.lookup
+ track(createServer()).listen(0)
+ expect(dns.lookup).toBe(beforeListen)
})
diff --git a/scripts/testing/bind-loopback-in-tests.mjs b/scripts/testing/bind-loopback-in-tests.mjs
index bdfd81e37..cbc0c646e 100644
--- a/scripts/testing/bind-loopback-in-tests.mjs
+++ b/scripts/testing/bind-loopback-in-tests.mjs
@@ -1,14 +1,14 @@
-// Vitest setup file: make an ephemeral bind with no host bind IPv4 loopback.
+// Vitest setup file: give an ephemeral test bind exclusive ownership of the
+// IPv4 loopback address its clients actually dial.
//
// THE DEFECT
//
// `server.listen(0)` with no host binds the dual-stack wildcard `[::]:0`, while
-// clients in tests connect to `127.0.0.1`. Those are different addresses. On
-// macOS the sequential ephemeral allocator can hand the dual-stack socket a
-// port that an IPv4-only `127.0.0.1` listener already holds, because such a
-// listener is not a conflict for a `[::]` bind. The kernel then delivers the
-// client's IPv4 connection to that more specific listener instead of to the
-// test server.
+// clients in tests connect to `127.0.0.1`. Those are different addresses, and an
+// IPv4-only `127.0.0.1` listener is not a bind conflict for a `[::]` bind, so
+// the sequential ephemeral allocator on macOS can hand the test server a port
+// another process already holds. The kernel then delivers the client's IPv4
+// connection to that more specific listener instead of to the test server.
//
// A developer host running Docker Desktop with minikube holds one such listener
// per mapped port per profile, all inside the ephemeral range, so the test talks
@@ -26,10 +26,32 @@
//
// 174 test files across seven packages reach this through `supertest`, whose
// `request(app)` performs the host-less `listen(0)` itself
-// (`supertest/lib/test.js:63`). Fixing those at the call site means giving every
-// one of them an explicit server lifecycle; the bind is not ours to pass a host
-// to. Patching the one primitive they all funnel through fixes every call site,
-// including supertest's own.
+// (`supertest/lib/test.js:63`). The bind is not theirs to pass a host to.
+//
+// WHY THE NAME-RESOLUTION HOP IS COLLAPSED
+//
+// Asking for the host is not enough on its own, and the first revision of this
+// file shipped exactly that mistake. `listen(port, host)` routes through
+// `lookupAndListen` -> `dns.lookup(host, { all: true }, doListen)`, which is
+// asynchronous even for an IP literal, so `server.address()` is null when
+// `listen()` returns -- and supertest reads `app.address().port` on the very
+// next line (`supertest/lib/test.js:67`). Every supertest suite failed with
+// `TypeError: Cannot read properties of null (reading 'port')`.
+//
+// The bind itself is synchronous; only the resolution in front of it is not. So
+// for the duration of a single `listen()` call -- installed and removed inside
+// one synchronous window, where no other code can observe it -- `dns.lookup`
+// answers an IP literal inline. `doListen` then runs within `listen()`, the
+// handle is bound before it returns, and `address()` reads the port.
+// `'listening'` is still emitted on `nextTick`, so handlers attached after
+// `listen()` returns still arrive in time.
+//
+// That calling convention (`{ all: true }`, answered with an array of
+// `{ address, family }`) is Node's internal contract, not public API. Were a
+// Node upgrade to change it, an inline answer Node no longer understands sends
+// it back to the wildcard bind -- the defect this file exists to remove,
+// reinstated silently. The bind is therefore asserted before `listen()`
+// returns, so a changed contract fails the run instead.
//
// WHAT IS AND IS NOT REWRITTEN
//
@@ -41,24 +63,28 @@
//
// This runs only under vitest, through `setupFiles`. No production code path
// loads it.
+import dns from 'node:dns'
import net from 'node:net'
const LOOPBACK = '127.0.0.1'
-const originalListen = net.Server.prototype.listen
+const INSTALLED = Symbol.for('evenfire.bindLoopbackInTests')
/** True when the argument list carries no host, so the kernel would pick `[::]`. */
function hostIsAbsent(args) {
- // listen(port, host?, backlog?, callback?) — the host, if given, is a string
+ // listen(port, host?, backlog?, callback?) -- the host, if given, is a string
// in position 1. Anything else there (a backlog number, a callback) means no
// host was passed.
return typeof args[1] !== 'string'
}
-net.Server.prototype.listen = function listenOnLoopbackWhenEphemeral(...args) {
+/**
+ * The argument list to bind loopback instead, or `null` to leave the call alone.
+ */
+function withLoopbackHost(args) {
const [first] = args
if (first === 0 && hostIsAbsent(args)) {
- return originalListen.call(this, 0, LOOPBACK, ...args.slice(1))
+ return [0, LOOPBACK, ...args.slice(1)]
}
if (
@@ -68,8 +94,69 @@ net.Server.prototype.listen = function listenOnLoopbackWhenEphemeral(...args) {
first.host === undefined &&
first.path === undefined
) {
- return originalListen.call(this, { ...first, host: LOOPBACK }, ...args.slice(1))
+ return [{ ...first, host: LOOPBACK }, ...args.slice(1)]
+ }
+
+ return null
+}
+
+/**
+ * Answer an IP literal without leaving the current tick, so the bind Node
+ * queues behind the lookup happens inside `listen()`.
+ */
+function lookupResolvingLiteralsInline(realLookup) {
+ return function lookupInline(address, ...rest) {
+ const callback = rest[rest.length - 1]
+ const family = net.isIP(address)
+
+ if (family === 0 || typeof callback !== 'function') {
+ return realLookup.call(this, address, ...rest)
+ }
+
+ const options = rest.length > 1 ? rest[0] : undefined
+ if (options !== null && typeof options === 'object' && options.all === true) {
+ callback(null, [{ address, family }])
+ } else {
+ callback(null, address, family)
+ }
+ return undefined
+ }
+}
+
+function assertBoundOnLoopback(server) {
+ const address = server.address()
+ if (address === null || typeof address === 'string' || address.address !== LOOPBACK) {
+ throw new Error(
+ `bind-loopback-in-tests: expected an ephemeral listen to be bound on ${LOOPBACK} ` +
+ `by the time listen() returned, but address() reported ${JSON.stringify(address)}. ` +
+ "Node's host resolution for listen() no longer matches the dns.lookup contract " +
+ 'this setup file collapses, so the bind fell back to the dual-stack wildcard. ' +
+ 'Fix scripts/testing/bind-loopback-in-tests.mjs rather than removing it: the ' +
+ 'wildcard bind is the defect it exists to prevent.'
+ )
+ }
+}
+
+if (net.Server.prototype.listen[INSTALLED] !== true) {
+ const originalListen = net.Server.prototype.listen
+
+ function listenOnLoopbackWhenEphemeral(...args) {
+ const loopbackArgs = withLoopbackHost(args)
+ if (loopbackArgs === null) {
+ return originalListen.apply(this, args)
+ }
+
+ const realLookup = dns.lookup
+ dns.lookup = lookupResolvingLiteralsInline(realLookup)
+ try {
+ const result = originalListen.apply(this, loopbackArgs)
+ assertBoundOnLoopback(this)
+ return result
+ } finally {
+ dns.lookup = realLookup
+ }
}
- return originalListen.apply(this, args)
+ listenOnLoopbackWhenEphemeral[INSTALLED] = true
+ net.Server.prototype.listen = listenOnLoopbackWhenEphemeral
}
diff --git a/webhook-gateway/test/bindLoopbackSetup.test.ts b/webhook-gateway/test/bindLoopbackSetup.test.ts
index 525695e2d..6fca61fc6 100644
--- a/webhook-gateway/test/bindLoopbackSetup.test.ts
+++ b/webhook-gateway/test/bindLoopbackSetup.test.ts
@@ -1,18 +1,20 @@
import { afterEach, expect, it } from 'vitest'
+import dns from 'node:dns'
import { type Server, createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
-// this package's vitest `setupFiles`.
+// this package's vitest `setupFiles`. A package that forgets to register it
+// keeps the defect and says nothing: every test still passes while its ephemeral
+// binds go back to the dual-stack wildcard, where another process holding the
+// same port on `127.0.0.1` receives the test's own requests.
//
-// That setup file makes a host-less `listen(0)` bind the IPv4 loopback instead
-// of the dual-stack wildcard, which is what stops a test server from being
-// handed an ephemeral port another process already holds on 127.0.0.1. A
-// package that forgets to register it keeps the defect and says nothing: every
-// test still passes, and the collision resurfaces later as a parse error, a
-// bogus status code or a socket hang up that reads as flakiness.
-//
-// So this file is the signal. It fails the moment the registration is dropped,
-// renamed or moved.
+// The synchronous reads below are the point, not incidental. supertest calls
+// `app.listen(0)` and reads `app.address().port` on the next line
+// (`supertest/lib/test.js:63-67`), so a setup file that reaches loopback through
+// an asynchronous host resolution satisfies a witness that awaits `listening`
+// and still breaks every supertest suite. That revision shipped once; these
+// assertions are what would have stopped it.
const servers: Server[] = []
afterEach(async () => {
@@ -21,40 +23,43 @@ afterEach(async () => {
)
})
-function boundAddress(server: Server): string {
+function track(server: Server): Server {
+ servers.push(server)
+ return server
+}
+
+function boundAddress(server: Server): AddressInfo {
const address = server.address()
if (address === null || typeof address === 'string') {
throw new Error(`expected a bound TCP address, got ${JSON.stringify(address)}`)
}
- return address.address
+ return address
}
-function track(server: Server): Server {
- servers.push(server)
- return server
-}
-
-it('binds an ephemeral port on the IPv4 loopback when the caller gives no host', async () => {
+it('binds an ephemeral port on the IPv4 loopback, readably, before listen() returns', () => {
const numeric = track(createServer())
- await new Promise<void>(resolve => {
- numeric.listen(0, () => resolve())
- })
- expect(boundAddress(numeric)).toBe('127.0.0.1')
+ numeric.listen(0)
+ const numericAddress = boundAddress(numeric)
+ expect(numericAddress.address).toBe('127.0.0.1')
+ expect(numericAddress.port).toBeGreaterThan(0)
- // The options form reaches the same kernel default and needs the same fix.
const options = track(createServer())
- await new Promise<void>(resolve => {
- options.listen({ port: 0 }, () => resolve())
- })
- expect(boundAddress(options)).toBe('127.0.0.1')
+ options.listen({ port: 0 })
+ const optionsAddress = boundAddress(options)
+ expect(optionsAddress.address).toBe('127.0.0.1')
+ expect(optionsAddress.port).toBeGreaterThan(0)
})
it('leaves a host the caller asked for alone', async () => {
- // The setup file rewrites only the case where the caller expressed no
- // preference. A test that wants the wildcard still gets it.
const explicit = track(createServer())
await new Promise<void>(resolve => {
explicit.listen(0, '0.0.0.0', () => resolve())
})
- expect(boundAddress(explicit)).toBe('0.0.0.0')
+ expect(boundAddress(explicit).address).toBe('0.0.0.0')
+})
+
+it('leaves node:dns as it found it once listen() has returned', () => {
+ const beforeListen = dns.lookup
+ track(createServer()).listen(0)
+ expect(dns.lookup).toBe(beforeListen)
})
diff --git a/webhook-proxy/test/bindLoopbackSetup.test.ts b/webhook-proxy/test/bindLoopbackSetup.test.ts
index 525695e2d..6fca61fc6 100644
--- a/webhook-proxy/test/bindLoopbackSetup.test.ts
+++ b/webhook-proxy/test/bindLoopbackSetup.test.ts
@@ -1,18 +1,20 @@
import { afterEach, expect, it } from 'vitest'
+import dns from 'node:dns'
import { type Server, createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
-// this package's vitest `setupFiles`.
+// this package's vitest `setupFiles`. A package that forgets to register it
+// keeps the defect and says nothing: every test still passes while its ephemeral
+// binds go back to the dual-stack wildcard, where another process holding the
+// same port on `127.0.0.1` receives the test's own requests.
//
-// That setup file makes a host-less `listen(0)` bind the IPv4 loopback instead
-// of the dual-stack wildcard, which is what stops a test server from being
-// handed an ephemeral port another process already holds on 127.0.0.1. A
-// package that forgets to register it keeps the defect and says nothing: every
-// test still passes, and the collision resurfaces later as a parse error, a
-// bogus status code or a socket hang up that reads as flakiness.
-//
-// So this file is the signal. It fails the moment the registration is dropped,
-// renamed or moved.
+// The synchronous reads below are the point, not incidental. supertest calls
+// `app.listen(0)` and reads `app.address().port` on the next line
+// (`supertest/lib/test.js:63-67`), so a setup file that reaches loopback through
+// an asynchronous host resolution satisfies a witness that awaits `listening`
+// and still breaks every supertest suite. That revision shipped once; these
+// assertions are what would have stopped it.
const servers: Server[] = []
afterEach(async () => {
@@ -21,40 +23,43 @@ afterEach(async () => {
)
})
-function boundAddress(server: Server): string {
+function track(server: Server): Server {
+ servers.push(server)
+ return server
+}
+
+function boundAddress(server: Server): AddressInfo {
const address = server.address()
if (address === null || typeof address === 'string') {
throw new Error(`expected a bound TCP address, got ${JSON.stringify(address)}`)
}
- return address.address
+ return address
}
-function track(server: Server): Server {
- servers.push(server)
- return server
-}
-
-it('binds an ephemeral port on the IPv4 loopback when the caller gives no host', async () => {
+it('binds an ephemeral port on the IPv4 loopback, readably, before listen() returns', () => {
const numeric = track(createServer())
- await new Promise<void>(resolve => {
- numeric.listen(0, () => resolve())
- })
- expect(boundAddress(numeric)).toBe('127.0.0.1')
+ numeric.listen(0)
+ const numericAddress = boundAddress(numeric)
+ expect(numericAddress.address).toBe('127.0.0.1')
+ expect(numericAddress.port).toBeGreaterThan(0)
- // The options form reaches the same kernel default and needs the same fix.
const options = track(createServer())
- await new Promise<void>(resolve => {
- options.listen({ port: 0 }, () => resolve())
- })
- expect(boundAddress(options)).toBe('127.0.0.1')
+ options.listen({ port: 0 })
+ const optionsAddress = boundAddress(options)
+ expect(optionsAddress.address).toBe('127.0.0.1')
+ expect(optionsAddress.port).toBeGreaterThan(0)
})
it('leaves a host the caller asked for alone', async () => {
- // The setup file rewrites only the case where the caller expressed no
- // preference. A test that wants the wildcard still gets it.
const explicit = track(createServer())
await new Promise<void>(resolve => {
explicit.listen(0, '0.0.0.0', () => resolve())
})
- expect(boundAddress(explicit)).toBe('0.0.0.0')
+ expect(boundAddress(explicit).address).toBe('0.0.0.0')
+})
+
+it('leaves node:dns as it found it once listen() has returned', () => {
+ const beforeListen = dns.lookup
+ track(createServer()).listen(0)
+ expect(dns.lookup).toBe(beforeListen)
})
diff --git a/workspace-files-controller/src/__tests__/bindLoopbackSetup.test.ts b/workspace-files-controller/src/__tests__/bindLoopbackSetup.test.ts
index 525695e2d..6fca61fc6 100644
--- a/workspace-files-controller/src/__tests__/bindLoopbackSetup.test.ts
+++ b/workspace-files-controller/src/__tests__/bindLoopbackSetup.test.ts
@@ -1,18 +1,20 @@
import { afterEach, expect, it } from 'vitest'
+import dns from 'node:dns'
import { type Server, createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
-// this package's vitest `setupFiles`.
+// this package's vitest `setupFiles`. A package that forgets to register it
+// keeps the defect and says nothing: every test still passes while its ephemeral
+// binds go back to the dual-stack wildcard, where another process holding the
+// same port on `127.0.0.1` receives the test's own requests.
//
-// That setup file makes a host-less `listen(0)` bind the IPv4 loopback instead
-// of the dual-stack wildcard, which is what stops a test server from being
-// handed an ephemeral port another process already holds on 127.0.0.1. A
-// package that forgets to register it keeps the defect and says nothing: every
-// test still passes, and the collision resurfaces later as a parse error, a
-// bogus status code or a socket hang up that reads as flakiness.
-//
-// So this file is the signal. It fails the moment the registration is dropped,
-// renamed or moved.
+// The synchronous reads below are the point, not incidental. supertest calls
+// `app.listen(0)` and reads `app.address().port` on the next line
+// (`supertest/lib/test.js:63-67`), so a setup file that reaches loopback through
+// an asynchronous host resolution satisfies a witness that awaits `listening`
+// and still breaks every supertest suite. That revision shipped once; these
+// assertions are what would have stopped it.
const servers: Server[] = []
afterEach(async () => {
@@ -21,40 +23,43 @@ afterEach(async () => {
)
})
-function boundAddress(server: Server): string {
+function track(server: Server): Server {
+ servers.push(server)
+ return server
+}
+
+function boundAddress(server: Server): AddressInfo {
const address = server.address()
if (address === null || typeof address === 'string') {
throw new Error(`expected a bound TCP address, got ${JSON.stringify(address)}`)
}
- return address.address
+ return address
}
-function track(server: Server): Server {
- servers.push(server)
- return server
-}
-
-it('binds an ephemeral port on the IPv4 loopback when the caller gives no host', async () => {
+it('binds an ephemeral port on the IPv4 loopback, readably, before listen() returns', () => {
const numeric = track(createServer())
- await new Promise<void>(resolve => {
- numeric.listen(0, () => resolve())
- })
- expect(boundAddress(numeric)).toBe('127.0.0.1')
+ numeric.listen(0)
+ const numericAddress = boundAddress(numeric)
+ expect(numericAddress.address).toBe('127.0.0.1')
+ expect(numericAddress.port).toBeGreaterThan(0)
- // The options form reaches the same kernel default and needs the same fix.
const options = track(createServer())
- await new Promise<void>(resolve => {
- options.listen({ port: 0 }, () => resolve())
- })
- expect(boundAddress(options)).toBe('127.0.0.1')
+ options.listen({ port: 0 })
+ const optionsAddress = boundAddress(options)
+ expect(optionsAddress.address).toBe('127.0.0.1')
+ expect(optionsAddress.port).toBeGreaterThan(0)
})
it('leaves a host the caller asked for alone', async () => {
- // The setup file rewrites only the case where the caller expressed no
- // preference. A test that wants the wildcard still gets it.
const explicit = track(createServer())
await new Promise<void>(resolve => {
explicit.listen(0, '0.0.0.0', () => resolve())
})
- expect(boundAddress(explicit)).toBe('0.0.0.0')
+ expect(boundAddress(explicit).address).toBe('0.0.0.0')
+})
+
+it('leaves node:dns as it found it once listen() has returned', () => {
+ const beforeListen = dns.lookup
+ track(createServer()).listen(0)
+ expect(dns.lookup).toBe(beforeListen)
})