Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Fix in-process test rig port handoff (#6599)

Nick Gomezc19056070e65
diff --git a/packages/app/tests/integration/test-harness-port-handoff.test.ts b/packages/app/tests/integration/test-harness-port-handoff.test.ts
new file mode 100644
index 000000000..686ac3f10
--- /dev/null
+++ b/packages/app/tests/integration/test-harness-port-handoff.test.ts
@@ -0,0 +1,67 @@
+import { createServer as createHttpServer } from 'node:http';
+import { Server } from 'node:net';
+import { afterEach, expect, test, vi } from 'vitest';
+
+let createdServer: { destroy: () => Promise<unknown> } | undefined;
+
+vi.mock('@inkeep/open-knowledge-server', async () => {
+ const actual = await vi.importActual<typeof import('@inkeep/open-knowledge-server')>(
+ '@inkeep/open-knowledge-server',
+ );
+ return {
+ ...actual,
+ createServer: (...args: Parameters<typeof actual.createServer>) => {
+ createdServer = actual.createServer(...args);
+ return createdServer;
+ },
+ };
+});
+
+const { createTestServer } = await import('./test-harness');
+
+const originalClose = Server.prototype.close;
+let competitor: ReturnType<typeof createHttpServer> | undefined;
+let competitorListening: Promise<Error | undefined> | undefined;
+let injected = false;
+
+afterEach(async () => {
+ Server.prototype.close = originalClose;
+ if (createdServer !== undefined) {
+ await createdServer.destroy().catch(() => undefined);
+ createdServer = undefined;
+ }
+ if (competitor !== undefined) {
+ await new Promise<void>((resolve) => competitor?.close(() => resolve()));
+ competitor = undefined;
+ }
+ competitorListening = undefined;
+ injected = false;
+});
+
+test('keeps the selected serving port owned until the app rig binds', async () => {
+ Server.prototype.close = function close(callback?: (error?: Error) => void) {
+ const address = this.address();
+ if (!injected && typeof address === 'object' && address !== null) {
+ injected = true;
+ return originalClose.call(this, (error?: Error) => {
+ const rival = createHttpServer((_request, response) => response.end('competitor'));
+ competitor = rival;
+ competitorListening = new Promise<Error | undefined>((resolve) => {
+ rival.once('error', resolve);
+ rival.listen(address.port, '127.0.0.1', () => resolve(undefined));
+ });
+ void competitorListening.then(() => callback?.(error));
+ });
+ }
+ return originalClose.call(this, callback);
+ };
+
+ const server = await createTestServer({ ephemeral: true });
+ Server.prototype.close = originalClose;
+ const releasedAddressedPortDuringSetup = injected;
+ await server.cleanup();
+ createdServer = undefined;
+
+ expect(await competitorListening).toBeUndefined();
+ expect(releasedAddressedPortDuringSetup).toBe(false);
+});
diff --git a/packages/app/tests/integration/test-harness.ts b/packages/app/tests/integration/test-harness.ts
index fca5deff1..975cc654f 100644
--- a/packages/app/tests/integration/test-harness.ts
+++ b/packages/app/tests/integration/test-harness.ts
@@ -52,6 +52,7 @@ import { yXmlFragmentToProseMirrorRootNode } from '@tiptap/y-tiptap';
import * as Y from 'yjs';
import { configureTestGitRepository } from '../../../../test-support/configure-git-fixture.test-helper.ts';
import { testAuthorityRegistryPath } from '../../../../test-support/server-authority-registry.test-helper.ts';
+import { listenOnLoopback } from '../../../server/src/loopback-rig-test-helpers.ts';
import {
ORIGIN_TEXT_TO_TREE,
ORIGIN_TREE_TO_TEXT,
@@ -61,7 +62,6 @@ import type { ProviderPool } from '../../src/editor/provider-pool';
import { dispatchCC1Stateless, SYSTEM_DOC_NAME } from '../../src/lib/cc1';
import { createSyncedReconnectGate, refreshServerInfo } from '../../src/lib/server-info-refresh';
import { getServerInstanceId } from '../../src/lib/server-instance-store';
-import { getFreePort } from '../free-port.test-helper.ts';
import {
removeAllDuringTeardown,
removeAllStrictDuringTeardown,
@@ -163,7 +163,6 @@ export async function createTestServer(options: CreateTestServerOptions = {}): P
}
}
- port = await getFreePort();
srv = createServer({
authorityRegistryPath: options.authorityRegistryPath ?? testAuthorityRegistryPath,
contentDir,
@@ -223,17 +222,7 @@ export async function createTestServer(options: CreateTestServerOptions = {}): P
keepaliveGraceMs: options.keepaliveGraceMs,
});
- await new Promise<void>((resolve, reject) => {
- const onErr = (err: Error): void => {
- httpServer.off('error', onErr);
- reject(err);
- };
- httpServer.once('error', onErr);
- httpServer.listen(port, '127.0.0.1', () => {
- httpServer.off('error', onErr);
- resolve();
- });
- });
+ ({ port } = await listenOnLoopback(httpServer));
return {
port,
@@ -1077,7 +1066,6 @@ export interface InspectableServer {
}
export interface CreateInspectableServerOptions extends CreateTestServerOptions {
- port?: number;
gitEnabled?: boolean;
commitDebounceMs?: number;
}
@@ -1121,7 +1109,6 @@ export async function createInspectableServer(
await ensureProjectGit(contentDir);
configureTestGitRepository(contentDir);
- const port = options.port ?? (await getFreePort());
const srv = createServer({
authorityRegistryPath: options.authorityRegistryPath ?? testAuthorityRegistryPath,
contentDir,
@@ -1158,37 +1145,7 @@ export async function createInspectableServer(
});
const wss = mount.wss;
- const listenWithRetry = async (): Promise<void> => {
- const deadline = Date.now() + 2500;
- let lastErr: unknown;
- while (Date.now() < deadline) {
- try {
- await new Promise<void>((resolve, reject) => {
- const onErr = (err: Error): void => {
- httpServer.off('error', onErr);
- reject(err);
- };
- httpServer.once('error', onErr);
- httpServer.listen(port, '127.0.0.1', () => {
- httpServer.off('error', onErr);
- resolve();
- });
- });
- return;
- } catch (err) {
- lastErr = err;
- const code = (err as NodeJS.ErrnoException)?.code;
- if (code !== 'EADDRINUSE') throw err;
- await wait(100);
- }
- }
- throw new Error(
- `createRestartableServer: could not bind port ${port} within 2500ms; last error: ${
- lastErr instanceof Error ? lastErr.message : String(lastErr)
- }`,
- );
- };
- await listenWithRetry();
+ const { port } = await listenOnLoopback(httpServer);
let networkKilled = false;
diff --git a/packages/server/src/health-routes.test.ts b/packages/server/src/health-routes.test.ts
index 89eac2d06..0f96e611d 100644
--- a/packages/server/src/health-routes.test.ts
+++ b/packages/server/src/health-routes.test.ts
@@ -12,7 +12,7 @@ import {
type RawResponse,
rawRequest,
} from './composition-rig.test-helper.ts';
-import { getFreeLoopbackPort } from './loopback-rig-test-helpers.ts';
+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';
import { mountMcpAndApi } from './mcp-mount.ts';
let tmpRoot: string;
@@ -162,8 +162,7 @@ describe('/readyz provider states (mounted harness)', () => {
? {}
: { health: { readiness: () => readiness, degraded: () => ['shadow-repo'] } }),
});
- const port = await getFreeLoopbackPort();
- await new Promise<void>((r) => httpServer.listen(port, '127.0.0.1', () => r()));
+ const { port } = await listenOnLoopback(httpServer);
try {
const res = await fetch(`http://127.0.0.1:${port}/readyz`);
return {
@@ -209,8 +208,7 @@ describe('/readyz provider states (mounted harness)', () => {
degraded: () => [],
},
});
- const port = await getFreeLoopbackPort();
- await new Promise<void>((r) => httpServer.listen(port, '127.0.0.1', () => r()));
+ const { port } = await listenOnLoopback(httpServer);
try {
const res = await fetch(`http://127.0.0.1:${port}/readyz`);
expect(res.status).toBe(500);
diff --git a/packages/server/src/loopback-rig-test-helpers.ts b/packages/server/src/loopback-rig-test-helpers.ts
index 848bfad11..3a3cc676f 100644
--- a/packages/server/src/loopback-rig-test-helpers.ts
+++ b/packages/server/src/loopback-rig-test-helpers.ts
@@ -1,5 +1,4 @@
import type { Server } from 'node:http';
-import { createServer } from 'node:http';
export interface LoopbackListenResult {
port: number;
@@ -23,22 +22,3 @@ export function listenOnLoopback(server: Server): Promise<LoopbackListenResult>
});
});
}
-
-export function getFreeLoopbackPort(): Promise<number> {
- return new Promise((resolve, reject) => {
- const probe = createServer();
- probe.once('error', reject);
- probe.listen(0, '127.0.0.1', () => {
- const addr = probe.address();
- if (typeof addr !== 'object' || addr === null) {
- probe.removeListener('error', reject);
- probe.close(() =>
- reject(new Error('getFreeLoopbackPort: probe.address() returned no port')),
- );
- return;
- }
- const { port } = addr;
- probe.close(() => resolve(port));
- });
- });
-}
diff --git a/packages/server/src/mcp-http.test.ts b/packages/server/src/mcp-http.test.ts
index f7f61defc..3d25c10c8 100644
--- a/packages/server/src/mcp-http.test.ts
+++ b/packages/server/src/mcp-http.test.ts
@@ -5,7 +5,7 @@ import { join } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
import { afterEach, beforeEach, expect, test } from 'vitest';
import { type Config, ConfigSchema } from './config/schema.ts';
-import { getFreeLoopbackPort } from './loopback-rig-test-helpers.ts';
+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';
import { MCP_CONNECTION_ID_HEADER, MCP_HOSTED_AGENT_HEADER } from './mcp/agent-identity.ts';
import {
createMcpHttpHandler,
@@ -26,9 +26,9 @@ async function bootHandler(
handlerOptions: Partial<Pick<McpHttpHandlerOptions, 'log' | 'maxSessions' | 'sessionTtlMs'>> = {},
): Promise<SessionHarness> {
const contentDir = mkdtempSync(join(tmpdir(), 'ok-mcp-http-cfg-'));
- const port = await getFreeLoopbackPort();
let handler: McpHttpHandler | null = null;
let httpServer: HttpServer | null = null;
+ let port = 0;
try {
handler = createMcpHttpHandler({
contentDir,
@@ -53,10 +53,7 @@ async function bootHandler(
res.writeHead(404);
res.end('Not found');
});
- await new Promise<void>((res) => {
- // biome-ignore lint/style/noNonNullAssertion: httpServer is set inside the try
- httpServer!.listen(port, '127.0.0.1', () => res());
- });
+ port = (await listenOnLoopback(httpServer)).port;
} catch (err) {
if (httpServer) await new Promise<void>((res) => httpServer?.close(() => res()));
if (handler) await handler.close();
@@ -248,9 +245,9 @@ test('PRD-6659: tools/call write with an invalid position returns field name + a
test('forwarded connectionId header reaches /api/agent-write-md as agentId', async () => {
const config: Config = ConfigSchema.parse({});
const contentDir = mkdtempSync(join(tmpdir(), 'ok-mcp-http-cid-'));
- const port = await getFreeLoopbackPort();
let handler: McpHttpHandler | null = null;
let httpServer: HttpServer | null = null;
+ let port = 0;
let capturedAgentId: string | undefined;
try {
@@ -291,10 +288,7 @@ test('forwarded connectionId header reaches /api/agent-write-md as agentId', asy
res.writeHead(404);
res.end('Not found');
});
- await new Promise<void>((res) => {
- // biome-ignore lint/style/noNonNullAssertion: httpServer set above
- httpServer!.listen(port, '127.0.0.1', () => res());
- });
+ port = (await listenOnLoopback(httpServer)).port;
const forwarded = 'forwarded-keepalive-id-1234';
@@ -370,9 +364,9 @@ test('forwarded connectionId header reaches /api/agent-write-md as agentId', asy
test('invalid connectionId header is ignored — session falls back to a fresh UUID', async () => {
const config: Config = ConfigSchema.parse({});
const contentDir = mkdtempSync(join(tmpdir(), 'ok-mcp-http-cid-bad-'));
- const port = await getFreeLoopbackPort();
let handler: McpHttpHandler | null = null;
let httpServer: HttpServer | null = null;
+ let port = 0;
let capturedAgentId: string | undefined;
const warnCalls: Array<{ obj: object; msg: string }> = [];
@@ -419,10 +413,7 @@ test('invalid connectionId header is ignored — session falls back to a fresh U
res.writeHead(404);
res.end('Not found');
});
- await new Promise<void>((res) => {
- // biome-ignore lint/style/noNonNullAssertion: httpServer set above
- httpServer!.listen(port, '127.0.0.1', () => res());
- });
+ port = (await listenOnLoopback(httpServer)).port;
const forwarded = 'bad value with spaces!';
diff --git a/packages/server/src/mcp-mount.test.ts b/packages/server/src/mcp-mount.test.ts
index e01759cc6..666bf9169 100644
--- a/packages/server/src/mcp-mount.test.ts
+++ b/packages/server/src/mcp-mount.test.ts
@@ -17,7 +17,7 @@ import {
__resetWarnedForwardedHeaderRefusalForTests,
buildIngressPolicy,
} from './ingress-policy.ts';
-import { getFreeLoopbackPort } from './loopback-rig-test-helpers.ts';
+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';
import type { McpHttpHandler } from './mcp-http.ts';
import {
type MountMcpAndApiHandle,
@@ -55,8 +55,7 @@ async function startMountedServer(
mcpHttpHandler: handler,
log,
});
- const port = await getFreeLoopbackPort();
- await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));
+ const { port } = await listenOnLoopback(httpServer);
servers.push({ httpServer, mount });
return { port, mount };
}
@@ -333,8 +332,7 @@ describe('mountMcpAndApi shutdown drains live WS clients', () => {
test(`drains live ${path.split('?')[0]} WS so wss.close + httpServer.close resolve promptly`, async () => {
const httpServer = createServer();
const mount = mountMcpAndApi({ httpServer, nativeApi: undefined, hocuspocus, log });
- const port = await getFreeLoopbackPort();
- await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));
+ const { port } = await listenOnLoopback(httpServer);
const client = new WebSocket(`ws://127.0.0.1:${port}${path}`);
client.on('error', () => {});
@@ -407,8 +405,7 @@ describe('mountMcpAndApi content-asset middleware', () => {
blocklistExtensions: EXECUTABLE_BLOCKLIST_EXTENSIONS,
}),
});
- const port = await getFreeLoopbackPort();
- await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));
+ const { port } = await listenOnLoopback(httpServer);
servers.push({ httpServer, mount });
return { port };
}
@@ -463,8 +460,7 @@ describe('mountMcpAndApi content-asset middleware', () => {
throw new Error('simulated EMFILE');
},
});
- const port = await getFreeLoopbackPort();
- await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));
+ const { port } = await listenOnLoopback(httpServer);
servers.push({ httpServer, mount });
const res = await fetch(`http://127.0.0.1:${port}/assets/x.png`);
@@ -509,8 +505,7 @@ describe('mountMcpAndApi ephemeral content-asset gate', () => {
ingressPolicy: buildIngressPolicy({}),
}),
});
- const port = await getFreeLoopbackPort();
- await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));
+ const { port } = await listenOnLoopback(httpServer);
servers.push({ httpServer, mount });
return { port };
}
@@ -574,8 +569,7 @@ describe('mountMcpAndApi react-shell middleware', () => {
immutable: true,
}),
});
- const port = await getFreeLoopbackPort();
- await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));
+ const { port } = await listenOnLoopback(httpServer);
servers.push({ httpServer, mount });
return { port, shellDir };
}
diff --git a/packages/server/src/remote-mcp.test.ts b/packages/server/src/remote-mcp.test.ts
index 601cc0c8c..76646a65d 100644
--- a/packages/server/src/remote-mcp.test.ts
+++ b/packages/server/src/remote-mcp.test.ts
@@ -12,7 +12,7 @@ import { resolveServerRuntimeConfig } from '@inkeep/open-knowledge-core';
import { afterEach, describe, expect, test } from 'vitest';
import { ConfigSchema } from './config/schema.ts';
import { buildIngressPolicy } from './ingress-policy.ts';
-import { getFreeLoopbackPort } from './loopback-rig-test-helpers.ts';
+import { listenOnLoopback } from './loopback-rig-test-helpers.ts';
import { createMcpHttpHandler, type McpHttpHandler } from './mcp-http.ts';
import { type MountMcpAndApiHandle, mountMcpAndApi } from './mcp-mount.ts';
@@ -69,7 +69,6 @@ async function bootRemoteRig(externalUrl: string | null, extras: RigExtras = {})
const config = ConfigSchema.parse(
externalUrl === null ? {} : { server: { externalUrl, allowExternal: true } },
);
- const port = await getFreeLoopbackPort();
const handler: McpHttpHandler = createMcpHttpHandler({
contentDir,
projectDir: contentDir,
@@ -89,7 +88,7 @@ async function bootRemoteRig(externalUrl: string | null, extras: RigExtras = {})
: {}),
log,
});
- await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));
+ const { port } = await listenOnLoopback(httpServer);
const rig: Rig = {
port,
contentDir,