Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

PRD-9756 Let the project server finish shutting down before quit (#7352)

Nick Gomez29eda806db3d
diff --git a/.changeset/server-stop-continues-after-watcher-failure.md b/.changeset/server-stop-continues-after-watcher-failure.md
new file mode 100644
index 000000000..cfd9df7ac
--- /dev/null
+++ b/.changeset/server-stop-continues-after-watcher-failure.md
@@ -0,0 +1,5 @@
+---
+'@inkeep/open-knowledge': patch
+---
+
+Stopping a server now keeps stopping its other file watchers when one of them fails to stop.
diff --git a/packages/desktop/src/main/app-quit-drain.ts b/packages/desktop/src/main/app-quit-drain.ts
new file mode 100644
index 000000000..35df0d49e
--- /dev/null
+++ b/packages/desktop/src/main/app-quit-drain.ts
@@ -0,0 +1,15 @@
+export interface AppQuitDrainDeps {
+ stopTerminals(): Promise<void>;
+ reapSlideDecks(): Promise<void>;
+ drainProjectServers(): Promise<void>;
+ onTerminalStopFailed(reason: unknown): void;
+}
+
+export async function drainAppOwnedWork(deps: AppQuitDrainDeps): Promise<void> {
+ const [terminalResult] = await Promise.allSettled([
+ deps.stopTerminals(),
+ deps.reapSlideDecks(),
+ deps.drainProjectServers(),
+ ]);
+ if (terminalResult.status === 'rejected') deps.onTerminalStopFailed(terminalResult.reason);
+}
diff --git a/packages/desktop/src/main/index.ts b/packages/desktop/src/main/index.ts
index 95b90b57c..ece0322b1 100644
--- a/packages/desktop/src/main/index.ts
+++ b/packages/desktop/src/main/index.ts
@@ -177,6 +177,7 @@ import {
type ProjectWriterSurface,
} from './agent-registry-apply.ts';
import { collectDesktopHostSnapshot, withoutProjectScope } from './agent-registry-probes.ts';
+import { drainAppOwnedWork } from './app-quit-drain.ts';
import { appendOkIgnoreSync } from './append-okignore.ts';
import { registerAppImageDeepLinks } from './appimage-integration.ts';
import { openAssetOrReveal, openAssetSafely, revealAssetSafely } from './asset-allowlist.ts';
@@ -588,6 +589,7 @@ import {
windowChromeOptsForKind,
} from './window-chrome.ts';
import {
+ APP_QUITTING_OPEN_KIND,
type BrowserWindowLike,
bringWindowToFront,
collabUrlFromApiOrigin,
@@ -2203,6 +2205,31 @@ async function openProjectOrFallbackToNavigator(
} catch (err) {
const errorMessage = (err as Error).message;
const kind = (err as Error & { kind?: string }).kind;
+ if (kind === APP_QUITTING_OPEN_KIND) {
+ const cause = (err as Error).cause;
+ const underlying:
+ | (Error & {
+ kind?: string;
+ holderPid?: number;
+ exitCode?: number | null;
+ exitSignal?: string | null;
+ })
+ | undefined = cause instanceof Error ? cause : undefined;
+ getLogger('project').info(
+ {
+ event: 'desktop-open-project-cancelled-by-quit',
+ projectPath,
+ entryPoint,
+ causeKind: underlying?.kind,
+ holderPid: underlying?.holderPid,
+ exitCode: underlying?.exitCode,
+ exitSignal: underlying?.exitSignal,
+ err,
+ },
+ '[main] project open cancelled because the app is quitting',
+ );
+ return false;
+ }
const otherChannelHolder = failedOpenHolder(err, projectPath, wm as WindowManager | undefined);
const holderPid =
otherChannelHolder?.holderPid ?? (err as Error & { holderPid?: number }).holderPid;
@@ -7098,15 +7125,14 @@ function bootPrimaryInstance(): void {
const runTerminalQuitDrain = createTerminalQuitDrain({
defer: (callback) => setImmediate(callback),
- drain: async () => {
- const [terminalResult] = await Promise.allSettled([
- terminalReaper?.killAll('quit') ?? Promise.resolve(),
- slidesDeckRegistry.reapAll(),
- ]);
- if (terminalResult.status === 'rejected') {
- getLogger('lifecycle').warn({ err: terminalResult.reason }, 'terminal quit drain failed');
- }
- },
+ drain: () =>
+ drainAppOwnedWork({
+ stopTerminals: () => terminalReaper?.killAll('quit') ?? Promise.resolve(),
+ reapSlideDecks: () => slidesDeckRegistry.reapAll(),
+ drainProjectServers: () => wm?.drainOwnedUtilities() ?? Promise.resolve(),
+ onTerminalStopFailed: (err) =>
+ getLogger('lifecycle').warn({ err }, 'terminal quit drain failed'),
+ }),
resumeQuit: () => app.quit(),
});
app.on('will-quit', (event) => {
diff --git a/packages/desktop/src/main/window-manager.ts b/packages/desktop/src/main/window-manager.ts
index 474cdac41..43f69747b 100644
--- a/packages/desktop/src/main/window-manager.ts
+++ b/packages/desktop/src/main/window-manager.ts
@@ -229,6 +229,21 @@ function otherChannelHolderError(
);
}
+export const APP_QUITTING_OPEN_KIND = 'app-quitting';
+
+interface TrackedUtility {
+ readonly exited: Promise<void>;
+ readonly serviceName: string;
+ spawnedPid(): number | undefined;
+}
+
+function openCancelledByQuitError(projectPath: string, cause: unknown): Error {
+ return Object.assign(
+ new Error(`opening ${projectPath} was cancelled because the app is quitting`, { cause }),
+ { name: 'OpenCancelledByQuitError', kind: APP_QUITTING_OPEN_KIND },
+ );
+}
+
export function isOtherChannelHolderError(err: unknown): err is OtherChannelHolderError {
if (!(err instanceof Error)) return false;
const fields = err as Partial<OtherChannelHolderError>;
@@ -575,6 +590,9 @@ export class WindowManager {
private readonly keepalives = new Map<string, KeepaliveHandle>();
+ private readonly liveUtilities = new Map<UtilityProcessLike, TrackedUtility>();
+ private quitDrainStarted = false;
+
private projectServerSequence = 0;
private readonly deps: WindowManagerDeps;
@@ -714,6 +732,75 @@ export class WindowManager {
]);
}
+ async drainOwnedUtilities(): Promise<void> {
+ this.quitDrainStarted = true;
+ const live = [...this.liveUtilities];
+ if (live.length === 0) return;
+ const graceMs = this.deps.sigtermGraceMs ?? DEFAULT_SIGTERM_GRACE_MS;
+ this.deps.log?.info(
+ { event: 'desktop-project-server-quit-drain', count: live.length, graceMs },
+ '[window-manager] waiting for project servers to exit before quit',
+ );
+ await Promise.all(
+ live.map(([utility, tracked]) => this.drainUtility(utility, tracked, graceMs)),
+ );
+ }
+
+ private drainUtility(
+ utility: UtilityProcessLike,
+ tracked: TrackedUtility,
+ graceMs: number,
+ ): Promise<void> {
+ const identity = () => ({ name: tracked.serviceName, pid: tracked.spawnedPid() });
+ let hasExited = false;
+ let graceExpired = false;
+ void tracked.exited.then(() => {
+ hasExited = true;
+ this.deps.log?.info(
+ { event: 'desktop-project-server-quit-drain-exited', ...identity(), graceExpired },
+ '[window-manager] project server exited during the quit drain',
+ );
+ });
+ try {
+ utility.postMessage({ type: 'shutdown' });
+ } catch (err) {
+ this.deps.log?.warn(
+ { err, ...identity() },
+ 'utility shutdown IPC failed at quit (likely already exited)',
+ );
+ }
+ this.deps.setTimeout(() => {
+ if (hasExited) return;
+ graceExpired = true;
+ const termination = utility.kill() ? 'killed' : 'kill-refused';
+ this.deps.log?.warn(
+ {
+ event: 'desktop-project-server-quit-drain-grace-expired',
+ ...identity(),
+ graceMs,
+ termination,
+ },
+ '[window-manager] project server did not exit within its grace at quit, terminating it',
+ );
+ this.deps.flushLog?.();
+ }, graceMs);
+ return tracked.exited;
+ }
+
+ private trackUtilityUntilExit(utility: UtilityProcessLike, serviceName: string): void {
+ let pid = utility.pid;
+ utility.once('spawn', () => {
+ pid = utility.pid;
+ });
+ const exited = new Promise<void>((resolveExit) => {
+ utility.on('exit', () => {
+ this.liveUtilities.delete(utility);
+ resolveExit();
+ });
+ });
+ this.liveUtilities.set(utility, { exited, serviceName, spawnedPid: () => pid });
+ }
+
signalStopAllOwnedServers(): void {
signalStopOwnedUtilityForks(this.windowsByPath.values(), this.deps.log);
@@ -1359,6 +1446,8 @@ export class WindowManager {
const work = (async (): Promise<ProjectContext> => {
try {
return await this.spawnProjectWindow(opts);
+ } catch (err) {
+ throw this.quitDrainStarted ? openCancelledByQuitError(opts.projectPath, err) : err;
} finally {
this.projectPendingByPath.delete(canonicalKey);
}
@@ -1624,6 +1713,9 @@ export class WindowManager {
? resolveLocalOpCliArgsForUtilityFork(opts.localOpCliInvocation)
: null;
+ if (this.quitDrainStarted) {
+ throw new Error('no project server is started once the app has begun quitting');
+ }
const serviceName = `OpenKnowledge Project Server ${++this.projectServerSequence}`;
const utility = this.deps.forkUtility(
this.deps.utilityEntryPath,
@@ -1633,6 +1725,7 @@ export class WindowManager {
serviceName,
},
);
+ this.trackUtilityUntilExit(utility, serviceName);
const forkedAt = Date.now();
this.deps.log?.info(
{
diff --git a/packages/desktop/src/utility/server-entry.ts b/packages/desktop/src/utility/server-entry.ts
index 5a47da0b9..33d6a2e14 100644
--- a/packages/desktop/src/utility/server-entry.ts
+++ b/packages/desktop/src/utility/server-entry.ts
@@ -155,7 +155,8 @@ export interface UtilityHandle {
export function setupUtility(deps: SetupUtilityDeps): UtilityHandle {
let booted: UtilityBootedServer | null = null;
let parentPollHandle: { unref?: () => void; clear: () => void } | null = null;
- let shuttingDown = false;
+ let initInFlight: Promise<void> | null = null;
+ let shutdownInFlight: Promise<void> | null = null;
let resolveReady!: (msg: UtilityReadyMessage) => void;
let rejectReady!: (err: Error) => void;
const readyPromise = new Promise<UtilityReadyMessage>((resolve, reject) => {
@@ -188,10 +189,14 @@ export function setupUtility(deps: SetupUtilityDeps): UtilityHandle {
parentPollHandle = null;
}
- async function shutdown(reason: UtilityShutdownReason): Promise<void> {
- if (shuttingDown) return;
- shuttingDown = true;
+ function shutdown(reason: UtilityShutdownReason): Promise<void> {
+ shutdownInFlight ??= drainAndExit(reason);
+ return shutdownInFlight;
+ }
+
+ async function drainAndExit(reason: UtilityShutdownReason): Promise<void> {
stopParentPoll();
+ await initInFlight;
let drainOk = true;
if (booted) {
try {
@@ -205,6 +210,11 @@ export function setupUtility(deps: SetupUtilityDeps): UtilityHandle {
});
}
}
+ console.warn('[utility] shutdown finished, exiting', {
+ reason,
+ destroyResolved: booted !== null && drainOk,
+ exitCode: drainOk ? 0 : 1,
+ });
deps.exit(drainOk ? 0 : 1);
}
@@ -237,7 +247,7 @@ export function setupUtility(deps: SetupUtilityDeps): UtilityHandle {
const projectDir = msg.opts.projectDir ?? msg.opts.contentDir;
const prepare = deps.prepareBootEnvironment ?? defaultPrepareBootEnvironment;
const prepared = await prepare(msg.opts, markInitPhase);
- if (shuttingDown) return;
+ if (shutdownInFlight !== null) return;
if (env.OK_DEBUG_DESKTOP_BOOT_TRACE === '1') {
console.warn(
@@ -289,6 +299,7 @@ export function setupUtility(deps: SetupUtilityDeps): UtilityHandle {
throw err;
}
}
+ if (shutdownInFlight !== null) return;
const readyMsg: UtilityReadyMessage = {
type: 'ready',
port: booted.port,
@@ -337,6 +348,7 @@ export function setupUtility(deps: SetupUtilityDeps): UtilityHandle {
errName === 'GitProbeTimeoutError' ||
errName === 'GitTooOldError';
deps.parentPort?.postMessage(errMsg);
+ if (shutdownInFlight !== null) return;
rejectReady(err as Error);
deps.exit(isGitPreflightFailure ? 78 : 1);
}
@@ -359,7 +371,7 @@ export function setupUtility(deps: SetupUtilityDeps): UtilityHandle {
deps.parentPort?.on('message', (event) => {
const msg = event.data as UtilityIncomingMessage;
if (msg?.type === 'init') {
- void handleInit(msg);
+ initInFlight = handleInit(msg);
} else if (msg?.type === 'shutdown') {
void shutdown('shutdown-ipc');
} else if (msg?.type === 'debug-keyring-smoke') {
diff --git a/packages/desktop/tests/main/window-manager.test.ts b/packages/desktop/tests/main/window-manager.test.ts
index 895011a91..014ef45e5 100644
--- a/packages/desktop/tests/main/window-manager.test.ts
+++ b/packages/desktop/tests/main/window-manager.test.ts
@@ -12,6 +12,7 @@ import { breakServerLockHeldBy } from '../../src/main/server-lock-break.ts';
import type { ShowGateRegistry } from '../../src/main/show-gate.ts';
import type { WindowChromeKind } from '../../src/main/window-chrome.ts';
import {
+ APP_QUITTING_OPEN_KIND,
type BrowserWindowLike,
isOtherChannelHolderError,
otherChannelStopOffer,
@@ -43,20 +44,24 @@ interface MockUtility extends UtilityProcessLike {
}
function makeUtility(pid: number): MockUtility {
- let messageHandler: ((m: unknown) => void) | null = null;
- let exitHandler: ((c: number | null) => void) | null = null;
+ const messageHandlers: Array<(m: unknown) => void> = [];
+ const exitHandlers: Array<(c: number | null) => void> = [];
return {
pid,
postMessage: vi.fn(() => {}),
on: vi.fn((event: 'message' | 'exit', cb: (msg: unknown) => void) => {
- if (event === 'message') messageHandler = cb;
- else if (event === 'exit') exitHandler = cb as (c: number | null) => void;
+ if (event === 'message') messageHandlers.push(cb);
+ else if (event === 'exit') exitHandlers.push(cb as (c: number | null) => void);
}) as UtilityProcessLike['on'],
once: vi.fn(() => {}),
removeListener: vi.fn(() => {}),
kill: vi.fn(() => true),
- fire: (msg) => messageHandler?.(msg),
- fireExit: (code) => exitHandler?.(code),
+ fire: (msg) => {
+ for (const handler of messageHandlers.slice()) handler(msg);
+ },
+ fireExit: (code) => {
+ for (const handler of exitHandlers.slice()) handler(code);
+ },
};
}
@@ -658,6 +663,173 @@ describe('WindowManager', () => {
expect(wm.closeProjectWindow('/tmp/never-opened')).toBe(false);
});
+ describe('drainOwnedUtilities at app quit', () => {
+ async function settles(promise: Promise<void>): Promise<boolean> {
+ let settled = false;
+ void promise.then(() => {
+ settled = true;
+ });
+ await new Promise<void>((resolveTurn) => setImmediate(resolveTurn));
+ return settled;
+ }
+
+ function shutdownPosts(utility: MockUtility): number {
+ return vi
+ .mocked(utility.postMessage)
+ .mock.calls.filter(([msg]) => (msg as { type?: unknown }).type === 'shutdown').length;
+ }
+
+ async function openReadyProject(wm: WindowManager, projectPath: string): Promise<MockUtility> {
+ const opened = wm.createProjectWindow({ projectPath });
+ const utility = env.utilities.at(-1);
+ if (utility === undefined) throw new Error('createProjectWindow forked no utility');
+ utility.fire({ type: 'ready', port: 51020, apiOrigin: 'http://localhost:51020' });
+ await opened;
+ return utility;
+ }
+
+ test('stays pending until a server told to shut down at window close has exited', async () => {
+ const wm = new WindowManager(env.deps);
+ const utility = await openReadyProject(wm, '/tmp/quit-drain-close');
+ env.windows[0]?.fireClose();
+
+ const drained = wm.drainOwnedUtilities();
+
+ expect(shutdownPosts(utility)).toBeGreaterThan(0);
+ expect(await settles(drained)).toBe(false);
+ utility.fireExit(0);
+ expect(await settles(drained)).toBe(true);
+ });
+
+ test('tells a server still starting to shut down and waits for its exit', async () => {
+ const wm = new WindowManager(env.deps);
+ const opening = wm.createProjectWindow({ projectPath: '/tmp/quit-drain-booting' });
+ const utility = env.utilities[0];
+ if (utility === undefined) throw new Error('createProjectWindow forked no utility');
+
+ const drained = wm.drainOwnedUtilities();
+
+ expect(shutdownPosts(utility)).toBe(1);
+ expect(await settles(drained)).toBe(false);
+ utility.fireExit(0);
+ await expect(opening).rejects.toMatchObject({ kind: APP_QUITTING_OPEN_KIND });
+ expect(await settles(drained)).toBe(true);
+ });
+
+ test('an open that fails during the drain keeps that failure as the cause of its quit cancellation', async () => {
+ const wm = new WindowManager(env.deps);
+ const opening = wm.createProjectWindow({ projectPath: '/tmp/quit-drain-collision' }).then(
+ () => null,
+ (err: unknown) => err,
+ );
+ const utility = env.utilities[0];
+ if (utility === undefined) throw new Error('createProjectWindow forked no utility');
+
+ const drained = wm.drainOwnedUtilities();
+ utility.fire({
+ type: 'error',
+ kind: 'lock-collision',
+ message: 'lock held by another server',
+ });
+ const failure = await opening;
+
+ expect(failure).toMatchObject({ kind: APP_QUITTING_OPEN_KIND });
+ expect(failure instanceof Error ? failure.cause : undefined).toMatchObject({
+ kind: 'lock-collision',
+ message: 'lock held by another server',
+ });
+ utility.fireExit(0);
+ expect(await settles(drained)).toBe(true);
+ });
+
+ test('starts no project server for an open still in progress when the drain begins', async () => {
+ let finishClean: (() => void) | undefined;
+ env.deps.runClean = () =>
+ new Promise<void>((resolveClean) => {
+ finishClean = resolveClean;
+ });
+ const wm = new WindowManager(env.deps);
+ const openFailure = wm
+ .createProjectWindow({ projectPath: '/tmp/quit-drain-pending-open' })
+ .then(
+ () => null,
+ (err: unknown) => err,
+ );
+ expect(finishClean).toBeDefined();
+
+ expect(await settles(wm.drainOwnedUtilities())).toBe(true);
+ finishClean?.();
+ await new Promise<void>((resolveTurn) => setImmediate(resolveTurn));
+
+ expect(env.utilities).toHaveLength(0);
+ expect(await openFailure).toMatchObject({ kind: APP_QUITTING_OPEN_KIND });
+ });
+
+ test('joins a server whose window closeProjectWindow closed', async () => {
+ const wm = new WindowManager(env.deps);
+ const utility = await openReadyProject(wm, '/tmp/quit-drain-close-api');
+ expect(wm.closeProjectWindow('/tmp/quit-drain-close-api')).toBe(true);
+
+ const drained = wm.drainOwnedUtilities();
+
+ expect(await settles(drained)).toBe(false);
+ utility.fireExit(0);
+ expect(await settles(drained)).toBe(true);
+ });
+
+ test('terminates a server still running at the end of its grace and ends when it exits', async () => {
+ const graceMs = 7_321;
+ env.deps.sigtermGraceMs = graceMs;
+ const wm = new WindowManager(env.deps);
+ const utility = await openReadyProject(wm, '/tmp/quit-drain-stuck');
+ const timersBefore = env.timers.length;
+
+ const drained = wm.drainOwnedUtilities();
+ const graceTimer = env.timers.slice(timersBefore).find((timer) => timer.ms === graceMs);
+ expect(graceTimer).toBeDefined();
+ expect(utility.kill).not.toHaveBeenCalled();
+ graceTimer?.cb();
+
+ expect(utility.kill).toHaveBeenCalledTimes(1);
+ expect(await settles(drained)).toBe(false);
+ utility.fireExit(null);
+ expect(await settles(drained)).toBe(true);
+ });
+
+ test('leaves a server that exited within its grace alone', async () => {
+ const graceMs = 7_322;
+ env.deps.sigtermGraceMs = graceMs;
+ const wm = new WindowManager(env.deps);
+ const utility = await openReadyProject(wm, '/tmp/quit-drain-prompt');
+ const timersBefore = env.timers.length;
+
+ const drained = wm.drainOwnedUtilities();
+ utility.fireExit(0);
+ expect(await settles(drained)).toBe(true);
+ env.timers
+ .slice(timersBefore)
+ .find((timer) => timer.ms === graceMs)
+ ?.cb();
+
+ expect(utility.kill).not.toHaveBeenCalled();
+ });
+
+ test('does not ask a server that already exited to shut down again', async () => {
+ const wm = new WindowManager(env.deps);
+ const utility = await openReadyProject(wm, '/tmp/quit-drain-exited');
+ utility.fireExit(0);
+ const postsAtExit = shutdownPosts(utility);
+
+ expect(await settles(wm.drainOwnedUtilities())).toBe(true);
+ expect(shutdownPosts(utility)).toBe(postsAtExit);
+ });
+
+ test('ends at once when no project server is running', async () => {
+ const wm = new WindowManager(env.deps);
+ expect(await settles(wm.drainOwnedUtilities())).toBe(true);
+ });
+ });
+
test('closeProjectWindow swallows postMessage errors', async () => {
const wm = new WindowManager(env.deps);
const p = wm.createProjectWindow({ projectPath: '/tmp/detached-port' });
diff --git a/packages/desktop/tests/utility/project-server-quit-drain.harness.ts b/packages/desktop/tests/utility/project-server-quit-drain.harness.ts
new file mode 100644
index 000000000..fbb4e2613
--- /dev/null
+++ b/packages/desktop/tests/utility/project-server-quit-drain.harness.ts
@@ -0,0 +1,235 @@
+import { EventEmitter } from 'node:events';
+import { fileURLToPath } from 'node:url';
+import { MessageChannel, Worker } from 'node:worker_threads';
+import { drainAppOwnedWork } from '../../src/main/app-quit-drain.ts';
+import { createTerminalQuitDrain, type QuitEventLike } from '../../src/main/terminal-quit-drain.ts';
+import {
+ type BrowserWindowLike,
+ type UtilityProcessLike,
+ WindowManager,
+} from '../../src/main/window-manager.ts';
+import {
+ isQuitDrainMode,
+ QUIT_DRAIN_FLAG,
+ QUIT_DRAIN_FLAG_COUNT,
+ QUIT_DRAIN_RESULT_PREFIX,
+ type QuitDrainHarnessResult,
+} from './project-server-quit-drain.test-helper.ts';
+
+process.stdin.on('end', () => process.exit(70));
+process.stdin.resume();
+process.stdin.unref();
+
+const [projectDir, mode] = process.argv.slice(2);
+if (projectDir === undefined || !isQuitDrainMode(mode)) {
+ throw new Error(
+ 'usage: project-server-quit-drain.harness.ts <projectDir> <quit-after-start|quit-during-start>',
+ );
+}
+const flags = new Int32Array(
+ new SharedArrayBuffer(QUIT_DRAIN_FLAG_COUNT * Int32Array.BYTES_PER_ELEMENT),
+);
+const flag = (name: keyof typeof QUIT_DRAIN_FLAG): number =>
+ Atomics.load(flags, QUIT_DRAIN_FLAG[name]);
+const desktopPackageJson = fileURLToPath(new URL('../../package.json', import.meta.url));
+type EventListener = Parameters<EventEmitter['on']>[1];
+
+const utilityWorkers: Worker[] = [];
+const postedToUtility: unknown[] = [];
+
+function forkUtilityInWorker(): UtilityProcessLike {
+ const { port1, port2 } = new MessageChannel();
+ const events = new EventEmitter();
+ const worker = new Worker(
+ new URL('./project-server-quit-drain.worker.harness.ts', import.meta.url),
+ {
+ workerData: { port: port2, flags: flags.buffer, desktopPackageJson, mode },
+ transferList: [port2],
+ },
+ );
+ utilityWorkers.push(worker);
+ port1.unref();
+ port1.on('message', (msg: unknown) => {
+ const message = msg as { type?: unknown; code?: unknown };
+ if (message.type === 'quit-drain-harness:exit') {
+ events.emit('exit', typeof message.code === 'number' ? message.code : null);
+ return;
+ }
+ events.emit('message', msg);
+ });
+ return {
+ pid: undefined,
+ postMessage(msg: unknown) {
+ postedToUtility.push(msg);
+ port1.postMessage(msg);
+ },
+ on(event: 'message' | 'exit', cb: EventListener) {
+ events.on(event, cb);
+ },
+ once(event: 'message' | 'spawn', cb: EventListener) {
+ events.once(event, cb);
+ },
+ removeListener(event: 'message' | 'exit', cb: EventListener) {
+ events.removeListener(event, cb);
+ },
+ kill: () => true,
+ };
+}
+
+function makeProjectWindow(): BrowserWindowLike & { closeForQuit(): void } {
+ const closedHandlers: Array<() => void> = [];
+ let destroyed = false;
+ return {
+ focus() {},
+ isDestroyed: () => destroyed,
+ on(_event: 'closed', cb: () => void) {
+ closedHandlers.push(cb);
+ },
+ once() {},
+ webContents: {
+ send() {},
+ once() {},
+ executeJavaScript: async () => undefined,
+ setWindowOpenHandler() {},
+ on() {},
+ },
+ loadFile: async () => {},
+ loadURL: async () => {},
+ closeForQuit() {
+ destroyed = true;
+ for (const handler of closedHandlers) handler();
+ },
+ };
+}
+
+async function untilWorker(condition: () => boolean): Promise<void> {
+ for (;;) {
+ const events = flag('workerEvents');
+ if (condition()) return;
+ const wake = Atomics.waitAsync(flags, QUIT_DRAIN_FLAG.workerEvents, events);
+ if (wake.async) await wake.value;
+ }
+}
+
+function releaseHeldNativeWork(): void {
+ Atomics.store(flags, QUIT_DRAIN_FLAG.holdsReleased, flag('holdsBegun'));
+ Atomics.notify(flags, QUIT_DRAIN_FLAG.holdsReleased);
+}
+
+const projectWindows: Array<ReturnType<typeof makeProjectWindow>> = [];
+const wm = new WindowManager({
+ createWindow: () => {
+ const window = makeProjectWindow();
+ projectWindows.push(window);
+ return window;
+ },
+ forkUtility: () => forkUtilityInWorker(),
+ utilityEntryPath: 'project-server-quit-drain.worker.harness.ts',
+ rendererEntryPath: 'renderer-is-not-loaded.html',
+ terminalAuthAvailable: false,
+ appVersion: '0.0.0-quit-drain-harness',
+ setTimeout: (cb, ms) => setTimeout(cb, ms).unref(),
+ killProbe: () => {},
+ readProcessStart: () => ({ startedAtMs: Date.now(), clock: 'creation' }),
+ activateApp: () => {},
+ showGate: { register: () => () => {}, fireThemeApplied: () => {} },
+});
+
+let quitDrainSettled = false;
+let resolveQuitProceeds!: () => void;
+const quitProceeds = new Promise<void>((resolve) => {
+ resolveQuitProceeds = resolve;
+});
+const runQuitDrain = createTerminalQuitDrain({
+ defer: (callback) => setImmediate(callback),
+ drain: async () => {
+ try {
+ await drainAppOwnedWork({
+ stopTerminals: async () => {},
+ reapSlideDecks: async () => {},
+ drainProjectServers: () => wm.drainOwnedUtilities(),
+ onTerminalStopFailed: () => {},
+ });
+ } finally {
+ quitDrainSettled = true;
+ }
+ },
+ resumeQuit: () => emitWillQuit(),
+});
+function emitWillQuit(): void {
+ let prevented = false;
+ const event: QuitEventLike = {
+ preventDefault() {
+ prevented = true;
+ },
+ };
+ runQuitDrain(event);
+ if (!prevented) resolveQuitProceeds();
+}
+
+let nativeWorkReleasedWhileQuitHeld = 0;
+async function untilElectronWouldFreeTheUtility(): Promise<QuitDrainHarnessResult['teardown']> {
+ for (;;) {
+ const events = flag('workerEvents');
+ const held = flag('holdsBegun') - flag('holdsReleased');
+ if (held > 0) {
+ if (quitDrainSettled) return 'native-work-held';
+ nativeWorkReleasedWhileQuitHeld += held;
+ releaseHeldNativeWork();
+ continue;
+ }
+ if (flag('exitCalled') === 1) {
+ await quitProceeds;
+ return 'utility-exited';
+ }
+ const wake = Atomics.waitAsync(flags, QUIT_DRAIN_FLAG.workerEvents, events);
+ if (wake.async) await wake.value;
+ }
+}
+
+let projectOpenOutcome: string | null = null;
+let quitBeganWithNativeWorkHeld = false;
+const opening = wm.createProjectWindow({ projectPath: projectDir }).then(
+ () => 'opened',
+ (err: unknown) => (err as { kind?: unknown }).kind?.toString() ?? 'failed',
+);
+
+if (mode === 'quit-after-start') {
+ projectOpenOutcome = await opening;
+ await untilWorker(() => flag('serverInitSettled') === 1);
+ for (const window of projectWindows) window.closeForQuit();
+ emitWillQuit();
+} else {
+ await untilWorker(() => flag('holdsBegun') > 0 || flag('serverInitSettled') === 1);
+ quitBeganWithNativeWorkHeld = flag('holdsBegun') > 0;
+ Atomics.store(flags, QUIT_DRAIN_FLAG.deliverParentMessagesOnRelease, 1);
+ emitWillQuit();
+}
+const shutdownPostedToUtility = postedToUtility.some(
+ (msg) => (msg as { type?: unknown }).type === 'shutdown',
+);
+
+const teardown = await untilElectronWouldFreeTheUtility();
+const nativeOpsPendingAtTeardown = flag('nativeOpsPending');
+if (teardown === 'utility-exited' && projectOpenOutcome === null) {
+ projectOpenOutcome = await opening;
+}
+
+const utilityExited = flag('exitCalled') === 1;
+const result: QuitDrainHarnessResult = {
+ mode,
+ quitBeganWithNativeWorkHeld,
+ shutdownPostedToUtility,
+ nativeOpsStartedDuringShutdown: flag('nativeOpsStartedDuringShutdown'),
+ nativeWorkReleasedWhileQuitHeld,
+ teardown,
+ nativeOpsPendingAtTeardown,
+ nativeSubscribes: flag('nativeSubscribes'),
+ utilityExitCode: utilityExited ? flag('exitCode') : null,
+ nativeOpsPendingAtExit: utilityExited ? flag('nativeOpsPendingAtExit') : null,
+ subscriptionsUnreleasedAtExit: utilityExited ? flag('subscriptionsUnreleasedAtExit') : null,
+ serverStartSettledBeforeExit: utilityExited ? flag('serverStartSettledAtExit') === 1 : null,
+ projectOpenOutcome,
+};
+process.stdout.write(`${QUIT_DRAIN_RESULT_PREFIX}${JSON.stringify(result)}\n`);
+await Promise.all(utilityWorkers.map((worker) => worker.terminate()));
diff --git a/packages/desktop/tests/utility/project-server-quit-drain.test-helper.ts b/packages/desktop/tests/utility/project-server-quit-drain.test-helper.ts
new file mode 100644
index 000000000..24a233731
--- /dev/null
+++ b/packages/desktop/tests/utility/project-server-quit-drain.test-helper.ts
@@ -0,0 +1,45 @@
+export const QUIT_DRAIN_FLAG = {
+ workerEvents: 0,
+ shutdownReceived: 1,
+ nativeOpsPending: 2,
+ nativeOpsStartedDuringShutdown: 3,
+ nativeSubscribes: 4,
+ nativeUnsubscribes: 5,
+ holdsBegun: 6,
+ holdsReleased: 7,
+ deliverParentMessagesOnRelease: 8,
+ serverStartSettled: 9,
+ serverInitSettled: 10,
+ exitCalled: 11,
+ exitCode: 12,
+ nativeOpsPendingAtExit: 13,
+ subscriptionsUnreleasedAtExit: 14,
+ serverStartSettledAtExit: 15,
+} as const;
+
+export const QUIT_DRAIN_FLAG_COUNT = Object.keys(QUIT_DRAIN_FLAG).length;
+
+export const QUIT_DRAIN_MODES = ['quit-after-start', 'quit-during-start'] as const;
+export type QuitDrainMode = (typeof QUIT_DRAIN_MODES)[number];
+
+export function isQuitDrainMode(value: unknown): value is QuitDrainMode {
+ return QUIT_DRAIN_MODES.some((mode) => mode === value);
+}
+
+export interface QuitDrainHarnessResult {
+ readonly mode: QuitDrainMode;
+ readonly quitBeganWithNativeWorkHeld: boolean;
+ readonly shutdownPostedToUtility: boolean;
+ readonly nativeOpsStartedDuringShutdown: number;
+ readonly nativeWorkReleasedWhileQuitHeld: number;
+ readonly teardown: 'utility-exited' | 'native-work-held';
+ readonly nativeOpsPendingAtTeardown: number;
+ readonly nativeSubscribes: number;
+ readonly utilityExitCode: number | null;
+ readonly nativeOpsPendingAtExit: number | null;
+ readonly subscriptionsUnreleasedAtExit: number | null;
+ readonly serverStartSettledBeforeExit: boolean | null;
+ readonly projectOpenOutcome: string | null;
+}
+
+export const QUIT_DRAIN_RESULT_PREFIX = 'quit-drain-harness-result ';
diff --git a/packages/desktop/tests/utility/project-server-quit-drain.test.ts b/packages/desktop/tests/utility/project-server-quit-drain.test.ts
new file mode 100644
index 000000000..e330787d7
--- /dev/null
+++ b/packages/desktop/tests/utility/project-server-quit-drain.test.ts
@@ -0,0 +1,155 @@
+import { type ChildProcess, spawn } from 'node:child_process';
+import { mkdirSync, mkdtempSync, realpathSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, describe, expect, test } from 'vitest';
+import { removeTempDirBestEffort } from '../support/temp-dir-cleanup.test-helper.ts';
+import {
+ QUIT_DRAIN_RESULT_PREFIX,
+ type QuitDrainHarnessResult,
+ type QuitDrainMode,
+} from './project-server-quit-drain.test-helper.ts';
+
+const HARNESS = fileURLToPath(new URL('./project-server-quit-drain.harness.ts', import.meta.url));
+const DESKTOP_DIR = fileURLToPath(new URL('../..', import.meta.url));
+const HARNESS_TEST_TIMEOUT_MS = 120_000;
+const OK_DEBUG_ENV_PREFIX = 'OK_DEBUG_';
+const GIT_ENV_PREFIX = 'GIT_';
+
+const scratchDirs: string[] = [];
+const harnesses: Array<{ child: ChildProcess; closed: Promise<void> }> = [];
+
+afterEach(async () => {
+ for (const { child, closed } of harnesses.splice(0)) {
+ if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
+ await closed;
+ }
+ for (const dir of scratchDirs.splice(0)) removeTempDirBestEffort(dir);
+});
+
+function scratchDir(prefix: string): string {
+ const dir = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
+ scratchDirs.push(dir);
+ return dir;
+}
+
+function fixtureProject(): string {
+ const projectDir = scratchDir('ok-quit-drain-project-');
+ writeFileSync(join(projectDir, 'start.md'), '# Start\n\nquit drain fixture\n');
+ mkdirSync(join(projectDir, 'docs'));
+ writeFileSync(join(projectDir, 'docs', 'second.md'), '# Second\n');
+ return projectDir;
+}
+
+function harnessEnv(home: string): NodeJS.ProcessEnv {
+ const env: NodeJS.ProcessEnv = {};
+ for (const [name, value] of Object.entries(process.env)) {
+ if (!name.startsWith(OK_DEBUG_ENV_PREFIX) && !name.startsWith(GIT_ENV_PREFIX))
+ env[name] = value;
+ }
+ const gitConfig = join(home, '.gitconfig');
+ writeFileSync(gitConfig, '[user]\n\tname = Quit Drain\n\temail = [email protected]\n');
+ return { ...env, HOME: home, USERPROFILE: home, GIT_CONFIG_GLOBAL: gitConfig };
+}
+
+interface HarnessRun {
+ code: number | null;
+ signal: NodeJS.Signals | null;
+ output: string;
+ result: QuitDrainHarnessResult | null;
+}
+
+function runHarness(mode: QuitDrainMode): Promise<HarnessRun> {
+ const projectDir = fixtureProject();
+ const home = scratchDir('ok-quit-drain-home-');
+ const child = spawn(process.execPath, ['--conditions=development', HARNESS, projectDir, mode], {
+ cwd: DESKTOP_DIR,
+ env: harnessEnv(home),
+ stdio: ['pipe', 'pipe', 'pipe'],
+ });
+ const closed = new Promise<void>((resolveClosed) => {
+ child.once('close', () => resolveClosed());
+ });
+ harnesses.push({ child, closed });
+ let output = '';
+ child.stdout?.on('data', (chunk: Buffer) => {
+ output += chunk.toString('utf8');
+ });
+ child.stderr?.on('data', (chunk: Buffer) => {
+ output += chunk.toString('utf8');
+ });
+ return new Promise<HarnessRun>((resolveRun, reject) => {
+ child.once('error', reject);
+ child.once('close', (code, signal) => {
+ const line = output
+ .split('\n')
+ .find((candidate) => candidate.startsWith(QUIT_DRAIN_RESULT_PREFIX));
+ resolveRun({
+ code,
+ signal,
+ output,
+ result:
+ line === undefined
+ ? null
+ : (JSON.parse(line.slice(QUIT_DRAIN_RESULT_PREFIX.length)) as QuitDrainHarnessResult),
+ });
+ });
+ });
+}
+
+function diagnosticsOf(run: HarnessRun): string {
+ return `harness exit code=${run.code} signal=${run.signal}\n${run.output}`;
+}
+
+describe.skipIf(process.platform === 'win32')(
+ 'app quit while the project server releases its file watchers',
+ () => {
+ test(
+ 'the quit waits for the server utility to exit, so no watcher work is pending when its environment is freed',
+ async () => {
+ const run = await runHarness('quit-after-start');
+
+ const diagnostics = diagnosticsOf(run);
+ expect(run.result?.nativeSubscribes, diagnostics).toBeGreaterThan(0);
+ expect(run.result?.nativeOpsStartedDuringShutdown, diagnostics).toBeGreaterThan(0);
+ expect(run.result?.nativeWorkReleasedWhileQuitHeld, diagnostics).toBeGreaterThan(0);
+ expect(run.result, diagnostics).toMatchObject({
+ shutdownPostedToUtility: true,
+ teardown: 'utility-exited',
+ utilityExitCode: 0,
+ nativeOpsPendingAtExit: 0,
+ subscriptionsUnreleasedAtExit: 0,
+ nativeOpsPendingAtTeardown: 0,
+ });
+ expect(run.signal, diagnostics).toBeNull();
+ expect(run.code, diagnostics).toBe(0);
+ },
+ HARNESS_TEST_TIMEOUT_MS,
+ );
+
+ test(
+ 'a quit while the server is still starting waits for that start and releases every watcher before the utility exits',
+ async () => {
+ const run = await runHarness('quit-during-start');
+
+ const diagnostics = diagnosticsOf(run);
+ expect(run.result?.nativeSubscribes, diagnostics).toBeGreaterThan(0);
+ expect(run.result, diagnostics).toMatchObject({
+ quitBeganWithNativeWorkHeld: true,
+ shutdownPostedToUtility: true,
+ teardown: 'utility-exited',
+ utilityExitCode: 0,
+ serverStartSettledBeforeExit: true,
+ nativeOpsPendingAtExit: 0,
+ subscriptionsUnreleasedAtExit: 0,
+ nativeOpsPendingAtTeardown: 0,
+ projectOpenOutcome: 'app-quitting',
+ });
+ expect(run.signal, diagnostics).toBeNull();
+ expect(run.code, diagnostics).toBe(0);
+ },
+ HARNESS_TEST_TIMEOUT_MS,
+ );
+ },
+);
diff --git a/packages/desktop/tests/utility/project-server-quit-drain.worker.harness.ts b/packages/desktop/tests/utility/project-server-quit-drain.worker.harness.ts
new file mode 100644
index 000000000..d08f9132b
--- /dev/null
+++ b/packages/desktop/tests/utility/project-server-quit-drain.worker.harness.ts
@@ -0,0 +1,164 @@
+import { createHook } from 'node:async_hooks';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { type MessagePort, receiveMessageOnPort, workerData } from 'node:worker_threads';
+import { setupUtility } from '../../src/utility/server-entry.ts';
+import { QUIT_DRAIN_FLAG, type QuitDrainMode } from './project-server-quit-drain.test-helper.ts';
+
+type ServerModule = typeof import('@inkeep/open-knowledge-server');
+
+interface QuitDrainWorkerData {
+ port: MessagePort;
+ flags: SharedArrayBuffer;
+ desktopPackageJson: string;
+ mode: QuitDrainMode;
+}
+
+const { port, flags: flagBuffer, desktopPackageJson, mode } = workerData as QuitDrainWorkerData;
+const flags = new Int32Array(flagBuffer);
+const pendingNativeWatcherOps = new Set<number>();
+let serverStartSubscribeHeld = false;
+
+function signalHarness(): void {
+ Atomics.add(flags, QUIT_DRAIN_FLAG.workerEvents, 1);
+ Atomics.notify(flags, QUIT_DRAIN_FLAG.workerEvents);
+}
+
+function parcelOperation(): 'subscribe' | 'unsubscribe' | 'other' | null {
+ const limit = Error.stackTraceLimit;
+ Error.stackTraceLimit = 80;
+ const stack = new Error('native watcher operation').stack ?? '';
+ Error.stackTraceLimit = limit;
+ const frame = stack.split('\n').find((line) => line.includes('@parcel/watcher'));
+ if (frame === undefined) return null;
+ const operation = /at (?:[\w$]+\.)?(subscribe|unsubscribe) \(/.exec(frame)?.[1];
+ return operation === 'subscribe' || operation === 'unsubscribe' ? operation : 'other';
+}
+
+const messageListeners: Array<(event: { data: unknown }) => void> = [];
+let resolveShutdownReceived!: () => void;
+const shutdownReceived = new Promise<void>((resolve) => {
+ resolveShutdownReceived = resolve;
+});
+
+function deliverFromParent(data: unknown): void {
+ if ((data as { type?: unknown }).type === 'shutdown') {
+ Atomics.store(flags, QUIT_DRAIN_FLAG.shutdownReceived, 1);
+ resolveShutdownReceived();
+ }
+ for (const listener of messageListeners) listener({ data });
+}
+
+function holdNativeOperationUntilReleased(): void {
+ const hold = Atomics.add(flags, QUIT_DRAIN_FLAG.holdsBegun, 1) + 1;
+ signalHarness();
+ for (
+ let released = Atomics.load(flags, QUIT_DRAIN_FLAG.holdsReleased);
+ released < hold;
+ released = Atomics.load(flags, QUIT_DRAIN_FLAG.holdsReleased)
+ ) {
+ Atomics.wait(flags, QUIT_DRAIN_FLAG.holdsReleased, released);
+ }
+ if (Atomics.exchange(flags, QUIT_DRAIN_FLAG.deliverParentMessagesOnRelease, 0) === 1) {
+ for (
+ let queued = receiveMessageOnPort(port);
+ queued !== undefined;
+ queued = receiveMessageOnPort(port)
+ ) {
+ deliverFromParent(queued.message);
+ }
+ }
+}
+
+createHook({
+ init(asyncId, type) {
+ if (type !== 'undefined') return;
+ const operation = parcelOperation();
+ if (operation === null) return;
+ pendingNativeWatcherOps.add(asyncId);
+ Atomics.add(flags, QUIT_DRAIN_FLAG.nativeOpsPending, 1);
+ if (operation === 'subscribe') Atomics.add(flags, QUIT_DRAIN_FLAG.nativeSubscribes, 1);
+ if (operation === 'unsubscribe') Atomics.add(flags, QUIT_DRAIN_FLAG.nativeUnsubscribes, 1);
+ if (Atomics.load(flags, QUIT_DRAIN_FLAG.shutdownReceived) === 1) {
+ Atomics.add(flags, QUIT_DRAIN_FLAG.nativeOpsStartedDuringShutdown, 1);
+ queueMicrotask(holdNativeOperationUntilReleased);
+ } else if (
+ mode === 'quit-during-start' &&
+ operation === 'subscribe' &&
+ !serverStartSubscribeHeld
+ ) {
+ serverStartSubscribeHeld = true;
+ queueMicrotask(holdNativeOperationUntilReleased);
+ }
+ },
+ before(asyncId) {
+ if (!pendingNativeWatcherOps.delete(asyncId)) return;
+ Atomics.sub(flags, QUIT_DRAIN_FLAG.nativeOpsPending, 1);
+ },
+}).enable();
+
+const serverModuleUrl = pathToFileURL(
+ createRequire(desktopPackageJson).resolve('@inkeep/open-knowledge-server'),
+).href;
+
+async function importServer(): Promise<ServerModule> {
+ const server: ServerModule = await import(serverModuleUrl);
+ const bootServer: ServerModule['bootServer'] = async (opts) => {
+ const booted = await server.bootServer(opts);
+ const noteInitSettled = () => {
+ Atomics.store(flags, QUIT_DRAIN_FLAG.serverInitSettled, 1);
+ signalHarness();
+ };
+ void booted.ready.then(noteInitSettled, noteInitSettled);
+ if (mode === 'quit-during-start') {
+ await shutdownReceived;
+ await booted.ready.catch(() => {});
+ }
+ Atomics.store(flags, QUIT_DRAIN_FLAG.serverStartSettled, 1);
+ return booted;
+ };
+ return { ...server, bootServer };
+}
+
+port.on('message', deliverFromParent);
+
+setupUtility({
+ parentPort: {
+ on(event: 'message', handler: (event: { data: unknown }) => void) {
+ if (event === 'message') messageListeners.push(handler);
+ },
+ postMessage(value: unknown) {
+ port.postMessage(value);
+ },
+ },
+ importServer,
+ exit: (code: number) => {
+ Atomics.store(
+ flags,
+ QUIT_DRAIN_FLAG.nativeOpsPendingAtExit,
+ Atomics.load(flags, QUIT_DRAIN_FLAG.nativeOpsPending),
+ );
+ Atomics.store(
+ flags,
+ QUIT_DRAIN_FLAG.subscriptionsUnreleasedAtExit,
+ Atomics.load(flags, QUIT_DRAIN_FLAG.nativeSubscribes) -
+ Atomics.load(flags, QUIT_DRAIN_FLAG.nativeUnsubscribes),
+ );
+ Atomics.store(
+ flags,
+ QUIT_DRAIN_FLAG.serverStartSettledAtExit,
+ Atomics.load(flags, QUIT_DRAIN_FLAG.serverStartSettled),
+ );
+ Atomics.store(flags, QUIT_DRAIN_FLAG.exitCode, code);
+ Atomics.store(flags, QUIT_DRAIN_FLAG.exitCalled, 1);
+ signalHarness();
+ port.postMessage({ type: 'quit-drain-harness:exit', code });
+ },
+ parentPid: process.pid,
+ killProbe: () => {},
+ onSignal: () => {},
+ setInterval: (cb: () => void, intervalMs: number) => {
+ const handle = setInterval(cb, intervalMs);
+ return { unref: () => handle.unref(), clear: () => clearInterval(handle) };
+ },
+});
diff --git a/packages/desktop/tests/utility/server-entry.test.ts b/packages/desktop/tests/utility/server-entry.test.ts
index c101d1709..af3b5ba76 100644
--- a/packages/desktop/tests/utility/server-entry.test.ts
+++ b/packages/desktop/tests/utility/server-entry.test.ts
@@ -1475,3 +1475,128 @@ describe('setupUtility honours a shutdown that arrives before its init reaches b
expect(env.exit.mock.calls).toEqual([[0]]);
});
});
+
+function startUtilityWhoseServerStartWaits(env: MockEnv) {
+ const destroy = vi.fn(() => Promise.resolve());
+ let enterServerStart!: () => void;
+ const reachedServerStart = new Promise<void>((resolve) => {
+ enterServerStart = resolve;
+ });
+ let settleServerStart!: (failure?: Error) => void;
+ const serverStarted = new Promise<void>((resolve, reject) => {
+ settleServerStart = (failure) => (failure === undefined ? resolve() : reject(failure));
+ });
+ const bootServer = vi.fn(async () => {
+ enterServerStart();
+ await serverStarted;
+ return { port: 51290, destroy, degraded: [] as readonly string[] };
+ });
+ setupUtility({
+ parentPort: env.parentPort,
+ importServer: () =>
+ Promise.resolve({
+ bootServer,
+ } as unknown as typeof import('@inkeep/open-knowledge-server')),
+ exit: env.exit,
+ parentPid: 99999,
+ killProbe: env.killProbe,
+ onSignal: (sig, h) => env.signalHandlers.set(sig, h),
+ setInterval: (cb, ms) => {
+ env.intervals.push({ cb, ms });
+ return { unref: vi.fn(() => {}), clear: env.intervalCancel };
+ },
+ prepareBootEnvironment: fakePrepare(),
+ });
+ env.parentPort.fire({
+ type: 'init',
+ opts: { contentDir: '/tmp/x', projectDir: '/tmp/x', port: 0, host: 'localhost' },
+ });
+ return { destroy, reachedServerStart, settleServerStart };
+}
+
+async function nextTurn(): Promise<void> {
+ await new Promise<void>((resolve) => setImmediate(resolve));
+}
+
+function postedTypes(env: MockEnv): unknown[] {
+ return env.parentPort.postMessage.mock.calls.map(([msg]) => (msg as { type?: unknown }).type);
+}
+
+describe('setupUtility joins a server start still in progress when shutdown arrives', () => {
+ test('waits for the server it is starting, shuts that server down, then exits 0 without announcing it ready', async () => {
+ const env = buildEnv();
+ const utility = startUtilityWhoseServerStartWaits(env);
+ await utility.reachedServerStart;
+
+ env.parentPort.fire({ type: 'shutdown' });
+ await nextTurn();
+ expect(env.exit).not.toHaveBeenCalled();
+
+ utility.settleServerStart();
+ await nextTurn();
+
+ expect(utility.destroy).toHaveBeenCalledTimes(1);
+ expect(env.exit.mock.calls).toEqual([[0]]);
+ expect(postedTypes(env)).not.toContain('ready');
+ });
+
+ test('exits once when the server it is starting fails after shutdown arrived', async () => {
+ const env = buildEnv();
+ const utility = startUtilityWhoseServerStartWaits(env);
+ await utility.reachedServerStart;
+
+ env.parentPort.fire({ type: 'shutdown' });
+ utility.settleServerStart(new Error('server start failed'));
+ await nextTurn();
+
+ expect(utility.destroy).not.toHaveBeenCalled();
+ expect(env.exit.mock.calls).toEqual([[0]]);
+ });
+});
+
+describe('setupUtility repeated shutdown', () => {
+ test('a second shutdown resolves only after the first has finished draining the server', async () => {
+ const env = buildEnv();
+ let finishDestroy!: () => void;
+ const destroy = vi.fn(
+ () =>
+ new Promise<void>((resolve) => {
+ finishDestroy = resolve;
+ }),
+ );
+ const handle = setupUtility({
+ parentPort: env.parentPort,
+ importServer: () =>
+ Promise.resolve({
+ bootServer: () => Promise.resolve({ port: 51291, destroy, degraded: [] }),
+ } as unknown as typeof import('@inkeep/open-knowledge-server')),
+ exit: env.exit,
+ parentPid: 99999,
+ killProbe: env.killProbe,
+ onSignal: (sig, h) => env.signalHandlers.set(sig, h),
+ setInterval: (cb, ms) => {
+ env.intervals.push({ cb, ms });
+ return { unref: vi.fn(() => {}), clear: env.intervalCancel };
+ },
+ prepareBootEnvironment: fakePrepare(),
+ });
+ env.parentPort.fire({
+ type: 'init',
+ opts: { contentDir: '/tmp/x', projectDir: '/tmp/x', port: 0, host: 'localhost' },
+ });
+ await handle.readyPromise;
+
+ const first = handle.shutdown('shutdown-ipc');
+ let secondSettled = false;
+ const second = handle.shutdown('SIGTERM').then(() => {
+ secondSettled = true;
+ });
+ await nextTurn();
+
+ expect(destroy).toHaveBeenCalledTimes(1);
+ expect(secondSettled).toBe(false);
+ finishDestroy();
+ await Promise.all([first, second]);
+ expect(env.exit.mock.calls).toEqual([[0]]);
+ });
+});
diff --git a/packages/server/src/parcel-watcher-double.test-helper.ts b/packages/server/src/parcel-watcher-double.test-helper.ts
index c67bef534..0d9b1912a 100644
--- a/packages/server/src/parcel-watcher-double.test-helper.ts
+++ b/packages/server/src/parcel-watcher-double.test-helper.ts
@@ -14,6 +14,7 @@ interface Registration extends NativeSubscriptionDouble {
}
const registrations: Registration[] = [];
+const failingReleases = new Set<string>();
function register(dir: string, callback: SubscribeCallback): Registration {
let releases = 0;
@@ -33,6 +34,9 @@ function register(dir: string, callback: SubscribeCallback): Registration {
release: async () => {
releases += 1;
for (const { events, error } of queuedForRelease.splice(0)) await deliver(events, error);
+ if (failingReleases.delete(dir)) {
+ throw new Error(`the watcher double failed to release ${dir}`);
+ }
},
};
}
@@ -67,6 +71,11 @@ export const parcelWatcherModule = { default: parcelWatcherDouble, ...parcelWatc
export function forgetNativeSubscriptions(): void {
registrations.length = 0;
refusals.clear();
+ failingReleases.clear();
+}
+
+export function failNextNativeRelease(dir: string): void {
+ failingReleases.add(resolve(dir));
}
export function refuseNativeSubscriptions(dir: string, count: number): void {
diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.ts
index 0e1811548..98bcbaad1 100644
--- a/packages/server/src/server-factory.ts
+++ b/packages/server/src/server-factory.ts
@@ -4899,45 +4899,48 @@ export function createServer(options: ServerOptions): ServerInstance {
}
const documentCount = hocuspocus.documents.size;
+ const releaseWatcher = async (
+ release: { unsubscribe(): Promise<void> } | null,
+ watched: 'head' | 'content',
+ ): Promise<void> => {
+ if (release === null) return;
+ try {
+ await release.unsubscribe();
+ } catch (err) {
+ phaseErrors.push({
+ phase: 'watcher-unsubscribe',
+ error: err instanceof Error ? err.message : String(err),
+ });
+ log.error({ err, watched }, '[server] shutdown phase-1 watcher unsubscribe failed');
+ }
+ };
try {
try {
- try {
- if (inPlaceRescanTimer) {
- clearTimeout(inPlaceRescanTimer);
- inPlaceRescanTimer = null;
- }
- if (shadowWarmupTimer) {
- clearTimeout(shadowWarmupTimer);
- shadowWarmupTimer = null;
- }
- if (headWatcher) {
- await headWatcher.unsubscribe();
- headWatcher = null;
- }
- if (watcher) {
- await watcher.unsubscribe();
- watcher = null;
- }
- for (const { docName, cleanup } of configFileWatcherCleanups) {
- try {
- await cleanup();
- } catch (cfgErr) {
- log.warn(
- { err: cfgErr, docName },
- `[server] failed to stop config-file-watcher for ${docName}`,
- );
- }
+ if (inPlaceRescanTimer) {
+ clearTimeout(inPlaceRescanTimer);
+ inPlaceRescanTimer = null;
+ }
+ if (shadowWarmupTimer) {
+ clearTimeout(shadowWarmupTimer);
+ shadowWarmupTimer = null;
+ }
+ await releaseWatcher(headWatcher, 'head');
+ headWatcher = null;
+ await releaseWatcher(watcher, 'content');
+ watcher = null;
+ for (const { docName, cleanup } of configFileWatcherCleanups) {
+ try {
+ await cleanup();
+ } catch (cfgErr) {
+ log.warn(
+ { err: cfgErr, docName },
+ `[server] failed to stop config-file-watcher for ${docName}`,
+ );
}
- configFileWatcherCleanups.length = 0;
- configFileWatcherResyncs.clear();
- } catch (err) {
- phaseErrors.push({
- phase: 'watcher-unsubscribe',
- error: err instanceof Error ? err.message : String(err),
- });
- log.error({ err }, '[server] shutdown phase-1 watcher unsubscribe failed');
}
+ configFileWatcherCleanups.length = 0;
+ configFileWatcherResyncs.clear();
try {
cc1Broadcaster?.destroy();
diff --git a/packages/server/src/server-shutdown-parcel-release.test.ts b/packages/server/src/server-shutdown-parcel-release.test.ts
index a4c79f66e..600655cf8 100644
--- a/packages/server/src/server-shutdown-parcel-release.test.ts
+++ b/packages/server/src/server-shutdown-parcel-release.test.ts
@@ -9,6 +9,7 @@ import { bootCompositionRig } from './composition-rig.test-helper.ts';
import { getWatcherDecisionRingSnapshot } from './file-watcher.ts';
import { getMetrics } from './metrics.ts';
import {
+ failNextNativeRelease,
forgetNativeSubscriptions,
nativeSubscriptionDirs,
nativeSubscriptionOn,
@@ -101,3 +102,23 @@ test('once the server is destroyed, a native delivery neither dispatches a disk
batchesBegun: getMetrics().batchCount - batchesAtDestroy,
}).toEqual({ dispatched: [], batchesBegun: 0 });
}, 60_000);
+
+test.skipIf(process.platform === 'win32')(
+ 'a HEAD watcher whose native release fails still lets the content watcher release',
+ async () => {
+ server = await bootCompositionRig(root);
+ await server.ready;
+ const content = nativeSubscriptionOn(root);
+ const head = nativeSubscriptionOn(join(root, '.git'));
+ failNextNativeRelease(join(root, '.git'));
+
+ await server.destroy();
+ server = undefined;
+
+ expect({ content: content.nativeReleases(), head: head.nativeReleases() }).toEqual({
+ content: 1,
+ head: 1,
+ });
+ },
+ 60_000,
+);