Skip to content

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

TypeScript

test(harness): bind ephemeral test servers on the IPv4 loopback

Alfredo Lopeza77f259f0eed
diff --git a/codex-llm-proxy/test/bindLoopbackSetup.test.ts b/codex-llm-proxy/test/bindLoopbackSetup.test.ts
new file mode 100644
index 000000000..525695e2d
--- /dev/null
+++ b/codex-llm-proxy/test/bindLoopbackSetup.test.ts
@@ -0,0 +1,60 @@
+import { afterEach, expect, it } from 'vitest'
+import { type Server, createServer } from 'node:http'
+
+// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
+// this package's vitest `setupFiles`.
+//
+// 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.
+const servers: Server[] = []
+
+afterEach(async () => {
+ await Promise.all(
+ servers.splice(0).map(server => new Promise<void>(resolve => server.close(() => resolve())))
+ )
+})
+
+function boundAddress(server: Server): string {
+ 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
+}
+
+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 () => {
+ const numeric = track(createServer())
+ await new Promise<void>(resolve => {
+ numeric.listen(0, () => resolve())
+ })
+ expect(boundAddress(numeric)).toBe('127.0.0.1')
+
+ // 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')
+})
+
+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')
+})
diff --git a/codex-llm-proxy/vitest.config.ts b/codex-llm-proxy/vitest.config.ts
index 642ffdf27..adaecc358 100644
--- a/codex-llm-proxy/vitest.config.ts
+++ b/codex-llm-proxy/vitest.config.ts
@@ -2,6 +2,7 @@ import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
+ setupFiles: ['../scripts/testing/bind-loopback-in-tests.mjs'],
include: ['test/**/*.test.ts'],
pool: 'forks',
},
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 5d2665b68..c76225829 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.587",
+ "version": "0.1.588",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.587",
+ "version": "0.1.588",
"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 9ac84821c..d3cc0edd9 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.587",
+ "version": "0.1.588",
"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
new file mode 100644
index 000000000..525695e2d
--- /dev/null
+++ b/control-api/test/bindLoopbackSetup.test.ts
@@ -0,0 +1,60 @@
+import { afterEach, expect, it } from 'vitest'
+import { type Server, createServer } from 'node:http'
+
+// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
+// this package's vitest `setupFiles`.
+//
+// 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.
+const servers: Server[] = []
+
+afterEach(async () => {
+ await Promise.all(
+ servers.splice(0).map(server => new Promise<void>(resolve => server.close(() => resolve())))
+ )
+})
+
+function boundAddress(server: Server): string {
+ 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
+}
+
+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 () => {
+ const numeric = track(createServer())
+ await new Promise<void>(resolve => {
+ numeric.listen(0, () => resolve())
+ })
+ expect(boundAddress(numeric)).toBe('127.0.0.1')
+
+ // 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')
+})
+
+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')
+})
diff --git a/control-api/vitest.config.ts b/control-api/vitest.config.ts
index 18e116d31..3db0f4243 100644
--- a/control-api/vitest.config.ts
+++ b/control-api/vitest.config.ts
@@ -3,7 +3,10 @@ import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
environment: 'node',
- setupFiles: ['test/realPostgres.requirement.ts'],
+ setupFiles: [
+ '../scripts/testing/bind-loopback-in-tests.mjs',
+ 'test/realPostgres.requirement.ts',
+ ],
// Control API route suites mock shared modules, env-backed config, and
// Supertest apps. Running files in parallel can leak those process-level
// fixtures across workers and produce nondeterministic HTTP parse failures.
diff --git a/external-rest-api/package-lock.json b/external-rest-api/package-lock.json
index d78479281..80cbdb3f0 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.82",
+ "version": "0.1.83",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-external-rest-api",
- "version": "0.1.82",
+ "version": "0.1.83",
"dependencies": {
"cors": "^2.8.5",
"express": "^4.21.2",
diff --git a/external-rest-api/package.json b/external-rest-api/package.json
index 6541f2d31..00d5f1326 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.82",
+ "version": "0.1.83",
"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 8e5935da1..1495a56ae 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.82',
- rpcProxyVersion: '0.1.82',
+ externalRestApiVersion: '0.1.83',
+ rpcProxyVersion: '0.1.83',
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
new file mode 100644
index 000000000..525695e2d
--- /dev/null
+++ b/external-rest-api/test/bindLoopbackSetup.test.ts
@@ -0,0 +1,60 @@
+import { afterEach, expect, it } from 'vitest'
+import { type Server, createServer } from 'node:http'
+
+// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
+// this package's vitest `setupFiles`.
+//
+// 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.
+const servers: Server[] = []
+
+afterEach(async () => {
+ await Promise.all(
+ servers.splice(0).map(server => new Promise<void>(resolve => server.close(() => resolve())))
+ )
+})
+
+function boundAddress(server: Server): string {
+ 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
+}
+
+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 () => {
+ const numeric = track(createServer())
+ await new Promise<void>(resolve => {
+ numeric.listen(0, () => resolve())
+ })
+ expect(boundAddress(numeric)).toBe('127.0.0.1')
+
+ // 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')
+})
+
+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')
+})
diff --git a/external-rest-api/vitest.config.ts b/external-rest-api/vitest.config.ts
index 37b473f54..bc7655069 100644
--- a/external-rest-api/vitest.config.ts
+++ b/external-rest-api/vitest.config.ts
@@ -1,8 +1,9 @@
-import { defineConfig } from "vitest/config";
+import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
- include: ["src/**/*.test.ts", "src/**/__tests__/**/*.ts", "test/**/*.test.ts"],
- exclude: ["dist/**", "node_modules/**"],
+ setupFiles: ['../scripts/testing/bind-loopback-in-tests.mjs'],
+ include: ['src/**/*.test.ts', 'src/**/__tests__/**/*.ts', 'test/**/*.test.ts'],
+ exclude: ['dist/**', 'node_modules/**'],
},
-});
+})
diff --git a/grok-llm-proxy/test/bindLoopbackSetup.test.ts b/grok-llm-proxy/test/bindLoopbackSetup.test.ts
new file mode 100644
index 000000000..525695e2d
--- /dev/null
+++ b/grok-llm-proxy/test/bindLoopbackSetup.test.ts
@@ -0,0 +1,60 @@
+import { afterEach, expect, it } from 'vitest'
+import { type Server, createServer } from 'node:http'
+
+// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
+// this package's vitest `setupFiles`.
+//
+// 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.
+const servers: Server[] = []
+
+afterEach(async () => {
+ await Promise.all(
+ servers.splice(0).map(server => new Promise<void>(resolve => server.close(() => resolve())))
+ )
+})
+
+function boundAddress(server: Server): string {
+ 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
+}
+
+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 () => {
+ const numeric = track(createServer())
+ await new Promise<void>(resolve => {
+ numeric.listen(0, () => resolve())
+ })
+ expect(boundAddress(numeric)).toBe('127.0.0.1')
+
+ // 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')
+})
+
+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')
+})
diff --git a/grok-llm-proxy/vitest.config.ts b/grok-llm-proxy/vitest.config.ts
index 642ffdf27..adaecc358 100644
--- a/grok-llm-proxy/vitest.config.ts
+++ b/grok-llm-proxy/vitest.config.ts
@@ -2,6 +2,7 @@ import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
+ setupFiles: ['../scripts/testing/bind-loopback-in-tests.mjs'],
include: ['test/**/*.test.ts'],
pool: 'forks',
},
diff --git a/mcp-host/package-lock.json b/mcp-host/package-lock.json
index bbd3cb218..4e3bd9218 100644
--- a/mcp-host/package-lock.json
+++ b/mcp-host/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.360",
+ "version": "0.1.361",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-host",
- "version": "0.1.360",
+ "version": "0.1.361",
"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 2a96d2c3b..7780e022f 100644
--- a/mcp-host/package.json
+++ b/mcp-host/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-host",
- "version": "0.1.360",
+ "version": "0.1.361",
"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
new file mode 100644
index 000000000..525695e2d
--- /dev/null
+++ b/mcp-host/src/bindLoopbackSetup.test.ts
@@ -0,0 +1,60 @@
+import { afterEach, expect, it } from 'vitest'
+import { type Server, createServer } from 'node:http'
+
+// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
+// this package's vitest `setupFiles`.
+//
+// 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.
+const servers: Server[] = []
+
+afterEach(async () => {
+ await Promise.all(
+ servers.splice(0).map(server => new Promise<void>(resolve => server.close(() => resolve())))
+ )
+})
+
+function boundAddress(server: Server): string {
+ 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
+}
+
+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 () => {
+ const numeric = track(createServer())
+ await new Promise<void>(resolve => {
+ numeric.listen(0, () => resolve())
+ })
+ expect(boundAddress(numeric)).toBe('127.0.0.1')
+
+ // 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')
+})
+
+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')
+})
diff --git a/mcp-host/vitest.config.ts b/mcp-host/vitest.config.ts
index 898541254..8238bfcbd 100644
--- a/mcp-host/vitest.config.ts
+++ b/mcp-host/vitest.config.ts
@@ -3,6 +3,7 @@ import { fileURLToPath } from 'node:url'
export default defineConfig({
test: {
+ setupFiles: ['../scripts/testing/bind-loopback-in-tests.mjs'],
// Client construction in unit tests uses a fixture, never a live context.
env: {
KUBECONFIG: fileURLToPath(new URL('./test/fixtures/kubernetes-unit.yaml', import.meta.url)),
diff --git a/mcp-proxy/package-lock.json b/mcp-proxy/package-lock.json
index 223d45a0a..96dc862c0 100644
--- a/mcp-proxy/package-lock.json
+++ b/mcp-proxy/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-mcp-proxy",
- "version": "0.1.5",
+ "version": "0.1.6",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-mcp-proxy",
- "version": "0.1.5",
+ "version": "0.1.6",
"license": "SEE LICENSE IN LICENSE",
"devDependencies": {
"@types/node": "^20.10.0",
diff --git a/mcp-proxy/package.json b/mcp-proxy/package.json
index e50573bb7..6c91322fe 100644
--- a/mcp-proxy/package.json
+++ b/mcp-proxy/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-mcp-proxy",
- "version": "0.1.5",
+ "version": "0.1.6",
"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
new file mode 100644
index 000000000..525695e2d
--- /dev/null
+++ b/mcp-proxy/test/bindLoopbackSetup.test.ts
@@ -0,0 +1,60 @@
+import { afterEach, expect, it } from 'vitest'
+import { type Server, createServer } from 'node:http'
+
+// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
+// this package's vitest `setupFiles`.
+//
+// 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.
+const servers: Server[] = []
+
+afterEach(async () => {
+ await Promise.all(
+ servers.splice(0).map(server => new Promise<void>(resolve => server.close(() => resolve())))
+ )
+})
+
+function boundAddress(server: Server): string {
+ 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
+}
+
+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 () => {
+ const numeric = track(createServer())
+ await new Promise<void>(resolve => {
+ numeric.listen(0, () => resolve())
+ })
+ expect(boundAddress(numeric)).toBe('127.0.0.1')
+
+ // 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')
+})
+
+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')
+})
diff --git a/mcp-proxy/vitest.config.ts b/mcp-proxy/vitest.config.ts
index 37b473f54..bc7655069 100644
--- a/mcp-proxy/vitest.config.ts
+++ b/mcp-proxy/vitest.config.ts
@@ -1,8 +1,9 @@
-import { defineConfig } from "vitest/config";
+import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
- include: ["src/**/*.test.ts", "src/**/__tests__/**/*.ts", "test/**/*.test.ts"],
- exclude: ["dist/**", "node_modules/**"],
+ setupFiles: ['../scripts/testing/bind-loopback-in-tests.mjs'],
+ include: ['src/**/*.test.ts', 'src/**/__tests__/**/*.ts', 'test/**/*.test.ts'],
+ exclude: ['dist/**', 'node_modules/**'],
},
-});
+})
diff --git a/rpc-proxy/package-lock.json b/rpc-proxy/package-lock.json
index a8715fece..fe8605a6e 100644
--- a/rpc-proxy/package-lock.json
+++ b/rpc-proxy/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-rpc-proxy",
- "version": "0.1.82",
+ "version": "0.1.83",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-rpc-proxy",
- "version": "0.1.82",
+ "version": "0.1.83",
"dependencies": {
"cors": "^2.8.5",
"express": "^4.21.2",
diff --git a/rpc-proxy/package.json b/rpc-proxy/package.json
index 936dba29e..7415bc5fe 100644
--- a/rpc-proxy/package.json
+++ b/rpc-proxy/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-rpc-proxy",
- "version": "0.1.82",
+ "version": "0.1.83",
"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
new file mode 100644
index 000000000..525695e2d
--- /dev/null
+++ b/rpc-proxy/test/bindLoopbackSetup.test.ts
@@ -0,0 +1,60 @@
+import { afterEach, expect, it } from 'vitest'
+import { type Server, createServer } from 'node:http'
+
+// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
+// this package's vitest `setupFiles`.
+//
+// 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.
+const servers: Server[] = []
+
+afterEach(async () => {
+ await Promise.all(
+ servers.splice(0).map(server => new Promise<void>(resolve => server.close(() => resolve())))
+ )
+})
+
+function boundAddress(server: Server): string {
+ 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
+}
+
+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 () => {
+ const numeric = track(createServer())
+ await new Promise<void>(resolve => {
+ numeric.listen(0, () => resolve())
+ })
+ expect(boundAddress(numeric)).toBe('127.0.0.1')
+
+ // 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')
+})
+
+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')
+})
diff --git a/rpc-proxy/vitest.config.ts b/rpc-proxy/vitest.config.ts
index 37b473f54..bc7655069 100644
--- a/rpc-proxy/vitest.config.ts
+++ b/rpc-proxy/vitest.config.ts
@@ -1,8 +1,9 @@
-import { defineConfig } from "vitest/config";
+import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
- include: ["src/**/*.test.ts", "src/**/__tests__/**/*.ts", "test/**/*.test.ts"],
- exclude: ["dist/**", "node_modules/**"],
+ setupFiles: ['../scripts/testing/bind-loopback-in-tests.mjs'],
+ include: ['src/**/*.test.ts', 'src/**/__tests__/**/*.ts', 'test/**/*.test.ts'],
+ exclude: ['dist/**', 'node_modules/**'],
},
-});
+})
diff --git a/scripts/testing/bind-loopback-in-tests.mjs b/scripts/testing/bind-loopback-in-tests.mjs
new file mode 100644
index 000000000..bdfd81e37
--- /dev/null
+++ b/scripts/testing/bind-loopback-in-tests.mjs
@@ -0,0 +1,75 @@
+// Vitest setup file: make an ephemeral bind with no host bind IPv4 loopback.
+//
+// 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.
+//
+// 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
+// to Docker and parses whatever it answers:
+//
+// port 22 mapping -> an SSH banner -> `Parse Error: Expected HTTP/, RTSP/ or ICE/`
+// 8443/2376 mappings -> an HTTP 400 -> a status assertion fails for no reason
+// 5000/32443 -> a reset -> `socket hang up`
+//
+// Whichever request draws the occupied port is the one that fails, so the
+// symptom moves between runs and between cases and reads as flakiness. It
+// aborted T2 run10 in `codex-llm-proxy` test (e).
+//
+// WHY A SHIM RATHER THAN CALL-SITE EDITS
+//
+// 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.
+//
+// WHAT IS AND IS NOT REWRITTEN
+//
+// Only the case where the caller expressed no preference at all: port 0 with no
+// host. An explicit host is honoured, a fixed port is left alone (a fixed port
+// cannot be mis-allocated), and IPC/pipe listens are untouched. Binding a test
+// server on loopback is also what a test means: nothing in this repository
+// tests reachability from another host.
+//
+// This runs only under vitest, through `setupFiles`. No production code path
+// loads it.
+import net from 'node:net'
+
+const LOOPBACK = '127.0.0.1'
+const originalListen = net.Server.prototype.listen
+
+/** 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
+ // 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) {
+ const [first] = args
+
+ if (first === 0 && hostIsAbsent(args)) {
+ return originalListen.call(this, 0, LOOPBACK, ...args.slice(1))
+ }
+
+ if (
+ first !== null &&
+ typeof first === 'object' &&
+ first.port === 0 &&
+ first.host === undefined &&
+ first.path === undefined
+ ) {
+ return originalListen.call(this, { ...first, host: LOOPBACK }, ...args.slice(1))
+ }
+
+ return originalListen.apply(this, args)
+}
diff --git a/webhook-gateway/test/bindLoopbackSetup.test.ts b/webhook-gateway/test/bindLoopbackSetup.test.ts
new file mode 100644
index 000000000..525695e2d
--- /dev/null
+++ b/webhook-gateway/test/bindLoopbackSetup.test.ts
@@ -0,0 +1,60 @@
+import { afterEach, expect, it } from 'vitest'
+import { type Server, createServer } from 'node:http'
+
+// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
+// this package's vitest `setupFiles`.
+//
+// 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.
+const servers: Server[] = []
+
+afterEach(async () => {
+ await Promise.all(
+ servers.splice(0).map(server => new Promise<void>(resolve => server.close(() => resolve())))
+ )
+})
+
+function boundAddress(server: Server): string {
+ 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
+}
+
+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 () => {
+ const numeric = track(createServer())
+ await new Promise<void>(resolve => {
+ numeric.listen(0, () => resolve())
+ })
+ expect(boundAddress(numeric)).toBe('127.0.0.1')
+
+ // 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')
+})
+
+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')
+})
diff --git a/webhook-gateway/vitest.config.ts b/webhook-gateway/vitest.config.ts
index 03d303c38..ae6283203 100644
--- a/webhook-gateway/vitest.config.ts
+++ b/webhook-gateway/vitest.config.ts
@@ -2,6 +2,7 @@ import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
+ setupFiles: ['../scripts/testing/bind-loopback-in-tests.mjs'],
include: ['test/**/*.test.ts', 'src/**/*.test.ts'],
pool: 'forks', // Each test file gets its own process so server bind-port collisions don't cross-contaminate.
},
diff --git a/webhook-proxy/test/bindLoopbackSetup.test.ts b/webhook-proxy/test/bindLoopbackSetup.test.ts
new file mode 100644
index 000000000..525695e2d
--- /dev/null
+++ b/webhook-proxy/test/bindLoopbackSetup.test.ts
@@ -0,0 +1,60 @@
+import { afterEach, expect, it } from 'vitest'
+import { type Server, createServer } from 'node:http'
+
+// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
+// this package's vitest `setupFiles`.
+//
+// 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.
+const servers: Server[] = []
+
+afterEach(async () => {
+ await Promise.all(
+ servers.splice(0).map(server => new Promise<void>(resolve => server.close(() => resolve())))
+ )
+})
+
+function boundAddress(server: Server): string {
+ 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
+}
+
+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 () => {
+ const numeric = track(createServer())
+ await new Promise<void>(resolve => {
+ numeric.listen(0, () => resolve())
+ })
+ expect(boundAddress(numeric)).toBe('127.0.0.1')
+
+ // 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')
+})
+
+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')
+})
diff --git a/webhook-proxy/vitest.config.ts b/webhook-proxy/vitest.config.ts
index c2351b785..de65a9193 100644
--- a/webhook-proxy/vitest.config.ts
+++ b/webhook-proxy/vitest.config.ts
@@ -2,6 +2,7 @@ import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
+ setupFiles: ['../scripts/testing/bind-loopback-in-tests.mjs'],
include: ['test/**/*.test.ts', 'src/**/*.test.ts'],
pool: 'forks',
},
diff --git a/workspace-files-controller/src/__tests__/bindLoopbackSetup.test.ts b/workspace-files-controller/src/__tests__/bindLoopbackSetup.test.ts
new file mode 100644
index 000000000..525695e2d
--- /dev/null
+++ b/workspace-files-controller/src/__tests__/bindLoopbackSetup.test.ts
@@ -0,0 +1,60 @@
+import { afterEach, expect, it } from 'vitest'
+import { type Server, createServer } from 'node:http'
+
+// Witness that `scripts/testing/bind-loopback-in-tests.mjs` is registered in
+// this package's vitest `setupFiles`.
+//
+// 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.
+const servers: Server[] = []
+
+afterEach(async () => {
+ await Promise.all(
+ servers.splice(0).map(server => new Promise<void>(resolve => server.close(() => resolve())))
+ )
+})
+
+function boundAddress(server: Server): string {
+ 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
+}
+
+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 () => {
+ const numeric = track(createServer())
+ await new Promise<void>(resolve => {
+ numeric.listen(0, () => resolve())
+ })
+ expect(boundAddress(numeric)).toBe('127.0.0.1')
+
+ // 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')
+})
+
+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')
+})
diff --git a/workspace-files-controller/vitest.config.ts b/workspace-files-controller/vitest.config.ts
index ed0d5aab7..de23a9c5e 100644
--- a/workspace-files-controller/vitest.config.ts
+++ b/workspace-files-controller/vitest.config.ts
@@ -2,6 +2,7 @@ import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
+ setupFiles: ['../scripts/testing/bind-loopback-in-tests.mjs'],
include: ['src/**/*.test.ts', 'src/**/__tests__/**/*.test.ts'],
exclude: ['dist/**', 'node_modules/**'],
},