@abloatai/ablo 0.36.0 → 0.37.0

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

@@ -1,84 +0,0 @@
-/**
- * Detects real network and session connectivity for the sync engine. It exists
- * because `navigator.onLine` is unreliable: it reports true whenever the device
- * has a local network connection, even with no route to the internet, and after
- * sleep/wake it can report true before Wi-Fi or DNS are working again.
- *
- * The probe makes one authenticated request to the sync server's
- * `/api/auth/check` endpoint — which runs the same auth middleware as the
- * WebSocket upgrade — and classifies the response into a single
- * {@link ProbeOutcome} through the recovery taxonomy ({@link classifyRecovery}):
- *   204 No Content                         → `reachable`        (credential valid)
- *   401 `apikey_expired` (ephemeral key)   → `credential_stale` (re-mint and retry, no sign-out)
- *   401 `session_expired` / bare 401       → `session_expired`  (sign out)
- *   401/403 credential-type/config/perm    → `auth_blocked`     (stop; no loop, no sign-out)
- *   network failure / offline              → `unreachable`
- *
- * This closes a real gap. The browser's WebSocket API hides the HTTP status of
- * a failed handshake, so a 401 on the upgrade surfaces only as close code 1006.
- * Without this HTTP probe, the client cannot tell an auth failure from a network
- * blip, and loops reconnecting forever instead of sending the user to sign in.
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine
- */
-import { z } from 'zod';
-import { type AuthTokenGetter } from '../auth/credentialSource.js';
-import { type Logger } from '../logger.js';
-/**
- * The complete set of probe outcomes. Each value carries both reachability and
- * credential state, so the connection state machine can branch on one exhaustive
- * discriminant instead of piecing the situation together from several booleans.
- * It mirrors the `RecoveryClass` taxonomy at the connectivity layer.
- */
-export declare const PROBE_OUTCOMES: readonly ["reachable", "unreachable", "session_expired", "credential_stale", "auth_blocked"];
-/** Zod enum derived from {@link PROBE_OUTCOMES}. */
-export declare const probeOutcomeSchema: z.ZodEnum<{
-    auth_blocked: "auth_blocked";
-    session_expired: "session_expired";
-    reachable: "reachable";
-    unreachable: "unreachable";
-    credential_stale: "credential_stale";
-}>;
-/** A single probe outcome. See {@link PROBE_OUTCOMES}. */
-export type ProbeOutcome = z.infer<typeof probeOutcomeSchema>;
-/** Result of a network probe: a single {@link ProbeOutcome} plus round-trip
- *  latency (null when the probe never completed). */
-export declare const probeResultSchema: z.ZodObject<{
-    outcome: z.ZodEnum<{
-        auth_blocked: "auth_blocked";
-        session_expired: "session_expired";
-        reachable: "reachable";
-        unreachable: "unreachable";
-        credential_stale: "credential_stale";
-    }>;
-    latencyMs: z.ZodNullable<z.ZodNumber>;
-}, z.core.$strip>;
-/** @see {@link probeResultSchema} */
-export type ProbeResult = z.infer<typeof probeResultSchema>;
-export interface NetworkProbeOptions {
-    /**
-     * Sync-server base URL (HTTP or WS scheme accepted). If omitted, the probe
-     * targets the canonical hosted endpoint ({@link ABLO_DEFAULT_BASE_URL}) —
-     * the same default `Ablo()` resolves.
-     */
-    baseUrl?: string;
-    /**
-     * Optional bearer credential. Browser cookie deployments can omit this;
-     * bearer-first deployments must pass the same `ek_`/`rk_` token used by
-     * bootstrap and the WebSocket upgrade.
-     */
-    getAuthToken?: AuthTokenGetter;
-    /** Compatibility fallback for callers with a copied token string. */
-    authToken?: string | null;
-    /** Where probe outcomes are logged. Defaults to silent. */
-    logger?: Logger;
-}
-/**
- * Probes the sync server with a lightweight HEAD request, returning both
- * reachability and session status in a single call so the connection state
- * machine can pick the right transition without guessing.
- *
- * @param input The sync-server base URL (an HTTP or WS scheme is accepted), or
- *              an options bag. A bare string is also accepted.
- */
-export declare function probeNetwork(input?: string | NetworkProbeOptions): Promise<ProbeResult>;

