Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(server): drain live WS sockets on shutdown so ok start quits promptly (PRD-7200) (#2239)

mike-inkeepb6894e2d6264
diff --git a/.changeset/fix-ok-start-shutdown-ws-drain.md b/.changeset/fix-ok-start-shutdown-ws-drain.md
new file mode 100644
index 000000000..5f4dae296
--- /dev/null
+++ b/.changeset/fix-ok-start-shutdown-ws-drain.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Fix `ok start` hanging for about 10 seconds on Ctrl+C when a live client was connected. If a browser preview tab or an agent/MCP session held a WebSocket open, shutdown left that socket alive, so the WebSocket-server close and the HTTP-server close each blocked until a 5-second internal timeout fired — adding ~10s of delay and printing an alarming `AggregateError` on a routine quit. Shutdown now drains the live upgrade sockets up front (mirroring the existing drain in `ok ui`), so both close steps finish promptly and the server lock is released right away.
diff --git a/packages/server/src/mcp-mount.test.ts b/packages/server/src/mcp-mount.test.ts
index 4d9ace0f4..6a2588c12 100644
--- a/packages/server/src/mcp-mount.test.ts
+++ b/packages/server/src/mcp-mount.test.ts
@@ -11,6 +11,7 @@ import {
INLINE_RENDERABLE_EXTENSIONS,
} from '@inkeep/open-knowledge-core';
import sirv from 'sirv';
+import { WebSocket } from 'ws';
import { createAssetServeMiddleware } from './asset-serve-middleware.ts';
import { getFreeLoopbackPort } from './loopback-rig-test-helpers.ts';
import type { McpHttpHandler } from './mcp-http.ts';
@@ -240,6 +241,57 @@ describe('mountMcpAndApi /mcp guard', () => {
});
});
+describe('mountMcpAndApi shutdown drains live WS clients', () => {
+ for (const path of ['/collab', '/collab/keepalive?connectionId=teardown-probe']) {
+ test(`drains live ${path.split('?')[0]} WS so wss.close + httpServer.close resolve promptly`, async () => {
+ const httpServer = createServer();
+ const mount = mountMcpAndApi({ httpServer, hocuspocus, log });
+ const port = await getFreeLoopbackPort();
+ await new Promise<void>((resolve) => httpServer.listen(port, '127.0.0.1', () => resolve()));
+
+ const client = new WebSocket(`ws://127.0.0.1:${port}${path}`);
+ client.on('error', () => {});
+ try {
+ await new Promise<void>((resolve, reject) => {
+ client.once('open', () => resolve());
+ client.once('error', reject);
+ });
+ expect(mount.wss.clients.size).toBe(1);
+
+ const teardown = (async (): Promise<'done'> => {
+ await mount.shutdown();
+ await new Promise<void>((resolve, reject) =>
+ mount.wss.close((err) => (err ? reject(err) : resolve())),
+ );
+ await new Promise<void>((resolve, reject) =>
+ httpServer.close((err) =>
+ err && (err as NodeJS.ErrnoException).code !== 'ERR_SERVER_NOT_RUNNING'
+ ? reject(err)
+ : resolve(),
+ ),
+ );
+ return 'done';
+ })();
+
+ let budgetTimer: ReturnType<typeof setTimeout> | undefined;
+ const result = await Promise.race([
+ teardown,
+ new Promise<'timeout'>((resolve) => {
+ budgetTimer = setTimeout(() => resolve('timeout'), 2000);
+ }),
+ ]);
+ if (budgetTimer !== undefined) clearTimeout(budgetTimer);
+
+ expect(result).toBe('done');
+ expect(mount.wss.clients.size).toBe(0);
+ } finally {
+ client.terminate();
+ httpServer.closeAllConnections?.();
+ }
+ });
+ }
+});
+
describe('mountMcpAndApi content-asset middleware', () => {
const tmpDirs: string[] = [];
diff --git a/packages/server/src/mcp-mount.ts b/packages/server/src/mcp-mount.ts
index 315dea6ea..764a4070c 100644
--- a/packages/server/src/mcp-mount.ts
+++ b/packages/server/src/mcp-mount.ts
@@ -67,6 +67,7 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl
const keepaliveGraceTimers = new Map<string, ReturnType<typeof setTimeout>>();
const keepaliveGraceInflight = new Set<Promise<void>>();
+ const liveUpgradeSockets = new Set<Duplex>();
let shuttingDown = false;
const onRequest = (req: IncomingMessage, res: ServerResponse): void => {
@@ -225,6 +226,8 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl
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) => {
const connectionId = parseKeepaliveConnectionId(req.url);
@@ -326,6 +329,8 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl
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,
@@ -380,6 +385,12 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandl
shutdown: async (): Promise<void> => {
if (shuttingDown) return;
shuttingDown = true;
+ for (const socket of liveUpgradeSockets) {
+ try {
+ socket.destroy();
+ } catch {}
+ }
+ liveUpgradeSockets.clear();
for (const timer of keepaliveGraceTimers.values()) {
clearTimeout(timer);
}