Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Route Vite through the collaboration host (#3053)

Dimitri POSTOLOVe87fef724681
diff --git a/.changeset/centralize-collaboration-host.md b/.changeset/centralize-collaboration-host.md
new file mode 100644
index 000000000..7af636fd1
--- /dev/null
+++ b/.changeset/centralize-collaboration-host.md
@@ -0,0 +1,6 @@
+---
+"@inkeep/open-knowledge": patch
+"@inkeep/open-knowledge-server": patch
+---
+
+Route the Vite development server through the same collaboration WebSocket host as `ok start`, so `/collab`, `/collab/keepalive`, and `/collab/thread` share admission, message-size, presence-cleanup, and shutdown behavior. This removes the duplicated upgrade stack that could drift between development and production.
diff --git a/packages/app/src/server/hocuspocus-plugin.test.ts b/packages/app/src/server/hocuspocus-plugin.test.ts
index 5c4cbcf7b..dd90f39f2 100644
--- a/packages/app/src/server/hocuspocus-plugin.test.ts
+++ b/packages/app/src/server/hocuspocus-plugin.test.ts
@@ -97,10 +97,43 @@ describe('hocuspocusPlugin.configureServer middleware ordering', () => {
innerAssetCalls += 1;
};
const createAssetServeMiddlewareSpy = vi.fn(() => innerAssetFn);
+ const handleUpgrade = vi.fn(() => false);
+ const teardownOrder: string[] = [];
+ let resolveHostShutdown: (() => void) | undefined;
+ const hostShutdown = new Promise<void>((resolve) => {
+ resolveHostShutdown = resolve;
+ });
+ const fakeHost = {
+ handleUpgrade,
+ shutdown: vi.fn(async () => {
+ teardownOrder.push('host');
+ await hostShutdown;
+ }),
+ wss: {
+ close: (done: (err?: Error) => void) => {
+ teardownOrder.push('wss');
+ done();
+ },
+ },
+ };
+ const createCollaborationHostSpy = vi.fn(() => fakeHost);
+ const acpInit = vi.fn(async () => {});
+ const acpDestroy = vi.fn(async () => {
+ teardownOrder.push('acp');
+ });
+ class FakeAcpThreadManager {
+ init = acpInit;
+ destroy = acpDestroy;
+ }
+ const destroyServer = vi.fn(async () => {
+ teardownOrder.push('server');
+ });
vi.doMock('@inkeep/open-knowledge-server', () => ({
...actualServerPkg,
+ AcpThreadManager: FakeAcpThreadManager,
createAssetServeMiddleware: createAssetServeMiddlewareSpy,
+ createCollaborationHost: createCollaborationHostSpy,
createServer: () => ({
lockDir: testContentDir,
contentFilter: { isPathIgnored: () => false },
@@ -115,7 +148,8 @@ describe('hocuspocusPlugin.configureServer middleware ordering', () => {
sessionManager: { closeAllForAgent: async () => {} },
agentFocusBroadcaster: { clearFocus: () => {} },
agentPresenceBroadcaster: { clearPresence: () => {}, bumpPresenceTs: () => {} },
- destroy: async () => {},
+ maintenanceCoordinator: {},
+ destroy: destroyServer,
}),
handleCollabSocketError: () => false,
parseKeepaliveConnectionId: () => null,
@@ -160,6 +194,14 @@ describe('hocuspocusPlugin.configureServer middleware ordering', () => {
// Asset middleware factory was called exactly once.
expect(createAssetServeMiddlewareSpy).toHaveBeenCalledTimes(1);
+ expect(createCollaborationHostSpy).toHaveBeenCalledTimes(1);
+ expect(createCollaborationHostSpy).toHaveBeenCalledWith(
+ expect.objectContaining({
+ maintenanceCoordinator: expect.anything(),
+ hocuspocus: expect.anything(),
+ }),
+ );
+ expect(httpServer.listeners('upgrade')).toEqual([handleUpgrade]);
// Two middlewares were registered synchronously: the asset wrapper +
// the api handler.
@@ -204,5 +246,281 @@ describe('hocuspocusPlugin.configureServer middleware ordering', () => {
assetWrapper({ url: nonBypassUrl }, {}, () => {});
}
expect(innerAssetCalls).toBe(4);
+
+ let buildEndSettled = false;
+ const buildEnd = Promise.resolve(plugin.buildEnd?.call(plugin)).then(() => {
+ buildEndSettled = true;
+ });
+ await new Promise((resolve) => setTimeout(resolve, 0));
+ expect(fakeHost.shutdown).toHaveBeenCalledOnce();
+ expect(buildEndSettled).toBe(false);
+ httpServer.emit('close');
+ expect(fakeHost.shutdown).toHaveBeenCalledOnce();
+ expect(teardownOrder).toEqual(['acp', 'host']);
+ resolveHostShutdown?.();
+ await buildEnd;
+ expect(buildEndSettled).toBe(true);
+ expect(fakeHost.shutdown).toHaveBeenCalledOnce();
+ expect(acpDestroy).toHaveBeenCalledOnce();
+ expect(destroyServer).toHaveBeenCalledOnce();
+ expect(teardownOrder).toEqual(['acp', 'host', 'wss', 'server']);
+ expect(httpServer.listeners('upgrade')).toEqual([]);
+ });
+
+ test('buildEnd awaits every overlapping configureServer runtime', async () => {
+ const testContentDir = mkTmp();
+ process.env.OK_TEST_CONTENT_DIR = testContentDir;
+ const shutdowns = [Promise.withResolvers<void>(), Promise.withResolvers<void>()];
+ const destroyServers = [vi.fn(async () => {}), vi.fn(async () => {})];
+ const hosts = shutdowns.map((shutdown) => ({
+ handleUpgrade: vi.fn(() => false),
+ shutdown: vi.fn(() => shutdown.promise),
+ wss: { close: (done: (err?: Error) => void) => done() },
+ }));
+ let serverIndex = 0;
+ let hostIndex = 0;
+ class FakeAcpThreadManager {
+ async init(): Promise<void> {}
+ async destroy(): Promise<void> {}
+ }
+ vi.doMock('@inkeep/open-knowledge-server', () => ({
+ ...actualServerPkg,
+ AcpThreadManager: FakeAcpThreadManager,
+ createAssetServeMiddleware: () => () => {},
+ createCollaborationHost: () => {
+ const host = hosts[hostIndex++];
+ if (host === undefined) throw new Error('missing fake host');
+ return host;
+ },
+ createServer: () => {
+ const destroy = destroyServers[serverIndex++];
+ if (destroy === undefined) throw new Error('missing fake server');
+ return {
+ lockDir: testContentDir,
+ contentFilter: { isPathIgnored: () => false, isExcluded: () => false },
+ hocuspocus: { hooks: async () => {} },
+ sessionManager: {},
+ agentFocusBroadcaster: {},
+ agentPresenceBroadcaster: {},
+ maintenanceCoordinator: {},
+ destroy,
+ };
+ },
+ getLogger: () => ({ info: () => {}, error: () => {} }),
+ makeLazyEmbeddingsKeyStore: () => ({}),
+ releaseServerLock: () => {},
+ updateServerLockPort: () => {},
+ }));
+ const { hocuspocusPlugin } = await import('./hocuspocus-plugin.ts?overlap-test');
+ const makeViteServer = () => {
+ const httpServer = new EventEmitter() as EventEmitter & {
+ address: () => null;
+ };
+ httpServer.address = () => null;
+ const middlewares = { use: () => middlewares };
+ return { httpServer, middlewares };
+ };
+ const plugin = hocuspocusPlugin();
+ const first = makeViteServer();
+ const second = makeViteServer();
+ // biome-ignore lint/suspicious/noExplicitAny: EventEmitter Vite stub
+ await (plugin.configureServer as any).call(plugin, first);
+ // biome-ignore lint/suspicious/noExplicitAny: EventEmitter Vite stub
+ await (plugin.configureServer as any).call(plugin, second);
+
+ let buildEndSettled = false;
+ const buildEnd = Promise.resolve(plugin.buildEnd?.call(plugin)).then(() => {
+ buildEndSettled = true;
+ });
+ await new Promise((resolve) => setImmediate(resolve));
+ for (const host of hosts) expect(host.shutdown).toHaveBeenCalledOnce();
+ expect(buildEndSettled).toBe(false);
+ shutdowns[0]?.resolve();
+ await new Promise((resolve) => setImmediate(resolve));
+ expect(buildEndSettled).toBe(false);
+ shutdowns[1]?.resolve();
+ await buildEnd;
+ expect(buildEndSettled).toBe(true);
+ for (const destroy of destroyServers) expect(destroy).toHaveBeenCalledOnce();
+ });
+
+ test('bounds WebSocket close and force-terminates clients before continuing teardown', async () => {
+ vi.useFakeTimers();
+ try {
+ const testContentDir = mkTmp();
+ process.env.OK_TEST_CONTENT_DIR = testContentDir;
+ const order: string[] = [];
+ const logger = { info: vi.fn(), error: vi.fn() };
+ const terminateClient = vi.fn(() => {
+ order.push('client');
+ });
+ class FakeAcpThreadManager {
+ async init(): Promise<void> {}
+ async destroy(): Promise<void> {
+ order.push('acp');
+ }
+ }
+ const host = {
+ handleUpgrade: vi.fn(() => false),
+ shutdown: vi.fn(async () => {
+ order.push('host');
+ }),
+ wss: {
+ clients: new Set([{ terminate: terminateClient }]),
+ close: vi.fn((_done: (err?: Error) => void) => {
+ order.push('wss');
+ }),
+ },
+ };
+ const destroy = vi.fn(async () => {
+ order.push('server');
+ });
+ vi.doMock('@inkeep/open-knowledge-server', () => ({
+ ...actualServerPkg,
+ AcpThreadManager: FakeAcpThreadManager,
+ createAssetServeMiddleware: () => () => {},
+ createCollaborationHost: () => host,
+ createServer: () => ({
+ lockDir: testContentDir,
+ contentFilter: { isPathIgnored: () => false, isExcluded: () => false },
+ hocuspocus: { hooks: async () => {} },
+ sessionManager: {},
+ agentFocusBroadcaster: {},
+ agentPresenceBroadcaster: {},
+ maintenanceCoordinator: {},
+ destroy,
+ }),
+ getLogger: () => logger,
+ makeLazyEmbeddingsKeyStore: () => ({}),
+ releaseServerLock: () => {},
+ updateServerLockPort: () => {},
+ }));
+ const { hocuspocusPlugin } = await import('./hocuspocus-plugin.ts?wss-timeout-test');
+ const httpServer = new EventEmitter() as EventEmitter & { address: () => null };
+ httpServer.address = () => null;
+ const middlewares = { use: () => middlewares };
+ const plugin = hocuspocusPlugin();
+ // biome-ignore lint/suspicious/noExplicitAny: EventEmitter Vite stub
+ await (plugin.configureServer as any).call(plugin, { httpServer, middlewares });
+
+ let buildEndSettled = false;
+ const buildEndResult = Promise.resolve(plugin.buildEnd?.call(plugin)).then(
+ () => {
+ buildEndSettled = true;
+ return undefined;
+ },
+ (err: unknown) => {
+ buildEndSettled = true;
+ return err;
+ },
+ );
+ await vi.advanceTimersByTimeAsync(0);
+ expect(order).toEqual(['acp', 'host', 'wss']);
+ expect(buildEndSettled).toBe(false);
+
+ await vi.advanceTimersByTimeAsync(4_999);
+ expect(terminateClient).not.toHaveBeenCalled();
+ expect(buildEndSettled).toBe(false);
+
+ await vi.advanceTimersByTimeAsync(1);
+ const buildEndError = await buildEndResult;
+ expect(buildEndError).toBeInstanceOf(AggregateError);
+ expect(terminateClient).toHaveBeenCalledOnce();
+ expect(host.wss.close).toHaveBeenCalledOnce();
+ expect(destroy).toHaveBeenCalledOnce();
+ expect(order).toEqual(['acp', 'host', 'wss', 'client', 'server']);
+ expect(logger.error).toHaveBeenCalledWith(
+ expect.objectContaining({ err: expect.any(Error) }),
+ 'Vite collaboration teardown failed: WebSocket server',
+ );
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ test('propagates buildEnd AggregateError and contains HTTP-close fallback failures', async () => {
+ const testContentDir = mkTmp();
+ process.env.OK_TEST_CONTENT_DIR = testContentDir;
+ const order: string[] = [];
+ const logger = { info: vi.fn(), error: vi.fn() };
+ class FakeAcpThreadManager {
+ async init(): Promise<void> {}
+ async destroy(): Promise<void> {
+ order.push('acp');
+ throw new Error('acp failed');
+ }
+ }
+ const host = {
+ handleUpgrade: vi.fn(() => false),
+ shutdown: vi.fn(async () => {
+ order.push('host');
+ throw new Error('host failed');
+ }),
+ wss: {
+ close: (done: (err?: Error) => void) => {
+ order.push('wss');
+ done(new Error('wss failed'));
+ },
+ },
+ };
+ const destroy = vi.fn(async () => {
+ order.push('server');
+ throw new Error('server failed');
+ });
+ vi.doMock('@inkeep/open-knowledge-server', () => ({
+ ...actualServerPkg,
+ AcpThreadManager: FakeAcpThreadManager,
+ createAssetServeMiddleware: () => () => {},
+ createCollaborationHost: () => host,
+ createServer: () => ({
+ lockDir: testContentDir,
+ contentFilter: { isPathIgnored: () => false, isExcluded: () => false },
+ hocuspocus: { hooks: async () => {} },
+ sessionManager: {},
+ agentFocusBroadcaster: {},
+ agentPresenceBroadcaster: {},
+ maintenanceCoordinator: {},
+ destroy,
+ }),
+ getLogger: () => logger,
+ makeLazyEmbeddingsKeyStore: () => ({}),
+ releaseServerLock: () => {},
+ updateServerLockPort: () => {},
+ }));
+ const { hocuspocusPlugin } = await import('./hocuspocus-plugin.ts?fallback-test');
+ const httpServer = new EventEmitter() as EventEmitter & { address: () => null };
+ httpServer.address = () => null;
+ const middlewares = { use: () => middlewares };
+ const plugin = hocuspocusPlugin();
+ // biome-ignore lint/suspicious/noExplicitAny: EventEmitter Vite stub
+ await (plugin.configureServer as any).call(plugin, { httpServer, middlewares });
+
+ const buildEndError: unknown = await Promise.resolve(plugin.buildEnd?.call(plugin)).then(
+ () => undefined,
+ (err: unknown) => err,
+ );
+
+ expect(buildEndError).toBeInstanceOf(AggregateError);
+ if (!(buildEndError instanceof AggregateError)) {
+ throw new Error('buildEnd did not propagate an AggregateError');
+ }
+ expect(buildEndError.message).toBe('Hocuspocus Vite teardown failed');
+ expect(buildEndError.errors).toHaveLength(1);
+ const runtimeError = buildEndError.errors[0];
+ expect(runtimeError).toBeInstanceOf(AggregateError);
+ if (!(runtimeError instanceof AggregateError)) {
+ throw new Error('runtime teardown did not aggregate phase failures');
+ }
+ expect(runtimeError.message).toBe('Vite collaboration teardown failed');
+ expect(runtimeError.errors).toHaveLength(4);
+ expect(order).toEqual(['acp', 'host', 'wss', 'server']);
+
+ httpServer.emit('close');
+ await new Promise((resolve) => setTimeout(resolve, 0));
+ expect(logger.error).toHaveBeenCalledWith(
+ expect.objectContaining({ err: expect.any(AggregateError) }),
+ 'HTTP close fallback teardown failed',
+ );
+ await expect(plugin.buildEnd?.call(plugin)).resolves.toBeUndefined();
});
});
diff --git a/packages/app/src/server/hocuspocus-plugin.ts b/packages/app/src/server/hocuspocus-plugin.ts
index 99a08896c..0327ca7c5 100644
--- a/packages/app/src/server/hocuspocus-plugin.ts
+++ b/packages/app/src/server/hocuspocus-plugin.ts
@@ -23,21 +23,18 @@ import {
} from '@inkeep/open-knowledge-core';
import {
AcpThreadManager,
- attachAcpThreadSocket,
buildOkMcpStdioCommand,
createAssetServeMiddleware,
+ createCollaborationHost,
createServer,
getLogger,
- handleCollabSocketError,
makeLazyEmbeddingsKeyStore,
- parseKeepaliveConnectionId,
releaseServerLock,
- toBroadcasterKey,
updateServerLockPort,
} from '@inkeep/open-knowledge-server';
import sirv from 'sirv';
import type { Plugin } from 'vite';
-import { WebSocketServer } from 'ws';
+import type { WebSocketServer } from 'ws';
import { parse as parseYaml } from 'yaml';
import { computeDevApiConfigResponse } from './api-config-handler.ts';
@@ -101,9 +98,6 @@ const TEST_PROJECT_DIR = process.env.OK_TEST_PROJECT_DIR
? realpathSync(process.env.OK_TEST_PROJECT_DIR)
: undefined;
-const KEEPALIVE_GRACE_MS = 10_000;
-const MAX_COLLAB_MESSAGE_BYTES = 1024 * 1024;
-
// Gate the process.once('exit', ...) registration to avoid tripping
// MaxListenersExceededWarning after ~10 Vite restarts. The exit handler
// reads `latestLockDir` inside its closure so a Vite restart that swaps
@@ -112,17 +106,66 @@ const MAX_COLLAB_MESSAGE_BYTES = 1024 * 1024;
let exitHandlerRegistered = false;
let latestLockDir: string | null = null;
+const VITE_WSS_CLOSE_TIMEOUT_MS = 5_000;
+
+function closeWebSocketServer(wss: WebSocketServer): Promise<void> {
+ return new Promise<void>((resolve, reject) => {
+ let settled = false;
+ const timer = setTimeout(() => {
+ if (settled) return;
+ settled = true;
+ const terminationErrors: unknown[] = [];
+ for (const client of wss.clients) {
+ try {
+ client.terminate();
+ } catch (err) {
+ terminationErrors.push(err);
+ }
+ }
+ const timeoutError = new Error(
+ `WebSocket server close timed out after ${VITE_WSS_CLOSE_TIMEOUT_MS}ms`,
+ );
+ reject(
+ terminationErrors.length === 0
+ ? timeoutError
+ : new AggregateError(
+ [timeoutError, ...terminationErrors],
+ 'WebSocket server close timed out and client termination failed',
+ ),
+ );
+ }, VITE_WSS_CLOSE_TIMEOUT_MS);
+ timer.unref?.();
+
+ const settle = (err?: unknown): void => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(timer);
+ if (err) reject(err);
+ else resolve();
+ };
+
+ try {
+ wss.close(settle);
+ } catch (err) {
+ settle(err);
+ }
+ });
+}
+
export function hocuspocusPlugin(): Plugin {
+ const activeRuntimeTeardowns = new Set<() => Promise<void>>();
return {
name: 'hocuspocus',
+ async buildEnd() {
+ const results = await Promise.allSettled(
+ [...activeRuntimeTeardowns].map((teardown) => teardown()),
+ );
+ const errors = results
+ .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
+ .map((result) => result.reason);
+ if (errors.length > 0) throw new AggregateError(errors, 'Hocuspocus Vite teardown failed');
+ },
async configureServer(server) {
- // Per-invocation closure state. On Vite restart the OLD close handler
- // sets its own `shuttingDown = true` on its own binding; the NEW
- // invocation starts fresh. Mirrors boot.ts's closure shape.
- const keepaliveGraceTimers = new Map<string, ReturnType<typeof setTimeout>>();
- const keepaliveGraceInflight = new Set<Promise<void>>();
- let shuttingDown = false;
-
configureServerInvocations += 1;
if (configureServerInvocations > 1) {
console.warn(
@@ -223,229 +266,16 @@ export function hocuspocusPlugin(): Plugin {
// Rehydrate archived threads before the first `list` can arrive.
await acpThreadManager?.init();
- const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_COLLAB_MESSAGE_BYTES });
- wss.on('error', (err) => {
- console.error('[collab] WebSocketServer error:', err);
- });
-
- // `prependListener` intercepts /collab BEFORE Vite's HMR handler.
- //
- // Instrumented because `/collab` has reported-but-non-reproducible
- // failure modes where the HTTP Upgrade never completes (Chrome shows
- // Status: pending, 0 B). The four log lines below pinpoint where in
- // the chain a stuck connection halted:
- //
- // [collab] upgrade received … — event reached our listener
- // [collab] handleUpgrade starting — path matched, pre-ws handoff
- // [collab] handleUpgrade threw … — sync throw (e.g. double-upgrade)
- // [collab] handshake complete … — 101 sent; hocuspocus takes over
- //
- // If a stuck WS report shows none of these lines for the offending
- // connection, the upgrade never reached this listener.
- server.httpServer?.prependListener('upgrade', (req, socket, head) => {
- if (!req.url?.startsWith('/collab')) return;
-
- console.info(
- `[collab] upgrade received url=${req.url} protocol=${req.headers['sec-websocket-protocol'] ?? 'none'} host=${req.headers.host ?? 'none'} origin=${req.headers.origin ?? 'none'}`,
- );
-
- // ACP agent-thread frames — bare WS, never Hocuspocus. Mirrors the
- // `/collab/thread` branch in mcp-mount.ts (drift hazard: keep both).
- if (req.url.startsWith('/collab/thread')) {
- if (acpThreadManager === null) {
- socket.destroy();
- return;
- }
- socket.on('error', (err: NodeJS.ErrnoException) => {
- if (handleCollabSocketError(err)) return;
- console.error('[collab] ACP thread socket error:', err);
- });
- try {
- wss.handleUpgrade(req, socket, head, (ws) => {
- attachAcpThreadSocket(ws, acpThreadManager, getLogger('acp-threads'));
- });
- } catch (err) {
- console.error(`[collab] thread handleUpgrade threw for ${req.url}:`, err);
- try {
- socket.destroy();
- } catch {
- // Already-destroyed — swallow.
- }
- }
- return;
- }
-
- // `ok mcp` holds a persistent WS to /collab/keepalive?connectionId=<id>
- // to register as an active client. Must route as a bare WS — MCP
- // never sends sync-step-1 that Hocuspocus waits for, so routing
- // through hocuspocus.handleConnection would leave the socket
- // half-initialized in the connection registry.
- if (req.url.startsWith('/collab/keepalive')) {
- socket.on('error', (err: NodeJS.ErrnoException) => {
- if (handleCollabSocketError(err)) return;
- console.error('[collab] MCP keepalive socket error:', err);
- });
- console.info(`[collab] keepalive handleUpgrade starting for ${req.url}`);
- try {
- wss.handleUpgrade(req, socket, head, (ws) => {
- // connectionId drives cleanup of agent sessions + focus +
- // presence. Legacy clients without it fall through to the
- // client-side 5s TTL filter.
- const connectionId = parseKeepaliveConnectionId(req.url);
-
- if (connectionId) {
- const existing = keepaliveGraceTimers.get(connectionId);
- if (existing !== undefined) {
- clearTimeout(existing);
- keepaliveGraceTimers.delete(connectionId);
- console.info(
- `[keepalive] reconnect during grace — timer cancelled connectionId=${connectionId}`,
- );
- }
- }
-
- console.info(`[collab] keepalive handshake complete for ${req.url}`);
-
- const pingTimer = setInterval(() => {
- try {
- ws.ping();
- } catch {
- // Dead socket fires 'close' + 'error' which clean up below.
- }
- }, 30_000);
- pingTimer.unref?.();
-
- // Client-side TTL filter hides presence entries older than 5s.
- // Write-path calls only fire on MCP edits, so agents between
- // tool calls (LLM thinking 10-30s) would drop off without this
- // 3s bump.
- // `toBroadcasterKey` converts the raw URL id into the
- // `agent-<id>` map key used by HTTP write handlers; without
- // it, `bumpPresenceTs` no-ops because the entry lives under
- // the prefixed key.
- const tsRefreshTimer = connectionId
- ? setInterval(() => {
- agentPresenceBroadcaster?.bumpPresenceTs(toBroadcasterKey(connectionId));
- }, 3_000)
- : null;
- tsRefreshTimer?.unref?.();
-
- ws.on('close', () => {
- clearInterval(pingTimer);
- if (tsRefreshTimer !== null) clearInterval(tsRefreshTimer);
- if (!connectionId) return;
- const timer = setTimeout(() => {
- keepaliveGraceTimers.delete(connectionId);
- // If destroy already ran, the sessionManager +
- // broadcasters may be mid-teardown. Racing them is worse
- // than skipping cleanup.
- if (shuttingDown) return;
- const work = (async () => {
- console.info(
- `[keepalive] grace expired — cleaning up sessions connectionId=${connectionId}`,
- );
- try {
- await sessionManager.closeAllForAgent(connectionId);
- } catch (err) {
- console.error(
- `[keepalive] closeAllForAgent failed connectionId=${connectionId}`,
- err,
- );
- }
- try {
- agentFocusBroadcaster?.clearFocus(connectionId);
- } catch (err) {
- console.error(
- `[keepalive] clearFocus failed connectionId=${connectionId}`,
- err,
- );
- }
- try {
- agentPresenceBroadcaster?.clearPresence(toBroadcasterKey(connectionId));
- } catch (err) {
- console.error(
- `[keepalive] clearPresence failed connectionId=${connectionId}`,
- err,
- );
- }
- })();
- keepaliveGraceInflight.add(work);
- work.finally(() => keepaliveGraceInflight.delete(work));
- }, KEEPALIVE_GRACE_MS);
- timer.unref?.();
- keepaliveGraceTimers.set(connectionId, timer);
- console.info(
- `[keepalive] disconnected — grace timer started connectionId=${connectionId} graceMs=${KEEPALIVE_GRACE_MS}`,
- );
- });
- ws.on('error', (err: NodeJS.ErrnoException) => {
- if (!handleCollabSocketError(err)) {
- console.error('[collab] keepalive WS error:', err);
- }
- ws.terminate();
- });
- });
- } catch (err) {
- console.error(`[collab] keepalive handleUpgrade threw for ${req.url}:`, err);
- try {
- socket.destroy();
- } catch {
- // Already-destroyed sockets throw on destroy; swallow.
- }
- }
- return;
- }
-
- // /collab — browser HocuspocusProvider connections. The socket error
- // handler attaches BEFORE handleUpgrade because ECONNRESET during
- // the upgrade handshake fires asynchronously with no listener, which
- // crashes the whole Node process (see websockets/ws#1017).
- socket.on('error', (err: NodeJS.ErrnoException) => {
- if (handleCollabSocketError(err)) return;
- console.error('[collab] Upgrade socket error:', err);
- });
-
- console.info(`[collab] handleUpgrade starting for ${req.url}`);
-
- try {
- wss.handleUpgrade(req, socket, head, (ws) => {
- const beforeCount = hocuspocus.getConnectionsCount?.() ?? -1;
- console.info(
- `[collab] handshake complete for ${req.url} (connections before=${beforeCount})`,
- );
- const clientConnection = hocuspocus.handleConnection(ws, req);
- let closedByPolicy = false;
- ws.on('message', (data: ArrayBuffer | Buffer) => {
- if (closedByPolicy) return;
- if (data.byteLength > MAX_COLLAB_MESSAGE_BYTES) {
- closedByPolicy = true;
- console.warn(
- `[collab] frame rejected: ${data.byteLength} bytes exceeds ${MAX_COLLAB_MESSAGE_BYTES} byte limit`,
- );
- ws.close(1009, 'Message Too Big');
- return;
- }
- clientConnection.handleMessage(new Uint8Array(data as Buffer));
- });
- ws.on('close', (code: number, reason: Buffer) => {
- clientConnection.handleClose({ code, reason: reason.toString() });
- });
- ws.on('error', (err: NodeJS.ErrnoException) => {
- if (!handleCollabSocketError(err)) {
- console.error('[collab] WebSocket error:', err);
- }
- ws.terminate();
- });
- });
- } catch (err) {
- console.error(`[collab] handleUpgrade threw for ${req.url}:`, err);
- try {
- socket.destroy();
- } catch {
- // Already-destroyed — swallow.
- }
- }
+ const collaborationHost = createCollaborationHost({
+ hocuspocus,
+ log: getLogger('hocuspocus'),
+ sessionManager,
+ agentFocusBroadcaster,
+ agentPresenceBroadcaster,
+ maintenanceCoordinator: currentSrv.maintenanceCoordinator,
+ acpThreadManager,
});
+ server.httpServer?.prependListener('upgrade', collaborationHost.handleUpgrade);
// Asset-serve middleware — sirv + Content-Disposition dispatch +
// fail-closed 404 guard. Policy rationale + branch diagram lives
@@ -560,29 +390,37 @@ export function hocuspocusPlugin(): Plugin {
next();
});
- // Close handler is pinned to THIS invocation's `currentSrv` so each
- // configureServer pass destroys the srv it created — Vite restart
- // semantics (close the old httpServer AFTER the new one has wired
- // up) made a module-scope `srv` reference race with itself.
- server.httpServer?.on('close', async () => {
- shuttingDown = true;
- for (const timer of keepaliveGraceTimers.values()) {
- clearTimeout(timer);
- }
- keepaliveGraceTimers.clear();
- if (keepaliveGraceInflight.size > 0) {
- await Promise.allSettled(keepaliveGraceInflight);
- }
- try {
- await acpThreadManager?.destroy();
- } catch (err) {
- console.error('[hocuspocus] acpThreadManager.destroy() failed:', err);
- }
- try {
- await currentSrv.destroy();
- } catch (err) {
- console.error('[hocuspocus] srv.destroy() failed:', err);
- }
+ let teardownPromise: Promise<void> | undefined;
+ const teardown = (): Promise<void> => {
+ teardownPromise ??= (async () => {
+ const errors: unknown[] = [];
+ const run = async (label: string, action: () => Promise<void>): Promise<void> => {
+ try {
+ await action();
+ } catch (err) {
+ errors.push(err);
+ getLogger('hocuspocus').error(
+ { err },
+ `Vite collaboration teardown failed: ${label}`,
+ );
+ }
+ };
+ server.httpServer?.off('upgrade', collaborationHost.handleUpgrade);
+ await run('ACP thread manager', async () => acpThreadManager?.destroy());
+ await run('collaboration host', () => collaborationHost.shutdown());
+ await run('WebSocket server', () => closeWebSocketServer(collaborationHost.wss));
+ await run('server instance', () => currentSrv.destroy());
+ if (errors.length > 0)
+ throw new AggregateError(errors, 'Vite collaboration teardown failed');
+ })();
+ void teardownPromise.finally(() => activeRuntimeTeardowns.delete(teardown)).catch(() => {});
+ return teardownPromise;
+ };
+ activeRuntimeTeardowns.add(teardown);
+ server.httpServer?.on('close', () => {
+ void teardown().catch((err) =>
+ getLogger('hocuspocus').error({ err }, 'HTTP close fallback teardown failed'),
+ );
});
getLogger('hocuspocus').info({}, 'WebSocket server ready on /collab');
diff --git a/packages/server/src/collaboration-host.test.ts b/packages/server/src/collaboration-host.test.ts
new file mode 100644
index 000000000..f18e0b8f0
--- /dev/null
+++ b/packages/server/src/collaboration-host.test.ts
@@ -0,0 +1,435 @@
+import { EventEmitter } from 'node:events';
+import { createServer } from 'node:http';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import { WebSocket } from 'ws';
+import { createCollaborationHost } from './collaboration-host.ts';
+
+function createLog() {
+ return {
+ error: vi.fn(),
+ warn: vi.fn(),
+ info: vi.fn(),
+ debug: vi.fn(),
+ } as never;
+}
+
+function createSocket() {
+ const value = new EventEmitter() as EventEmitter & { destroy: ReturnType<typeof vi.fn> };
+ value.destroy = vi.fn(() => value.emit('close'));
+ return value;
+}
+
+function request(url: string, host = 'localhost', origin?: string) {
+ return {
+ url,
+ headers: { host, ...(origin === undefined ? {} : { origin }) },
+ socket: { remoteAddress: '127.0.0.1' },
+ } as never;
+}
+
+function createHocuspocus() {
+ return {
+ handleConnection: vi.fn(() => ({ handleMessage: vi.fn(), handleClose: vi.fn() })),
+ getConnectionsCount: vi.fn(() => 0),
+ } as never;
+}
+
+function callbackUpgrade(host: ReturnType<typeof createCollaborationHost>, ws: EventEmitter): void {
+ vi.spyOn(host.wss, 'handleUpgrade').mockImplementation((_req, _socket, _head, callback) => {
+ callback(ws as never);
+ return host.wss;
+ });
+}
+
+async function withTimeout<T>(promise: Promise<T>, ms = 2_000): Promise<T> {
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ try {
+ return await Promise.race([
+ promise,
+ new Promise<T>((_resolve, reject) => {
+ timer = setTimeout(() => reject(new Error('timed out')), ms);
+ }),
+ ]);
+ } finally {
+ if (timer !== undefined) clearTimeout(timer);
+ }
+}
+
+const closers: Array<() => Promise<void>> = [];
+afterEach(async () => {
+ await Promise.allSettled(closers.splice(0).map((close) => close()));
+ vi.restoreAllMocks();
+});
+
+describe('createCollaborationHost', () => {
+ test('leaves non-collaboration upgrades completely untouched', () => {
+ const log = createLog();
+ const host = createCollaborationHost({ hocuspocus: createHocuspocus(), log });
+ const raw = createSocket();
+
+ expect(host.handleUpgrade(request('/vite-hmr'), raw as never, Buffer.alloc(0))).toBe(false);
+ expect(raw.destroy).not.toHaveBeenCalled();
+ expect(raw.listenerCount('error')).toBe(0);
+ expect(log.error).not.toHaveBeenCalled();
+ expect(log.warn).not.toHaveBeenCalled();
+ expect(log.info).not.toHaveBeenCalled();
+ expect(log.debug).not.toHaveBeenCalled();
+ });
+
+ test('routes thread then keepalive before bare collaboration', () => {
+ const log = createLog();
+ const hocuspocus = createHocuspocus();
+ const host = createCollaborationHost({ hocuspocus, log, acpThreadManager: null });
+ const thread = createSocket();
+ expect(host.handleUpgrade(request('/collab/thread'), thread as never, Buffer.alloc(0))).toBe(
+ true,
+ );
+ expect(thread.destroy).toHaveBeenCalledOnce();
+
+ const keepaliveWs = new EventEmitter();
+ callbackUpgrade(host, keepaliveWs);
+ const keepalive = createSocket();
+ expect(
+ host.handleUpgrade(request('/collab/keepalive'), keepalive as never, Buffer.alloc(0)),
+ ).toBe(true);
+
+ const bareWs = new EventEmitter();
+ callbackUpgrade(host, bareWs);
+ const bare = createSocket();
+ expect(host.handleUpgrade(request('/collab'), bare as never, Buffer.alloc(0))).toBe(true);
+ expect(hocuspocus.handleConnection).toHaveBeenCalledOnce();
+ });
+
+ test('routes an admitted thread socket without forwarding it to Hocuspocus', () => {
+ const log = createLog();
+ const hocuspocus = createHocuspocus();
+ const host = createCollaborationHost({
+ hocuspocus,
+ log,
+ acpThreadManager: {} as never,
+ });
+ const threadWs = new EventEmitter() as EventEmitter & {
+ close: () => void;
+ send: () => void;
+ };
+ threadWs.close = () => {};
+ threadWs.send = () => {};
+ callbackUpgrade(host, threadWs);
+
+ expect(
+ host.handleUpgrade(request('/collab/thread'), createSocket() as never, Buffer.alloc(0)),
+ ).toBe(true);
+ expect(threadWs.listenerCount('message')).toBe(1);
+ expect(hocuspocus.handleConnection).not.toHaveBeenCalled();
+ });
+
+ test('refuses local bad Host and foreign thread Origin', () => {
+ const log = createLog();
+ const host = createCollaborationHost({
+ hocuspocus: createHocuspocus(),
+ log,
+ acpThreadManager: {} as never,
+ });
+ const badThread = createSocket();
+ const badKeepalive = createSocket();
+ const foreignOrigin = createSocket();
+
+ host.handleUpgrade(
+ request('/collab/thread', 'evil.example'),
+ badThread as never,
+ Buffer.alloc(0),
+ );
+ host.handleUpgrade(
+ request('/collab/keepalive', 'evil.example'),
+ badKeepalive as never,
+ Buffer.alloc(0),
+ );
+ host.handleUpgrade(
+ request('/collab/thread', 'localhost', 'https://evil.example'),
+ foreignOrigin as never,
+ Buffer.alloc(0),
+ );
+ expect(badThread.destroy).toHaveBeenCalledOnce();
+ expect(badKeepalive.destroy).toHaveBeenCalledOnce();
+ expect(foreignOrigin.destroy).toHaveBeenCalledOnce();
+ });
+
+ test('refuses forwarded bare collaboration upgrades when remote access is disabled', () => {
+ const log = createLog();
+ const hocuspocus = createHocuspocus();
+ const host = createCollaborationHost({ hocuspocus, log });
+ const raw = createSocket();
+ const forwardedRequest = request('/collab') as {
+ headers: Record<string, string>;
+ };
+ forwardedRequest.headers['x-forwarded-for'] = '203.0.113.7';
+
+ expect(host.handleUpgrade(forwardedRequest as never, raw as never, Buffer.alloc(0))).toBe(true);
+ expect(raw.destroy).toHaveBeenCalledOnce();
+ expect(hocuspocus.handleConnection).not.toHaveBeenCalled();
+ expect(log.warn).toHaveBeenCalledWith(
+ { url: '/collab', host: 'localhost' },
+ '[remote] refused proxied WS upgrade; start the server with `ok start --remote <url>`',
+ );
+ });
+
+ test('uses remote access admission for bare collaboration upgrades', () => {
+ const log = createLog();
+ const hocuspocus = createHocuspocus();
+ const host = createCollaborationHost({
+ hocuspocus,
+ log,
+ remoteAccess: {
+ url: 'https://myproject.ngrok.app',
+ publicHost: 'myproject.ngrok.app',
+ port: 24_550,
+ },
+ });
+ const admittedWs = new EventEmitter();
+ callbackUpgrade(host, admittedWs);
+ const admitted = createSocket();
+ const refused = createSocket();
+
+ expect(
+ host.handleUpgrade(
+ request('/collab', 'myproject.ngrok.app'),
+ admitted as never,
+ Buffer.alloc(0),
+ ),
+ ).toBe(true);
+ expect(
+ host.handleUpgrade(request('/collab', 'evil.example'), refused as never, Buffer.alloc(0)),
+ ).toBe(true);
+ expect(hocuspocus.handleConnection).toHaveBeenCalledOnce();
+ expect(admitted.destroy).not.toHaveBeenCalled();
+ expect(refused.destroy).toHaveBeenCalledOnce();
+ });
+
+ test('bootstraps presence only for a complete valid keepalive identity', () => {
+ const log = createLog();
+ const setPresence = vi.fn();
+ const host = createCollaborationHost({
+ hocuspocus: createHocuspocus(),
+ log,
+ agentPresenceBroadcaster: { setPresence } as never,
+ });
+ const validWs = new EventEmitter();
+ callbackUpgrade(host, validWs);
+ host.handleUpgrade(
+ request(
+ '/collab/keepalive?connectionId=agent_1&displayName=Agent&clientName=Claude&colorSeed=seed',
+ ),
+ createSocket() as never,
+ Buffer.alloc(0),
+ );
+ const invalidWs = new EventEmitter();
+ callbackUpgrade(host, invalidWs);
+ host.handleUpgrade(
+ request('/collab/keepalive?connectionId=bad%0Aid&displayName=Agent&clientName=Claude'),
+ createSocket() as never,
+ Buffer.alloc(0),
+ );
+ expect(setPresence).toHaveBeenCalledOnce();
+ expect(setPresence).toHaveBeenCalledWith(
+ 'agent-agent_1',
+ expect.objectContaining({ displayName: 'Agent' }),
+ );
+ });
+
+ test('closes an oversized collaboration message with policy code 1009', () => {
+ const handleMessage = vi.fn();
+ const hocuspocus = {
+ handleConnection: vi.fn(() => ({ handleMessage, handleClose: vi.fn() })),
+ getConnectionsCount: vi.fn(() => 0),
+ } as never;
+ const host = createCollaborationHost({ hocuspocus, log: createLog() });
+ const ws = new EventEmitter() as EventEmitter & {
+ close: ReturnType<typeof vi.fn>;
+ terminate: ReturnType<typeof vi.fn>;
+ };
+ ws.close = vi.fn();
+ ws.terminate = vi.fn();
+ callbackUpgrade(host, ws);
+
+ host.handleUpgrade(request('/collab'), createSocket() as never, Buffer.alloc(0));
+ ws.emit('message', Buffer.alloc(1024 * 1024 + 1));
+
+ expect(ws.close).toHaveBeenCalledWith(1009, 'Message Too Big');
+ expect(handleMessage).not.toHaveBeenCalled();
+ });
+
+ test('routes unsupported-length WebSocket errors through the oversized-message path', () => {
+ const log = createLog();
+ const host = createCollaborationHost({ hocuspocus: createHocuspocus(), log });
+ const ws = new EventEmitter() as EventEmitter & {
+ terminate: ReturnType<typeof vi.fn>;
+ };
+ ws.terminate = vi.fn();
+ callbackUpgrade(host, ws);
+ host.handleUpgrade(request('/collab'), createSocket() as never, Buffer.alloc(0));
+
+ ws.emit(
+ 'error',
+ Object.assign(new Error('Max payload size exceeded'), {
+ code: 'WS_ERR_UNSUPPORTED_MESSAGE_LENGTH',
+ }),
+ );
+
+ expect(log.warn).toHaveBeenCalledWith(
+ {
+ event: 'collab-message-too-large',
+ limit: 1024 * 1024,
+ },
+ 'Collab WebSocket frame rejected by ws maxPayload before Yjs processing',
+ );
+ expect(log.error).not.toHaveBeenCalled();
+ expect(ws.terminate).toHaveBeenCalledOnce();
+ });
+
+ test('cancels keepalive cleanup when the same connection reconnects during grace', async () => {
+ vi.useFakeTimers();
+ try {
+ const closeAllForAgent = vi.fn();
+ const host = createCollaborationHost({
+ hocuspocus: createHocuspocus(),
+ log: createLog(),
+ sessionManager: { closeAllForAgent } as never,
+ keepaliveGraceMs: 1_000,
+ });
+ const firstWs = new EventEmitter();
+ callbackUpgrade(host, firstWs);
+ host.handleUpgrade(
+ request('/collab/keepalive?connectionId=agent1'),
+ createSocket() as never,
+ Buffer.alloc(0),
+ );
+ firstWs.emit('close');
+
+ const secondWs = new EventEmitter();
+ callbackUpgrade(host, secondWs);
+ host.handleUpgrade(
+ request('/collab/keepalive?connectionId=agent1'),
+ createSocket() as never,
+ Buffer.alloc(0),
+ );
+ await vi.advanceTimersByTimeAsync(1_000);
+
+ expect(closeAllForAgent).not.toHaveBeenCalled();
+ await host.shutdown();
+ secondWs.emit('close');
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ test('contains synchronous upgrade throws and destroys the raw socket', () => {
+ const log = createLog();
+ const host = createCollaborationHost({ hocuspocus: createHocuspocus(), log });
+ vi.spyOn(host.wss, 'handleUpgrade').mockImplementation(() => {
+ throw new Error('upgrade failed');
+ });
+ const raw = createSocket();
+
+ expect(host.handleUpgrade(request('/collab'), raw as never, Buffer.alloc(0))).toBe(true);
+ expect(raw.destroy).toHaveBeenCalledOnce();
+ expect(log.error).toHaveBeenCalledWith(
+ expect.objectContaining({ err: expect.any(Error) }),
+ expect.any(String),
+ );
+ });
+
+ test('shares shutdown, drains sockets, cancels grace work, and awaits active cleanup', async () => {
+ const log = createLog();
+ const closeAllForAgent = vi.fn();
+ const cleanup = Promise.withResolvers<void>();
+ closeAllForAgent.mockReturnValue(cleanup.promise);
+ const host = createCollaborationHost({
+ hocuspocus: createHocuspocus(),
+ log,
+ sessionManager: { closeAllForAgent } as never,
+ keepaliveGraceMs: 0,
+ });
+ const keepaliveWs = new EventEmitter();
+ callbackUpgrade(host, keepaliveWs);
+ const keepaliveRaw = createSocket();
+ host.handleUpgrade(
+ request('/collab/keepalive?connectionId=agent1'),
+ keepaliveRaw as never,
+ Buffer.alloc(0),
+ );
+ const bareWs = new EventEmitter();
+ callbackUpgrade(host, bareWs);
+ const bareRaw = createSocket();
+ host.handleUpgrade(request('/collab'), bareRaw as never, Buffer.alloc(0));
+
+ keepaliveWs.emit('close');
+ await new Promise((resolve) => setTimeout(resolve, 0));
+ expect(closeAllForAgent).toHaveBeenCalledOnce();
+ const first = host.shutdown();
+ expect(host.shutdown()).toBe(first);
+ keepaliveWs.emit('close');
+ expect(keepaliveRaw.destroy).toHaveBeenCalled();
+ expect(bareRaw.destroy).toHaveBeenCalled();
+ let settled = false;
+ void first.then(() => {
+ settled = true;
+ });
+ await Promise.resolve();
+ expect(settled).toBe(false);
+ cleanup.resolve();
+ await first;
+ });
+
+ test('cancels a pending keepalive grace timer during shutdown', async () => {
+ vi.useFakeTimers();
+ const closeAllForAgent = vi.fn();
+ const host = createCollaborationHost({
+ hocuspocus: createHocuspocus(),
+ log: createLog(),
+ sessionManager: { closeAllForAgent } as never,
+ keepaliveGraceMs: 1_000,
+ });
+ const keepaliveWs = new EventEmitter();
+ callbackUpgrade(host, keepaliveWs);
+ host.handleUpgrade(
+ request('/collab/keepalive?connectionId=agent1'),
+ createSocket() as never,
+ Buffer.alloc(0),
+ );
+
+ keepaliveWs.emit('close');
+ await host.shutdown();
+ await vi.advanceTimersByTimeAsync(1_000);
+
+ expect(closeAllForAgent).not.toHaveBeenCalled();
+ vi.useRealTimers();
+ });
+
+ test('allows HTTP and WSS close after draining a live upgraded socket', async () => {
+ const log = createLog();
+ const hocuspocus = createHocuspocus();
+ const host = createCollaborationHost({ hocuspocus, log });
+ const httpServer = createServer();
+ httpServer.on('upgrade', (req, socket, head) => host.handleUpgrade(req, socket, head));
+ await new Promise<void>((resolve) => httpServer.listen(0, '127.0.0.1', resolve));
+ const address = httpServer.address();
+ if (typeof address !== 'object' || address === null) throw new Error('missing test port');
+ const client = new WebSocket(`ws://127.0.0.1:${address.port}/collab`);
+ await new Promise<void>((resolve, reject) => {
+ client.once('open', resolve);
+ client.once('error', reject);
+ });
+ closers.push(async () => {
+ client.terminate();
+ await host.shutdown();
+ await new Promise<void>((resolve) => host.wss.close(() => resolve()));
+ await new Promise<void>((resolve) => httpServer.close(() => resolve()));
+ });
+
+ await withTimeout(host.shutdown());
+ await withTimeout(new Promise<void>((resolve) => host.wss.close(() => resolve())));
+ await withTimeout(new Promise<void>((resolve) => httpServer.close(() => resolve())));
+ client.terminate();
+ expect(hocuspocus.handleConnection).toHaveBeenCalledOnce();
+ });
+});
diff --git a/packages/server/src/collaboration-host.ts b/packages/server/src/collaboration-host.ts
new file mode 100644
index 000000000..5e36984b4
--- /dev/null
+++ b/packages/server/src/collaboration-host.ts
@@ -0,0 +1,366 @@
+import type { IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { Hocuspocus } from '@hocuspocus/server';
+import { AGENT_ICON_COLORS, colorFromSeed, iconFromClientName } from '@inkeep/open-knowledge-core';
+import { WebSocketServer } from 'ws';
+import type { AcpThreadManager } from './acp/thread-manager.ts';
+import { attachAcpThreadSocket } from './acp/thread-socket.ts';
+import type { AgentFocusBroadcaster } from './agent-focus.ts';
+import { toBroadcasterKey, validateAgentId } from './agent-id.ts';
+import type { AgentPresenceBroadcaster } from './agent-presence.ts';
+import type { AgentSessionManager } from './agent-sessions.ts';
+import { isAllowedApiOrigin } from './api-origin.ts';
+import type { PinoLogger } from './logger.ts';
+import { isAllowedWorkspaceHostHeader, isLoopbackAddress } from './loopback.ts';
+import type { MaintenanceCoordinator } from './maintenance-coordinator.ts';
+import { handleCollabSocketError, incrementCollabMessageTooLarge } from './metrics.ts';
+import {
+ hasForwardingHeaders,
+ isRemoteAdmitted,
+ type ResolvedRemoteAccess,
+} from './remote-access.ts';
+
+const DEFAULT_KEEPALIVE_GRACE_MS = 10_000;
+const MAX_COLLAB_MESSAGE_BYTES = 1024 * 1024;
+const MAX_KEEPALIVE_IDENTITY_LEN = 256;
+
+export interface CollaborationHostOptions {
+ hocuspocus: Hocuspocus;
+ log: PinoLogger;
+ sessionManager?: AgentSessionManager;
+ agentFocusBroadcaster?: AgentFocusBroadcaster | null;
+ agentPresenceBroadcaster?: AgentPresenceBroadcaster | null;
+ maintenanceCoordinator?: MaintenanceCoordinator;
+ keepaliveGraceMs?: number;
+ acpThreadManager?: AcpThreadManager | null;
+ remoteAccess?: ResolvedRemoteAccess | null;
+}
+
+export interface CollaborationHost {
+ readonly wss: WebSocketServer;
+ readonly handleUpgrade: (req: IncomingMessage, socket: Duplex, head: Buffer) => boolean;
+ shutdown(): Promise<void>;
+}
+
+export interface KeepaliveIdentity {
+ displayName: string;
+ clientName: string;
+ colorSeed: string;
+}
+
+export function parseKeepaliveConnectionId(url: string | undefined): string | null {
+ if (!url) return null;
+ try {
+ return validateAgentId(new URL(url, 'http://localhost').searchParams.get('connectionId'));
+ } catch {
+ return null;
+ }
+}
+
+function sanitizeIdentityField(raw: string | null): string | null {
+ if (raw === null || raw.length === 0 || raw.length > MAX_KEEPALIVE_IDENTITY_LEN) return null;
+ // biome-ignore lint/suspicious/noControlCharactersInRegex: rejects control characters in awareness values
+ return /[\u0000-\u001f\u007f]/.test(raw) ? null : raw;
+}
+
+export function parseKeepaliveIdentity(url: string | undefined): KeepaliveIdentity | null {
+ if (!url) return null;
+ try {
+ const parsed = new URL(url, 'http://localhost');
+ const displayName = sanitizeIdentityField(parsed.searchParams.get('displayName'));
+ const clientName = sanitizeIdentityField(parsed.searchParams.get('clientName'));
+ const colorSeed = sanitizeIdentityField(parsed.searchParams.get('colorSeed'));
+ return displayName === null || clientName === null || colorSeed === null
+ ? null
+ : { displayName, clientName, colorSeed };
+ } catch {
+ return null;
+ }
+}
+
+export function createCollaborationHost(options: CollaborationHostOptions): CollaborationHost {
+ const {
+ hocuspocus,
+ log,
+ sessionManager,
+ agentFocusBroadcaster,
+ agentPresenceBroadcaster,
+ maintenanceCoordinator,
+ acpThreadManager,
+ } = options;
+ const remoteAccess = options.remoteAccess ?? undefined;
+ const keepaliveGraceMs = options.keepaliveGraceMs ?? DEFAULT_KEEPALIVE_GRACE_MS;
+ const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_COLLAB_MESSAGE_BYTES });
+ const keepaliveGraceTimers = new Map<string, ReturnType<typeof setTimeout>>();
+ const keepaliveGraceInflight = new Set<Promise<void>>();
+ const liveUpgradeSockets = new Set<Duplex>();
+ let shuttingDown = false;
+ let shutdownPromise: Promise<void> | undefined;
+
+ wss.on('error', (err) => log.error({ err }, 'WebSocketServer error'));
+
+ const admitted = (req: IncomingMessage): boolean =>
+ remoteAccess !== undefined
+ ? isRemoteAdmitted(req, remoteAccess)
+ : isLoopbackAddress(req.socket.remoteAddress) &&
+ isAllowedWorkspaceHostHeader(req.headers.host);
+
+ const trackSocket = (socket: Duplex, label: string): void => {
+ socket.on('error', (err: NodeJS.ErrnoException) => {
+ if (!handleCollabSocketError(err)) log.error({ err }, `${label} socket error`);
+ });
+ liveUpgradeSockets.add(socket);
+ socket.once('close', () => liveUpgradeSockets.delete(socket));
+ };
+
+ const safelyHandleUpgrade = (
+ req: IncomingMessage,
+ socket: Duplex,
+ head: Buffer,
+ label: string,
+ onConnection: Parameters<WebSocketServer['handleUpgrade']>[3],
+ ): void => {
+ try {
+ wss.handleUpgrade(req, socket, head, onConnection);
+ } catch (err) {
+ log.error({ err, url: req.url }, `[collab] ${label} handleUpgrade threw`);
+ try {
+ socket.destroy();
+ } catch {
+ // Best effort for an already-destroyed upgrade socket.
+ }
+ }
+ };
+
+ const handleKeepalive = (req: IncomingMessage, socket: Duplex, head: Buffer): void => {
+ if (!admitted(req)) {
+ log.debug(
+ { url: req.url, host: req.headers.host },
+ '[collab] /collab/keepalive upgrade refused',
+ );
+ socket.destroy();
+ return;
+ }
+ trackSocket(socket, 'MCP keepalive');
+ safelyHandleUpgrade(req, socket, head, 'keepalive', (ws) => {
+ const connectionId = parseKeepaliveConnectionId(req.url);
+ if (connectionId) {
+ const existing = keepaliveGraceTimers.get(connectionId);
+ if (existing !== undefined) {
+ clearTimeout(existing);
+ keepaliveGraceTimers.delete(connectionId);
+ log.info({ connectionId }, '[keepalive] reconnect during grace — timer cancelled');
+ }
+ }
+ if (connectionId && agentPresenceBroadcaster) {
+ const identity = parseKeepaliveIdentity(req.url);
+ if (identity) {
+ try {
+ const icon = iconFromClientName(identity.clientName);
+ agentPresenceBroadcaster.setPresence(toBroadcasterKey(connectionId), {
+ displayName: identity.displayName,
+ icon,
+ color: AGENT_ICON_COLORS[icon] ?? colorFromSeed(identity.colorSeed),
+ // Presence filtering hides entries without `currentDoc`; this
+ // non-document sentinel surfaces the agent before its first write.
+ currentDoc: '(connected)',
+ mode: 'idle',
+ ts: Date.now(),
+ });
+ } catch (err) {
+ log.error({ err, connectionId }, '[keepalive] presence bootstrap failed');
+ }
+ }
+ }
+ const pingTimer = setInterval(() => {
+ try {
+ ws.ping();
+ } catch {
+ // The close/error callbacks dispose the dead socket.
+ }
+ }, 30_000);
+ pingTimer.unref?.();
+ // Refresh faster than the client-side 5 s TTL so an idle agent stays
+ // visible between tool calls. Presence lives under `agent-<id>`; using
+ // the raw URL id would make `bumpPresenceTs` a no-op.
+ const tsRefreshTimer = connectionId
+ ? setInterval(
+ () => agentPresenceBroadcaster?.bumpPresenceTs(toBroadcasterKey(connectionId)),
+ 3_000,
+ )
+ : null;
+ tsRefreshTimer?.unref?.();
+ ws.on('close', () => {
+ clearInterval(pingTimer);
+ if (tsRefreshTimer !== null) clearInterval(tsRefreshTimer);
+ if (!connectionId || shuttingDown) return;
+ const timer = setTimeout(() => {
+ keepaliveGraceTimers.delete(connectionId);
+ // Shutdown may begin after this timer is scheduled but before it
+ // fires; never race cleanup against session and broadcaster teardown.
+ if (shuttingDown) return;
+ const work = (async () => {
+ log.info({ connectionId }, '[keepalive] grace expired — cleaning up sessions');
+ try {
+ await sessionManager?.closeAllForAgent(connectionId);
+ } catch (err) {
+ log.error({ err, connectionId }, '[keepalive] closeAllForAgent failed');
+ }
+ try {
+ agentFocusBroadcaster?.clearFocus(connectionId);
+ } catch (err) {
+ log.error({ err, connectionId }, '[keepalive] clearFocus failed');
+ }
+ try {
+ agentPresenceBroadcaster?.clearPresence(toBroadcasterKey(connectionId));
+ } catch (err) {
+ log.error({ err, connectionId }, '[keepalive] clearPresence failed');
+ }
+ // A closed keepalive means its writer is dead, so maintenance can
+ // evaluate off the write path. Flush-counter and boot maintenance
+ // reap other session types; only `session-close` telemetry is
+ // intentionally limited to keepalive-backed sessions.
+ try {
+ await maintenanceCoordinator?.onSessionClose();
+ } catch (err) {
+ log.error({ err, connectionId }, '[keepalive] maintenance onSessionClose failed');
+ }
+ })();
+ keepaliveGraceInflight.add(work);
+ void work.finally(() => keepaliveGraceInflight.delete(work));
+ }, keepaliveGraceMs);
+ timer.unref?.();
+ keepaliveGraceTimers.set(connectionId, timer);
+ log.info(
+ { connectionId, graceMs: keepaliveGraceMs },
+ '[keepalive] disconnected — grace timer started',
+ );
+ });
+ ws.on('error', (err: NodeJS.ErrnoException) => {
+ if (!handleCollabSocketError(err)) log.error({ err }, 'MCP keepalive WS error');
+ ws.terminate();
+ });
+ });
+ };
+
+ const handleUpgrade = (req: IncomingMessage, socket: Duplex, head: Buffer): boolean => {
+ if (!req.url?.startsWith('/collab')) return false;
+ // These breadcrumbs locate a stalled upgrade: `upgrade received` reached
+ // this host, `handleUpgrade starting` passed routing, `handleUpgrade threw`
+ // marks a synchronous WS handoff failure, and `handshake complete` means
+ // Hocuspocus owns the connection.
+ log.info(
+ {
+ url: req.url,
+ protocol: req.headers['sec-websocket-protocol'] ?? 'none',
+ host: req.headers.host ?? 'none',
+ origin: req.headers.origin ?? 'none',
+ },
+ '[collab] upgrade received',
+ );
+ if (remoteAccess === undefined && hasForwardingHeaders(req)) {
+ log.warn(
+ { url: req.url, host: req.headers.host },
+ '[remote] refused proxied WS upgrade; start the server with `ok start --remote <url>`',
+ );
+ socket.destroy();
+ return true;
+ }
+ if (req.url.startsWith('/collab/thread')) {
+ if (
+ acpThreadManager === undefined ||
+ acpThreadManager === null ||
+ !admitted(req) ||
+ (req.headers.origin !== undefined &&
+ !isAllowedApiOrigin(req.headers.origin, remoteAccess?.publicHost))
+ ) {
+ log.debug(
+ { url: req.url, host: req.headers.host, origin: req.headers.origin },
+ '[collab] /collab/thread upgrade refused',
+ );
+ socket.destroy();
+ return true;
+ }
+ trackSocket(socket, 'ACP thread');
+ safelyHandleUpgrade(req, socket, head, 'thread', (ws) =>
+ attachAcpThreadSocket(ws, acpThreadManager, log),
+ );
+ return true;
+ }
+ if (req.url.startsWith('/collab/keepalive')) {
+ handleKeepalive(req, socket, head);
+ return true;
+ }
+ if (remoteAccess !== undefined && !isRemoteAdmitted(req, remoteAccess)) {
+ log.debug({ url: req.url, host: req.headers.host }, '[collab] /collab upgrade refused');
+ socket.destroy();
+ return true;
+ }
+ trackSocket(socket, 'Upgrade');
+ log.info({ url: req.url }, '[collab] handleUpgrade starting');
+ safelyHandleUpgrade(req, socket, head, 'collaboration', (ws) => {
+ const connectionsBefore = hocuspocus.getConnectionsCount?.() ?? -1;
+ const clientConnection = hocuspocus.handleConnection(ws, req as unknown as Request);
+ log.info({ url: req.url, connectionsBefore }, '[collab] handshake complete');
+ let closedByPolicy = false;
+ ws.on('message', (data: ArrayBuffer | Buffer) => {
+ if (closedByPolicy) return;
+ if (data.byteLength > MAX_COLLAB_MESSAGE_BYTES) {
+ closedByPolicy = true;
+ incrementCollabMessageTooLarge();
+ log.warn(
+ {
+ event: 'collab-message-too-large',
+ bytes: data.byteLength,
+ limit: MAX_COLLAB_MESSAGE_BYTES,
+ },
+ 'Collab WebSocket message rejected before Yjs processing',
+ );
+ ws.close(1009, 'Message Too Big');
+ return;
+ }
+ clientConnection.handleMessage(new Uint8Array(data as Buffer));
+ });
+ ws.on('close', (code: number, reason: Buffer) =>
+ clientConnection.handleClose({ code, reason: reason.toString() }),
+ );
+ ws.on('error', (err: NodeJS.ErrnoException) => {
+ if (err.code === 'WS_ERR_UNSUPPORTED_MESSAGE_LENGTH') {
+ incrementCollabMessageTooLarge();
+ log.warn(
+ { event: 'collab-message-too-large', limit: MAX_COLLAB_MESSAGE_BYTES },
+ 'Collab WebSocket frame rejected by ws maxPayload before Yjs processing',
+ );
+ } else if (!handleCollabSocketError(err)) {
+ log.error({ err }, 'WebSocket error');
+ }
+ ws.terminate();
+ });
+ });
+ return true;
+ };
+
+ const shutdown = (): Promise<void> => {
+ shutdownPromise ??= (async () => {
+ // Socket destruction emits close events; set the guard first so those
+ // callbacks cannot schedule fresh grace cleanup during teardown.
+ shuttingDown = true;
+ // Callers close WSS/HTTP after this promise. Live upgraded sockets would
+ // keep those closes pending, while destroying them also drives WS cleanup.
+ for (const socket of liveUpgradeSockets) {
+ try {
+ socket.destroy();
+ } catch {
+ /* best effort */
+ }
+ }
+ liveUpgradeSockets.clear();
+ for (const timer of keepaliveGraceTimers.values()) clearTimeout(timer);
+ keepaliveGraceTimers.clear();
+ await Promise.allSettled(keepaliveGraceInflight);
+ })();
+ return shutdownPromise;
+ };
+
+ return { wss, handleUpgrade, shutdown };
+}
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
index c714e2f67..274e3a7e6 100644
--- a/packages/server/src/index.ts
+++ b/packages/server/src/index.ts
@@ -96,6 +96,11 @@ export {
type HiddenWindowsConsoleOptions,
withHiddenWindowsConsole,
} from './child-process-windows-hide.ts';
+export {
+ type CollaborationHost,
+ type CollaborationHostOptions,
+ createCollaborationHost,
+} from './collaboration-host.ts';
export { getLocalDir, resolveContentDir, resolveLockDir } from './config/paths.ts';
export { type Config, ConfigSchema } from './config/schema.ts';
export { MCP_SERVER_NAME } from './constants.ts';
diff --git a/packages/server/src/mcp-mount.test.ts b/packages/server/src/mcp-mount.test.ts
index a14f0a24f..f2a78a841 100644
--- a/packages/server/src/mcp-mount.test.ts
+++ b/packages/server/src/mcp-mount.test.ts
@@ -10,7 +10,7 @@ import {
INLINE_RENDERABLE_EXTENSIONS,
} from '@inkeep/open-knowledge-core';
import sirv from 'sirv';
-import { afterEach, describe, expect, test } from 'vitest';
+import { afterEach, describe, expect, test, vi } from 'vitest';
import { WebSocket } from 'ws';
import { createAssetServeMiddleware } from './asset-serve-middleware.ts';
import { getFreeLoopbackPort } from './loopback-rig-test-helpers.ts';
@@ -23,7 +23,7 @@ import {
const log = {
error: () => {},
- warn: () => {},
+ warn: vi.fn(),
info: () => {},
debug: () => {},
child: () => log,
@@ -39,18 +39,21 @@ const hocuspocus = {
let servers: Array<{ httpServer: HttpServer; mount: MountMcpAndApiHandle }> = [];
-async function startMountedServer(handler: McpHttpHandler): Promise<{ port: number }> {
+async function startMountedServer(
+ handler: McpHttpHandler,
+ serverHocuspocus: Hocuspocus = hocuspocus,
+): Promise<{ port: number; mount: MountMcpAndApiHandle }> {
const httpServer = createServer();
const mount = mountMcpAndApi({
httpServer,
- hocuspocus,
+ hocuspocus: serverHocuspocus,
mcpHttpHandler: handler,
log,
});
const port = await getFreeLoopbackPort();
await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));
servers.push({ httpServer, mount });
- return { port };
+ return { port, mount };
}
async function postMcpWithHost(
@@ -106,7 +109,11 @@ async function getWithHost(
});
}
-async function requestUnknownUpgrade(port: number): Promise<string> {
+async function requestUnknownUpgrade(port: number, forwarding = false): Promise<string> {
+ return requestUpgrade(port, '/not-a-websocket-route', forwarding);
+}
+
+async function requestUpgrade(port: number, path: string, forwarding = false): Promise<string> {
return new Promise((resolve, reject) => {
const socket = createNetConnection({ host: '127.0.0.1', port });
const chunks: Buffer[] = [];
@@ -118,12 +125,13 @@ async function requestUnknownUpgrade(port: number): Promise<string> {
socket.on('connect', () => {
socket.write(
[
- 'GET /not-a-websocket-route HTTP/1.1',
+ `GET ${path} HTTP/1.1`,
'Host: 127.0.0.1',
'Connection: Upgrade',
'Upgrade: websocket',
'Sec-WebSocket-Version: 13',
'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==',
+ ...(forwarding ? ['X-Forwarded-For: 203.0.113.7'] : []),
'',
'',
].join('\r\n'),
@@ -141,6 +149,34 @@ async function requestUnknownUpgrade(port: number): Promise<string> {
});
}
+async function requestRejectedUpgrade(port: number, path: string): Promise<number> {
+ return new Promise((resolve, reject) => {
+ const req = httpRequest({
+ hostname: '127.0.0.1',
+ port,
+ path,
+ headers: {
+ Connection: 'Upgrade',
+ Upgrade: 'websocket',
+ 'Sec-WebSocket-Version': '13',
+ 'Sec-WebSocket-Key': 'dGhlIHNhbXBsZSBub25jZQ==',
+ },
+ });
+ req.on('response', (res) => {
+ const status = res.statusCode ?? 0;
+ res.resume();
+ res.on('end', () => resolve(status));
+ });
+ req.on('upgrade', (_res, socket) => {
+ socket.destroy();
+ reject(new Error('upgrade was admitted after shutdown'));
+ });
+ req.on('error', reject);
+ req.setTimeout(1_000, () => req.destroy(new Error('timed out waiting for upgrade refusal')));
+ req.end();
+ });
+}
+
afterEach(async () => {
const active = servers;
servers = [];
@@ -239,6 +275,47 @@ describe('mountMcpAndApi /mcp guard', () => {
expect(response).toBe('');
expect(calls).toBe(0);
});
+
+ test('warns before closing a proxied unknown upgrade', async () => {
+ vi.mocked(log.warn).mockClear();
+ const { port } = await startMountedServer({ handle: async () => {}, close: async () => {} });
+
+ await expect(requestUnknownUpgrade(port, true)).resolves.toBe('');
+ expect(log.warn).toHaveBeenCalledWith(
+ expect.objectContaining({ host: '127.0.0.1' }),
+ expect.stringContaining('refused proxied WS upgrade'),
+ );
+ });
+
+ test('shares shutdown and keeps routing attached until the server closes', async () => {
+ const handleConnection = vi.fn(() => ({
+ handleMessage: () => {},
+ handleClose: () => {},
+ }));
+ const scopedHocuspocus = {
+ hooks: async () => {},
+ handleConnection,
+ } as unknown as Hocuspocus;
+ const { port, mount } = await startMountedServer(
+ {
+ handle: async () => {},
+ close: async () => {},
+ },
+ scopedHocuspocus,
+ );
+ const first = mount.shutdown();
+ expect(mount.shutdown()).toBe(first);
+ await first;
+
+ const response = await fetch(`http://127.0.0.1:${port}/still-routed`, {
+ signal: AbortSignal.timeout(1_000),
+ });
+ expect(response.status).toBe(404);
+
+ await expect(requestRejectedUpgrade(port, '/collab')).resolves.toBe(404);
+ expect(handleConnection).not.toHaveBeenCalled();
+ expect(mount.wss.clients.size).toBe(0);
+ });
});
// Regression: a live `/collab` or `/collab/keepalive` WS that survives into
diff --git a/packages/server/src/mcp-mount.ts b/packages/server/src/mcp-mount.ts
index 0d1ec80c7..dc2e5e3e4 100644
--- a/packages/server/src/mcp-mount.ts
+++ b/packages/server/src/mcp-mount.ts
@@ -1,59 +1,46 @@
/**
- * `mountMcpAndApi` — single canonical wiring for `/mcp` + `/api/*` + WS upgrade.
+ * `mountMcpAndApi` is the canonical HTTP adapter for `/mcp`, `/api/*`, content
+ * assets, and the optional React shell. `bootServer()` and the integration
+ * harnesses use it; Vite owns its Connect middleware and shares only the
+ * collaboration host.
*
- * Three consumers compose the same four ingredients on top of an `http.Server`:
- * 1. `bootServer()` (CLI `ok start`, Electron utility, Vite dev plugin via the
- * shared boot path).
- * 2. The integration test harness's `createTestServer()`.
- * 3. The integration test harness's `createRestartableServer()` (no `/mcp` —
- * passes `mcpHttpHandler: undefined`).
+ * Collaboration WebSocket routing and lifecycle live in
+ * `createCollaborationHost()`. This adapter delegates `/collab`,
+ * `/collab/keepalive`, and `/collab/thread` upgrades to that host, then owns
+ * only the fallback that rejects unknown upgrade paths.
*
- * Before this extraction every consumer reimplemented the request handler, the
- * `WebSocketServer({ noServer: true })`, the `/collab/keepalive` short-circuit,
- * the keepalive-grace timer map, and the per-`connectionId` cleanup cascade
- * (`closeAllForAgent` + `clearFocus` + `clearPresence`). The duplication had
- * already drifted: `boot.ts` validated `connectionId` via `validateAgentId` to
- * defend against log-injection / `clearPresence` cross-eviction; the harness
- * accepted any `connectionId` query param. Centralizing in one helper closes
- * that drift class permanently — every consumer gets the production-grade
- * validation path.
- *
- * The helper attaches both `'request'` and `'upgrade'` listeners to the
+ * The adapter attaches both `'request'` and `'upgrade'` listeners to the
* supplied `httpServer`. Callers therefore MUST `createHttpServer()` with no
* constructor callback — passing a `(req, res) => {…}` arg would install a
* second `'request'` listener and double-handle every inbound HTTP request.
*
- * `shutdown()` cancels pending grace timers + awaits in-flight cleanups so
- * caller `destroy()` paths do not race a still-firing grace callback into
- * a torn-down `sessionManager` / broadcaster.
+ * `shutdown()` leaves request routing attached until the caller closes the HTTP
+ * server so requests do not silently hang during later teardown phases. It
+ * detaches upgrades before draining the collaboration host so no new WebSocket
+ * can escape that one-shot drain.
*/
import type { Server as HttpServer, IncomingMessage, ServerResponse } from 'node:http';
import type { Duplex } from 'node:stream';
import type { Hocuspocus } from '@hocuspocus/server';
-import { AGENT_ICON_COLORS, colorFromSeed, iconFromClientName } from '@inkeep/open-knowledge-core';
-import { WebSocketServer } from 'ws';
+import type { WebSocketServer } from 'ws';
import type { AcpThreadManager } from './acp/thread-manager.ts';
-import { attachAcpThreadSocket } from './acp/thread-socket.ts';
import type { AgentFocusBroadcaster } from './agent-focus.ts';
-import { toBroadcasterKey, validateAgentId } from './agent-id.ts';
import type { AgentPresenceBroadcaster } from './agent-presence.ts';
import type { AgentSessionManager } from './agent-sessions.ts';
import { isAllowedApiOrigin } from './api-origin.ts';
+import { createCollaborationHost } from './collaboration-host.ts';
import { errorResponse } from './http/error-response.ts';
import type { PinoLogger } from './logger.ts';
import { isAllowedWorkspaceHostHeader, isLoopbackAddress } from './loopback.ts';
import type { MaintenanceCoordinator } from './maintenance-coordinator.ts';
import type { McpHttpHandler } from './mcp-http.ts';
-import { handleCollabSocketError, incrementCollabMessageTooLarge } from './metrics.ts';
import {
hasForwardingHeaders,
isRemoteAdmitted,
type ResolvedRemoteAccess,
} from './remote-access.ts';
-const DEFAULT_KEEPALIVE_GRACE_MS = 10_000;
-const MAX_COLLAB_MESSAGE_BYTES = 1024 * 1024;
const MCP_CORS_HEADERS = {
'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
'Access-Control-Allow-Headers':
@@ -202,30 +189,19 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl
ephemeral,
} = opts;
const remoteAccess = opts.remoteAccess ?? undefined;
- const keepaliveGraceMs = opts.keepaliveGraceMs ?? DEFAULT_KEEPALIVE_GRACE_MS;
- const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_COLLAB_MESSAGE_BYTES });
- wss.on('error', (err) => {
- log.error({ err }, 'WebSocketServer error');
+ const collaborationHost = createCollaborationHost({
+ hocuspocus,
+ log,
+ sessionManager,
+ agentFocusBroadcaster,
+ agentPresenceBroadcaster,
+ maintenanceCoordinator,
+ keepaliveGraceMs: opts.keepaliveGraceMs,
+ acpThreadManager: opts.acpThreadManager,
+ remoteAccess,
});
- // connectionId → pending grace timer handle.
- const keepaliveGraceTimers = new Map<string, ReturnType<typeof setTimeout>>();
- // In-flight grace-timer callbacks so `shutdown()` can await them rather than
- // racing against the sessionManager / agentFocusBroadcaster teardown.
- const keepaliveGraceInflight = new Set<Promise<void>>();
- // Raw upgrade sockets (the `Duplex` handed to the `'upgrade'` handler) for
- // every live `/collab` + `/collab/keepalive` connection. `shutdown()` destroys
- // these so the caller's `wss.close()` / `httpServer.close()` steps resolve —
- // an upgraded socket is detached from the HTTP server and `httpServer.close()`
- // will not return while one is open, and `httpServer.closeAllConnections()`
- // does not reliably reap upgrade-detached sockets across runtimes. Mirrors
- // the drain in `cli/src/commands/ui.ts` / `ui-proxy.ts`.
- const liveUpgradeSockets = new Set<Duplex>();
- // Set when `shutdown()` runs so any callback that fired just before the
- // timer was cleared can short-circuit instead of touching disposed resources.
- let shuttingDown = false;
-
const onRequest = (req: IncomingMessage, res: ServerResponse): void => {
const url = req.url?.split('?')[0];
// Tripwire: proxy-forwarding headers on a server that never opted into
@@ -448,311 +424,33 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl
};
const onUpgrade = (req: IncomingMessage, socket: Duplex, head: Buffer): void => {
- // Same tripwire as the HTTP leg: a proxied upgrade on a server that never
- // opted into remote access is refused rather than trusted as local.
+ if (collaborationHost.handleUpgrade(req, socket, head)) return;
if (remoteAccess === undefined && hasForwardingHeaders(req)) {
log.warn(
{ url: req.url, host: req.headers.host },
'[remote] refused proxied WS upgrade; start the server with `ok start --remote <url>`',
);
- socket.destroy();
- return;
- }
- // Shared admit decision for the `/collab/thread` + `/collab/keepalive`
- // upgrades. Remote mode widens the Host allowlist to the tunnel's public
- // host through the `isRemoteAdmitted` choke point (tunnel traffic arrives
- // loopback-peer + public-Host); local mode keeps the loopback-peer +
- // workspace-Host gate. The bare `/collab` catch-all below relies on the
- // loopback bind in local mode, so it only consults `isRemoteAdmitted`.
- const collabUpgradeAdmitted = (): boolean =>
- remoteAccess !== undefined
- ? isRemoteAdmitted(req, remoteAccess)
- : isLoopbackAddress(req.socket.remoteAddress) &&
- isAllowedWorkspaceHostHeader(req.headers.host);
- if (req.url?.startsWith('/collab/thread')) {
- // Admit via the shared `/collab` upgrade gate (remote-widened Host in
- // remote mode), plus the browser-Origin allowlist when an Origin is
- // present (WS upgrades from pages always carry one; a DNS-rebound page
- // fails the Host check, a foreign page fails the Origin check).
- const acp = opts.acpThreadManager;
- if (
- acp === undefined ||
- acp === null ||
- !collabUpgradeAdmitted() ||
- (req.headers.origin !== undefined &&
- !isAllowedApiOrigin(req.headers.origin, remoteAccess?.publicHost))
- ) {
- log.debug(
- { url: req.url, host: req.headers.host, origin: req.headers.origin },
- '[collab] /collab/thread upgrade refused',
- );
- socket.destroy();
- return;
- }
- socket.on('error', (err: NodeJS.ErrnoException) => {
- if (handleCollabSocketError(err)) return;
- log.error({ err }, 'ACP thread socket error');
- });
- liveUpgradeSockets.add(socket);
- socket.once('close', () => liveUpgradeSockets.delete(socket));
- wss.handleUpgrade(req, socket, head, (ws) => {
- attachAcpThreadSocket(ws, acp, log);
- });
- return;
- }
-
- if (req.url?.startsWith('/collab/keepalive')) {
- if (!collabUpgradeAdmitted()) {
- log.debug(
- { url: req.url, host: req.headers.host },
- '[collab] /collab/keepalive upgrade refused',
- );
- socket.destroy();
- return;
- }
- socket.on('error', (err: NodeJS.ErrnoException) => {
- if (handleCollabSocketError(err)) return;
- log.error({ err }, 'MCP keepalive socket error');
- });
- liveUpgradeSockets.add(socket);
- socket.once('close', () => liveUpgradeSockets.delete(socket));
- wss.handleUpgrade(req, socket, head, (ws) => {
- // Per-session connectionId from the URL. Validated through the same
- // regex as the HTTP write path (`extractAgentIdentity` in
- // `api-extension.ts`) so the keepalive cleanup surface and the write
- // surface share one contract — without it a caller who can reach the
- // keepalive WS could force-evict another agent's presence by
- // crafting `connectionId=<victim>` on close.
- const connectionId = parseKeepaliveConnectionId(req.url);
-
- // Reconnect within the grace window cancels the pending eviction.
- if (connectionId) {
- const existing = keepaliveGraceTimers.get(connectionId);
- if (existing !== undefined) {
- clearTimeout(existing);
- keepaliveGraceTimers.delete(connectionId);
- log.info({ connectionId }, '[keepalive] reconnect during grace — timer cancelled');
- }
- }
-
- // Bootstrap a presence entry on connect when the cli's MCP shim
- // forwarded full identity in the URL. Without this, `bumpPresenceTs`
- // (the 3 s heartbeat below) is a documented no-op until something
- // else calls `setPresence` first — which only happens for the four
- // mutating HTTP write handlers in `api-extension.ts`. Lifting the
- // bootstrap to the WS-upgrade handler makes presence appear on
- // every MCP connect, regardless of whether the agent ever issues
- // a write tool.
- //
- // Identity sanitisation lives in `parseKeepaliveIdentity` — log
- // injection / awareness pollution surface. Mirrors the helper-chain
- // the four handler-level setPresence sites use (iconFromClientName /
- // AGENT_ICON_COLORS / colorFromSeed) so the entry shape is
- // bit-identical to what a write would have produced.
- if (connectionId && agentPresenceBroadcaster) {
- const identity = parseKeepaliveIdentity(req.url);
- if (identity) {
- try {
- const icon = iconFromClientName(identity.clientName);
- const color = AGENT_ICON_COLORS[icon] ?? colorFromSeed(identity.colorSeed);
- agentPresenceBroadcaster.setPresence(toBroadcasterKey(connectionId), {
- displayName: identity.displayName,
- icon,
- color,
- // Sentinel `currentDoc` so the badge surfaces in the
- // cross-doc bucket — the client filter at
- // `packages/app/src/lib/agent-presence.ts` drops entries
- // with falsy `currentDoc`, so null would mean the
- // bootstrap entry stays hidden until the agent's first
- // write. The `(connected)` form is human-readable and
- // distinct from any real docName; future click-to-navigate
- // handlers can short-circuit on the leading `(`.
- currentDoc: '(connected)',
- mode: 'idle',
- ts: Date.now(),
- });
- } catch (err) {
- log.error({ err, connectionId }, '[keepalive] presence bootstrap failed');
- }
- }
- }
-
- const pingTimer = setInterval(() => {
- try {
- ws.ping();
- } catch {
- // Dead socket fires 'close' + 'error' which clean up below.
- }
- }, 30_000);
- pingTimer.unref?.();
-
- // Presence-ts heartbeat — beats the client-side 5 s TTL filter when
- // an agent sits idle between tool calls (LLM "thinking" 10–30 s).
- // `toBroadcasterKey(connectionId)` translates the raw URL id into
- // the `agent-<id>` map key used by HTTP write handlers via
- // `extractAgentIdentity`; without the prefix `bumpPresenceTs` no-ops
- // because no entry lives under the bare key.
- const tsRefreshTimer = connectionId
- ? setInterval(() => {
- agentPresenceBroadcaster?.bumpPresenceTs(toBroadcasterKey(connectionId));
- }, 3_000)
- : null;
- tsRefreshTimer?.unref?.();
-
- ws.on('close', () => {
- clearInterval(pingTimer);
- if (tsRefreshTimer !== null) clearInterval(tsRefreshTimer);
- if (!connectionId) return;
- const timer = setTimeout(() => {
- keepaliveGraceTimers.delete(connectionId);
- // If `shutdown()` already ran, the sessionManager + broadcasters
- // may be mid-teardown — racing them is worse than skipping
- // cleanup (TOCTOU between our clearTimeout loop and the timer
- // firing).
- if (shuttingDown) return;
- const work = (async () => {
- log.info({ connectionId }, '[keepalive] grace expired — cleaning up sessions');
- try {
- await sessionManager?.closeAllForAgent(connectionId);
- } catch (err) {
- log.error({ err, connectionId }, '[keepalive] closeAllForAgent failed');
- }
- try {
- agentFocusBroadcaster?.clearFocus(connectionId);
- } catch (err) {
- log.error({ err, connectionId }, '[keepalive] clearFocus failed');
- }
- try {
- agentPresenceBroadcaster?.clearPresence(toBroadcasterKey(connectionId));
- } catch (err) {
- log.error({ err, connectionId }, '[keepalive] clearPresence failed');
- }
- // The closed session's writer is now dead — evaluate maintenance
- // (session-close trigger) off the write path. Gated +
- // fire-and-forget; never blocks session teardown.
- // Scope: this is the ONLY `session-close`-labelled trigger, so it
- // fires only for keepalive-WS sessions. HTTP-only MCP callers,
- // direct Hocuspocus connections, and bulk `closeAll()` on shutdown
- // don't reach it — their dead chains are still reaped by the
- // flush-counter and boot triggers, so coverage is complete; only the
- // `session-close` telemetry label under-counts those paths.
- try {
- await maintenanceCoordinator?.onSessionClose();
- } catch (err) {
- log.error({ err, connectionId }, '[keepalive] maintenance onSessionClose failed');
- }
- })();
- keepaliveGraceInflight.add(work);
- work.finally(() => keepaliveGraceInflight.delete(work));
- }, keepaliveGraceMs);
- timer.unref?.();
- keepaliveGraceTimers.set(connectionId, timer);
- log.info(
- { connectionId, graceMs: keepaliveGraceMs },
- '[keepalive] disconnected — grace timer started',
- );
- });
- ws.on('error', (err: NodeJS.ErrnoException) => {
- if (!handleCollabSocketError(err)) {
- log.error({ err }, 'MCP keepalive WS error');
- }
- ws.terminate();
- });
- });
- return;
- }
-
- if (req.url?.startsWith('/collab')) {
- // Same admit gate as the HTTP legs: a wrong-Host upgrade never reaches
- // Hocuspocus (the CRDT write surface).
- if (remoteAccess !== undefined && !isRemoteAdmitted(req, remoteAccess)) {
- log.debug({ url: req.url, host: req.headers.host }, '[collab] /collab upgrade refused');
- socket.destroy();
- return;
- }
- socket.on('error', (err: NodeJS.ErrnoException) => {
- if (handleCollabSocketError(err)) return;
- log.error({ err }, 'Upgrade socket error');
- });
- liveUpgradeSockets.add(socket);
- socket.once('close', () => liveUpgradeSockets.delete(socket));
- wss.handleUpgrade(req, socket, head, (ws) => {
- const clientConnection = hocuspocus.handleConnection(
- ws as unknown as WebSocket,
- req as unknown as Request,
- );
- let closedByPolicy = false;
- ws.on('message', (data: ArrayBuffer | Buffer) => {
- if (closedByPolicy) return;
- const bytes = data.byteLength;
- if (bytes > MAX_COLLAB_MESSAGE_BYTES) {
- closedByPolicy = true;
- incrementCollabMessageTooLarge();
- log.warn(
- { event: 'collab-message-too-large', bytes, limit: MAX_COLLAB_MESSAGE_BYTES },
- 'Collab WebSocket message rejected before Yjs processing',
- );
- ws.close(1009, 'Message Too Big');
- return;
- }
- clientConnection.handleMessage(new Uint8Array(data as Buffer));
- });
- ws.on('close', (code: number, reason: Buffer) => {
- clientConnection.handleClose({ code, reason: reason.toString() });
- });
- ws.on('error', (err: NodeJS.ErrnoException) => {
- if (err.code === 'WS_ERR_UNSUPPORTED_MESSAGE_LENGTH') {
- incrementCollabMessageTooLarge();
- log.warn(
- { event: 'collab-message-too-large', limit: MAX_COLLAB_MESSAGE_BYTES },
- 'Collab WebSocket frame rejected by ws maxPayload before Yjs processing',
- );
- ws.terminate();
- return;
- }
- if (!handleCollabSocketError(err)) {
- log.error({ err }, 'WebSocket error');
- }
- ws.terminate();
- });
- });
- return;
}
-
socket.destroy();
};
httpServer.on('request', onRequest);
httpServer.on('upgrade', onUpgrade);
+ let shutdownPromise: Promise<void> | undefined;
+ const shutdown = (): Promise<void> => {
+ shutdownPromise ??= (async () => {
+ // Reject new upgrades before the host's one-shot socket drain; a socket
+ // admitted afterward would have no later mount shutdown to reap it.
+ httpServer.off('upgrade', onUpgrade);
+ await collaborationHost.shutdown();
+ })();
+ return shutdownPromise;
+ };
+
return {
- wss,
- shutdown: async (): Promise<void> => {
- if (shuttingDown) return;
- // Set before destroying sockets so any `'close'` handler that fires as a
- // result sees the flag and skips scheduling fresh grace-cleanup work.
- shuttingDown = true;
- // Destroy every live upgrade socket. Without this the caller's
- // `wss.close()` and `httpServer.close()` steps block on the still-open
- // sockets until their destroy-step timeout fires (see
- // `MountMcpAndApiHandle.shutdown`). Destroying the raw socket also fires
- // each WS's `'close'` handler, so keepalive cleanup still runs.
- for (const socket of liveUpgradeSockets) {
- try {
- socket.destroy();
- } catch {
- // Best-effort — an already-destroyed socket is a no-op.
- }
- }
- liveUpgradeSockets.clear();
- for (const timer of keepaliveGraceTimers.values()) {
- clearTimeout(timer);
- }
- keepaliveGraceTimers.clear();
- if (keepaliveGraceInflight.size > 0) {
- await Promise.allSettled(keepaliveGraceInflight);
- }
- },
+ wss: collaborationHost.wss,
+ shutdown,
};
}
@@ -777,62 +475,4 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl
*
* Exported for unit testing. Never throws.
*/
-export function parseKeepaliveConnectionId(url: string | undefined): string | null {
- if (!url) return null;
- try {
- // The second arg is a dummy base so `new URL` accepts path-only inputs.
- const parsed = new URL(url, 'http://localhost');
- const connectionId = parsed.searchParams.get('connectionId');
- return validateAgentId(connectionId);
- } catch {
- return null;
- }
-}
-
-/**
- * Identity bundle parsed from the keepalive URL when the cli's MCP shim
- * passes `displayName` + `clientName` + `colorSeed` alongside `connectionId`.
- * All three must be present for the server's WS-upgrade handler to bootstrap
- * a presence entry — the entry shape requires `displayName` + `icon` (derived
- * from `clientName`) + `color` (derived from `colorSeed`), and a partial
- * identity has no useful fallback.
- *
- * Length cap mirrors `validateAgentId` defense-in-depth: log-injection +
- * bounded-cardinality span attribute hygiene. 256 chars is generous for
- * human display names and conservatively below the URL line-length some
- * proxies start truncating at.
- *
- * Exported for unit testing. Never throws.
- */
-const MAX_KEEPALIVE_IDENTITY_LEN = 256;
-
-function sanitizeIdentityField(raw: string | null): string | null {
- if (raw === null) return null;
- if (raw.length === 0 || raw.length > MAX_KEEPALIVE_IDENTITY_LEN) return null;
- // Strip control chars (defense-in-depth against log-injection / awareness
- // value pollution). Allow normal printable Unicode (display names may
- // include spaces, punctuation, non-ASCII letters).
- // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional sanitisation
- if (/[-]/.test(raw)) return null;
- return raw;
-}
-
-interface KeepaliveIdentity {
- displayName: string;
- clientName: string;
- colorSeed: string;
-}
-
-export function parseKeepaliveIdentity(url: string | undefined): KeepaliveIdentity | null {
- if (!url) return null;
- try {
- const parsed = new URL(url, 'http://localhost');
- const displayName = sanitizeIdentityField(parsed.searchParams.get('displayName'));
- const clientName = sanitizeIdentityField(parsed.searchParams.get('clientName'));
- const colorSeed = sanitizeIdentityField(parsed.searchParams.get('colorSeed'));
- if (displayName === null || clientName === null || colorSeed === null) return null;
- return { displayName, clientName, colorSeed };
- } catch {
- return null;
- }
-}
+export { parseKeepaliveConnectionId, parseKeepaliveIdentity } from './collaboration-host.ts';