@abloatai/ablo 0.34.1 → 0.36.0

package/dist/sync/BootstrapFetcher.d.ts

@@ -27,6 +27,12 @@ export interface BootstrapData {
      * when the app's schema and the deployed schema have drifted apart.
      */
     schemaHash?: string;
+    /**
+     * Present when a paged single-model request stopped at its row limit with
+     * rows remaining: pass it back as the next page's `cursor`. Absent on the
+     * final page, on unpaged responses, and from servers that predate paging.
+     */
+    nextCursor?: string;
 }
 export interface BootstrapFetchResult {
     notModified: boolean;
@@ -58,8 +64,23 @@ export interface BootstrapOptions {
     syncGroups?: string[];
     maxRetries?: number;
     retryDelay?: number;
-    /** How long to wait for a single fetch before timing out, in milliseconds. Default 10000 (10 seconds). */
+    /**
+     * How long to wait for the server to START responding (response headers), in
+     * milliseconds. Default 20000 (20 seconds).
+     *
+     * Deliberately NOT a bound on the whole download: a cold-start snapshot can
+     * be tens of megabytes, and its transfer time depends on the connection. A
+     * healthy download that is actively delivering bytes is never aborted, no
+     * matter how long it takes — {@link stallTimeout} guards the body instead.
+     */
     fetchTimeout?: number;
+    /**
+     * The longest quiet gap allowed between body chunks while downloading, in
+     * milliseconds. Default 15000 (15 seconds). This is the progress watchdog:
+     * it aborts a download whose stream has gone silent (dead connection,
+     * hung proxy) without ever penalizing a slow-but-moving transfer.
+     */
+    stallTimeout?: number;
     /**
      * The model names to request. When set, the server returns only these models
      * and skips the rest. This is derived from each model's `load` strategy: only
@@ -73,14 +94,53 @@ export interface BootstrapOptions {
      * {@link BootstrapFetcher.setAuthToken}.
      */
     getAuthToken?: AuthTokenGetter;
+    /** The owning client's runtime. Defaults to the module-global bridge. */
+    runtime?: RuntimeContext;
 }
-import { type AuthTokenGetter } from '../auth/credentialSource.js';
+import type { RuntimeContext } from '../RuntimeContext.js';
+import { type AuthTokenGetter } from '../transaction/auth/credentialSource.js';
 import { type ValidatedServerDelta } from './schemas.js';
 export declare class BootstrapFetcher {
     private options;
-    private abortController;
+    private readonly runtime;
+    /**
+     * Every in-flight request's controller, tagged with the lane it belongs to. A
+     * registry rather than a single field because a chunked cold start runs
+     * several model fetches concurrently — aborting one request (its own
+     * TTFB/stall watchdog) must never take its siblings down, while
+     * {@link abort} takes down all of them.
+     */
+    private readonly activeControllers;
+    /**
+     * Non-scoped bootstraps currently running, keyed by request identity. A
+     * second call for the same snapshot joins the one already in flight rather
+     * than cancelling and restarting it — see {@link fetchBootstrap}.
+     */
+    private readonly flights;
     /** Warn about schema drift at most once per helper. */
     private schemaDriftWarned;
+    /**
+     * Abort every in-flight request in `lane` — or in every lane when none is
+     * given — with an explicit reason.
+     *
+     * The reason is load-bearing, not decoration. `fetch` rejects with the exact
+     * value handed to `abort()`, so passing a typed error is what lets the retry
+     * loop below tell a deliberate cancellation apart from a dead connection. A
+     * bare `abort()` produces an `AbortError` indistinguishable from the one the
+     * browser's stop button produces, and a retry loop that cannot tell them
+     * apart re-issues the requests it just killed.
+     */
+    private cancelActive;
+    /**
+     * The longest a single bootstrap can run before every watchdog below has
+     * necessarily fired, derived from those watchdogs rather than guessed. A
+     * caller wanting an outer deadline reads this instead of picking a number,
+     * so it cannot set one shorter than the work it wraps. A cold start pages
+     * through its models {@link CHUNK_CONCURRENCY} at a time; each request may
+     * spend `fetchTimeout` waiting for response headers and `stallTimeout`
+     * waiting for the next body chunk, and may be retried `maxRetries` times.
+     */
+    get budgetMs(): number;
     get baseUrl(): string;
     /**
      * Advisory schema-drift check: compare the server's active schema hash (on the
@@ -100,6 +160,10 @@ export declare class BootstrapFetcher {
      * common wrong-target and version-skew cases.
      */
     private warnOnSchemaDrift;
+    /** Fetch the server's per-model schema surface and warn precisely — or stay
+     *  silent when every model this client declares matches (additive lead). */
+    private resolveSemanticDrift;
+    private warnWholeHashDrift;
     constructor(options: BootstrapOptions);
     /**
      * Update the offline-cache namespace once auth has resolved the server-side
@@ -127,14 +191,54 @@ export declare class BootstrapFetcher {
      * request.
      */
     syncGroupsOverride?: readonly string[]): Promise<BootstrapData>;
+    /**
+     * The identity of a bootstrap request: everything that determines its answer.
+     * Two calls with the same key are asking the same question, so the second can
+     * take the first's result.
+     */
+    private flightKey;
+    /** One bootstrap, start to finish. {@link fetchBootstrap} owns whether it runs. */
+    private runBootstrap;
+    /**
+     * One bootstrap URL, fetched with backoff. Session errors and other
+     * non-retryable failures throw immediately; only transient failures
+     * (5xx, 429, timeouts, network blips) consume attempts. A cancellation is
+     * deliberate and therefore non-retryable — it leaves through the same gate.
+     */
+    private fetchWithRetries;
+    /**
+     * Cold-start bootstrap, one request per instant model with a small
+     * concurrency cap. Any chunk's terminal failure fails the whole
+     * bootstrap (a partial snapshot must never masquerade as a full one)
+     * and cancels its siblings.
+     */
+    private fetchChunkedBootstrap;
     /**
      * Fetch bootstrap with ETag, returning 304 hints
      */
     fetchBootstrapWithETag(): Promise<BootstrapFetchResult>;
+    private fetchWithETagUsing;
+    /**
+     * Read a response body as a stream under a progress watchdog: the stall
+     * timer re-arms on every chunk, so only a silent stream is aborted — a
+     * slow-but-moving download is never killed for total duration. A cold-start
+     * snapshot can be tens of megabytes; bounding its total transfer time was
+     * what trapped large orgs in an endless full-bootstrap retry loop.
+     *
+     * Falls back to `response.json()` when the response exposes no readable
+     * stream (empty bodies, some test doubles).
+     */
+    private readJsonWithStallGuard;
     /**
-     * Perform the actual fetch request with timeout protection
+     * Perform one fetch. The timeout here bounds time to response headers
+     * only; the body download is guarded by the stall watchdog in
+     * {@link readJsonWithStallGuard}. Superseding an older in-flight
+     * bootstrap is the caller's job ({@link fetchBootstrap} cancels the
+     * registry) — chunk requests run through here concurrently and must
+     * not cancel each other.
      */
-    private performFetch;
+    private fetchOnce;
+    private fetchOnceWith;
     /**
      * Fetch a single entity by ID (on-demand self-healing).
      * Returns `null` for 404 (entity deleted) — this is an expected state, not an error.
@@ -149,7 +253,12 @@ export declare class BootstrapFetcher {
     private saveCachedBootstrap;
     private loadCachedBootstrap;
     /**
-     * Abort ongoing fetch request
+     * Abort every ongoing bootstrap request (including all chunks of a
+     * chunked cold start). Entity self-heal fetches are unaffected.
+     *
+     * The flight registry is cleared first and synchronously, so a caller that
+     * bootstraps again in the same tick starts a fresh request rather than
+     * joining the one being torn down.
      */
     abort(): void;
     /**
@@ -161,3 +270,15 @@ export declare class BootstrapFetcher {
      */
     checkHealth(): Promise<boolean>;
 }
+/**
+ * Assemble per-model chunk responses into one full snapshot.
+ *
+ * Each chunk is internally consistent at its own sync position, and the
+ * positions differ (the chunks were served seconds apart). Anchoring the
+ * merged snapshot at the MINIMUM position turns that skew into an ordinary
+ * "briefly offline client": the WS catch-up replays every delta from the
+ * anchor, and since deltas carry full rows, re-applying one a later chunk
+ * already reflects converges to the same state. Anchoring at anything later
+ * would silently skip deltas for the earliest-fetched models.
+ */
+export declare function mergeBootstrapChunks(chunks: readonly BootstrapData[]): BootstrapData;