@syncular/client 0.0.6-204 → 0.0.6-206

package/src/engine/SyncEngine.test.ts

@@ -795,19 +795,19 @@ describe('SyncEngine WS inline apply', () => {
       expect(state.error?.httpStatus).toBe(429);
       expect(state.retryCount).toBe(1);
       expect(state.isRetrying).toBe(true);
-      expect(delays).toEqual([2000]);
+      expect(delays).toEqual([1000]);
 
       await engine.sync();
       state = engine.getState();
       expect(state.retryCount).toBe(2);
       expect(state.isRetrying).toBe(true);
-      expect(delays).toEqual([2000, 4000]);
+      expect(delays).toEqual([1000, 2000]);
 
       await engine.sync();
       state = engine.getState();
       expect(state.retryCount).toBe(3);
       expect(state.isRetrying).toBe(true);
-      expect(delays).toEqual([2000, 4000, 8000]);
+      expect(delays).toEqual([1000, 2000, 4000]);
       expect(syncAttempts).toBe(3);
 
       engine.destroy();
@@ -819,6 +819,183 @@ describe('SyncEngine WS inline apply', () => {
     }
   });
 
+  it('uses a shorter capped recovery retry delay after a recent successful read-only sync', async () => {
+    let syncAttempts = 0;
+    const delayedFailureTransport: SyncTransport = {
+      async sync() {
+        syncAttempts += 1;
+        if (syncAttempts === 1) {
+          return { ok: true, subscriptions: [] };
+        }
+        throw new SyncTransportError('service unavailable', 503);
+      },
+      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: delayedFailureTransport,
+        handlers,
+        actorId: 'u1',
+        clientId: 'client-recovery-retry',
+        subscriptions: [
+          {
+            id: 'sub-1',
+            table: 'tasks',
+            scopes: {},
+          },
+        ],
+        stateId: 'default',
+        pollIntervalMs: 60_000,
+        maxRetries: 5,
+      });
+
+      await engine.start();
+      expect(engine.getState().lastSyncAt).not.toBeNull();
+
+      await engine.sync();
+      let state = engine.getState();
+      expect(state.error?.code).toBe('NETWORK_ERROR');
+      expect(state.retryCount).toBe(1);
+      expect(state.isRetrying).toBe(true);
+
+      await engine.sync();
+      state = engine.getState();
+      expect(state.retryCount).toBe(2);
+
+      await engine.sync();
+      state = engine.getState();
+      expect(state.retryCount).toBe(3);
+
+      await engine.sync();
+      state = engine.getState();
+      expect(state.retryCount).toBe(4);
+      expect(delays).toEqual([250, 500, 1000, 1000]);
+
+      engine.destroy();
+    } finally {
+      globalThis.setTimeout = originalSetTimeout;
+      for (const handle of timeoutHandles) {
+        clearTimeout(handle);
+      }
+    }
+  });
+
+  it('uses deterministic jitter for realtime reconnect sync and catchup scheduling', () => {
+    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 engineA = new SyncEngine<TestDb>({
+        db,
+        transport: noopTransport,
+        handlers,
+        actorId: 'u1',
+        clientId: 'client-reconnect-jitter',
+        subscriptions: [],
+        stateId: 'default',
+      });
+      const engineB = new SyncEngine<TestDb>({
+        db,
+        transport: noopTransport,
+        handlers,
+        actorId: 'u1',
+        clientId: 'client-reconnect-jitter',
+        subscriptions: [],
+        stateId: 'default',
+      });
+
+      const scheduleReconnectSyncA = Reflect.get(
+        engineA,
+        'scheduleRealtimeReconnectSync'
+      );
+      const scheduleReconnectCatchupA = Reflect.get(
+        engineA,
+        'scheduleRealtimeReconnectCatchupSync'
+      );
+      const scheduleReconnectSyncB = Reflect.get(
+        engineB,
+        'scheduleRealtimeReconnectSync'
+      );
+
+      if (
+        typeof scheduleReconnectSyncA !== 'function' ||
+        typeof scheduleReconnectCatchupA !== 'function' ||
+        typeof scheduleReconnectSyncB !== 'function'
+      ) {
+        throw new Error('Expected reconnect scheduling helpers to be callable');
+      }
+
+      scheduleReconnectSyncA.call(engineA);
+      scheduleReconnectCatchupA.call(engineA);
+      scheduleReconnectSyncB.call(engineB);
+
+      expect(delays.length).toBe(3);
+      expect(delays[0]).toBeGreaterThanOrEqual(0);
+      expect(delays[0]).toBeLessThanOrEqual(250);
+      expect(delays[1]).toBeGreaterThanOrEqual(500);
+      expect(delays[1]).toBeLessThanOrEqual(750);
+      expect(delays[2]).toBe(delays[0]);
+
+      engineA.destroy();
+      engineB.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 = {
@@ -953,7 +1130,7 @@ describe('SyncEngine WS inline apply', () => {
                         id: 'chunk-retry-1',
                         byteLength: payload.length,
                         sha256: '',
-                        encoding: 'json-row-frame-v1',
+                        encoding: 'json-row-batch-frame-v2',
                         compression: 'gzip',
                       },
                     ],
@@ -1045,7 +1222,7 @@ describe('SyncEngine WS inline apply', () => {
       const state = engine.getState();
       expect(state.retryCount).toBe(0);
       expect(state.isRetrying).toBe(false);
-      expect(delays[0]).toBe(2000);
+      expect(delays[0]).toBe(1000);
       expect(chunkFetchCalls).toBeGreaterThanOrEqual(2);
       expect(syncCalls).toBeGreaterThanOrEqual(2);
 

package/src/engine/SyncEngine.ts

@@ -75,7 +75,11 @@ const DEFAULT_MAX_RETRIES = 5;
 const INITIAL_RETRY_DELAY_MS = 1000;
 const MAX_RETRY_DELAY_MS = 60000;
 const EXPONENTIAL_FACTOR = 2;
+const RECOVERY_RETRY_DELAY_MS = 250;
+const MAX_RECOVERY_RETRY_DELAY_MS = 1000;
+const RECOVERY_RETRY_WINDOW_MS = 120000;
 const REALTIME_RECONNECT_CATCHUP_DELAY_MS = 500;
+const REALTIME_RECONNECT_SYNC_JITTER_MS = 250;
 const DEFAULT_AWAIT_TIMEOUT_MS = 60_000;
 const DEFAULT_INSPECTOR_EVENT_LIMIT = 100;
 const MAX_INSPECTOR_EVENT_LIMIT = 500;
@@ -88,6 +92,27 @@ function calculateRetryDelay(attemptIndex: number): number {
   );
 }
 
+function calculateRecoveryRetryDelay(attemptIndex: number): number {
+  return Math.min(
+    RECOVERY_RETRY_DELAY_MS * EXPONENTIAL_FACTOR ** attemptIndex,
+    MAX_RECOVERY_RETRY_DELAY_MS
+  );
+}
+
+function calculateDeterministicClientJitter(
+  clientId: string,
+  maxJitterMs: number
+): number {
+  if (maxJitterMs <= 0 || clientId.length === 0) return 0;
+
+  let hash = 0;
+  for (let index = 0; index < clientId.length; index += 1) {
+    hash = (hash * 31 + clientId.charCodeAt(index)) >>> 0;
+  }
+
+  return hash % (maxJitterMs + 1);
+}
+
 function isRealtimeTransport(
   transport: unknown
 ): transport is RealtimeTransportLike {
@@ -310,6 +335,8 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
   private syncRequestedWhileRunning = false;
   private retryTimeoutId: ReturnType<typeof setTimeout> | null = null;
   private realtimeCatchupTimeoutId: ReturnType<typeof setTimeout> | null = null;
+  private realtimeReconnectSyncTimeoutId: ReturnType<typeof setTimeout> | null =
+    null;
   private dataChangeDebounceTimeoutId: ReturnType<typeof setTimeout> | null =
     null;
   private pendingDataChangeScopes = new Set<string>();
@@ -1704,6 +1731,10 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
       clearTimeout(this.realtimeCatchupTimeoutId);
       this.realtimeCatchupTimeoutId = null;
     }
+    if (this.realtimeReconnectSyncTimeoutId) {
+      clearTimeout(this.realtimeReconnectSyncTimeoutId);
+      this.realtimeReconnectSyncTimeoutId = null;
+    }
   }
 
   /**
@@ -1980,7 +2011,7 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
       // Schedule retry if under max retries
       const maxRetries = this.config.maxRetries ?? DEFAULT_MAX_RETRIES;
       if (error.retryable && this.state.retryCount < maxRetries) {
-        this.scheduleRetry();
+        this.scheduleRetry(error);
       }
       this.flushReconnectBatchedDataChangesIfReady();
 
@@ -2338,12 +2369,22 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
     }
   }
 
-  private scheduleRetry(): void {
+  private shouldUseRecoveryRetryDelay(error?: SyncError): boolean {
+    if (!error || error.code !== 'NETWORK_ERROR') return false;
+    if (this.state.pendingCount > 0) return false;
+    if (this.state.lastSyncAt === null) return false;
+    return Date.now() - this.state.lastSyncAt <= RECOVERY_RETRY_WINDOW_MS;
+  }
+
+  private scheduleRetry(error?: SyncError): void {
     if (this.retryTimeoutId) {
       clearTimeout(this.retryTimeoutId);
     }
 
-    const delay = calculateRetryDelay(this.state.retryCount);
+    const attemptIndex = Math.max(0, this.state.retryCount - 1);
+    const delay = this.shouldUseRecoveryRetryDelay(error)
+      ? calculateRecoveryRetryDelay(attemptIndex)
+      : calculateRetryDelay(attemptIndex);
     if (this.state.pendingCount > 0) {
       countSyncMetric('sync.outbox.retry_count', 1, {
         attributes: {
@@ -2524,9 +2565,14 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
               fallbackReason: null,
             });
             this.stopFallbackPolling();
-            this.triggerSyncInBackground(undefined, 'realtime connected state');
             if (wasConnectedBefore) {
+              this.scheduleRealtimeReconnectSync();
               this.scheduleRealtimeReconnectCatchupSync();
+            } else {
+              this.triggerSyncInBackground(
+                undefined,
+                'realtime connected state'
+              );
             }
             break;
           }
@@ -2555,6 +2601,10 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
       clearTimeout(this.realtimeCatchupTimeoutId);
       this.realtimeCatchupTimeoutId = null;
     }
+    if (this.realtimeReconnectSyncTimeoutId) {
+      clearTimeout(this.realtimeReconnectSyncTimeoutId);
+      this.realtimeReconnectSyncTimeoutId = null;
+    }
     if (this.realtimePresenceUnsub) {
       this.realtimePresenceUnsub();
       this.realtimePresenceUnsub = null;
@@ -2575,6 +2625,11 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
       clearTimeout(this.realtimeCatchupTimeoutId);
     }
 
+    const jitterMs = calculateDeterministicClientJitter(
+      this.config.clientId ?? '',
+      REALTIME_RECONNECT_SYNC_JITTER_MS
+    );
+
     this.realtimeCatchupTimeoutId = setTimeout(() => {
       this.realtimeCatchupTimeoutId = null;
 
@@ -2582,7 +2637,27 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
       if (this.state.connectionState !== 'connected') return;
 
       this.triggerSyncInBackground(undefined, 'realtime reconnect catchup');
-    }, REALTIME_RECONNECT_CATCHUP_DELAY_MS);
+    }, REALTIME_RECONNECT_CATCHUP_DELAY_MS + jitterMs);
+  }
+
+  private scheduleRealtimeReconnectSync(): void {
+    if (this.realtimeReconnectSyncTimeoutId) {
+      clearTimeout(this.realtimeReconnectSyncTimeoutId);
+    }
+
+    const jitterMs = calculateDeterministicClientJitter(
+      this.config.clientId ?? '',
+      REALTIME_RECONNECT_SYNC_JITTER_MS
+    );
+
+    this.realtimeReconnectSyncTimeoutId = setTimeout(() => {
+      this.realtimeReconnectSyncTimeoutId = null;
+
+      if (this.isDestroyed || !this.isEnabled()) return;
+      if (this.state.connectionState !== 'connected') return;
+
+      this.triggerSyncInBackground(undefined, 'realtime connected state');
+    }, jitterMs);
   }
 
   private startFallbackPolling(): void {

package/src/pull-engine.test.ts

@@ -133,7 +133,7 @@ describe('applyPullResponse chunk streaming', () => {
                   id: 'chunk-1',
                   byteLength: compressed.length,
                   sha256: '',
-                  encoding: 'json-row-frame-v1',
+                  encoding: 'json-row-batch-frame-v2',
                   compression: 'gzip',
                 },
               ],
@@ -258,14 +258,14 @@ describe('applyPullResponse chunk streaming', () => {
                   id: 'chunk-1',
                   byteLength: firstChunk.length,
                   sha256: '',
-                  encoding: 'json-row-frame-v1',
+                  encoding: 'json-row-batch-frame-v2',
                   compression: 'gzip',
                 },
                 {
                   id: 'chunk-2',
                   byteLength: secondChunk.length,
                   sha256: '',
-                  encoding: 'json-row-frame-v1',
+                  encoding: 'json-row-batch-frame-v2',
                   compression: 'gzip',
                 },
               ],
@@ -374,14 +374,14 @@ describe('applyPullResponse chunk streaming', () => {
                   id: 'chunk-1',
                   byteLength: firstChunk.length,
                   sha256: '',
-                  encoding: 'json-row-frame-v1',
+                  encoding: 'json-row-batch-frame-v2',
                   compression: 'gzip',
                 },
                 {
                   id: 'chunk-2',
                   byteLength: secondChunk.length,
                   sha256: '',
-                  encoding: 'json-row-frame-v1',
+                  encoding: 'json-row-batch-frame-v2',
                   compression: 'gzip',
                 },
               ],
@@ -497,7 +497,7 @@ describe('applyPullResponse chunk streaming', () => {
                   id: 'chunk-1',
                   byteLength: chunk.length,
                   sha256: 'deadbeef',
-                  encoding: 'json-row-frame-v1',
+                  encoding: 'json-row-batch-frame-v2',
                   compression: 'gzip',
                 },
               ],
@@ -592,7 +592,7 @@ describe('applyPullResponse chunk streaming', () => {
                   id: 'chunk-1',
                   byteLength: chunk.length,
                   sha256: 'expected-hash',
-                  encoding: 'json-row-frame-v1',
+                  encoding: 'json-row-batch-frame-v2',
                   compression: 'gzip',
                 },
               ],
@@ -700,14 +700,14 @@ describe('applyPullResponse chunk streaming', () => {
                   id: 'chunk-1',
                   byteLength: firstChunk.length,
                   sha256: 'hash-1',
-                  encoding: 'json-row-frame-v1',
+                  encoding: 'json-row-batch-frame-v2',
                   compression: 'gzip',
                 },
                 {
                   id: 'chunk-2',
                   byteLength: secondChunk.length,
                   sha256: 'hash-2',
-                  encoding: 'json-row-frame-v1',
+                  encoding: 'json-row-batch-frame-v2',
                   compression: 'gzip',
                 },
               ],
@@ -804,7 +804,7 @@ describe('applyPullResponse chunk streaming', () => {
                   id: 'chunk-1',
                   byteLength: chunk.length,
                   sha256: '',
-                  encoding: 'json-row-frame-v1',
+                  encoding: 'json-row-batch-frame-v2',
                   compression: 'gzip',
                 },
               ],