@abloatai/ablo 0.34.0 → 0.35.0

package/dist/transaction/transport/connectionManager.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Owns the sync engine's connection lifecycle: the state machine that carries a
+ * client from a healthy connection, through a dropout, and back to live. It
+ * watches the browser's online/offline and visibility events, probes real
+ * connectivity and session validity with {@link probeNetwork}, applies retry
+ * backoff with a ceiling and jitter, and runs a watchdog for the cases where
+ * the browser never fires an event (VPN flips, captive portals). When it
+ * decides to recover, it drives the reconnect sequence — bootstrap, then
+ * WebSocket connect — through the {@link ConnectionCallbacks.onReconnect}
+ * callback and reacts to the outcome.
+ *
+ * It deliberately does not perform the bootstrap, local-storage, or object-pool
+ * work itself; that lives in the embedding store, which the manager reaches
+ * only through its callbacks. One manager is created per store, started on the
+ * first successful connect and disposed on teardown.
+ *
+ * This is a plain state machine, not a reactive object: it lives in the
+ * settlement core, which carries no reactivity runtime (ADR 0016). A consumer
+ * that wants to render recovery progress mirrors the transitions through
+ * {@link ConnectionCallbacks.onStateChange} into its own observable state —
+ * which is what the reactive engine's store does.
+ *
+ *   CONNECTED ──(socket drop)──► PROBING_NETWORK ──► RECONNECTING ──► CONNECTED
+ *        │                              │                  │
+ *   (network lost)                      ▼                  ▼
+ *        ▼                        SESSION_EXPIRED       BACKOFF ──► PROBING_NETWORK
+ *     OFFLINE ──(online)──► PROBING_NETWORK
+ *        │
+ *        ▼
+ *   WAITING_FOR_NETWORK
+ *
+ * Three behaviors are worth calling out. A network return or tab focus during a
+ * backoff delay jumps straight to probing instead of waiting out the full
+ * interval. Reaching the retry ceiling while the browser reports offline parks
+ * in `waiting_for_network` rather than hard-reloading a browser that has no
+ * network. And a socket drop (close code 1006) goes straight to probing rather
+ * than the passive `offline` state — 1006 is generated locally and carries no
+ * connectivity signal, so on a healthy machine no online/offline event ever
+ * fires; only a genuine operating-system network loss parks in `offline` to
+ * wait for the `online` event.
+ */
+import { type ProbeResult } from './networkProbe.js';
+import type { AuthTokenGetter } from '../auth/credentialSource.js';
+import type { CredentialRefreshOutcome } from './credentialLifecycle.js';
+import { type Logger } from '../logger.js';
+import { type TransportObservability } from '../observability.js';
+export type ConnectionState = 'connected' | 'offline' | 'probing_network' | 'validating_session' | 'refreshing_credential' | 'reconnecting' | 'backoff' | 'waiting_for_network' | 'auth_blocked' | '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_AUTH_BLOCKED';
+}
+/** The probe saw an expired ephemeral access key (`access_credential_expiry`).
+ *  Recoverable: re-mint a fresh `ek_`/`rk_` and re-probe — never a sign-out. */
+ | {
+    type: 'PROBE_CREDENTIAL_STALE';
+} | {
+    type: 'PROBE_FAILED';
+}
+/** A fresh access credential is available (the re-mint succeeded, or one was
+ *  pushed in via `setAuthToken`). Re-probe so a parked connection picks it up. */
+ | {
+    type: 'CREDENTIAL_REFRESHED';
+} | {
+    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'>;
+    /**
+     * Re-mints the short-lived access credential (the `ek_`/`rk_`) and pushes it
+     * into the credential source, then reports the outcome. Invoked in the
+     * `refreshing_credential` state — that is, when a probe found the access key
+     * stale (`PROBE_CREDENTIAL_STALE`). The three outcomes map onto recovery:
+     *   - `'refreshed'`     → a fresh credential is in place; re-probe and reconnect.
+     *   - `'session_error'` → the long-lived login itself is gone (the mint
+     *                          returned null, a 401/403); terminal, so sign out.
+     *   - `'network_error'` → the mint endpoint was unreachable (offline, 5xx, or
+     *                          a throw); transient, so back off and retry rather
+     *                          than sign out.
+     * Optional: a deployment with no re-mint path (for example a static `apiKey`)
+     * omits it, and the state machine falls back to a plain re-probe.
+     */
+    onRefreshCredential?: () => Promise<CredentialRefreshOutcome>;
+    /** 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;
+    /**
+     * Fires on every state transition. It lets the embedding store mirror
+     * recovery progress into its visible `syncStatus`, so the UI can show
+     * "Reconnecting…" instead of a sticky "offline" while the machine cycles
+     * through `probing_network` → `reconnecting` → `backoff`. Optional; when
+     * omitted, the state machine is simply 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;
+    /**
+     * Current bearer credential for authenticated probes. Read lazily so token
+     * refreshes pushed through `Ablo.setAuthToken()` are used by the next probe
+     * without recreating the manager.
+     */
+    getAuthToken?: AuthTokenGetter;
+    /** Override retry ceilings / jitter. Production should leave defaults. */
+    backoff?: Partial<typeof DEFAULT_BACKOFF>;
+    /** Where transitions are logged. Defaults to silent. */
+    logger?: Logger;
+    /** Where dead-end states are reported. Defaults to silent. */
+    observability?: TransportObservability;
+}
+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;
+    /** Consecutive access-key re-mints in the current recovery cycle; reset on
+     *  reaching `connected`. See {@link MAX_CREDENTIAL_REFRESH_ATTEMPTS}. */
+    private credentialRefreshAttempts;
+    private disposed;
+    private readonly baseUrl?;
+    private readonly getAuthToken?;
+    private readonly backoff;
+    private readonly logger;
+    private readonly observability;
+    private handleBrowserOnline;
+    private handleBrowserOffline;
+    private handleVisibilityChange;
+    constructor(options?: ConnectionManagerOptions);
+    start(callbacks: ConnectionCallbacks): void;
+    dispose(): void;
+    send(event: ConnectionEvent): void;
+    private transition;
+    private onEnterState;
+    /**
+     * FSM effects are fire-and-forget by design (`onEnterState` is sync). Each
+     * effect catches its own operational failures and maps them onto an FSM
+     * event, so a rejection here means the machine wedged mid-transition
+     * (`send()` or a transition listener threw) with no retry timer armed past
+     * it — capture it instead of losing the reconnect loop silently.
+     */
+    private captureEffectFailure;
+    private runProbe;
+    /**
+     * Re-mint the short-lived access key on `refreshing_credential`. Delegates to
+     * the `onRefreshCredential` callback (which mints a fresh `ek_`/`rk_` from the
+     * still-valid login and pushes it into the credential source) and maps its
+     * tri-state outcome onto the FSM:
+     *   - `refreshed`     → `CREDENTIAL_REFRESHED` → re-probe & reconnect.
+     *   - `session_error` → `BOOTSTRAP_FAILED_SESSION` → sign out (login is gone).
+     *   - `network_error` → `RECONNECT_FAILED` → back off & retry (never sign out).
+     *
+     * A bounded attempt counter guards against a hot loop where the server keeps
+     * reporting the key stale even after a "successful" re-mint (e.g. a clock skew
+     * or a mint that returns an already-rejected key): after
+     * `MAX_CREDENTIAL_REFRESH_ATTEMPTS` we fall through to `auth_blocked` (stop,
+     * no sign-out) rather than spin. The counter resets once we reach `connected`.
+     *
+     * When no refresher is wired (e.g. a static `apiKey` deployment), we re-probe
+     * directly — the credential source's own scheduler owns refresh there.
+     */
+    private runRefreshCredential;
+    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 {};