@syncular/client 0.0.6-219 → 0.0.6-223

package/src/pull-engine.test.ts

@@ -9,6 +9,7 @@ import {
 } from '@syncular/core';
 import { type Kysely, sql } from 'kysely';
 import { createBunSqliteDialect } from '../../dialect-bun-sqlite/src';
+import { SyncClientStageError } from './errors';
 import type { ClientHandlerCollection } from './handlers/collection';
 import { createClientHandler } from './handlers/create-handler';
 import { ensureClientSyncSchema } from './migrate';
@@ -269,6 +270,277 @@ describe('applyPullResponse chunk streaming', () => {
     }
   });
 
+  it('surfaces gzip decode failures with stage metadata', async () => {
+    const invalidCompressed = new Uint8Array(
+      gzipSync(new TextEncoder().encode('truncated-gzip')).subarray(0, 8)
+    );
+
+    const transport: SyncTransport = {
+      capabilities: {
+        snapshotChunkReadMode: 'bytes',
+        preferMaterializedSnapshots: true,
+      },
+      async sync() {
+        return {};
+      },
+      async fetchSnapshotChunk() {
+        return invalidCompressed;
+      },
+    };
+
+    const handlers: ClientHandlerCollection<TestDb> = [
+      createClientHandler({
+        table: 'items',
+        scopes: ['items:{id}'],
+      }),
+    ];
+
+    const options = {
+      clientId: 'client-1',
+      subscriptions: [
+        {
+          id: 'items-sub',
+          table: 'items',
+          scopes: {},
+        },
+      ],
+      stateId: 'default',
+    };
+
+    const pullState = await buildPullRequest(db, options);
+
+    const response: SyncPullResponse = {
+      ok: true,
+      subscriptions: [
+        {
+          id: 'items-sub',
+          status: 'active',
+          scopes: {},
+          bootstrap: true,
+          bootstrapState: null,
+          nextCursor: 1,
+          commits: [],
+          snapshots: [
+            {
+              table: 'items',
+              rows: [],
+              chunks: [
+                {
+                  id: 'chunk-1',
+                  byteLength: invalidCompressed.length,
+                  sha256: '',
+                  encoding: 'json-row-frame-v1',
+                  compression: 'gzip',
+                },
+              ],
+              isFirstPage: true,
+              isLastPage: true,
+            },
+          ],
+        },
+      ],
+    };
+
+    try {
+      await applyPullResponse(
+        db,
+        transport,
+        handlers,
+        options,
+        pullState,
+        response
+      );
+      throw new Error('Expected applyPullResponse to fail');
+    } catch (error) {
+      expect(error).toBeInstanceOf(SyncClientStageError);
+      expect((error as SyncClientStageError).stage).toBe(
+        'snapshot-gzip-decode'
+      );
+      expect((error as SyncClientStageError).chunkId).toBe('chunk-1');
+      expect((error as SyncClientStageError).subscriptionId).toBe('items-sub');
+    }
+  });
+
+  it('surfaces snapshot decode failures with stage metadata', async () => {
+    const invalidPayload = new TextEncoder().encode('not-a-row-frame');
+    const compressed = new Uint8Array(gzipSync(invalidPayload));
+
+    const transport: SyncTransport = {
+      async sync() {
+        return {};
+      },
+      async fetchSnapshotChunk() {
+        throw new Error('fetchSnapshotChunk should not be used');
+      },
+      async fetchSnapshotChunkStream() {
+        return createStreamFromBytes(compressed, 13);
+      },
+    };
+
+    const handlers: ClientHandlerCollection<TestDb> = [
+      createClientHandler({
+        table: 'items',
+        scopes: ['items:{id}'],
+      }),
+    ];
+
+    const options = {
+      clientId: 'client-1',
+      subscriptions: [
+        {
+          id: 'items-sub',
+          table: 'items',
+          scopes: {},
+        },
+      ],
+      stateId: 'default',
+    };
+
+    const pullState = await buildPullRequest(db, options);
+
+    const response: SyncPullResponse = {
+      ok: true,
+      subscriptions: [
+        {
+          id: 'items-sub',
+          status: 'active',
+          scopes: {},
+          bootstrap: true,
+          bootstrapState: null,
+          nextCursor: 1,
+          commits: [],
+          snapshots: [
+            {
+              table: 'items',
+              rows: [],
+              chunks: [
+                {
+                  id: 'chunk-1',
+                  byteLength: compressed.length,
+                  sha256: '',
+                  encoding: 'json-row-frame-v1',
+                  compression: 'gzip',
+                },
+              ],
+              isFirstPage: true,
+              isLastPage: true,
+            },
+          ],
+        },
+      ],
+    };
+
+    try {
+      await applyPullResponse(
+        db,
+        transport,
+        handlers,
+        options,
+        pullState,
+        response
+      );
+      throw new Error('Expected applyPullResponse to fail');
+    } catch (error) {
+      expect(error).toBeInstanceOf(SyncClientStageError);
+      expect((error as SyncClientStageError).stage).toBe(
+        'snapshot-chunk-decode'
+      );
+      expect((error as SyncClientStageError).chunkId).toBe('chunk-1');
+      expect((error as SyncClientStageError).table).toBe('items');
+    }
+  });
+
+  it('surfaces snapshot apply failures with stage metadata', async () => {
+    const rows = [{ id: '1', name: 'Item 1' }];
+    const encoded = encodeSnapshotRows(rows);
+    const compressed = new Uint8Array(gzipSync(encoded));
+
+    const transport: SyncTransport = {
+      async sync() {
+        return {};
+      },
+      async fetchSnapshotChunk() {
+        throw new Error('fetchSnapshotChunk should not be used');
+      },
+      async fetchSnapshotChunkStream() {
+        return createStreamFromBytes(compressed, 17);
+      },
+    };
+
+    const handlers: ClientHandlerCollection<TestDb> = [
+      {
+        table: 'items',
+        async applySnapshot() {
+          throw new Error('apply failed');
+        },
+        async clearAll() {},
+      },
+    ];
+
+    const options = {
+      clientId: 'client-1',
+      subscriptions: [
+        {
+          id: 'items-sub',
+          table: 'items',
+          scopes: {},
+        },
+      ],
+      stateId: 'default',
+    };
+
+    const pullState = await buildPullRequest(db, options);
+
+    const response: SyncPullResponse = {
+      ok: true,
+      subscriptions: [
+        {
+          id: 'items-sub',
+          status: 'active',
+          scopes: {},
+          bootstrap: true,
+          bootstrapState: null,
+          nextCursor: 1,
+          commits: [],
+          snapshots: [
+            {
+              table: 'items',
+              rows: [],
+              chunks: [
+                {
+                  id: 'chunk-1',
+                  byteLength: compressed.length,
+                  sha256: '',
+                  encoding: 'json-row-frame-v1',
+                  compression: 'gzip',
+                },
+              ],
+              isFirstPage: true,
+              isLastPage: true,
+            },
+          ],
+        },
+      ],
+    };
+
+    try {
+      await applyPullResponse(
+        db,
+        transport,
+        handlers,
+        options,
+        pullState,
+        response
+      );
+      throw new Error('Expected applyPullResponse to fail');
+    } catch (error) {
+      expect(error).toBeInstanceOf(SyncClientStageError);
+      expect((error as SyncClientStageError).stage).toBe('snapshot-apply');
+      expect((error as SyncClientStageError).subscriptionId).toBe('items-sub');
+      expect((error as SyncClientStageError).table).toBe('items');
+    }
+  });
+
   it('materializes chunked bootstrap snapshots for afterPull plugins via streaming transport', async () => {
     const firstRows = Array.from({ length: 1200 }, (_, index) => ({
       id: `${index + 1}`,
@@ -501,16 +773,26 @@ describe('applyPullResponse chunk streaming', () => {
     };
 
     const firstPullState = await buildPullRequest(db, options);
-    await expect(
-      applyPullResponse(
+    try {
+      await applyPullResponse(
         db,
         transport,
         handlers,
         options,
         firstPullState,
         response
-      )
-    ).rejects.toThrow('chunk-2 missing');
+      );
+      throw new Error('Expected applyPullResponse to fail');
+    } catch (error) {
+      expect(error).toBeInstanceOf(SyncClientStageError);
+      expect((error as SyncClientStageError).stage).toBe(
+        'snapshot-chunk-fetch'
+      );
+      expect((error as SyncClientStageError).chunkId).toBe('chunk-2');
+      expect((error as SyncClientStageError).cause?.message).toContain(
+        'chunk-2 missing'
+      );
+    }
 
     const countAfterFailure = await sql<{ count: number }>`
       select count(*) as count
@@ -655,9 +937,24 @@ describe('applyPullResponse chunk streaming', () => {
       ],
     };
 
-    await expect(
-      applyPullResponse(db, transport, handlers, options, pullState, response)
-    ).rejects.toThrow('scoped bootstrap failed');
+    try {
+      await applyPullResponse(
+        db,
+        transport,
+        handlers,
+        options,
+        pullState,
+        response
+      );
+      throw new Error('Expected applyPullResponse to fail');
+    } catch (error) {
+      expect(error).toBeInstanceOf(SyncClientStageError);
+      expect((error as SyncClientStageError).stage).toBe('snapshot-apply');
+      expect((error as SyncClientStageError).subscriptionId).toBe('scoped-sub');
+      expect((error as SyncClientStageError).cause?.message).toContain(
+        'scoped bootstrap failed'
+      );
+    }
 
     const itemCount = await sql<{ count: number }>`
       select count(*) as count
@@ -1790,3 +2087,121 @@ describe('applyPullResponse chunk streaming', () => {
     expect(clearedScopes).toEqual([{ project_id: 'p1' }]);
   });
 });
+
+describe('buildPullRequest phased bootstrap selection', () => {
+  let db: Kysely<TestDb>;
+
+  beforeEach(async () => {
+    db = createDatabase<TestDb>({
+      dialect: createBunSqliteDialect({ path: ':memory:' }),
+      family: 'sqlite',
+    });
+    await ensureClientSyncSchema(db);
+  });
+
+  afterEach(async () => {
+    await db.destroy();
+  });
+
+  it('requests only the lowest pending bootstrap phase by default', async () => {
+    const pullState = await buildPullRequest(db, {
+      clientId: 'client-1',
+      stateId: 'default',
+      subscriptions: [
+        { id: 'catalog-meta', table: 'items', bootstrapPhase: 0 },
+        { id: 'catalog-relations', table: 'scoped_items', bootstrapPhase: 1 },
+      ],
+    });
+
+    expect(pullState.request.subscriptions.map((sub) => sub.id)).toEqual([
+      'catalog-meta',
+    ]);
+  });
+
+  it('unlocks later phases once earlier phases are ready', async () => {
+    const now = Date.now();
+
+    await db
+      .insertInto('sync_subscription_state')
+      .values({
+        state_id: 'default',
+        subscription_id: 'catalog-meta',
+        table: 'items',
+        scopes_json: '{}',
+        params_json: '{}',
+        cursor: 12,
+        bootstrap_state_json: null,
+        status: 'active',
+        created_at: now,
+        updated_at: now,
+      })
+      .execute();
+
+    const pullState = await buildPullRequest(db, {
+      clientId: 'client-1',
+      stateId: 'default',
+      subscriptions: [
+        { id: 'catalog-meta', table: 'items', bootstrapPhase: 0 },
+        { id: 'catalog-relations', table: 'scoped_items', bootstrapPhase: 1 },
+      ],
+    });
+
+    expect(pullState.request.subscriptions.map((sub) => sub.id)).toEqual([
+      'catalog-meta',
+      'catalog-relations',
+    ]);
+  });
+
+  it('keeps already-ready later phases live while earlier phases rebootstrap', async () => {
+    const now = Date.now();
+
+    await db
+      .insertInto('sync_subscription_state')
+      .values([
+        {
+          state_id: 'default',
+          subscription_id: 'catalog-meta',
+          table: 'items',
+          scopes_json: '{}',
+          params_json: '{}',
+          cursor: -1,
+          bootstrap_state_json: JSON.stringify({
+            asOfCommitSeq: 0,
+            tables: ['items'],
+            tableIndex: 0,
+            rowCursor: null,
+          }),
+          status: 'active',
+          created_at: now,
+          updated_at: now,
+        },
+        {
+          state_id: 'default',
+          subscription_id: 'catalog-relations',
+          table: 'scoped_items',
+          scopes_json: '{}',
+          params_json: '{}',
+          cursor: 42,
+          bootstrap_state_json: null,
+          status: 'active',
+          created_at: now,
+          updated_at: now,
+        },
+      ])
+      .execute();
+
+    const pullState = await buildPullRequest(db, {
+      clientId: 'client-1',
+      stateId: 'default',
+      subscriptions: [
+        { id: 'catalog-meta', table: 'items', bootstrapPhase: 0 },
+        { id: 'catalog-relations', table: 'scoped_items', bootstrapPhase: 1 },
+      ],
+    });
+
+    expect(pullState.request.subscriptions.map((sub) => sub.id)).toEqual([
+      'catalog-meta',
+      'catalog-relations',
+    ]);
+  });
+});