Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
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.mdnew file mode 100644index 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.tsindex 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.tsindex 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 untimestampeddiff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.tsindex 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);});