@abloatai/ablo 0.34.1 → 0.36.0

package/dist/{sync/NetworkProbe.d.ts → transaction/transport/networkProbe.d.ts}

@@ -23,11 +23,12 @@
  */
 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 {@link ConnectionManager} can branch on one exhaustive
+ * 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 {@link RecoveryClass} taxonomy at the connectivity layer.
+ * 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}. */
@@ -69,11 +70,13 @@ export interface NetworkProbeOptions {
     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 {@link ConnectionManager}
- * can pick the right state transition without guessing.
+ * 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.

package/dist/{sync/NetworkProbe.js → transaction/transport/networkProbe.js}

@@ -22,15 +22,15 @@
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine
  */
 import { z } from 'zod';
-import { getContext } from '../context.js';
 import { classifyRecovery } from '../errors.js';
 import { withAuthHeaders } from '../auth/credentialSource.js';
-import { ABLO_DEFAULT_BASE_URL } from '../client/hostedEndpoints.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 {@link ConnectionManager} can branch on one exhaustive
+ * 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 {@link RecoveryClass} taxonomy at the connectivity layer.
+ * It mirrors the `RecoveryClass` taxonomy at the connectivity layer.
  */
 export const PROBE_OUTCOMES = [
     /** Server reachable and the access credential is currently valid. */
@@ -72,8 +72,8 @@ function resolveProbeUrl(baseUrl) {
 }
 /**
  * Probes the sync server with a lightweight HEAD request, returning both
- * reachability and session status in a single call so {@link ConnectionManager}
- * can pick the right state transition without guessing.
+ * 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.
@@ -82,6 +82,7 @@ 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
@@ -115,14 +116,14 @@ export async function probeNetwork(input) {
             const recovery = classifyRecovery(authFailure);
             switch (recovery) {
                 case 'session_expiry':
-                    getContext().logger.info('[NetworkProbe] Server reachable, login expired', {
+                    logger.info('[NetworkProbe] Server reachable, login expired', {
                         status: response.status,
                         code: authFailure,
                         latencyMs,
                     });
                     return { outcome: 'session_expired', latencyMs };
                 case 'access_credential_expiry':
-                    getContext().logger.info('[NetworkProbe] Server reachable, access key stale — will re-mint', {
+                    logger.info('[NetworkProbe] Server reachable, access key stale — will re-mint', {
                         status: response.status,
                         code: authFailure,
                         latencyMs,
@@ -136,7 +137,7 @@ export async function probeNetwork(input) {
                     // Re-authenticating re-mints the same rejected credential and
                     // retrying will not help, so stop rather than reconnect-loop or sign
                     // the user out.
-                    getContext().logger.debug('[NetworkProbe] Reachable but auth-blocked (non-retryable, non-expiry)', {
+                    logger.debug('[NetworkProbe] Reachable but auth-blocked (non-retryable, non-expiry)', {
                         status: response.status,
                         code: authFailure,
                         recovery,
@@ -168,7 +169,7 @@ export async function probeNetwork(input) {
             // 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.
-            getContext().logger.info('[NetworkProbe] Server reachable, bare 401 — re-mint (not sign-out)', {
+            logger.info('[NetworkProbe] Server reachable, bare 401 — re-mint (not sign-out)', {
                 latencyMs,
             });
             return { outcome: 'credential_stale', latencyMs };
@@ -178,14 +179,14 @@ export async function probeNetwork(input) {
         // expected 204; log a warning so misconfigurations surface instead of
         // silently passing.
         if (response.status < 200 || response.status >= 300) {
-            getContext().logger.debug('[NetworkProbe] Unexpected probe response', {
+            logger.debug('[NetworkProbe] Unexpected probe response', {
                 status: response.status,
                 url,
                 latencyMs,
             });
         }
         else {
-            getContext().logger.debug('[NetworkProbe] Server reachable, credential valid', {
+            logger.debug('[NetworkProbe] Server reachable, credential valid', {
                 status: response.status,
                 latencyMs,
             });
@@ -195,7 +196,7 @@ export async function probeNetwork(input) {
     catch (error) {
         clearTimeout(timeout);
         const isAbort = error instanceof DOMException && error.name === 'AbortError';
-        getContext().logger.info('[NetworkProbe] Probe failed', {
+        logger.info('[NetworkProbe] Probe failed', {
             reason: isAbort ? 'timeout' : error.message,
         });
         return { outcome: 'unreachable', latencyMs: null };

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

@@ -0,0 +1,128 @@
+/**
+ * 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;