@syncular/client 0.0.6-221 → 0.0.6-224

package/src/client.ts

@@ -147,7 +147,17 @@ export interface ClientState {
   /** Last successful sync timestamp */
   lastSyncAt: number | null;
   /** Current error if any */
-  error: { code: string; message: string } | null;
+  error: {
+    code: string;
+    message: string;
+    stage?: string;
+    retryable?: boolean;
+    httpStatus?: number;
+    subscriptionId?: string;
+    chunkId?: string;
+    table?: string;
+    stateId?: string;
+  } | null;
   /** Outbox statistics */
   outbox: OutboxStats;
 }
@@ -198,7 +208,17 @@ type ClientEventPayloads = {
   'sync:complete': SyncResult;
   'sync:trace': SyncTraceEvent;
   'sync:live': { timestamp: number };
-  'sync:error': { code: string; message: string };
+  'sync:error': {
+    code: string;
+    message: string;
+    stage?: string;
+    retryable?: boolean;
+    httpStatus?: number;
+    subscriptionId?: string;
+    chunkId?: string;
+    table?: string;
+    stateId?: string;
+  };
   'push:result': PushResultInfo;
   'bootstrap:start': {
     timestamp: number;
@@ -498,7 +518,17 @@ export class Client<DB extends SyncClientDb = SyncClientDb> {
       connectionState: engineState.connectionState,
       lastSyncAt: engineState.lastSyncAt,
       error: engineState.error
-        ? { code: engineState.error.code, message: engineState.error.message }
+        ? {
+            code: engineState.error.code,
+            message: engineState.error.message,
+            stage: engineState.error.stage,
+            retryable: engineState.error.retryable,
+            httpStatus: engineState.error.httpStatus,
+            subscriptionId: engineState.error.subscriptionId,
+            chunkId: engineState.error.chunkId,
+            table: engineState.error.table,
+            stateId: engineState.error.stateId,
+          }
         : null,
       outbox: this.outboxStats,
     };
@@ -972,7 +1002,17 @@ export class Client<DB extends SyncClientDb = SyncClientDb> {
     });
 
     this.engine.on('sync:error', (error) => {
-      this.emit('sync:error', { code: error.code, message: error.message });
+      this.emit('sync:error', {
+        code: error.code,
+        message: error.message,
+        stage: error.stage,
+        retryable: error.retryable,
+        httpStatus: error.httpStatus,
+        subscriptionId: error.subscriptionId,
+        chunkId: error.chunkId,
+        table: error.table,
+        stateId: error.stateId,
+      });
     });
 
     this.engine.on('push:result', (payload) => {

package/src/engine/SyncEngine.test.ts

@@ -745,11 +745,185 @@ describe('SyncEngine WS inline apply', () => {
 
     const state = engine.getState();
     expect(state.error?.code).toBe('SNAPSHOT_CHUNK_NOT_FOUND');
+    expect(state.error?.stage).toBe('pull');
     expect(state.error?.retryable).toBe(false);
     expect(state.retryCount).toBe(1);
     expect(state.isRetrying).toBe(false);
   });
 
+  it('classifies gzip decode failures with chunk 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 {
+          pull: {
+            ok: true,
+            subscriptions: [
+              {
+                id: 'sub-1',
+                status: 'active',
+                scopes: {},
+                bootstrap: true,
+                bootstrapState: null,
+                nextCursor: 1,
+                commits: [],
+                snapshots: [
+                  {
+                    table: 'tasks',
+                    rows: [],
+                    chunks: [
+                      {
+                        id: 'chunk-1',
+                        byteLength: invalidCompressed.length,
+                        sha256: '',
+                        encoding: 'json-row-frame-v1',
+                        compression: 'gzip',
+                      },
+                    ],
+                    isFirstPage: true,
+                    isLastPage: true,
+                  },
+                ],
+              },
+            ],
+          },
+        };
+      },
+      async fetchSnapshotChunk() {
+        return invalidCompressed;
+      },
+    };
+
+    const handlers: ClientHandlerCollection<TestDb> = [
+      {
+        table: 'tasks',
+        async applySnapshot() {},
+        async clearAll() {},
+        async applyChange() {},
+      },
+    ];
+
+    const engine = new SyncEngine<TestDb>({
+      db,
+      transport,
+      handlers,
+      actorId: 'u1',
+      clientId: 'client-gzip-failure',
+      subscriptions: [
+        {
+          id: 'sub-1',
+          table: 'tasks',
+          scopes: {},
+        },
+      ],
+      stateId: 'default',
+      pollIntervalMs: 60_000,
+      maxRetries: 1,
+    });
+
+    await engine.start();
+    engine.stop();
+
+    const state = engine.getState();
+    expect(state.error?.code).toBe('SNAPSHOT_GZIP_DECODE_FAILED');
+    expect(state.error?.stage).toBe('snapshot-gzip-decode');
+    expect(state.error?.subscriptionId).toBe('sub-1');
+    expect(state.error?.chunkId).toBe('chunk-1');
+    expect(state.error?.table).toBe('tasks');
+    expect(state.error?.retryable).toBe(false);
+  });
+
+  it('classifies snapshot apply failures with stage metadata', async () => {
+    const rows = [{ id: 't2', title: 'new', server_version: 1 }];
+    const encoded = encodeSnapshotRows(rows);
+    const compressed = new Uint8Array(gzipSync(encoded));
+    const transport: SyncTransport = {
+      async sync() {
+        return {
+          pull: {
+            ok: true,
+            subscriptions: [
+              {
+                id: 'sub-1',
+                status: 'active',
+                scopes: {},
+                bootstrap: true,
+                bootstrapState: null,
+                nextCursor: 1,
+                commits: [],
+                snapshots: [
+                  {
+                    table: 'tasks',
+                    rows: [],
+                    chunks: [
+                      {
+                        id: 'chunk-1',
+                        byteLength: compressed.length,
+                        sha256: '',
+                        encoding: 'json-row-frame-v1',
+                        compression: 'gzip',
+                      },
+                    ],
+                    isFirstPage: true,
+                    isLastPage: true,
+                  },
+                ],
+              },
+            ],
+          },
+        };
+      },
+      async fetchSnapshotChunk() {
+        return compressed;
+      },
+    };
+
+    const handlers: ClientHandlerCollection<TestDb> = [
+      {
+        table: 'tasks',
+        async applySnapshot() {
+          throw new Error('forced snapshot apply failure');
+        },
+        async clearAll() {},
+        async applyChange() {},
+      },
+    ];
+
+    const engine = new SyncEngine<TestDb>({
+      db,
+      transport,
+      handlers,
+      actorId: 'u1',
+      clientId: 'client-apply-failure',
+      subscriptions: [
+        {
+          id: 'sub-1',
+          table: 'tasks',
+          scopes: {},
+        },
+      ],
+      stateId: 'default',
+      pollIntervalMs: 60_000,
+      maxRetries: 1,
+    });
+
+    await engine.start();
+    engine.stop();
+
+    const state = engine.getState();
+    expect(state.error?.code).toBe('SNAPSHOT_APPLY_FAILED');
+    expect(state.error?.stage).toBe('snapshot-apply');
+    expect(state.error?.subscriptionId).toBe('sub-1');
+    expect(state.error?.table).toBe('tasks');
+    expect(state.error?.retryable).toBe(false);
+  });
+
   it('skips outbox and conflict refresh after a read-only successful sync', async () => {
     const handlers: ClientHandlerCollection<TestDb> = [
       {

package/src/engine/SyncEngine.ts

@@ -18,6 +18,7 @@ import {
   startSyncSpan,
 } from '@syncular/core';
 import { type Kysely, sql, type Transaction } from 'kysely';
+import { type SyncClientFailureStage, SyncClientStageError } from '../errors';
 import { getClientHandler } from '../handlers/collection';
 import { ensureClientSyncSchema } from '../migrate';
 import { withDefaultClientPlugins } from '../plugins';
@@ -132,7 +133,10 @@ function createSyncError(args: {
   cause?: Error;
   retryable?: boolean;
   httpStatus?: number;
+  stage?: SyncError['stage'];
   subscriptionId?: string;
+  chunkId?: string;
+  table?: string;
   stateId?: string;
 }): SyncError {
   return {
@@ -142,7 +146,10 @@ function createSyncError(args: {
     timestamp: Date.now(),
     retryable: args.retryable ?? false,
     httpStatus: args.httpStatus,
+    stage: args.stage,
     subscriptionId: args.subscriptionId,
+    chunkId: args.chunkId,
+    table: args.table,
     stateId: args.stateId,
   };
 }
@@ -153,56 +160,150 @@ function classifySyncFailure(error: unknown): {
   cause: Error;
   retryable: boolean;
   httpStatus?: number;
+  stage?: SyncError['stage'];
+  subscriptionId?: string;
+  chunkId?: string;
+  table?: string;
+  stateId?: string;
 } {
   const cause = error instanceof Error ? error : new Error(String(error));
   const message = cause.message || 'Sync failed';
   const normalized = message.toLowerCase();
 
-  if (cause instanceof SyncTransportError) {
-    if (cause.status === 401 || cause.status === 403) {
+  const classifyTransportFailure = (
+    transportError: SyncTransportError,
+    stage?: SyncClientFailureStage
+  ) => {
+    if (transportError.status === 401 || transportError.status === 403) {
       return {
-        code: 'AUTH_FAILED',
+        code: 'AUTH_FAILED' as const,
         message,
         cause,
         retryable: false,
-        httpStatus: cause.status,
+        httpStatus: transportError.status,
+        stage,
       };
     }
 
     if (
-      cause.status === 404 &&
+      transportError.status === 404 &&
       normalized.includes('snapshot') &&
       normalized.includes('chunk')
     ) {
       return {
-        code: 'SNAPSHOT_CHUNK_NOT_FOUND',
+        code: 'SNAPSHOT_CHUNK_NOT_FOUND' as const,
         message,
         cause,
         retryable: false,
-        httpStatus: cause.status,
+        httpStatus: transportError.status,
+        stage,
       };
     }
 
     if (
-      cause.status !== undefined &&
-      (cause.status >= 500 || cause.status === 408 || cause.status === 429)
+      transportError.status !== undefined &&
+      (transportError.status >= 500 ||
+        transportError.status === 408 ||
+        transportError.status === 429)
     ) {
       return {
-        code: 'NETWORK_ERROR',
+        code: 'NETWORK_ERROR' as const,
         message,
         cause,
         retryable: true,
-        httpStatus: cause.status,
+        httpStatus: transportError.status,
+        stage,
       };
     }
 
     return {
-      code: 'SYNC_ERROR',
+      code: 'SYNC_ERROR' as const,
       message,
       cause,
       retryable: false,
-      httpStatus: cause.status,
+      httpStatus: transportError.status,
+      stage,
+    };
+  };
+
+  if (cause instanceof SyncClientStageError) {
+    const stageContext = {
+      stage: cause.stage,
+      subscriptionId: cause.subscriptionId,
+      chunkId: cause.chunkId,
+      table: cause.table,
+      stateId: cause.stateId,
     };
+    const stageCause = cause.cause instanceof Error ? cause.cause : cause;
+
+    if (stageCause instanceof SyncTransportError) {
+      return {
+        ...classifyTransportFailure(stageCause, cause.stage),
+        ...stageContext,
+      };
+    }
+
+    if (
+      normalized.includes('network') ||
+      normalized.includes('fetch') ||
+      normalized.includes('timeout') ||
+      normalized.includes('offline')
+    ) {
+      return {
+        code: 'NETWORK_ERROR',
+        message,
+        cause,
+        retryable: true,
+        ...stageContext,
+      };
+    }
+
+    switch (cause.stage) {
+      case 'snapshot-gzip-decode':
+        return {
+          code: 'SNAPSHOT_GZIP_DECODE_FAILED',
+          message,
+          cause,
+          retryable: false,
+          ...stageContext,
+        };
+      case 'snapshot-chunk-decode':
+        return {
+          code: 'SNAPSHOT_CHUNK_DECODE_FAILED',
+          message,
+          cause,
+          retryable: false,
+          ...stageContext,
+        };
+      case 'snapshot-integrity':
+        return {
+          code: 'SNAPSHOT_INTEGRITY_FAILED',
+          message,
+          cause,
+          retryable: false,
+          ...stageContext,
+        };
+      case 'snapshot-apply':
+        return {
+          code: 'SNAPSHOT_APPLY_FAILED',
+          message,
+          cause,
+          retryable: false,
+          ...stageContext,
+        };
+      default:
+        return {
+          code: 'SYNC_ERROR',
+          message,
+          cause,
+          retryable: false,
+          ...stageContext,
+        };
+    }
+  }
+
+  if (cause instanceof SyncTransportError) {
+    return classifyTransportFailure(cause, 'pull');
   }
 
   if (
@@ -926,8 +1027,11 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
       }
 
       if (this.state.error) {
+        const detailSuffix = this.state.error.stage
+          ? ` [stage=${this.state.error.stage}]`
+          : '';
         throw new Error(
-          `[SyncEngine.awaitBootstrapComplete] Failed while waiting for bootstrap completion: ${this.state.error.message}`
+          `[SyncEngine.awaitBootstrapComplete] Failed while waiting for bootstrap completion${detailSuffix}: ${this.state.error.message}`
         );
       }
 
@@ -937,9 +1041,25 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
           options.subscriptionId === undefined
             ? `state "${stateId}"`
             : `subscription "${options.subscriptionId}" in state "${stateId}"`;
+        const bootstrap = await this.getBootstrapStatus({
+          stateId,
+          subscriptionIds:
+            options.subscriptionId === undefined
+              ? undefined
+              : [options.subscriptionId],
+          maxPhase: options.maxPhase,
+        }).catch(() => null);
+        const pendingSummary =
+          bootstrap && bootstrap.pendingSubscriptionIds.length > 0
+            ? ` Pending subscriptions: ${bootstrap.pendingSubscriptionIds.join(', ')}.`
+            : '';
+        const phaseSummary =
+          bootstrap && bootstrap.activePhase !== null
+            ? ` Active phase: ${bootstrap.activePhase}.`
+            : '';
 
         throw new Error(
-          `[SyncEngine.awaitBootstrapComplete] Timed out after ${timeoutMs}ms waiting for ${target}`
+          `[SyncEngine.awaitBootstrapComplete] Timed out after ${timeoutMs}ms waiting for ${target}. Bootstrap is still in progress.${phaseSummary}${pendingSummary}`
         );
       }
 
@@ -2166,7 +2286,11 @@ export class SyncEngine<DB extends SyncClientDb = SyncClientDb> {
         cause: classified.cause,
         retryable: classified.retryable,
         httpStatus: classified.httpStatus,
-        stateId: this.getStateId(),
+        stage: classified.stage,
+        subscriptionId: classified.subscriptionId,
+        chunkId: classified.chunkId,
+        table: classified.table,
+        stateId: classified.stateId ?? this.getStateId(),
       });
 
       this.updateState({

package/src/engine/types.ts

@@ -13,6 +13,7 @@ import type {
   SyncTransport,
 } from '@syncular/core';
 import type { Kysely } from 'kysely';
+import type { SyncClientFailureStage } from '../errors';
 import type { ClientHandlerCollection } from '../handlers/collection';
 import type { SyncClientPlugin } from '../plugins/types';
 import type { SyncClientDb } from '../schema';
@@ -214,6 +215,10 @@ export interface SyncError {
     | 'NETWORK_ERROR'
     | 'AUTH_FAILED'
     | 'SNAPSHOT_CHUNK_NOT_FOUND'
+    | 'SNAPSHOT_GZIP_DECODE_FAILED'
+    | 'SNAPSHOT_CHUNK_DECODE_FAILED'
+    | 'SNAPSHOT_INTEGRITY_FAILED'
+    | 'SNAPSHOT_APPLY_FAILED'
     | 'MIGRATION_FAILED'
     | 'CONFLICT'
     | 'SYNC_ERROR'
@@ -228,8 +233,14 @@ export interface SyncError {
   retryable: boolean;
   /** HTTP status code when available */
   httpStatus?: number;
+  /** Sync stage where the error originated */
+  stage?: SyncClientFailureStage;
   /** Related subscription id when available */
   subscriptionId?: string;
+  /** Related snapshot chunk id when available */
+  chunkId?: string;
+  /** Related table when available */
+  table?: string;
   /** Related state id when available */
   stateId?: string;
 }

package/src/errors.ts

@@ -0,0 +1,59 @@
+export type SyncClientFailureStage =
+  | 'pull'
+  | 'snapshot-chunk-fetch'
+  | 'snapshot-gzip-decode'
+  | 'snapshot-chunk-decode'
+  | 'snapshot-integrity'
+  | 'snapshot-apply'
+  | 'bootstrap-timeout';
+
+export interface SyncClientFailureContext {
+  stage: SyncClientFailureStage;
+  stateId?: string;
+  subscriptionId?: string;
+  table?: string;
+  chunkId?: string;
+}
+
+function normalizeError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+export class SyncClientStageError extends Error {
+  readonly stage: SyncClientFailureStage;
+  readonly stateId?: string;
+  readonly subscriptionId?: string;
+  readonly table?: string;
+  readonly chunkId?: string;
+
+  constructor(
+    message: string,
+    context: SyncClientFailureContext,
+    cause?: unknown
+  ) {
+    const normalizedCause =
+      cause === undefined ? undefined : normalizeError(cause);
+    super(message);
+    this.name = 'SyncClientStageError';
+    this.stage = context.stage;
+    this.stateId = context.stateId;
+    this.subscriptionId = context.subscriptionId;
+    this.table = context.table;
+    this.chunkId = context.chunkId;
+    if (normalizedCause) {
+      this.cause = normalizedCause;
+    }
+  }
+}
+
+export function wrapSyncClientStageError(
+  error: unknown,
+  context: SyncClientFailureContext,
+  message?: string
+): SyncClientStageError {
+  if (error instanceof SyncClientStageError) {
+    return error;
+  }
+  const cause = normalizeError(error);
+  return new SyncClientStageError(message ?? cause.message, context, cause);
+}

package/src/index.ts

@@ -8,6 +8,7 @@ export * from './conflicts';
 export * from './create-client';
 export * from './engine';
 export type * from './engine/types';
+export * from './errors';
 export * from './handlers/collection';
 export * from './handlers/create-handler';
 export * from './handlers/types';