@abloatai/ablo 0.3.0

package/dist/sync/ConnectionManager.js

@@ -0,0 +1,465 @@
+/**
+ * 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 { makeAutoObservable, runInAction } from 'mobx';
+import { getContext } from '../context.js';
+import { probeNetwork } from './NetworkProbe.js';
+// ─── Tunables ─────────────────────────────────────────────────────────────
+const DEFAULT_BACKOFF = {
+    BASE_MS: 2_000,
+    MAX_MS: 30_000,
+    MAX_ATTEMPTS: 8,
+    JITTER: 0.15,
+};
+const ONLINE_DEBOUNCE_MS = 500;
+const WATCHDOG_INTERVAL_MS = 30_000;
+const MAX_STUCK_CYCLES_BEFORE_RELOAD = 6;
+// ─── ConnectionManager ────────────────────────────────────────────────────
+export class ConnectionManager {
+    // Observable state
+    state = 'connected';
+    offlineSince = null;
+    attempt = 0;
+    lastProbeResult = null;
+    // Private
+    callbacks = null;
+    backoffTimer = null;
+    debounceTimer = null;
+    watchdogTimer = null;
+    stuckCycles = 0;
+    disposed = false;
+    baseUrl;
+    backoff;
+    handleBrowserOnline = null;
+    handleBrowserOffline = null;
+    handleVisibilityChange = null;
+    constructor(options = {}) {
+        this.baseUrl = options.baseUrl;
+        this.backoff = { ...DEFAULT_BACKOFF, ...(options.backoff ?? {}) };
+        makeAutoObservable(this, {}, { autoBind: true });
+    }
+    // ── Lifecycle ────────────────────────────────────────────────────────
+    start(callbacks) {
+        this.callbacks = callbacks;
+        this.setupBrowserListeners();
+        this.startWatchdog();
+        getContext().logger.info('[ConnectionManager] Started');
+    }
+    dispose() {
+        this.disposed = true;
+        this.clearBackoffTimer();
+        this.clearDebounceTimer();
+        if (this.watchdogTimer) {
+            clearInterval(this.watchdogTimer);
+            this.watchdogTimer = null;
+        }
+        this.removeBrowserListeners();
+        this.callbacks = null;
+        getContext().logger.info('[ConnectionManager] Disposed');
+    }
+    // ── Send events ──────────────────────────────────────────────────────
+    send(event) {
+        if (this.disposed)
+            return;
+        const prevState = this.state;
+        const nextState = this.transition(prevState, event);
+        if (nextState === null)
+            return;
+        getContext().logger.info('[ConnectionManager] Transition', {
+            from: prevState,
+            to: nextState,
+            event: event.type,
+        });
+        runInAction(() => {
+            this.state = nextState;
+            if (prevState === 'connected' && nextState !== 'connected') {
+                this.offlineSince = new Date();
+            }
+            if (nextState === 'connected') {
+                this.offlineSince = null;
+                this.attempt = 0;
+                this.stuckCycles = 0;
+            }
+        });
+        // Notify the embedding store BEFORE running side effects, so the
+        // UI flips to the new label (e.g. "Reconnecting…") at the same
+        // tick the probe / backoff actually starts. Errors in the consumer
+        // must not break the FSM — wrap defensively.
+        try {
+            this.callbacks?.onStateChange?.(nextState, prevState);
+        }
+        catch (err) {
+            getContext().logger.warn('[ConnectionManager] onStateChange threw', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        this.onEnterState(nextState, event);
+    }
+    // ── Pure transition ──────────────────────────────────────────────────
+    transition(state, event) {
+        switch (state) {
+            case 'connected':
+                switch (event.type) {
+                    case 'NETWORK_LOST':
+                    case 'WS_DISCONNECTED':
+                        return 'offline';
+                    case 'WS_SESSION_ERROR':
+                    case 'BOOTSTRAP_FAILED_SESSION':
+                        return 'session_expired';
+                    case 'WS_HANDSHAKE_FAILED':
+                        return 'probing_network';
+                    case 'TAB_VISIBLE':
+                        return 'probing_network';
+                    default:
+                        return null;
+                }
+            case 'offline':
+                switch (event.type) {
+                    case 'NETWORK_ONLINE':
+                    case 'MANUAL_RETRY':
+                    case 'TAB_VISIBLE':
+                    case 'WS_HANDSHAKE_FAILED':
+                        return 'probing_network';
+                    case 'WS_SESSION_ERROR':
+                    case 'BOOTSTRAP_FAILED_SESSION':
+                        return 'session_expired';
+                    default:
+                        return null;
+                }
+            case 'probing_network':
+                switch (event.type) {
+                    case 'PROBE_SUCCESS':
+                        return event.sessionValid ? 'reconnecting' : 'session_expired';
+                    case 'PROBE_FAILED':
+                        return 'waiting_for_network';
+                    case 'NETWORK_LOST':
+                        return 'offline';
+                    default:
+                        return null;
+                }
+            case 'waiting_for_network':
+                switch (event.type) {
+                    case 'NETWORK_ONLINE':
+                    case 'TAB_VISIBLE':
+                    case 'MANUAL_RETRY':
+                    case 'BACKOFF_ELAPSED':
+                        return 'probing_network';
+                    case 'NETWORK_LOST':
+                        return 'offline';
+                    default:
+                        return null;
+                }
+            case 'validating_session':
+                switch (event.type) {
+                    case 'PROBE_SUCCESS':
+                        return event.sessionValid ? 'reconnecting' : 'session_expired';
+                    case 'NETWORK_LOST':
+                        return 'offline';
+                    default:
+                        return null;
+                }
+            case 'reconnecting':
+                switch (event.type) {
+                    case 'RECONNECT_SUCCESS':
+                    case 'WS_CONNECTED':
+                        return 'connected';
+                    case 'RECONNECT_FAILED':
+                    case 'WS_HANDSHAKE_FAILED':
+                        return 'backoff';
+                    case 'BOOTSTRAP_FAILED_SESSION':
+                    case 'WS_SESSION_ERROR':
+                        return 'session_expired';
+                    case 'NETWORK_LOST':
+                        return 'offline';
+                    default:
+                        return null;
+                }
+            case 'backoff':
+                switch (event.type) {
+                    case 'BACKOFF_ELAPSED':
+                    case 'MANUAL_RETRY':
+                    case 'WS_HANDSHAKE_FAILED':
+                        return 'probing_network';
+                    case 'NETWORK_ONLINE':
+                    case 'TAB_VISIBLE':
+                        // Network came back while we were waiting out a backoff
+                        // delay — jump straight to probing instead of waiting the
+                        // full exponential interval. Fixes the "doesn't retrigger
+                        // when internet comes back" bug.
+                        return 'probing_network';
+                    case 'NETWORK_LOST':
+                        return 'offline';
+                    case 'WS_SESSION_ERROR':
+                    case 'BOOTSTRAP_FAILED_SESSION':
+                        return 'session_expired';
+                    default:
+                        return null;
+                }
+            case 'session_expired':
+                return null; // terminal
+            default:
+                return null;
+        }
+    }
+    // ── Side effects per state ───────────────────────────────────────────
+    onEnterState(state, _event) {
+        switch (state) {
+            case 'connected':
+                this.clearBackoffTimer();
+                break;
+            case 'offline':
+                this.clearBackoffTimer();
+                this.callbacks?.onDisconnectWebSocket();
+                break;
+            case 'probing_network':
+                this.runProbe();
+                break;
+            case 'waiting_for_network':
+                this.scheduleBackoff();
+                break;
+            case 'reconnecting':
+                this.runReconnect();
+                break;
+            case 'backoff':
+                this.scheduleBackoff();
+                break;
+            case 'session_expired':
+                this.clearBackoffTimer();
+                this.callbacks?.onDisconnectWebSocket();
+                this.callbacks?.onSessionExpired();
+                getContext().observability.breadcrumb('Session expired — redirecting to signin', 'sync.offline', 'warning');
+                break;
+        }
+    }
+    // ── Async operations ─────────────────────────────────────────────────
+    async runProbe() {
+        try {
+            const result = await probeNetwork(this.baseUrl);
+            runInAction(() => {
+                this.lastProbeResult = result;
+            });
+            if (result.reachable) {
+                this.send({ type: 'PROBE_SUCCESS', sessionValid: result.sessionValid ?? true });
+            }
+            else {
+                this.send({ type: 'PROBE_FAILED' });
+            }
+        }
+        catch {
+            this.send({ type: 'PROBE_FAILED' });
+        }
+    }
+    async runReconnect() {
+        if (!this.callbacks)
+            return;
+        try {
+            const result = await this.callbacks.onReconnect();
+            switch (result) {
+                case 'success':
+                    this.send({ type: 'RECONNECT_SUCCESS' });
+                    break;
+                case 'session_error':
+                    this.send({ type: 'BOOTSTRAP_FAILED_SESSION' });
+                    break;
+                case 'network_error':
+                    this.send({ type: 'RECONNECT_FAILED' });
+                    break;
+            }
+        }
+        catch (error) {
+            getContext().logger.error('[ConnectionManager] Reconnect threw', { error });
+            this.send({ type: 'RECONNECT_FAILED' });
+        }
+    }
+    // ── Backoff ──────────────────────────────────────────────────────────
+    scheduleBackoff() {
+        this.clearBackoffTimer();
+        if (this.attempt >= this.backoff.MAX_ATTEMPTS) {
+            // If still offline, a hard reload will fail or serve cached and
+            // we'll loop. Park in waiting_for_network and let the `online`
+            // event (or watchdog) restart the cycle when the network comes
+            // back.
+            if (typeof navigator !== 'undefined' && navigator.onLine === false) {
+                getContext().logger.warn('[ConnectionManager] Max retries while offline — parking until network restored');
+                getContext().observability.breadcrumb('Max retries — parking offline', 'sync.offline', 'warning');
+                runInAction(() => {
+                    this.attempt = 0;
+                });
+                return;
+            }
+            getContext().logger.warn('[ConnectionManager] Max retries — hard reload');
+            getContext().observability.breadcrumb('Max retries — hard reload', 'sync.offline', 'error');
+            if (typeof window !== 'undefined') {
+                window.location.reload();
+            }
+            return;
+        }
+        const baseDelay = Math.min(this.backoff.BASE_MS * Math.pow(2, this.attempt), this.backoff.MAX_MS);
+        const jitter = baseDelay * this.backoff.JITTER * (2 * Math.random() - 1);
+        const delay = Math.round(baseDelay + jitter);
+        runInAction(() => {
+            this.attempt++;
+        });
+        this.backoffTimer = setTimeout(() => {
+            this.backoffTimer = null;
+            this.send({ type: 'BACKOFF_ELAPSED' });
+        }, delay);
+    }
+    // ── Browser listeners ────────────────────────────────────────────────
+    setupBrowserListeners() {
+        if (typeof window === 'undefined')
+            return;
+        this.handleBrowserOnline = () => {
+            this.clearDebounceTimer();
+            this.debounceTimer = setTimeout(() => {
+                this.send({ type: 'NETWORK_ONLINE' });
+            }, ONLINE_DEBOUNCE_MS);
+        };
+        this.handleBrowserOffline = () => {
+            this.clearDebounceTimer();
+            this.send({ type: 'NETWORK_LOST' });
+        };
+        this.handleVisibilityChange = () => {
+            if (typeof document !== 'undefined' && document.visibilityState === 'visible') {
+                this.send({ type: 'TAB_VISIBLE' });
+            }
+        };
+        window.addEventListener('online', this.handleBrowserOnline);
+        window.addEventListener('offline', this.handleBrowserOffline);
+        if (typeof document !== 'undefined') {
+            document.addEventListener('visibilitychange', this.handleVisibilityChange);
+        }
+    }
+    removeBrowserListeners() {
+        if (typeof window === 'undefined')
+            return;
+        if (this.handleBrowserOnline) {
+            window.removeEventListener('online', this.handleBrowserOnline);
+        }
+        if (this.handleBrowserOffline) {
+            window.removeEventListener('offline', this.handleBrowserOffline);
+        }
+        if (this.handleVisibilityChange && typeof document !== 'undefined') {
+            document.removeEventListener('visibilitychange', this.handleVisibilityChange);
+        }
+    }
+    // ── Watchdog ─────────────────────────────────────────────────────────
+    startWatchdog() {
+        if (typeof window === 'undefined')
+            return;
+        this.watchdogTimer = setInterval(() => {
+            if (this.disposed)
+                return;
+            // "Stuck" = parked in a non-active recovery state (offline,
+            // waiting_for_network, backoff). We deliberately do NOT gate on
+            // `navigator.onLine === true` here: per MDN, `navigator.onLine`
+            // is only reliable when it returns false ("definitely offline"),
+            // and even that lies after laptop wake / VPN flips. Gating the
+            // watchdog on `onLine` was the actual "offline forever" bug —
+            // when the browser briefly reported offline and never re-fired
+            // the `online` event, the FSM had no escape from `'offline'`.
+            // The probe itself fast-fails when truly offline (NetworkProbe.ts),
+            // so an unconditional retry costs nothing in the genuine case.
+            const isStuck = this.state !== 'connected' &&
+                this.state !== 'session_expired' &&
+                this.state !== 'probing_network' &&
+                this.state !== 'reconnecting';
+            if (isStuck) {
+                this.stuckCycles++;
+                // Hard-reload gate: only reload when `navigator.onLine` is true.
+                // `onLine === false` is the one direction we trust (MDN: "false
+                // means definitely offline"), and reloading while truly offline
+                // would either serve cached content forever or fail and leave
+                // the user with a broken page.
+                const browserOnline = typeof navigator === 'undefined' || navigator.onLine === true;
+                if (this.stuckCycles >= MAX_STUCK_CYCLES_BEFORE_RELOAD && browserOnline) {
+                    getContext().logger.warn('[ConnectionManager] Watchdog: sustained stuck — hard reload');
+                    getContext().observability.breadcrumb('Watchdog hard reload', 'sync.offline', 'error');
+                    if (typeof window !== 'undefined') {
+                        window.location.reload();
+                    }
+                    return;
+                }
+                getContext().logger.info('[ConnectionManager] Watchdog: stuck — retry', {
+                    state: this.state,
+                    stuckCycles: this.stuckCycles,
+                    browserOnline,
+                });
+                runInAction(() => {
+                    this.attempt = 0;
+                });
+                this.send({ type: 'MANUAL_RETRY' });
+            }
+            else {
+                this.stuckCycles = 0;
+            }
+        }, WATCHDOG_INTERVAL_MS);
+    }
+    // ── UI-friendly computed ──────────────────────────────────────────────
+    get isConnected() { return this.state === 'connected'; }
+    get isOffline() { return this.state === 'offline' || this.state === 'waiting_for_network'; }
+    get isReconnecting() {
+        return this.state === 'probing_network' || this.state === 'reconnecting' || this.state === 'backoff';
+    }
+    get isSessionExpired() { return this.state === 'session_expired'; }
+    get offlineDuration() {
+        if (!this.offlineSince)
+            return null;
+        const ms = Date.now() - this.offlineSince.getTime();
+        const seconds = Math.floor(ms / 1000);
+        const minutes = Math.floor(seconds / 60);
+        const hours = Math.floor(minutes / 60);
+        if (seconds < 60)
+            return 'Just now';
+        if (minutes < 60)
+            return `${minutes}m ago`;
+        if (hours < 24)
+            return `${hours}h ago`;
+        return `${Math.floor(hours / 24)}d ago`;
+    }
+    // ── Timer helpers ─────────────────────────────────────────────────────
+    clearBackoffTimer() {
+        if (this.backoffTimer) {
+            clearTimeout(this.backoffTimer);
+            this.backoffTimer = null;
+        }
+    }
+    clearDebounceTimer() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+    }
+}

package/dist/sync/HydrationCoordinator.d.ts

@@ -0,0 +1,137 @@
+/**
+ * HydrationCoordinator — the lazy-load lane of the sync engine.
+ *
+ * Bridges "I need this entity but bootstrap didn't fetch it" → pool
+ * hydration. Replaces the per-app loader files (documentLoaders,
+ * slideLayerLoaders, layoutLoaders, ensureVaultFiles, ensureDataroomFiles)
+ * with one engine-level path.
+ *
+ * Lookup order on `fetch(modelName, where)`:
+ *   1. ObjectPool — if rows already match the where, return them (cheap).
+ *   2. IndexedDB — if matching rows exist locally, hydrate pool, return.
+ *   3. Network — `postQuery` against `/sync/query`, hydrate pool + IDB.
+ *
+ * Single-flight dedup: concurrent calls with the same query key share
+ * one in-flight promise. Prevents the loader anti-pattern where N
+ * components mount and fire N identical hydrations on first paint.
+ *
+ * The coordinator does NOT replace bootstrap (full sync of `instant`
+ * models) or live deltas (WS push). It only fills the gap for `lazy`
+ * models accessed by id/where after the engine is ready.
+ */
+import type { ObjectPool } from '../ObjectPool.js';
+import type { Database } from '../Database.js';
+import type { Model } from '../Model.js';
+import type { ModelRegistry } from '../ModelRegistry.js';
+import type { LoadWhere, WhereClause } from '../query/types.js';
+import type { Schema } from '../schema/schema.js';
+export interface HydrationCoordinatorOptions {
+    readonly objectPool: ObjectPool;
+    readonly database: Database;
+    readonly registry: ModelRegistry;
+    readonly schema: Schema;
+    /** Bootstrap base URL (without trailing slash), e.g. `https://api.example.com/api`. */
+    readonly baseUrl: string;
+    /**
+     * Lazy getter for the active capability token. Resolved per-request
+     * so cap refreshes propagate without re-instantiating the coordinator.
+     * Optional: browser consumers ride session cookies and can omit this;
+     * Node consumers (agent-worker) must wire it through or HTTP queries
+     * fail with 401 because cookies aren't available.
+     */
+    readonly getCapabilityToken?: () => string | null;
+}
+export interface FetchOptions<T> {
+    /**
+     * Filter clauses for the lookup. Accepts either the equality-object
+     * form (`{ id: 'abc' }` → `WHERE id = 'abc'`, array values → `IN`)
+     * or the explicit tuple form (`[['name', 'ILIKE', '%Goldman%']]`)
+     * matching the wire `WhereClause[]` 1:1. Multiple entries AND
+     * together. See `LoadWhere` in `../query/types.ts` for the full shape.
+     */
+    readonly where?: LoadWhere<T>;
+    readonly orderBy?: {
+        [K in keyof T]?: 'asc' | 'desc';
+    };
+    readonly limit?: number;
+    /**
+     * `'complete'` (default): wait for network round-trip even if local
+     * data exists, so the caller observes server-confirmed state.
+     * `'unknown'`: return whatever's in the pool/IDB immediately and
+     * fire the network in the background.
+     */
+    readonly type?: 'complete' | 'unknown';
+    /**
+     * Schema-declared relation names to hydrate alongside the primary
+     * rows. Each related entity is hydrated into its own typed pool
+     * via the same path as the primary fetch (network → pool + IDB).
+     */
+    readonly expand?: readonly string[];
+}
+export declare class HydrationCoordinator {
+    private readonly opts;
+    private readonly inFlight;
+    private capabilityTokenProvider;
+    constructor(opts: HydrationCoordinatorOptions);
+    /**
+     * Late-bind the capability token getter. Used by `Ablo.ts` to wire
+     * the token closure after the coordinator is constructed (the token
+     * isn't known until auth resolves, which happens after component
+     * construction). Browser consumers ride session cookies and don't
+     * need this; Node consumers (agent-worker) MUST call it or HTTP
+     * queries fail with 401 because cookies aren't available.
+     */
+    setCapabilityTokenProvider(provider: () => string | null): void;
+    private resolveToken;
+    /**
+     * Fetch matching rows for a model, hydrating the pool from IDB or
+     * network if not already present. Idempotent and single-flight
+     * deduped on the (modelName, where, orderBy, limit) tuple.
+     */
+    fetch<T>(modelName: string, options?: FetchOptions<T>): Promise<Model[]>;
+    private runFetch;
+    private hydrateOne;
+    /**
+     * Stamp `__typename` onto a row when it's known (from the schema's
+     * relation target). Strips the mangled `_Typename` key the
+     * `postgres.camel` driver leaves behind when the server's SQL
+     * bakes `__typename` into a JSONB literal — the driver's
+     * snake↔camel transform misreads `__typename` as `_typename` with
+     * a leading underscore and produces `_Typename`. ObjectPool only
+     * recognises `__typename`, so without this step nested rows fall
+     * through to the 'Unknown' branch and never instantiate.
+     */
+    private stampTypename;
+    private queryNetwork;
+    /**
+     * Hydrate nested expanded rows. Resolves each relation's target
+     * typename via the schema and stamps `__typename` on every nested
+     * row before passing to `hydrateOne` — the server's JSONB
+     * `__typename` field gets mangled by `postgres.camel` (`__typename`
+     * → `_Typename`), so the SDK can't trust whatever string lands.
+     */
+    private hydrateExpanded;
+    private persistToIdb;
+    private resolveTypename;
+}
+/**
+ * Normalize `LoadWhere<T>` input to the canonical `readonly WhereClause[]`
+ * tuple form used throughout `runFetch`. Tuple inputs pass through; object
+ * inputs become one `['col', '=', val]` or `['col', 'IN', vals]` per key.
+ *
+ * Detection: an array whose first element is itself an array is treated
+ * as tuple form. Object form is the fallback.
+ *
+ * Exported so callers can pre-normalize (e.g., for tests, or to inspect
+ * the canonical clauses before passing them to `load`/`subscribe`).
+ */
+export declare function normalizeWhere(where: unknown): readonly WhereClause[];
+/**
+ * Operator-aware predicate. Mirrors the server's WhereOp semantics for
+ * local matching against pool/IDB rows. LIKE/ILIKE use SQL wildcards
+ * (`%` = any chars, `_` = one char) translated to a JS regex.
+ *
+ * Exported so callers can apply the same predicate to in-memory
+ * collections (tests, batch operations) using the canonical clauses.
+ */
+export declare function matchesClauses(entity: Record<string, unknown>, clauses: readonly WhereClause[]): boolean;