package/dist/transaction/transport/networkProbe.js

@@ -1,207 +0,0 @@
-/**
- * Detects real network and session connectivity for the sync engine. It exists
- * because `navigator.onLine` is unreliable: it reports true whenever the device
- * has a local network connection, even with no route to the internet, and after
- * sleep/wake it can report true before Wi-Fi or DNS are working again.
- *
- * The probe makes one authenticated request to the sync server's
- * `/api/auth/check` endpoint — which runs the same auth middleware as the
- * WebSocket upgrade — and classifies the response into a single
- * {@link ProbeOutcome} through the recovery taxonomy ({@link classifyRecovery}):
- *   204 No Content                         → `reachable`        (credential valid)
- *   401 `apikey_expired` (ephemeral key)   → `credential_stale` (re-mint and retry, no sign-out)
- *   401 `session_expired` / bare 401       → `session_expired`  (sign out)
- *   401/403 credential-type/config/perm    → `auth_blocked`     (stop; no loop, no sign-out)
- *   network failure / offline              → `unreachable`
- *
- * This closes a real gap. The browser's WebSocket API hides the HTTP status of
- * a failed handshake, so a 401 on the upgrade surfaces only as close code 1006.
- * Without this HTTP probe, the client cannot tell an auth failure from a network
- * blip, and loops reconnecting forever instead of sending the user to sign in.
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine
- */
-import { z } from 'zod';
-import { classifyRecovery } from '../errors.js';
-import { withAuthHeaders } from '../auth/credentialSource.js';
-import { ABLO_DEFAULT_BASE_URL } from '../auth/hostedEndpoints.js';
-import { noopLogger } from '../logger.js';
-/**
- * The complete set of probe outcomes. Each value carries both reachability and
- * credential state, so the connection state machine can branch on one exhaustive
- * discriminant instead of piecing the situation together from several booleans.
- * It mirrors the `RecoveryClass` taxonomy at the connectivity layer.
- */
-export const PROBE_OUTCOMES = [
-    /** Server reachable and the access credential is currently valid. */
-    'reachable',
-    /** Could not reach the server (offline, DNS, TLS, or timeout). */
-    'unreachable',
-    /** Reachable, but the long-lived login is gone. Terminal: sign out. */
-    'session_expired',
-    /** Reachable, but the ephemeral access key (`ek_`/`rk_`) expired. Silently
-     *  re-mint a fresh key from the still-valid login and retry; not a sign-out. */
-    'credential_stale',
-    /** Reachable, but the credential's type or configuration was rejected (wrong
-     *  key kind, untrusted issuer, no organization, or a 403). Stop: neither
-     *  reconnecting nor re-authenticating helps. Distinct from a sign-out. */
-    'auth_blocked',
-];
-/** Zod enum derived from {@link PROBE_OUTCOMES}. */
-export const probeOutcomeSchema = z.enum(PROBE_OUTCOMES);
-/** Result of a network probe: a single {@link ProbeOutcome} plus round-trip
- *  latency (null when the probe never completed). */
-export const probeResultSchema = z.object({
-    outcome: probeOutcomeSchema,
-    latencyMs: z.number().nullable(),
-});
-const PROBE_TIMEOUT_MS = 4000;
-/**
- * Derive the probe URL from a sync-server base URL. Accepts `ws://`,
- * `wss://`, `http://`, `https://`, or a bare host — mirrors the
- * normalisation in `BootstrapFetcher` / `createSyncEngine`.
- */
-function resolveProbeUrl(baseUrl) {
-    // No explicit baseUrl → probe the canonical hosted endpoint, matching the
-    // `Ablo()` default.
-    const resolved = baseUrl ?? ABLO_DEFAULT_BASE_URL;
-    // Normalize ws → http so fetch() accepts the URL. Strip any trailing slash
-    // so we don't produce `//api/auth/check`.
-    const httpBase = resolved.replace(/^ws/, 'http').replace(/\/+$/, '');
-    return `${httpBase}/api/auth/check`;
-}
-/**
- * Probes the sync server with a lightweight HEAD request, returning both
- * reachability and session status in a single call so the connection state
- * machine can pick the right transition without guessing.
- *
- * @param input The sync-server base URL (an HTTP or WS scheme is accepted), or
- *              an options bag. A bare string is also accepted.
- */
-export async function probeNetwork(input) {
-    const baseUrl = typeof input === 'string' ? input : input?.baseUrl;
-    const getAuthToken = typeof input === 'string' ? undefined : input?.getAuthToken;
-    const authToken = typeof input === 'string' ? undefined : input?.authToken;
-    const logger = (typeof input === 'string' ? undefined : input?.logger) ?? noopLogger;
-    const url = resolveProbeUrl(baseUrl);
-    // Fast-fail: if navigator.onLine is false, skip the probe entirely. This is
-    // the one case where navigator.onLine is reliable (MDN: "false means
-    // definitely offline"). Use `=== false` rather than `!onLine` because Node
-    // 22+ exposes `navigator` with `onLine === undefined`, and `!undefined` is
-    // true, which would short-circuit the probe server-side.
-    if (typeof navigator !== 'undefined' && navigator.onLine === false) {
-        return { outcome: 'unreachable', latencyMs: null };
-    }
-    const controller = new AbortController();
-    const timeout = setTimeout(() => { controller.abort(); }, PROBE_TIMEOUT_MS);
-    const start = performance.now();
-    try {
-        const headers = withAuthHeaders(getAuthToken, { 'Cache-Control': 'no-cache' }, authToken);
-        const response = await fetch(url, {
-            method: 'HEAD',
-            signal: controller.signal,
-            // Cache-bust to avoid stale responses
-            headers,
-        });
-        const latencyMs = Math.round(performance.now() - start);
-        // The probe is a HEAD request (no body), but the server sets
-        // `X-Auth-Failure: <code>` on every auth rejection. Route the code through
-        // the recovery taxonomy so each failure mode gets its correct outcome. That
-        // distinction is the whole point: an expired ephemeral key
-        // (`access_credential_expiry`) must re-mint, not sign the user out the way a
-        // genuine login expiry (`session_expiry`) does, and not wedge the way a
-        // credential type or configuration rejection (`auth_blocked`) does.
-        const authFailure = response.headers.get('x-auth-failure');
-        if (authFailure) {
-            const recovery = classifyRecovery(authFailure);
-            switch (recovery) {
-                case 'session_expiry':
-                    logger.info('[NetworkProbe] Server reachable, login expired', {
-                        status: response.status,
-                        code: authFailure,
-                        latencyMs,
-                    });
-                    return { outcome: 'session_expired', latencyMs };
-                case 'access_credential_expiry':
-                    logger.info('[NetworkProbe] Server reachable, access key stale — will re-mint', {
-                        status: response.status,
-                        code: authFailure,
-                        latencyMs,
-                    });
-                    return { outcome: 'credential_stale', latencyMs };
-                case 'auth_blocked':
-                case 'permission':
-                case 'none':
-                    // A non-expiry auth rejection — wrong credential type or config, a
-                    // 403, or an auth-tagged code this SDK does not recognise.
-                    // Re-authenticating re-mints the same rejected credential and
-                    // retrying will not help, so stop rather than reconnect-loop or sign
-                    // the user out.
-                    logger.debug('[NetworkProbe] Reachable but auth-blocked (non-retryable, non-expiry)', {
-                        status: response.status,
-                        code: authFailure,
-                        recovery,
-                        latencyMs,
-                    });
-                    return { outcome: 'auth_blocked', latencyMs };
-                case 'transient':
-                    // Retryable auth-tagged response — connectivity is proven; fall
-                    // through to `reachable` and let the normal retry path handle it.
-                    break;
-                default: {
-                    const _exhaustive = recovery;
-                    void _exhaustive;
-                }
-            }
-        }
-        else if (response.status === 401) {
-            // Bare 401 with no readable structured code. This is ambiguous and must
-            // not sign the user out on its own — two common causes are both
-            // recoverable, and only one is a real logout:
-            //   1. The server did send `X-Auth-Failure: apikey_expired`, but it is a
-            //      custom header on a cross-origin response the server did not list in
-            //      `Access-Control-Expose-Headers`, so the browser stripped it to
-            //      null. The access key just needs a re-mint.
-            //   2. A genuinely expired access key on a non-Ablo proxy or cookie path.
-            // So route to `credential_stale`: the state machine attempts a re-mint,
-            // and the only way to actually sign out is that re-mint resolving `null`
-            // (the login is truly gone). If no refresher is wired, the bounded attempt
-            // counter falls through to `auth_blocked` (stop) — still never a spurious
-            // logout. The invariant holds: null is the only terminal path, never a
-            // bare 401.
-            logger.info('[NetworkProbe] Server reachable, bare 401 — re-mint (not sign-out)', {
-                latencyMs,
-            });
-            return { outcome: 'credential_stale', latencyMs };
-        }
-        // 2xx (including 204) means reachable + credential valid.
-        // 3xx/4xx (non-auth) still prove connectivity even though the probe
-        // expected 204; log a warning so misconfigurations surface instead of
-        // silently passing.
-        if (response.status < 200 || response.status >= 300) {
-            logger.debug('[NetworkProbe] Unexpected probe response', {
-                status: response.status,
-                url,
-                latencyMs,
-            });
-        }
-        else {
-            logger.debug('[NetworkProbe] Server reachable, credential valid', {
-                status: response.status,
-                latencyMs,
-            });
-        }
-        return { outcome: 'reachable', latencyMs };
-    }
-    catch (error) {
-        clearTimeout(timeout);
-        const isAbort = error instanceof DOMException && error.name === 'AbortError';
-        logger.info('[NetworkProbe] Probe failed', {
-            reason: isAbort ? 'timeout' : error.message,
-        });
-        return { outcome: 'unreachable', latencyMs: null };
-    }
-    finally {
-        clearTimeout(timeout);
-    }
-}

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

