@abloatai/ablo 0.34.1 → 0.36.0

package/dist/sync/ConnectionManager.d.ts

@@ -1,200 +1,8 @@
 /**
- * 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.
- *
- *   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.
+ * Moved to the settlement core with the duplex transport (ADR 0016): the
+ * connection state machine is plain, mobx-free plumbing an agent needs as much
+ * as a browser does. This path re-exports it so existing importers stay
+ * unchanged; the reactive store mirrors its transitions through
+ * `ConnectionCallbacks.onStateChange` into its own observable `syncStatus`.
  */
-import { type ProbeResult } from './NetworkProbe.js';
-import type { AuthTokenGetter } from '../auth/credentialSource.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<'refreshed' | '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;
-    /**
-     * 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>;
-}
-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 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 {};
+export { ConnectionManager, type ConnectionState, type ConnectionEvent, type ConnectionCallbacks, type ConnectionManagerOptions, } from '../transaction/transport/connectionManager.js';