@abloatai/ablo 0.3.0

package/dist/sync/BootstrapHelper.js

@@ -0,0 +1,434 @@
+/**
+ * BootstrapHelper - Fixed to always fetch fresh data
+ * Removed problematic caching that was serving stale data
+ */
+import { getContext } from '../context.js';
+import { SyncSessionError, AbloConnectionError, translateHttpError } from '../errors.js';
+// SyncObservability replaced by getContext().observability
+import { parseBootstrapResponse } from './schemas.js';
+export class BootstrapHelper {
+    options;
+    abortController = null;
+    get baseUrl() {
+        return this.options.baseUrl;
+    }
+    constructor(options) {
+        // Defaults are spread first; the explicit `baseUrl` then takes precedence
+        // and is computed from `options.baseUrl` (or the localhost fallback).
+        //
+        // Historical note: a previous version of this constructor placed
+        // `baseUrl: \`${baseUrl}/api\`` BEFORE the `...options` spread, which
+        // meant the spread silently overwrote it back to the caller's value
+        // and the `/api` suffix was dead code. Both Ablo and `createSyncEngine`
+        // already pass `${url}/api` explicitly, so removing the suffix here
+        // preserves the actual on-the-wire behavior while making the contract
+        // explicit: callers pass the full base URL including `/api`.
+        this.options = {
+            syncGroups: [],
+            maxRetries: 3,
+            retryDelay: 1000,
+            fetchTimeout: 10_000, // 10 second timeout per request - fail fast for good UX
+            ...options,
+            baseUrl: options.baseUrl || 'http://localhost:8080/api',
+            cacheScope: options.cacheScope ?? options.organizationId ?? null,
+        };
+        // Do not clear cache here; keep offline fallback available
+    }
+    /**
+     * Update the offline-cache namespace once auth has resolved the server-side
+     * account scope. This is intentionally not a public organizationId input.
+     */
+    setCacheScope(cacheScope) {
+        if (cacheScope.trim().length === 0)
+            return;
+        this.options.cacheScope = cacheScope;
+    }
+    setSyncGroups(syncGroups) {
+        this.options.syncGroups = [...(syncGroups ?? [])];
+    }
+    setAuthToken(authToken) {
+        if (!authToken) {
+            delete this.options.authToken;
+            return;
+        }
+        this.options.authToken = authToken;
+    }
+    /**
+     * Create a promise that rejects after a timeout
+     * Used to race against fetch requests that may hang indefinitely
+     */
+    createTimeoutPromise(ms, operation) {
+        return new Promise((_, reject) => {
+            setTimeout(() => {
+                reject(new Error(`Bootstrap ${operation} timed out after ${ms}ms`));
+            }, ms);
+        });
+    }
+    /**
+     * Wrap a promise with a timeout - if the promise doesn't resolve within
+     * the timeout period, the AbortController is triggered and an error is thrown
+     */
+    async withTimeout(promise, timeoutMs, operation) {
+        return Promise.race([promise, this.createTimeoutPromise(timeoutMs, operation)]);
+    }
+    /**
+     * Fetch bootstrap data from sync engine with partial bootstrap support
+     * @param lastSyncId - Optional: client's current lastSyncId for partial bootstrap
+     * @returns Bootstrap data (either full snapshot or delta batch)
+     */
+    async fetchBootstrap(lastSyncId) {
+        // organizationId omitted — server reads it from auth identity.
+        // See `fetchBootstrapWithETag` for the full rationale.
+        const params = new URLSearchParams();
+        // Add lastSyncId for partial bootstrap support
+        if (lastSyncId !== undefined && lastSyncId > 0) {
+            params.append('lastSyncId', lastSyncId.toString());
+        }
+        // Add sync groups
+        this.options.syncGroups.forEach((group) => {
+            params.append('syncGroups', group);
+        });
+        // Selective bootstrap: only request instant-strategy models.
+        // When present, the server skips all other models → smaller payload.
+        // When absent, server returns all models (backward compat).
+        if (this.options.instantModels && this.options.instantModels.length > 0) {
+            params.append('models', this.options.instantModels.join(','));
+        }
+        const url = `${this.options.baseUrl}/sync/bootstrap?${params.toString()}`;
+        // If offline, try cached bootstrap
+        if (typeof navigator !== 'undefined' && navigator && navigator.onLine === false) {
+            const cached = this.options.cacheScope
+                ? this.loadCachedBootstrap(this.options.cacheScope)
+                : null;
+            if (cached) {
+                getContext().logger.info('Using cached bootstrap (offline)');
+                return cached;
+            }
+            throw new AbloConnectionError('Offline and no cached bootstrap available', {
+                code: 'bootstrap_offline_no_cache',
+            });
+        }
+        getContext().logger.info('Fetching fresh bootstrap data', { url });
+        // Fetch with retries
+        let lastError = null;
+        for (let attempt = 0; attempt < this.options.maxRetries; attempt++) {
+            try {
+                const data = await this.performFetch(url);
+                getContext().logger.info('Bootstrap data fetched', {
+                    type: data.type,
+                    lastSyncId: data.lastSyncId,
+                    modelCount: data.models ? Object.keys(data.models).length : 0,
+                    deltaCount: data.deltaCount || 0,
+                    totalItems: data.models
+                        ? Object.values(data.models).reduce((sum, arr) => sum + (Array.isArray(arr) ? arr.length : 0), 0)
+                        : 0,
+                });
+                // Persist for offline fallback
+                if (this.options.cacheScope) {
+                    this.saveCachedBootstrap(this.options.cacheScope, data);
+                }
+                return data;
+            }
+            catch (error) {
+                // SessionError should NOT be retried - the session is invalid and needs re-authentication
+                // Also do NOT fallback to cache - the user must sign in again
+                if (SyncSessionError.isSessionError(error)) {
+                    getContext().observability.breadcrumb('Bootstrap session error - redirecting to sign-in', 'sync.bootstrap', 'warning', {
+                        statusCode: error.statusCode,
+                    });
+                    throw error;
+                }
+                lastError = error;
+                getContext().observability.breadcrumb('Bootstrap fetch failed', 'sync.bootstrap', 'warning', {
+                    attempt: attempt + 1,
+                });
+                if (attempt < this.options.maxRetries - 1) {
+                    await this.delay(this.options.retryDelay * Math.pow(2, attempt));
+                }
+            }
+        }
+        // On error, attempt cached fallback (but NOT for session errors - already handled above)
+        const cached = this.options.cacheScope
+            ? this.loadCachedBootstrap(this.options.cacheScope)
+            : null;
+        if (cached) {
+            getContext().observability.breadcrumb('Bootstrap cache fallback', 'sync.bootstrap', 'warning', {
+                error: lastError?.message,
+            });
+            return cached;
+        }
+        throw lastError || new Error('Failed to fetch bootstrap data');
+    }
+    /**
+     * Fetch bootstrap with ETag, returning 304 hints
+     */
+    async fetchBootstrapWithETag() {
+        // organizationId is intentionally NOT sent. Server resolves it from
+        // the authenticated identity (`c.var.identity.organizationId`) —
+        // see `apps/sync-server/src/routes/bootstrap.ts`. Sending it
+        // client-side was historical: it predated the auth-context pipeline
+        // and forced a cross-org guard to defend against the SDK lying.
+        const params = new URLSearchParams();
+        this.options.syncGroups.forEach((g) => params.append('syncGroups', g));
+        if (this.options.instantModels && this.options.instantModels.length > 0) {
+            params.append('models', this.options.instantModels.join(','));
+        }
+        const url = `${this.options.baseUrl}/sync/bootstrap?${params.toString()}`;
+        // Note: ETag caching is deliberately app-side, not SDK-side. The server
+        // still returns an ETag on responses, which is captured below and
+        // forwarded to callers via BootstrapFetchResult.etag — apps that want
+        // conditional revalidation (If-None-Match) implement it at their own
+        // level where they own the cache-key namespace. The 304 branch below
+        // remains defensively in place for when a caller enables revalidation.
+        const headers = { 'Content-Type': 'application/json' };
+        if (this.options.authToken) {
+            headers.Authorization = `Bearer ${this.options.authToken}`;
+        }
+        this.abortController = new AbortController();
+        const res = await fetch(url, {
+            method: 'GET',
+            headers,
+            credentials: 'include',
+            signal: this.abortController.signal,
+        });
+        const etag = res.headers.get('ETag');
+        if (res.status === 304) {
+            // Log for telemetry
+            getContext().logger.info('[Bootstrap] 304 Not Modified - using cached data');
+            return { notModified: true, etag };
+        }
+        if (!res.ok) {
+            // Check for session/auth errors - these should redirect to login
+            if (SyncSessionError.isSessionErrorResponse(res.status)) {
+                let body = '';
+                try {
+                    body = await res.text();
+                }
+                catch {
+                    // Ignore body parsing errors
+                }
+                throw new SyncSessionError(body || `Session expired or invalid: ${res.status}`, res.status);
+            }
+            const bodyText = await res.text().catch(() => '');
+            let parsed = bodyText;
+            if (bodyText) {
+                try {
+                    parsed = JSON.parse(bodyText);
+                }
+                catch {
+                    // Keep as string.
+                }
+            }
+            throw translateHttpError(res.status, parsed || `Bootstrap fetch failed: ${res.status} ${res.statusText}`, res.headers.get('x-request-id') ?? undefined);
+        }
+        const rawJson = await res.json();
+        const data = parseBootstrapResponse(rawJson);
+        // Persist payload for offline
+        try {
+            if (this.options.cacheScope) {
+                this.saveCachedBootstrap(this.options.cacheScope, data);
+            }
+        }
+        catch { }
+        getContext().logger.info('[Bootstrap] 200 OK - received new data');
+        return { notModified: false, data, etag };
+    }
+    /**
+     * Perform the actual fetch request with timeout protection
+     */
+    async performFetch(url) {
+        // Cancel any previous in-flight request
+        if (this.abortController) {
+            this.abortController.abort();
+        }
+        this.abortController = new AbortController();
+        const timeoutId = setTimeout(() => {
+            getContext().observability.breadcrumb('Bootstrap fetch timeout', 'sync.bootstrap', 'warning', {
+                timeoutMs: this.options.fetchTimeout,
+            });
+            this.abortController?.abort();
+        }, this.options.fetchTimeout);
+        let response;
+        try {
+            response = await fetch(url, {
+                method: 'GET',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Cache-Control': 'no-cache, no-store, must-revalidate',
+                    Pragma: 'no-cache',
+                    ...(this.options.authToken
+                        ? { Authorization: `Bearer ${this.options.authToken}` }
+                        : {}),
+                },
+                credentials: 'include',
+                signal: this.abortController.signal,
+                cache: 'no-store', // Force browser to not cache
+            });
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            // Convert abort to timeout error for better error messaging
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new AbloConnectionError(`Bootstrap fetch timed out after ${this.options.fetchTimeout}ms`, { code: 'bootstrap_fetch_timeout', cause: error });
+            }
+            throw error;
+        }
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+            // Check for session/auth errors - these should redirect to login
+            if (SyncSessionError.isSessionErrorResponse(response.status)) {
+                let body = '';
+                try {
+                    body = await response.text();
+                }
+                catch {
+                    // Ignore body parsing errors
+                }
+                throw new SyncSessionError(body || `Session expired or invalid: ${response.status}`, response.status);
+            }
+            const bodyText = await response.text().catch(() => '');
+            let parsed = bodyText;
+            if (bodyText) {
+                try {
+                    parsed = JSON.parse(bodyText);
+                }
+                catch {
+                    // Keep as string.
+                }
+            }
+            throw translateHttpError(response.status, parsed || `Bootstrap fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
+        }
+        const rawJson = await response.json();
+        const data = parseBootstrapResponse(rawJson);
+        // Save a copy for offline
+        try {
+            if (this.options.cacheScope) {
+                this.saveCachedBootstrap(this.options.cacheScope, data);
+            }
+        }
+        catch { }
+        return data;
+    }
+    /**
+     * Fetch a single entity by ID (on-demand self-healing).
+     * Returns `null` for 404 (entity deleted) — this is an expected state, not an error.
+     * Throws for unexpected HTTP errors (5xx, network failures).
+     */
+    async fetchEntity(modelName, id) {
+        const url = `${this.options.baseUrl}/sync/entity/${modelName}/${id}`;
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            credentials: 'include',
+        });
+        if (response.status === 404) {
+            return null;
+        }
+        if (!response.ok) {
+            const bodyText = await response.text().catch(() => '');
+            let parsed = bodyText;
+            if (bodyText) {
+                try {
+                    parsed = JSON.parse(bodyText);
+                }
+                catch {
+                    // Keep as string.
+                }
+            }
+            throw translateHttpError(response.status, parsed || `Entity fetch failed: ${response.status} ${response.statusText}`, response.headers.get('x-request-id') ?? undefined);
+        }
+        return await response.json();
+    }
+    // ─────────────────────────────────────────────────────────────────────
+    /**
+     * Clear all cached bootstrap data
+     */
+    clearCache() {
+        if (typeof window === 'undefined')
+            return;
+        try {
+            // Clear all bootstrap cache keys
+            const keysToRemove = [];
+            for (let i = 0; i < localStorage.length; i++) {
+                const key = localStorage.key(i);
+                if (key && key.includes('sync-bootstrap')) {
+                    keysToRemove.push(key);
+                }
+            }
+            keysToRemove.forEach((key) => {
+                localStorage.removeItem(key);
+                getContext().logger.debug('Cleared cache key', { key });
+            });
+        }
+        catch (error) {
+            getContext().logger.warn('Failed to clear cache', { error });
+        }
+    }
+    // Cache helpers for offline bootstrap
+    getBootstrapCacheKey(orgId) {
+        return `ablo:bootstrap:${orgId}`;
+    }
+    saveCachedBootstrap(orgId, data) {
+        if (typeof window === 'undefined')
+            return;
+        try {
+            localStorage.setItem(this.getBootstrapCacheKey(orgId), JSON.stringify(data));
+        }
+        catch (e) {
+            getContext().logger.warn('Failed to cache bootstrap payload', {
+                error: e instanceof Error ? e.message : String(e),
+            });
+        }
+    }
+    loadCachedBootstrap(orgId) {
+        if (typeof window === 'undefined')
+            return null;
+        try {
+            const raw = localStorage.getItem(this.getBootstrapCacheKey(orgId));
+            if (!raw)
+                return null;
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Abort ongoing fetch request
+     */
+    abort() {
+        if (this.abortController) {
+            this.abortController.abort();
+            this.abortController = null;
+        }
+    }
+    /**
+     * Helper to delay execution
+     */
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Get health status of sync engine
+     */
+    async checkHealth() {
+        try {
+            const response = await fetch(`${this.options.baseUrl}/health`, {
+                method: 'GET',
+                credentials: 'include',
+                signal: AbortSignal.timeout(5000),
+                cache: 'no-store',
+            });
+            if (!response.ok)
+                return false;
+            const data = await response.json();
+            return data.status === 'healthy';
+        }
+        catch (error) {
+            getContext().observability.breadcrumb('Health check failed', 'sync.bootstrap', 'warning');
+            return false;
+        }
+    }
+}

package/dist/sync/ConnectionManager.d.ts

@@ -0,0 +1,136 @@
+/**
+ * ConnectionManager — single source of truth for the sync engine's
+ * connection lifecycle. Absorbs the FSM every SDK consumer used to
+ * rebuild by hand (apps/web's `ConnectionStore` was the reference
+ * implementation — 605 LOC of FSM + watchdog + backoff).
+ *
+ * What it owns:
+ *  - Browser online/offline + visibility events
+ *  - Network probe orchestration (via `probeNetwork`)
+ *  - Session-validity checks (HEAD /api/auth/check)
+ *  - Retry backoff with ceiling, jitter, and offline-aware parking
+ *  - Watchdog for browser events that never fire (VPN, captive portal)
+ *  - The reconnect → bootstrap → WebSocket connect sequence
+ *
+ * What it DOES NOT own:
+ *  - The actual bootstrap / IndexedDB / ObjectPool work — that lives in
+ *    `BaseSyncedStore.performReconnect()`. This class calls it via the
+ *    `onReconnect` callback and reacts to the outcome.
+ *
+ * Designed to be embedded by `BaseSyncedStore`: one instance per store,
+ * started on first successful connect, disposed on teardown.
+ *
+ *   CONNECTED ──► OFFLINE ──► PROBING_NETWORK ──► RECONNECTING ──► CONNECTED
+ *                    │              │                    │
+ *                    ▼              ▼                    ▼
+ *             WAITING_FOR_NETWORK  SESSION_EXPIRED    BACKOFF ──► PROBING_NETWORK
+ *
+ * Includes two fixes over the original app-side FSM:
+ *   1. `backoff` accepts `NETWORK_ONLINE` / `TAB_VISIBLE` — jumps to
+ *      probing immediately when the network comes back, without
+ *      waiting for the backoff timer to elapse.
+ *   2. `scheduleBackoff` parks in `waiting_for_network` (resetting
+ *      `attempt`) when `navigator.onLine === false` at max retries,
+ *      instead of hard-reloading an already-offline browser.
+ */
+import { type ProbeResult } from './NetworkProbe.js';
+export type ConnectionState = 'connected' | 'offline' | 'probing_network' | 'validating_session' | 'reconnecting' | 'backoff' | 'waiting_for_network' | 'session_expired';
+export type ConnectionEvent = {
+    type: 'NETWORK_LOST';
+} | {
+    type: 'NETWORK_ONLINE';
+} | {
+    type: 'TAB_VISIBLE';
+} | {
+    type: 'WS_CONNECTED';
+} | {
+    type: 'WS_DISCONNECTED';
+} | {
+    type: 'WS_SESSION_ERROR';
+} | {
+    type: 'WS_HANDSHAKE_FAILED';
+} | {
+    type: 'PROBE_SUCCESS';
+    sessionValid: boolean;
+} | {
+    type: 'PROBE_FAILED';
+} | {
+    type: 'RECONNECT_SUCCESS';
+} | {
+    type: 'RECONNECT_FAILED';
+} | {
+    type: 'BACKOFF_ELAPSED';
+} | {
+    type: 'BOOTSTRAP_FAILED_SESSION';
+} | {
+    type: 'MANUAL_RETRY';
+};
+export interface ConnectionCallbacks {
+    /** Run bootstrap + WebSocket reconnect. Returns the outcome. */
+    onReconnect: () => Promise<'success' | 'session_error' | 'network_error'>;
+    /** Called when the session is confirmed expired — route to signin. */
+    onSessionExpired: () => void;
+    /** Called to tear down the WebSocket when entering a dead state. */
+    onDisconnectWebSocket: () => void;
+    /**
+     * Fired on every FSM state transition. Lets the embedding store
+     * mirror recovery progress into its visible `syncStatus` so the UI
+     * can show "Reconnecting…" instead of a sticky "offline" while the
+     * FSM cycles through `probing_network` → `reconnecting` → `backoff`.
+     * Optional — omitting it preserves the previous behavior where the
+     * FSM was opaque to the UI.
+     */
+    onStateChange?: (next: ConnectionState, prev: ConnectionState) => void;
+}
+export interface ConnectionManagerOptions {
+    /**
+     * Sync-server base URL used for probes. Falls back to the env-based
+     * default of `probeNetwork`.
+     */
+    baseUrl?: string;
+    /** Override retry ceilings / jitter. Production should leave defaults. */
+    backoff?: Partial<typeof DEFAULT_BACKOFF>;
+}
+declare const DEFAULT_BACKOFF: {
+    readonly BASE_MS: 2000;
+    readonly MAX_MS: 30000;
+    readonly MAX_ATTEMPTS: 8;
+    readonly JITTER: 0.15;
+};
+export declare class ConnectionManager {
+    state: ConnectionState;
+    offlineSince: Date | null;
+    attempt: number;
+    lastProbeResult: ProbeResult | null;
+    private callbacks;
+    private backoffTimer;
+    private debounceTimer;
+    private watchdogTimer;
+    private stuckCycles;
+    private disposed;
+    private readonly baseUrl?;
+    private readonly backoff;
+    private handleBrowserOnline;
+    private handleBrowserOffline;
+    private handleVisibilityChange;
+    constructor(options?: ConnectionManagerOptions);
+    start(callbacks: ConnectionCallbacks): void;
+    dispose(): void;
+    send(event: ConnectionEvent): void;
+    private transition;
+    private onEnterState;
+    private runProbe;
+    private runReconnect;
+    private scheduleBackoff;
+    private setupBrowserListeners;
+    private removeBrowserListeners;
+    private startWatchdog;
+    get isConnected(): boolean;
+    get isOffline(): boolean;
+    get isReconnecting(): boolean;
+    get isSessionExpired(): boolean;
+    get offlineDuration(): string | null;
+    private clearBackoffTimer;
+    private clearDebounceTimer;
+}
+export {};