Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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,