@syncular/client 0.0.6-108 → 0.0.6-109

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/client",
-  "version": "0.0.6-108",
+  "version": "0.0.6-109",
   "description": "Client-side sync engine with offline-first support, outbox, and conflict resolution",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -46,8 +46,8 @@
     "release": "bunx syncular-publish"
   },
   "dependencies": {
-    "@syncular/core": "0.0.6-108",
-    "@syncular/transport-http": "0.0.6-108"
+    "@syncular/core": "0.0.6-109",
+    "@syncular/transport-http": "0.0.6-109"
   },
   "peerDependencies": {
     "kysely": "*"

package/src/engine/SyncEngine.test.ts

@@ -1,6 +1,8 @@
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { gzipSync } from 'node:zlib';
 import {
   createDatabase,
+  encodeSnapshotRows,
   type SyncChange,
   type SyncTransport,
   SyncTransportError,
@@ -10,6 +12,7 @@ import { sql } from 'kysely';
 import { createBunSqliteDialect } from '../../../dialect-bun-sqlite/src';
 import type { ClientHandlerCollection } from '../handlers/collection';
 import { ensureClientSyncSchema } from '../migrate';
+import { enqueueOutboxCommit } from '../outbox';
 import type { SyncClientDb } from '../schema';
 import { SyncEngine } from './SyncEngine';
 
@@ -23,6 +26,21 @@ interface TestDb extends SyncClientDb {
   tasks: TasksTable;
 }
 
+async function waitFor(
+  condition: () => boolean,
+  timeoutMs = 2000,
+  stepMs = 10
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (condition()) {
+      return;
+    }
+    await new Promise<void>((resolve) => setTimeout(resolve, stepMs));
+  }
+  throw new Error(`Timed out waiting for condition after ${timeoutMs}ms`);
+}
+
 const noopTransport: SyncTransport = {
   async sync() {
     return {};
@@ -300,6 +318,337 @@ describe('SyncEngine WS inline apply', () => {
     expect(state.isRetrying).toBe(false);
   });
 
+  it('classifies 429 sync failures as retryable and schedules exponential backoff', async () => {
+    let syncAttempts = 0;
+    const rateLimitedTransport: SyncTransport = {
+      async sync() {
+        syncAttempts += 1;
+        throw new SyncTransportError('rate limited', 429);
+      },
+      async fetchSnapshotChunk() {
+        return new Uint8Array();
+      },
+    };
+
+    const handlers: ClientHandlerCollection<TestDb> = [
+      {
+        table: 'tasks',
+        async applySnapshot() {},
+        async clearAll() {},
+        async applyChange() {},
+      },
+    ];
+
+    const delays: number[] = [];
+    const timeoutHandles: Array<ReturnType<typeof setTimeout>> = [];
+    const originalSetTimeout = globalThis.setTimeout;
+    const patchedSetTimeout: typeof globalThis.setTimeout = (
+      _handler,
+      timeout,
+      ..._args
+    ) => {
+      const delayMs = typeof timeout === 'number' ? timeout : 0;
+      delays.push(delayMs);
+      const handle = originalSetTimeout(() => {}, 60_000);
+      timeoutHandles.push(handle);
+      return handle;
+    };
+    globalThis.setTimeout = patchedSetTimeout;
+
+    try {
+      const engine = new SyncEngine<TestDb>({
+        db,
+        transport: rateLimitedTransport,
+        handlers,
+        actorId: 'u1',
+        clientId: 'client-rate-limit',
+        subscriptions: [
+          {
+            id: 'sub-1',
+            table: 'tasks',
+            scopes: {},
+          },
+        ],
+        stateId: 'default',
+        pollIntervalMs: 60_000,
+        maxRetries: 4,
+      });
+
+      await engine.start();
+
+      let state = engine.getState();
+      expect(state.error?.code).toBe('NETWORK_ERROR');
+      expect(state.error?.retryable).toBe(true);
+      expect(state.error?.httpStatus).toBe(429);
+      expect(state.retryCount).toBe(1);
+      expect(state.isRetrying).toBe(true);
+      expect(delays).toEqual([2000]);
+
+      await engine.sync();
+      state = engine.getState();
+      expect(state.retryCount).toBe(2);
+      expect(state.isRetrying).toBe(true);
+      expect(delays).toEqual([2000, 4000]);
+
+      await engine.sync();
+      state = engine.getState();
+      expect(state.retryCount).toBe(3);
+      expect(state.isRetrying).toBe(true);
+      expect(delays).toEqual([2000, 4000, 8000]);
+      expect(syncAttempts).toBe(3);
+
+      engine.destroy();
+    } finally {
+      globalThis.setTimeout = originalSetTimeout;
+      for (const handle of timeoutHandles) {
+        clearTimeout(handle);
+      }
+    }
+  });
+
+  it('keeps push failures retryable on 503 and preserves pending outbox state', async () => {
+    let sawPushRequest = false;
+    const unavailablePushTransport: SyncTransport = {
+      async sync(request) {
+        sawPushRequest = sawPushRequest || Boolean(request.push);
+        throw new SyncTransportError('service unavailable', 503);
+      },
+      async fetchSnapshotChunk() {
+        return new Uint8Array();
+      },
+    };
+
+    const handlers: ClientHandlerCollection<TestDb> = [
+      {
+        table: 'tasks',
+        async applySnapshot() {},
+        async clearAll() {},
+        async applyChange() {},
+      },
+    ];
+
+    const originalSetTimeout = globalThis.setTimeout;
+    const timeoutHandles: Array<ReturnType<typeof setTimeout>> = [];
+    const patchedSetTimeout: typeof globalThis.setTimeout = (
+      _handler,
+      _timeout,
+      ..._args
+    ) => {
+      const handle = originalSetTimeout(() => {}, 60_000);
+      timeoutHandles.push(handle);
+      return handle;
+    };
+    globalThis.setTimeout = patchedSetTimeout;
+
+    try {
+      await enqueueOutboxCommit(db, {
+        operations: [
+          {
+            table: 'tasks',
+            row_id: 'push-failure-task',
+            op: 'upsert',
+            payload: {
+              title: 'Push Failure Task',
+            },
+            base_version: null,
+          },
+        ],
+      });
+
+      const engine = new SyncEngine<TestDb>({
+        db,
+        transport: unavailablePushTransport,
+        handlers,
+        actorId: 'u1',
+        clientId: 'client-push-503',
+        subscriptions: [
+          {
+            id: 'sub-1',
+            table: 'tasks',
+            scopes: {},
+          },
+        ],
+        stateId: 'default',
+        pollIntervalMs: 60_000,
+      });
+
+      await engine.start();
+
+      const state = engine.getState();
+      expect(state.error?.code).toBe('NETWORK_ERROR');
+      expect(state.error?.retryable).toBe(true);
+      expect(state.error?.httpStatus).toBe(503);
+      expect(sawPushRequest).toBe(true);
+
+      const row = await db
+        .selectFrom('sync_outbox_commits')
+        .select(['status'])
+        .executeTakeFirst();
+      const failedCount = await db
+        .selectFrom('sync_outbox_commits')
+        .select(({ fn }) => fn.countAll().as('total'))
+        .where('status', '=', 'failed')
+        .executeTakeFirst();
+      expect(row?.status === 'pending' || row?.status === 'sending').toBe(true);
+      expect(Number(failedCount?.total ?? 0)).toBe(0);
+
+      engine.destroy();
+    } finally {
+      globalThis.setTimeout = originalSetTimeout;
+      for (const handle of timeoutHandles) {
+        clearTimeout(handle);
+      }
+    }
+  });
+
+  it('classifies 503 snapshot chunk fetch failures as retryable and recovers on retry', async () => {
+    let syncCalls = 0;
+    let chunkFetchCalls = 0;
+    const payload = new Uint8Array(
+      gzipSync(
+        encodeSnapshotRows([
+          {
+            id: 'chunk-retry-task',
+            title: 'Chunk Retry',
+            server_version: 1,
+          },
+        ])
+      )
+    );
+    const chunkFailThenRecoverTransport: SyncTransport = {
+      async sync() {
+        syncCalls += 1;
+        return {
+          ok: true,
+          pull: {
+            ok: true,
+            subscriptions: [
+              {
+                id: 'sub-1',
+                status: 'active',
+                scopes: {},
+                bootstrap: true,
+                bootstrapState: null,
+                nextCursor: 1,
+                commits: [],
+                snapshots: [
+                  {
+                    table: 'tasks',
+                    rows: [],
+                    chunks: [
+                      {
+                        id: 'chunk-retry-1',
+                        byteLength: payload.length,
+                        sha256: '',
+                        encoding: 'json-row-frame-v1',
+                        compression: 'gzip',
+                      },
+                    ],
+                    isFirstPage: true,
+                    isLastPage: true,
+                  },
+                ],
+              },
+            ],
+          },
+        };
+      },
+      async fetchSnapshotChunk() {
+        chunkFetchCalls += 1;
+        if (chunkFetchCalls === 1) {
+          throw new SyncTransportError('temporary chunk outage', 503);
+        }
+        return payload;
+      },
+    };
+
+    const handlers: ClientHandlerCollection<TestDb> = [
+      {
+        table: 'tasks',
+        async applySnapshot(ctx, snapshot) {
+          for (const row of snapshot.rows as TasksTable[]) {
+            await sql`
+              insert into ${sql.table('tasks')} (
+                ${sql.ref('id')},
+                ${sql.ref('title')},
+                ${sql.ref('server_version')}
+              ) values (
+                ${sql.val(row.id)},
+                ${sql.val(row.title)},
+                ${sql.val(row.server_version)}
+              )
+              on conflict (${sql.ref('id')})
+              do update set
+                ${sql.ref('title')} = excluded.${sql.ref('title')},
+                ${sql.ref('server_version')} = excluded.${sql.ref('server_version')}
+            `.execute(ctx.trx);
+          }
+        },
+        async clearAll(ctx) {
+          await sql`delete from ${sql.table('tasks')}`.execute(ctx.trx);
+        },
+        async applyChange() {},
+      },
+    ];
+
+    const originalSetTimeout = globalThis.setTimeout;
+    const delays: number[] = [];
+    const patchedSetTimeout: typeof globalThis.setTimeout = (
+      handler,
+      timeout,
+      ...args
+    ) => {
+      const delayMs = typeof timeout === 'number' ? timeout : 0;
+      delays.push(delayMs);
+      return originalSetTimeout(() => {
+        if (typeof handler === 'function') {
+          handler(...args);
+        }
+      }, 0);
+    };
+    globalThis.setTimeout = patchedSetTimeout;
+
+    try {
+      const engine = new SyncEngine<TestDb>({
+        db,
+        transport: chunkFailThenRecoverTransport,
+        handlers,
+        actorId: 'u1',
+        clientId: 'client-chunk-503',
+        subscriptions: [
+          {
+            id: 'sub-1',
+            table: 'tasks',
+            scopes: {},
+          },
+        ],
+        stateId: 'default',
+        pollIntervalMs: 60_000,
+      });
+
+      await engine.start();
+      await waitFor(() => engine.getState().error === null, 2000, 10);
+
+      const state = engine.getState();
+      expect(state.retryCount).toBe(0);
+      expect(state.isRetrying).toBe(false);
+      expect(delays[0]).toBe(2000);
+      expect(chunkFetchCalls).toBeGreaterThanOrEqual(2);
+      expect(syncCalls).toBeGreaterThanOrEqual(2);
+
+      const row = await db
+        .selectFrom('tasks')
+        .select(['id', 'title'])
+        .where('id', '=', 'chunk-retry-task')
+        .executeTakeFirst();
+      expect(row?.title).toBe('Chunk Retry');
+
+      engine.destroy();
+    } finally {
+      globalThis.setTimeout = originalSetTimeout;
+    }
+  });
+
   it('repairs rebootstrap-missing-chunks by clearing synced state and data', async () => {
     const outboxId = 'outbox-1';
     const now = Date.now();