@syncular/client 0.0.6-219 → 0.0.6-223

package/dist/engine/SyncEngine.js

@@ -6,6 +6,7 @@
  */
 import { captureSyncException, countSyncMetric, distributionSyncMetric, isRecord, SyncTransportError, startSyncSpan, } from '@syncular/core';
 import { sql } from 'kysely';
+import { SyncClientStageError } from '../errors.js';
 import { getClientHandler } from '../handlers/collection.js';
 import { ensureClientSyncSchema } from '../migrate.js';
 import { withDefaultClientPlugins } from '../plugins/index.js';
@@ -55,7 +56,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,
     };
 }
@@ -63,17 +67,18 @@ function classifySyncFailure(error) {
     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, stage) => {
+        if (transportError.status === 401 || transportError.status === 403) {
             return {
                 code: 'AUTH_FAILED',
                 message,
                 cause,
                 retryable: false,
-                httpStatus: cause.status,
+                httpStatus: transportError.status,
+                stage,
             };
         }
-        if (cause.status === 404 &&
+        if (transportError.status === 404 &&
             normalized.includes('snapshot') &&
             normalized.includes('chunk')) {
             return {
@@ -81,17 +86,21 @@ function classifySyncFailure(error) {
                 message,
                 cause,
                 retryable: false,
-                httpStatus: cause.status,
+                httpStatus: transportError.status,
+                stage,
             };
         }
-        if (cause.status !== undefined &&
-            (cause.status >= 500 || cause.status === 408 || cause.status === 429)) {
+        if (transportError.status !== undefined &&
+            (transportError.status >= 500 ||
+                transportError.status === 408 ||
+                transportError.status === 429)) {
             return {
                 code: 'NETWORK_ERROR',
                 message,
                 cause,
                 retryable: true,
-                httpStatus: cause.status,
+                httpStatus: transportError.status,
+                stage,
             };
         }
         return {
@@ -99,8 +108,82 @@ function classifySyncFailure(error) {
             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 (normalized.includes('network') ||
         normalized.includes('fetch') ||
@@ -159,6 +242,11 @@ function serializeInspectorRecord(value) {
 function defaultSelectorEquality(left, right) {
     return Object.is(left, right);
 }
+function normalizeBootstrapPhase(value) {
+    if (value === undefined)
+        return 0;
+    return Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;
+}
 function areMetadataRecordsEqual(left, right) {
     if (left === right)
         return true;
@@ -536,31 +624,77 @@ export class SyncEngine {
                 completedAt: progress?.completedAt,
                 lastErrorCode: progress?.lastErrorCode,
                 lastErrorMessage: progress?.lastErrorMessage,
+                bootstrapPhase: normalizeBootstrapPhase(configuredSub?.bootstrapPhase),
             };
         });
         const expectedSubscriptions = subscriptions.filter((sub) => sub.expected);
-        const readySubscriptionIds = expectedSubscriptions
+        const activePhase = expectedSubscriptions
+            .filter((sub) => !sub.ready)
+            .reduce((lowest, sub) => lowest === null || sub.bootstrapPhase < lowest
+            ? sub.bootstrapPhase
+            : lowest, null) ?? null;
+        const selectedMaxPhase = options.maxPhase ??
+            (explicitIdSet.size > 0
+                ? 'all'
+                : expectedSubscriptions.length > 0
+                    ? expectedSubscriptions.reduce((lowest, sub) => Math.min(lowest, sub.bootstrapPhase), Number.POSITIVE_INFINITY)
+                    : 0);
+        const blockingSubscriptions = expectedSubscriptions.filter((sub) => selectedMaxPhase === 'all' ? true : sub.bootstrapPhase <= selectedMaxPhase);
+        const readySubscriptionIds = blockingSubscriptions
             .filter((sub) => sub.ready)
             .map((sub) => sub.id);
-        const pendingSubscriptionIds = expectedSubscriptions
+        const pendingSubscriptionIds = blockingSubscriptions
             .filter((sub) => !sub.ready)
             .map((sub) => sub.id);
         const channelPhase = this.resolveChannelPhase(filteredStates.map((sub) => this.mapSubscriptionToProgress(sub)));
-        const progressPercent = expectedSubscriptions.length === 0
+        const progressPercent = blockingSubscriptions.length === 0
             ? pendingSubscriptionIds.length === 0
                 ? 100
                 : 0
-            : Math.round(expectedSubscriptions.reduce((sum, sub) => sum + sub.progressPercent, 0) / expectedSubscriptions.length);
+            : Math.round(blockingSubscriptions.reduce((sum, sub) => sum + sub.progressPercent, 0) / blockingSubscriptions.length);
+        const phases = Array.from(expectedSubscriptions.reduce((acc, sub) => {
+            const current = acc.get(sub.bootstrapPhase) ?? {
+                phase: sub.bootstrapPhase,
+                expectedSubscriptionIds: [],
+                readySubscriptionIds: [],
+                pendingSubscriptionIds: [],
+                progressPercent: 0,
+            };
+            current.expectedSubscriptionIds.push(sub.id);
+            if (sub.ready) {
+                current.readySubscriptionIds.push(sub.id);
+            }
+            else {
+                current.pendingSubscriptionIds.push(sub.id);
+            }
+            current.progressPercent += sub.progressPercent;
+            acc.set(sub.bootstrapPhase, current);
+            return acc;
+        }, new Map()))
+            .sort(([left], [right]) => left - right)
+            .map(([, phase]) => ({
+            phase: phase.phase,
+            expectedSubscriptionIds: phase.expectedSubscriptionIds,
+            readySubscriptionIds: phase.readySubscriptionIds,
+            pendingSubscriptionIds: phase.pendingSubscriptionIds,
+            isReady: phase.pendingSubscriptionIds.length === 0,
+            progressPercent: phase.expectedSubscriptionIds.length === 0
+                ? 100
+                : Math.round(phase.progressPercent / phase.expectedSubscriptionIds.length),
+        }));
         return {
             stateId,
             channelPhase,
             progressPercent,
             isBootstrapping: pendingSubscriptionIds.length > 0,
             isReady: pendingSubscriptionIds.length === 0,
-            expectedSubscriptionIds: expectedSubscriptions.map((sub) => sub.id),
+            expectedSubscriptionIds: blockingSubscriptions.map((sub) => sub.id),
             readySubscriptionIds,
             pendingSubscriptionIds,
             subscriptions,
+            activePhase,
+            selectedMaxPhase,
+            phases,
         };
     }
     /**
@@ -593,23 +727,49 @@ export class SyncEngine {
         const stateId = options.stateId ?? this.getStateId();
         const deadline = Date.now() + timeoutMs;
         while (true) {
-            const states = await this.listSubscriptionStates({ stateId });
-            const relevantStates = options.subscriptionId === undefined
-                ? states
-                : states.filter((state) => state.subscriptionId === options.subscriptionId);
-            const hasPendingBootstrap = relevantStates.some((state) => state.status === 'active' && state.bootstrapState !== null);
-            if (!hasPendingBootstrap) {
-                return this.getProgress();
+            if (options.subscriptionId !== undefined) {
+                const state = await this.getSubscriptionState(options.subscriptionId, {
+                    stateId,
+                });
+                const hasPendingBootstrap = state?.status === 'active' && state.bootstrapState !== null;
+                if (!hasPendingBootstrap) {
+                    return this.getProgress();
+                }
+            }
+            else {
+                const bootstrap = await this.getBootstrapStatus({
+                    stateId,
+                    maxPhase: options.maxPhase,
+                });
+                if (bootstrap.isReady) {
+                    return this.getProgress();
+                }
             }
             if (this.state.error) {
-                throw new Error(`[SyncEngine.awaitBootstrapComplete] Failed while waiting for bootstrap completion: ${this.state.error.message}`);
+                const detailSuffix = this.state.error.stage
+                    ? ` [stage=${this.state.error.stage}]`
+                    : '';
+                throw new Error(`[SyncEngine.awaitBootstrapComplete] Failed while waiting for bootstrap completion${detailSuffix}: ${this.state.error.message}`);
             }
             const remainingMs = deadline - Date.now();
             if (remainingMs <= 0) {
                 const target = options.subscriptionId === undefined
                     ? `state "${stateId}"`
                     : `subscription "${options.subscriptionId}" in state "${stateId}"`;
-                throw new Error(`[SyncEngine.awaitBootstrapComplete] Timed out after ${timeoutMs}ms waiting for ${target}`);
+                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}. Bootstrap is still in progress.${phaseSummary}${pendingSummary}`);
             }
             await this.waitForProgressSignal(remainingMs);
         }
@@ -1248,6 +1408,15 @@ export class SyncEngine {
             }
         }
     }
+    shouldTrace() {
+        return (this.config.traceEnabled === true ||
+            (this.listeners.get('sync:trace')?.size ?? 0) > 0);
+    }
+    emitTrace(payload) {
+        if (!this.shouldTrace())
+            return;
+        this.emit('sync:trace', payload);
+    }
     updateState(partial) {
         const nextState = { ...this.state, ...partial };
         const unchanged = this.state.enabled === nextState.enabled &&
@@ -1489,14 +1658,14 @@ export class SyncEngine {
                 clientId: this.config.clientId,
                 actorId: this.config.actorId ?? undefined,
                 plugins: this.config.plugins,
-                subscriptions: this.config
-                    .subscriptions,
+                subscriptions: this.config.subscriptions,
                 limitCommits: this.config.limitCommits,
                 limitSnapshotRows: this.config.limitSnapshotRows,
                 maxSnapshotPages: this.config.maxSnapshotPages,
                 dedupeRows: this.config.dedupeRows,
                 stateId: this.config.stateId,
                 sha256: this.config.sha256,
+                onTrace: (event) => this.emitTrace(event),
                 trigger,
                 allowSkipPullOnLocalWsPush: this.state.transportMode === 'realtime',
             }));
@@ -1578,7 +1747,11 @@ export class SyncEngine {
                 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({
                 isSyncing: false,