@@ -1,128 +0,0 @@
-/**
- * Routes each inbound frame from the sync WebSocket to the handler for its
- * type. Handlers work against a minimal {@link WsSession} interface — only
- * the members they actually touch, rather than the transport object itself,
- * which keeps this module free of an import cycle. Reading a message off the
- * socket, parsing its JSON, and tracking heartbeats all happen before this
- * point; every parsed frame then passes through {@link dispatchWsFrame}.
- */
-import { type WsInboundEnvelope } from '../wire/inboundFrames.js';
-import { type CommitAck } from './commitFrames.js';
-import type { Logger } from '../logger.js';
-import type { SocketObservability } from '../observability.js';
-/**
- * In-flight `commit` request record, keyed by clientTxId in the session.
- * Resolved when a matching `mutation_result` frame arrives from the
- * server, or rejected on timeout / disconnect.
- */
-export interface PendingCommit {
-    resolve: (value: CommitAck) => void;
-    reject: (err: Error) => void;
-    timeout: ReturnType<typeof setTimeout>;
-}
-/**
- * In-flight `claim` request record, keyed by claimId. Resolved when the
- * matching `claim_ack` arrives, or rejected on timeout/disconnect.
- */
-export interface PendingClaim {
-    resolve: (value: {
-        syncGroups: string[];
-        ttlSeconds?: number;
-    }) => void;
-    reject: (err: Error) => void;
-    timeout: ReturnType<typeof setTimeout>;
-}
-/**
- * An in-flight `update_subscription` request awaiting its
- * `subscription_ack`. The wire carries no correlation id, so requests are
- * matched to their acknowledgements in first-in, first-out order, the same
- * order the server applies them.
- */
-export interface PendingSubscription {
-    resolve: (value: {
-        syncGroups: string[];
-    }) => void;
-    reject: (err: Error) => void;
-    timeout: ReturnType<typeof setTimeout>;
-}
-/**
- * A parsed inbound wire frame — the envelope only, with its payload still
- * untrusted. Inferred from {@link wsInboundEnvelopeSchema} rather than written
- * out, so the type a handler sees and the check the socket runs are the same
- * statement. The open key set is what carries the oldest delta form, which puts
- * a delta's own fields (`actionType`, `modelName`) at the top level instead of
- * under `payload`.
- */
-export type WsInboundFrame = WsInboundEnvelope;
-/** Narrow arbitrary wire data to a plain string-keyed record. */
-export declare function isRecord(value: unknown): value is Record<string, unknown>;
-/**
- * Read the envelope off an inbound message, or `null` when it is not one —
- * anything that is not an object, or whose `type` is not a string. The payload
- * is not checked here; that belongs to the frame's own schema, applied at
- * dispatch.
- */
-export declare function readWsInboundFrame(value: unknown): WsInboundFrame | null;
-/**
- * The subset of the sync WebSocket that the frame handlers need. The
- * transport builds a single object exposing these members over its own
- * private state. Handlers read the fields live rather than capturing them,
- * so resetting a field elsewhere — such as clearing pending subscriptions
- * on close — never leaves a handler holding a stale value.
- */
-export interface WsSession {
-    /** EventEmitter surface — handlers emit the typed transport events. */
-    emit(event: string, ...args: unknown[]): boolean;
-    /** Where the handlers log. The transport passes its own port. */
-    logger: Logger;
-    /** Where coordination outcomes and lifecycle breadcrumbs are reported. */
-    observability: SocketObservability;
-    /** In-flight commit acks keyed by clientTxId. */
-    pendingMutations: Map<string, PendingCommit>;
-    /** In-flight claim acks keyed by claimId. */
-    pendingClaims: Map<string, PendingClaim>;
-    /** Removes and returns the oldest in-flight `update_subscription` request. */
-    shiftPendingSubscription(): PendingSubscription | undefined;
-    /** Connection options subset the handlers write back (acked sync groups). */
-    options: {
-        syncGroups: string[];
-    };
-    /** Registered collaboration event keys (colon format). */
-    collaborationEventTypes: ReadonlySet<string>;
-    /**
-     * Processes one inbound delta. The argument is untrusted wire data; the
-     * transport validates it against the canonical delta schema and drops
-     * anything malformed, so handlers here never cast.
-     */
-    handleDelta(delta: unknown): void;
-    handleSyncResponse(payload: unknown): void;
-    handleBootstrapResponse(payload: unknown): void;
-    handlePresenceUpdate(message: {
-        payload?: unknown;
-        [k: string]: unknown;
-    }): void;
-}
-export type WsFrameHandler = (session: WsSession, message: WsInboundFrame) => void;
-/**
- * Maps each frame type to its handler. Every named server frame this
- * package understands is dispatched from this table; anything else falls
- * through to the collaboration-event and unknown-type path in
- * {@link dispatchWsFrame}.
- */
-export declare const wsFrameHandlers: Record<string, WsFrameHandler>;
-/**
- * Routes one inbound frame to its handler, validating the payload first.
- *
- * A frame the protocol declares with a payload schema is parsed here, so its
- * handler works on a proven shape. A frame the protocol does not declare is
- * rejected: the server and this package ship together, so an unrecognised type
- * means the two have drifted, and a change nobody validated should not reach a
- * local store. The one exception is an application's own collaboration events,
- * which the consumer registers at construction and the protocol knows nothing
- * about.
- *
- * Throwing is the reporting channel. The transport's message loop catches and
- * reports through `captureWebSocketError`, so a bad frame surfaces as a
- * captured error and the connection survives.
- */
-export declare function dispatchWsFrame(session: WsSession, message: WsInboundFrame): void;