Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(ok): converge server and client before reading settled bytes (#4192)
Nick Gomez7fbee53aea62
diff --git a/packages/app/tests/integration/fm-collision-guard.test.ts b/packages/app/tests/integration/fm-collision-guard.test.tsindex aa7440bc0..56dfecaae 100644--- a/packages/app/tests/integration/fm-collision-guard.test.ts+++ b/packages/app/tests/integration/fm-collision-guard.test.ts@@ -7,6 +7,7 @@ import {agentWriteMd,assertAllConverged,attachBridgeInvariantWatcher,+ awaitConvergedServerText,awaitDocQuiescence,createTestClient,createTestClients,@@ -50,10 +51,7 @@ function mintRulePair(client: TestClient): void {}async function settled(client: TestClient): Promise<string> {- await awaitDocQuiescence(client.doc);- await pollUntil(() => getServerState(server, client.docName) !== null, 5_000);- await awaitDocQuiescence(client.doc);- return getServerState(server, client.docName)?.ytext.toString() ?? '';+ return awaitConvergedServerText(server, client);}describe('Observer A drain', () => {@@ -112,6 +110,8 @@ describe('Observer A drain', () => {});const withFm = await settled(client);expect(withFm).toBe(`---\ntitle: t\n---\n${guarded}`);++ await awaitDocQuiescence(client.doc);expect(await settled(client)).toBe(withFm);expect(stripFrontmatter(withFm).body).toContain('x');} finally {diff --git a/packages/app/tests/integration/harness-server-convergence.test.ts b/packages/app/tests/integration/harness-server-convergence.test.tsnew file mode 100644index 000000000..2fde8c76d--- /dev/null+++ b/packages/app/tests/integration/harness-server-convergence.test.ts@@ -0,0 +1,303 @@+import { setTimeout as wait } from 'node:timers/promises';+import { afterAll, beforeAll, describe, expect, test } from 'vitest';+import * as Y from 'yjs';+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';+import {+ agentWriteMd,+ awaitConvergedServerText,+ createTestClient,+ createTestClients,+ createTestServer,+ getServerState,+ type TestServer,+} from './test-harness';++let server: TestServer;++beforeAll(async () => {+ server = await createTestServer();+}, HARNESS_BOOT_TIMEOUT_MS);++afterAll(async () => {+ await server.cleanup();+});++describe('awaitConvergedServerText', () => {+ test('stops waiting rather than returning bytes the client has not received', async () => {+ const client = await createTestClient(server.port, undefined, { syncControl: true });+ try {+ client.pauseSync();+ await agentWriteMd(server.port, 'held body\n', {+ docName: client.docName,+ position: 'replace',+ });++ const failure = await awaitConvergedServerText(server, client, {+ timeoutMs: 400,+ pollIntervalMs: 10,+ }).then(+ () => null,+ (error: Error) => error,+ );++ expect(failure?.message).toMatch(/did not converge/);+ expect(failure?.message).toContain('server Y.Text');+ expect(failure?.message).not.toContain('server has no document by that name');++ expect(getServerState(server, client.docName)?.ytext.toString()).toContain('held body');+ expect(client.ytext.toString()).not.toContain('held body');+ } finally {+ client.resumeSync();+ await client.cleanup();+ }+ });++ test('stops waiting when the client fragment edit has not reached the server', async () => {+ const client = await createTestClient(server.port, undefined, { syncControl: true });+ try {+ client.setDropOutbound(true);+ client.fragment.push([new Y.XmlElement('thematicBreak')]);++ await expect(+ awaitConvergedServerText(server, client, { timeoutMs: 400, pollIntervalMs: 10 }),+ ).rejects.toThrow(/did not converge/);++ expect(getServerState(server, client.docName)?.ytext.toString()).toBe('');+ expect(client.fragment.length).toBe(1);+ } finally {+ client.setDropOutbound(false);+ await client.cleanup();+ }+ });++ test('stops waiting when the client deletion has not reached the server', async () => {+ const client = await createTestClient(server.port, undefined, { syncControl: true });+ try {+ await agentWriteMd(server.port, 'alpha\n\nbravo\n', {+ docName: client.docName,+ position: 'replace',+ });+ const seeded = await awaitConvergedServerText(server, client);+ expect(seeded).toContain('alpha');++ client.setDropOutbound(true);+ client.doc.transact(() => {+ client.ytext.delete(0, 6);+ });+ expect(client.ytext.toString()).not.toContain('alpha');++ await expect(+ awaitConvergedServerText(server, client, { timeoutMs: 400, pollIntervalMs: 10 }),+ ).rejects.toThrow(/did not converge/);++ expect(getServerState(server, client.docName)?.ytext.toString()).toContain('alpha');+ } finally {+ client.setDropOutbound(false);+ await client.cleanup();+ }+ });++ test('stops waiting when a peer deletion has not reached the client', async () => {+ const [reader, deleter] = await createTestClients(server.port, {+ count: 2,+ perClientOptions: { syncControl: true },+ });+ try {+ await agentWriteMd(server.port, 'alpha\n\nbravo\n', {+ docName: reader.docName,+ position: 'replace',+ });+ expect(await awaitConvergedServerText(server, reader)).toContain('alpha');+ expect(await awaitConvergedServerText(server, deleter)).toContain('alpha');++ reader.pauseSync();+ deleter.doc.transact(() => {+ deleter.ytext.delete(0, 6);+ });+ await awaitConvergedServerText(server, deleter);++ await expect(+ awaitConvergedServerText(server, reader, { timeoutMs: 400, pollIntervalMs: 10 }),+ ).rejects.toThrow(/did not converge/);++ expect(reader.ytext.toString()).toContain('alpha');+ } finally {+ reader.resumeSync();+ await Promise.all([reader.cleanup(), deleter.cleanup()]);+ }+ });++ test('bounds the wait and names the doc when the client keeps writing', async () => {+ const client = await createTestClient(server.port, undefined, { syncControl: true });+ client.setDropOutbound(true);+ client.doc.transact(() => {+ client.ytext.insert(0, 'unsent');+ });+ const churn = setInterval(() => {+ client.doc.transact(() => {+ client.ytext.insert(0, '.');+ });+ }, 1);+ try {+ const startedAt = Date.now();+ const failure = await awaitConvergedServerText(server, client, {+ timeoutMs: 300,+ pollIntervalMs: 10,+ }).then(+ () => null,+ (error: Error) => error,+ );+ const elapsedMs = Date.now() - startedAt;++ expect(failure).not.toBeNull();+ expect(failure?.message).toMatch(/did not converge/);+ expect(failure?.message).toContain(client.docName);+ expect(failure?.message).toMatch(/client Y\.Text \([1-9]\d* chars\)/);+ expect(failure?.message).not.toContain('server has no document by that name');+ expect(elapsedMs).toBeLessThan(1_000);+ } finally {+ clearInterval(churn);+ client.setDropOutbound(false);+ await client.cleanup();+ }+ });++ test('compares once before consulting the clock, so a zero budget still resolves', async () => {+ const client = await createTestClient(server.port, undefined, { syncControl: true });+ try {+ await agentWriteMd(server.port, 'zero budget body\n', {+ docName: client.docName,+ position: 'replace',+ });+ await awaitConvergedServerText(server, client);++ const converged = await awaitConvergedServerText(server, client, { timeoutMs: 0 });+ expect(converged).toContain('zero budget body');+ expect(client.ytext.toString()).toBe(converged);++ client.pauseSync();+ await agentWriteMd(server.port, 'held past the zero budget\n', {+ docName: client.docName,+ position: 'replace',+ });++ const failure = await awaitConvergedServerText(server, client, { timeoutMs: 0 }).then(+ () => null,+ (error: Error) => error,+ );+ expect(failure?.message).toMatch(/did not converge/);+ expect(failure?.message).toContain('held past the zero budget');+ expect(failure?.message).not.toContain('server has no document by that name');+ } finally {+ client.resumeSync();+ await client.cleanup();+ }+ });++ test('spends only the remaining budget on the final sleep, not a whole cadence', async () => {+ const client = await createTestClient(server.port, undefined, { syncControl: true });+ try {+ client.pauseSync();+ await agentWriteMd(server.port, 'cadence larger than budget\n', {+ docName: client.docName,+ position: 'replace',+ });++ const startedAt = Date.now();+ const failure = await awaitConvergedServerText(server, client, {+ timeoutMs: 120,+ pollIntervalMs: 1_000,+ }).then(+ () => null,+ (error: Error) => error,+ );+ const elapsedMs = Date.now() - startedAt;++ expect(failure?.message).toMatch(/did not converge within 120 ms/);+ expect(elapsedMs).toBeLessThan(600);+ } finally {+ client.resumeSync();+ await client.cleanup();+ }+ });++ test('polls at the cadence rather than sleeping the budget in one go', async () => {+ const client = await createTestClient(server.port, undefined, { syncControl: true });+ try {+ client.pauseSync();+ await agentWriteMd(server.port, 'cadence smaller than budget\n', {+ docName: client.docName,+ position: 'replace',+ });++ const startedAt = Date.now();+ const pending = awaitConvergedServerText(server, client, {+ timeoutMs: 2_000,+ pollIntervalMs: 20,+ });+ const stillWaiting = await Promise.race([+ pending.then(() => 'resolved' as const),+ wait(100).then(() => 'pending' as const),+ ]);+ expect(stillWaiting).toBe('pending');++ client.resumeSync();++ const converged = await pending;+ const elapsedMs = Date.now() - startedAt;++ expect(converged).toContain('cadence smaller than budget');+ expect(client.ytext.toString()).toBe(converged);+ expect(elapsedMs).toBeLessThan(1_000);+ } finally {+ client.resumeSync();+ await client.cleanup();+ }+ });++ test('keeps waiting while the server update is held, then returns the converged bytes', async () => {+ const client = await createTestClient(server.port, undefined, { syncControl: true });+ try {+ client.pauseSync();+ await agentWriteMd(server.port, 'late body\n', {+ docName: client.docName,+ position: 'replace',+ });++ const pending = awaitConvergedServerText(server, client, {+ timeoutMs: 5_000,+ pollIntervalMs: 10,+ });+ const stillWaiting = await Promise.race([+ pending.then(() => 'resolved' as const),+ wait(100).then(() => 'pending' as const),+ ]);+ expect(stillWaiting).toBe('pending');++ client.resumeSync();++ const converged = await pending;+ expect(converged).toContain('late body');+ expect(client.ytext.toString()).toBe(converged);+ expect(getServerState(server, client.docName)?.ytext.toString()).toBe(converged);+ } finally {+ await client.cleanup();+ }+ });++ test('resolves the two-hop fragment chain with the server-derived bytes', async () => {+ const client = await createTestClient(server.port);+ try {+ expect(client.ytext.toString()).toBe('');+ client.fragment.push([new Y.XmlElement('thematicBreak')]);++ const converged = await awaitConvergedServerText(server, client, { timeoutMs: 10_000 });++ expect(converged).toContain('---');+ expect(client.ytext.toString()).toBe(converged);+ expect(getServerState(server, client.docName)?.ytext.toString()).toBe(converged);+ } finally {+ await client.cleanup();+ }+ });+});diff --git a/packages/app/tests/integration/test-harness.ts b/packages/app/tests/integration/test-harness.tsindex 2a8f71b12..38bd95a44 100644--- a/packages/app/tests/integration/test-harness.ts+++ b/packages/app/tests/integration/test-harness.ts@@ -10,7 +10,7 @@ import { promisify } from 'node:util';export { wait };import { HocuspocusProvider } from '@hocuspocus/provider';-import type { LocalTransactionOrigin } from '@hocuspocus/server';+import type { Document, LocalTransactionOrigin } from '@hocuspocus/server';import {type BridgeInvariantViolation,BridgeInvariantViolationError,@@ -775,8 +775,12 @@ export type ServerDocState = {connectionCount: number;};+function getServerDoc(server: TestServer, docName: string): Document | null {+ return server.instance.hocuspocus.documents.get(docName) ?? null;+}+export function getServerState(server: TestServer, docName: string): ServerDocState | null {- const document = server.instance.hocuspocus.documents.get(docName);+ const document = getServerDoc(server, docName);if (!document) return null;const ytext = document.getText('source');@@ -800,6 +804,44 @@ export function getServerState(server: TestServer, docName: string): ServerDocSt};}+function docsHaveConverged(a: Y.Doc, b: Y.Doc): boolean {+ return Y.equalSnapshots(Y.snapshot(a), Y.snapshot(b));+}++export async function awaitConvergedServerText(+ server: TestServer,+ client: TestClient,+ opts: { timeoutMs?: number; pollIntervalMs?: number } = {},+): Promise<string> {+ const timeoutMs = opts.timeoutMs ?? 5_000;+ const pollIntervalMs = opts.pollIntervalMs ?? 50;+ const deadline = Date.now() + timeoutMs;++ for (;;) {+ const serverDoc = getServerDoc(server, client.docName);+ if (serverDoc !== null && docsHaveConverged(serverDoc, client.doc)) {+ return serverDoc.getText('source').toString();+ }++ const remainingMs = deadline - Date.now();+ if (remainingMs <= 0) {+ let replicas = '\n server has no document by that name';+ if (serverDoc !== null) {+ const serverText = serverDoc.getText('source').toString();+ const clientText = client.ytext.toString();+ replicas =+ `\n server Y.Text (${serverText.length} chars): ${JSON.stringify(serverText.slice(0, 200))}` ++ `\n client Y.Text (${clientText.length} chars): ${JSON.stringify(clientText.slice(0, 200))}`;+ }+ throw new Error(+ `awaitConvergedServerText: server and client for ${client.docName} did not converge within ${timeoutMs} ms${replicas}`,+ );+ }++ await wait(Math.min(pollIntervalMs, remainingMs));+ }+}+const BRIDGE_ENFORCING_NON_PAIRED_ORIGINS: Set<LocalTransactionOrigin> = new Set([ORIGIN_TREE_TO_TEXT,ORIGIN_TEXT_TO_TREE,