Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

PRD-7886: stop stale branch claim wedging every document (#3380)

Andrew Mikofalvy1dba80f998bc
diff --git a/.changeset/tidy-donkeys-repeat.md b/.changeset/tidy-donkeys-repeat.md
new file mode 100644
index 000000000..5170de8ca
--- /dev/null
+++ b/.changeset/tidy-donkeys-repeat.md
@@ -0,0 +1,15 @@
+---
+'@inkeep/open-knowledge': patch
+---
+
+Fix documents that never load on a workspace whose git branch is not `main`.
+
+The server accepted WebSocket connections before it had read HEAD, so during the
+boot window it compared every client's branch claim against a `main` placeholder
+and rejected the connection as a branch mismatch. The rejection recycled the
+client's providers, which re-armed the same load budget against a server still in
+the same window, and every document in the workspace timed out. The branch check
+now waits for the server to resolve its real branch before it decides anything,
+and only for that — it does not wait for the rest of startup, so opening a large
+workspace is no slower than before. If the branch cannot be established quickly
+the connection is admitted rather than judged against a guess.
diff --git a/packages/app/src/lib/server-info-refresh.test.ts b/packages/app/src/lib/server-info-refresh.test.ts
index e45c27a0e..a8a2a9407 100644
--- a/packages/app/src/lib/server-info-refresh.test.ts
+++ b/packages/app/src/lib/server-info-refresh.test.ts
@@ -17,8 +17,20 @@
* directly.
*/
-import { describe, expect, test } from 'vitest';
-import { createSyncedReconnectGate } from './server-info-refresh';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import type { ProviderPool } from '../editor/provider-pool';
+import { createSyncedReconnectGate, refreshServerInfo } from './server-info-refresh';
+
+vi.mock('../editor/branch-invalidation', () => ({
+ handleBranchSwitched: vi.fn(() => Promise.resolve()),
+}));
+vi.mock('./documents-events', () => ({
+ emitBranchChanged: vi.fn(),
+ subscribeToBranchChanged: vi.fn(() => () => {}),
+}));
+vi.mock('./server-instance-store', () => ({
+ setServerInstanceId: vi.fn(),
+}));
describe('createSyncedReconnectGate', () => {
test('does NOT fire on the first invocation (cold boot)', () => {
@@ -102,3 +114,67 @@ describe('createSyncedReconnectGate', () => {
expect(calls).toBe(10); // every subsequent call fires
});
});
+
+/**
+ * `refreshServerInfo` is what the pool runs when the server rejects a connect
+ * with `branch-mismatch`. It is the ONLY thing that stops the pool re-claiming
+ * a branch the server has already disagreed with: the claim is read from
+ * `localStorage` on every auth token, so without adoption the client would
+ * re-offer the same rejected value on every reconnect forever.
+ */
+describe('refreshServerInfo — branch adoption', () => {
+ let originalFetch: typeof globalThis.fetch;
+
+ beforeEach(() => {
+ originalFetch = globalThis.fetch;
+ });
+ afterEach(() => {
+ globalThis.fetch = originalFetch;
+ vi.clearAllMocks();
+ });
+
+ function stubServerInfo(body: Record<string, unknown>) {
+ globalThis.fetch = vi.fn(() =>
+ Promise.resolve({
+ ok: true,
+ json: () => Promise.resolve(body),
+ } as Response),
+ ) as unknown as typeof globalThis.fetch;
+ }
+
+ function createPoolStub() {
+ const observed: string[] = [];
+ const pool = {
+ setExpectedServerInstanceId: vi.fn(),
+ compareAndUpdateObservedBranch: vi.fn((branch: string) => {
+ observed.push(branch);
+ return true;
+ }),
+ observeDiskAckBatch: vi.fn(),
+ };
+ return { pool: pool as unknown as ProviderPool, observed, spies: pool };
+ }
+
+ test('adopts the branch the server reports', async () => {
+ stubServerInfo({ serverInstanceId: 'srv-1', currentBranch: 'master' });
+ const { pool, observed, spies } = createPoolStub();
+
+ await refreshServerInfo(pool);
+
+ expect(observed).toEqual(['master']);
+ expect(spies.setExpectedServerInstanceId).toHaveBeenCalledWith('srv-1');
+ });
+
+ test('adopts nothing when the endpoint is unreachable', async () => {
+ // The claim stays as-is and the next reconnect retries — silently
+ // overwriting it with a guess would be worse than re-offering it.
+ globalThis.fetch = vi.fn(() =>
+ Promise.reject(new Error('network down')),
+ ) as unknown as typeof globalThis.fetch;
+ const { pool, observed } = createPoolStub();
+
+ await refreshServerInfo(pool);
+
+ expect(observed).toEqual([]);
+ });
+});
diff --git a/packages/server/src/server-factory.test.ts b/packages/server/src/server-factory.test.ts
index 718e05fb7..aa5d32bef 100644
--- a/packages/server/src/server-factory.test.ts
+++ b/packages/server/src/server-factory.test.ts
@@ -2258,6 +2258,156 @@ describe("createServer() — onAuthenticate rejects 'branch-mismatch'", () => {
});
});
+// The branch gate compares a client claim against `getActiveBranch()`, which
+// starts life as the DocumentDurabilityState `'main'` default and only becomes
+// the workspace's real HEAD branch once `initAsync` runs
+// `switchReconciledBaseScope(startupBranch)`. WebSocket connections are
+// accepted from the moment `createServer()` returns, so without a readiness
+// gate every cold-boot connect from a workspace on a non-`main` branch is
+// rejected against a placeholder the server has no business comparing against.
+// The rejection recycles the client pool, which re-arms the same 30s sync
+// budget, which surfaces as a document that never loads.
+describe('createServer() — onAuthenticate branch gate parks on readiness', () => {
+ let tmpDir: string;
+
+ beforeEach(async () => {
+ tmpDir = await mkdtemp(join(tmpdir(), 'ok-auth-branch-boot-'));
+ });
+ afterEach(async () => {
+ await rm(tmpDir, { recursive: true, force: true });
+ });
+
+ function getAuthExtension(server: Awaited<ReturnType<typeof createServer>>): {
+ onAuthenticate: (payload: unknown) => Promise<void>;
+ } {
+ const ext = server.hocuspocus.configuration.extensions.find(
+ (e) => (e as { __kind?: string }).__kind === 'principal-auth',
+ ) as { onAuthenticate: (payload: unknown) => Promise<void> } | undefined;
+ if (!ext) throw new Error('expected principalAuthExtension on hocuspocus.configuration');
+ return ext;
+ }
+
+ test('a claim matching the real HEAD branch survives the boot window', async () => {
+ const git = simpleGit(tmpDir);
+ await git.init(['--initial-branch=master']);
+ await git.addConfig('user.email', '[email protected]');
+ await git.addConfig('user.name', 'Test');
+ writeFileSync(join(tmpDir, 'seed.md'), '# Seed\n');
+ await git.add('.');
+ await git.commit('seed');
+
+ const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
+ try {
+ // Deliberately NOT awaiting `server.ready` — this is the cold-boot
+ // window the reporter hit, where the durability state still holds the
+ // `'main'` placeholder because `initAsync` has not resolved HEAD yet.
+ const authExt = getAuthExtension(server);
+ const token = JSON.stringify({
+ principalId: 'p-1',
+ tabSessionId: 's-1',
+ expectedBranch: 'master',
+ });
+ const context: Record<string, unknown> = {};
+
+ let thrown: unknown = null;
+ try {
+ await authExt.onAuthenticate({ token, context, documentName: 'boot-window-doc' });
+ } catch (err) {
+ thrown = err;
+ }
+
+ expect(thrown).toBeNull();
+ expect(context.kind).toBe('human');
+ } finally {
+ await server.destroy();
+ }
+ });
+
+ test('a genuinely stale claim is still rejected after the branch resolves', async () => {
+ const git = simpleGit(tmpDir);
+ await git.init(['--initial-branch=master']);
+ await git.addConfig('user.email', '[email protected]');
+ await git.addConfig('user.name', 'Test');
+ writeFileSync(join(tmpDir, 'seed.md'), '# Seed\n');
+ await git.add('.');
+ await git.commit('seed');
+
+ const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
+ try {
+ const authExt = getAuthExtension(server);
+ const token = JSON.stringify({
+ principalId: 'p-1',
+ tabSessionId: 's-1',
+ expectedBranch: 'some-other-branch',
+ });
+ const context: Record<string, unknown> = {};
+
+ let thrown: unknown = null;
+ try {
+ await authExt.onAuthenticate({ token, context, documentName: 'boot-window-doc' });
+ } catch (err) {
+ thrown = err;
+ }
+
+ expect((thrown as { reason?: string } | null)?.reason).toBe('branch-mismatch');
+ // The message must name the resolved branch, not the placeholder — the
+ // client adopts this value to correct its own claim.
+ expect((thrown as { message?: string } | null)?.message).toContain('master');
+ } finally {
+ await server.destroy();
+ }
+ });
+
+ // The gate must wait for the branch value and nothing else. Parking it on the
+ // full boot promise instead would put the index rebuild, the O(n) seed walk,
+ // the tag reconcile and the sync engine in front of WebSocket admission on
+ // every branch — a tail the client's 30s sync budget outlives on a large
+ // workspace, which is the same never-loading document from the other end.
+ test('admission settles before the rest of boot does', async () => {
+ const git = simpleGit(tmpDir);
+ await git.init(['--initial-branch=master']);
+ await git.addConfig('user.email', '[email protected]');
+ await git.addConfig('user.name', 'Test');
+ // Enough files that the post-branch-resolution boot work (backlink rebuild,
+ // seed walk, tag reconcile) is measurably slower than an auth handshake
+ // that no longer waits for any of it. Kept modest on purpose: a bigger
+ // vault widens the margin but its I/O spills onto the sibling workers
+ // vitest runs in parallel and destabilizes timing tests elsewhere.
+ const noteCount = 120;
+ for (let i = 0; i < noteCount; i++) {
+ writeFileSync(
+ join(tmpDir, `note-${i}.md`),
+ `# Note ${i}\n\nSee [[note-${(i + 1) % noteCount}]].\n`,
+ );
+ }
+ await git.add('.');
+ await git.commit('seed');
+
+ const server = createServer({ contentDir: tmpDir, projectDir: tmpDir, quiet: true });
+ try {
+ const order: string[] = [];
+ const readySettled = server.ready.then(
+ () => order.push('ready'),
+ () => order.push('ready'),
+ );
+
+ const authExt = getAuthExtension(server);
+ const token = JSON.stringify({
+ principalId: 'p-1',
+ tabSessionId: 's-1',
+ expectedBranch: 'master',
+ });
+ await authExt.onAuthenticate({ token, context: {}, documentName: 'boot-window-doc' });
+ order.push('auth');
+
+ await readySettled;
+ expect(order[0]).toBe('auth');
+ } finally {
+ await server.destroy();
+ }
+ });
+});
+
// ---------------------------------------------------------------------------
// A rejection thrown out of onAuthenticate refuses a document's WebSocket
// connection. Without a structured record it surfaces only as untimestamped
diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.ts
index 9df004b89..2a2fd4585 100644
--- a/packages/server/src/server-factory.ts
+++ b/packages/server/src/server-factory.ts
@@ -1145,6 +1145,69 @@ export function createServer(options: ServerOptions): ServerInstance {
rejectReady = rej;
});
+ // Narrow sibling of `ready` covering ONE value: has `durabilityState` been
+ // aligned with the project's real HEAD branch yet? `DocumentDurabilityState`
+ // starts on a `'main'` default and the WebSocket listener accepts from the
+ // moment this factory returns, so anything comparing `getActiveBranch()`
+ // against a client claim has to park until this settles or it compares
+ // against a placeholder. It settles early in `initAsync`, long before `ready`
+ // does — parking on `ready` instead would put the whole O(n) boot tail (index
+ // rebuild, seed walk, tag reconcile, sync engine) in front of WebSocket
+ // admission on every branch, which the client's sync budget would outlive on
+ // a large workspace. Never rejects: a boot that fails before the alignment
+ // resolves this too, so admission degrades to "skip the branch check" rather
+ // than hanging forever.
+ let resolveBranchScopeAligned!: () => void;
+ const branchScopeAligned = new Promise<void>((res) => {
+ resolveBranchScopeAligned = res;
+ });
+
+ // Ceiling on how long a WebSocket connection waits for the alignment above.
+ // The client arms a 30s sync budget when its provider attaches, and the work
+ // ahead of the alignment (shadow-repo init, the 10s-capped boot GC, a
+ // HEAD-drift upstream import over the whole content root) can be slow on a
+ // large workspace. Expiring well inside the client budget keeps a stalled
+ // boot from turning into a document that never loads.
+ const BRANCH_SCOPE_GATE_TIMEOUT_MS = 10_000;
+
+ /**
+ * The branch to compare a client's claim against, or `null` when the server
+ * cannot answer in time and the claim should not be judged at all.
+ *
+ * Fast path: the alignment already ran, so `getActiveBranch()` is the live
+ * authority (including after a mid-session branch switch, where HEAD on disk
+ * can be ahead of the scope the server is actually serving).
+ *
+ * Slow path: boot is still ahead of the alignment. Waiting is correct until
+ * the ceiling, after which we read HEAD off disk — the same value the
+ * alignment itself uses — rather than compare against the `'main'` default
+ * the durability state is still holding.
+ */
+ async function resolveBranchForClaimCheck(): Promise<string | null> {
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ const expired = Symbol('branch-scope-gate-timeout');
+ const timeout = new Promise<typeof expired>((res) => {
+ timer = setTimeout(() => res(expired), BRANCH_SCOPE_GATE_TIMEOUT_MS);
+ // Never hold the process (or a test run) open on this timer.
+ timer.unref?.();
+ });
+ try {
+ const outcome = await Promise.race([branchScopeAligned, timeout]);
+ if (outcome !== expired) return getActiveBranch();
+ } finally {
+ if (timer) clearTimeout(timer);
+ }
+ try {
+ return readProjectHeadState(projectDir).branch ?? null;
+ } catch (err) {
+ log.warn(
+ { err },
+ '[auth] branch scope gate expired and HEAD is unreadable — skipping the branch claim check',
+ );
+ return null;
+ }
+ }
+
function signalChannel(
channel: 'files' | 'backlinks' | 'graph' | 'tags' | 'comments' | 'lint-config',
): void {
@@ -1705,20 +1768,26 @@ export function createServer(options: ServerOptions): ServerInstance {
// union-merge stale-branch state. Empty / absent claim = legacy
// path (accepted unconditionally).
const claimedBranch = parsed?.expectedBranch;
- const currentBranch = getActiveBranch();
- if (
- typeof claimedBranch === 'string' &&
- claimedBranch.length > 0 &&
- claimedBranch !== currentBranch
- ) {
- logAuthRejection('branch-mismatch', payload.documentName, {
- claimedBranch,
- currentBranch,
- });
- throw new HocuspocusAuthRejection(
- 'branch-mismatch',
- `branch mismatch: client claimed ${claimedBranch}, server is on ${currentBranch}`,
- );
+ if (typeof claimedBranch === 'string' && claimedBranch.length > 0) {
+ // Park until the server knows its own branch. `DocumentDurabilityState`
+ // starts on a `'main'` default while the WebSocket listener is already
+ // accepting, so an ungated comparison rejects every cold-boot client of
+ // a workspace that isn't on `main` — the client recycles, re-arms its
+ // sync budget against a server still in the same window, and the
+ // document never loads. `null` means the server could not establish a
+ // branch to judge against, in which case admitting is the only answer
+ // that cannot wedge the client.
+ const currentBranch = await resolveBranchForClaimCheck();
+ if (currentBranch !== null && claimedBranch !== currentBranch) {
+ logAuthRejection('branch-mismatch', payload.documentName, {
+ claimedBranch,
+ currentBranch,
+ });
+ throw new HocuspocusAuthRejection(
+ 'branch-mismatch',
+ `branch mismatch: client claimed ${claimedBranch}, server is on ${currentBranch}`,
+ );
+ }
}
if (!parsed) return;
@@ -3764,6 +3833,10 @@ export function createServer(options: ServerOptions): ServerInstance {
// current HEAD before either is read or written.
const startupBranch = readProjectHeadState(projectDir).branch ?? 'main';
switchReconciledBaseScope(startupBranch);
+ // `getActiveBranch()` is authoritative from here — release anything parked
+ // on the branch value (the WebSocket branch-claim gate) without making it
+ // wait for the rest of the boot pipeline.
+ resolveBranchScopeAligned();
const derivedIndexStartup = derivedDocumentIndex.beginStartup(startupBranch);
let derivedIndexStartupSettled = false;
@@ -4619,6 +4692,10 @@ export function createServer(options: ServerOptions): ServerInstance {
// behind unresolved admission/readiness barriers. Failed server startup
// has no recovery path, so close releases every waiter with a rejection.
void derivedDocumentIndex.close();
+ // A failure BEFORE the branch scope was aligned leaves this deferred
+ // pending, which would park WebSocket admission forever. Release it (no-op
+ // when the alignment already ran) so the branch gate falls through instead.
+ resolveBranchScopeAligned();
rejectReady(err);
});