@drakkar.software/starfish-client 3.0.0-alpha.25 → 3.0.0-alpha.26

package/README.md

@@ -187,6 +187,8 @@ new StarfishClient({
   fetch,                  // optional custom fetch
   cache,                  // optional offline-first read-through cache — see below
   cacheMaxAgeMs,          // optional TTL (ms) for cache entries
+  cacheFallbackStatuses,  // optional — serve cache on 429/5xx (stale-while-revalidate)
+  onRevalidated,          // optional — called after a background revalidation succeeds
 })
 ```
 
@@ -200,7 +202,8 @@ Pass a `cache` (a `PullCache`: `{ get(k): Promise<string|null>; set(k, v): Promi
 
 - **Write-through:** a successful pull stores the raw `{data, hash, timestamp}` keyed by document path.
 - **Offline fallback:** a pull that fails because the **transport** is unreachable (`fetch` rejects — offline/DNS/timeout) returns the last cached snapshot, tagged so callers can tell it's stale (`pullWasFromCache(result)`).
-- **Real HTTP errors propagate:** 404/403/5xx are genuine server answers — the cache is *not* consulted, so "no document yet" and "access denied" keep their meaning.
+- **Real HTTP errors propagate:** 404/403 are genuine server answers — the cache is *not* consulted, so "no document yet" and "access denied" keep their meaning. 429 and 5xx can optionally be caught via `cacheFallbackStatuses` (see below).
+- **Stale-while-revalidate:** set `cacheFallbackStatuses: [429, 500, 502, 503, 504]` to make transient server failures serve the last-synced snapshot immediately and retry in the background (honoring `Retry-After`). When the live response arrives, the cache is updated and `onRevalidated` fires. No snapshot → the error propagates as usual. Do NOT include 403/404 — they are genuine answers, not transient failures.
 - **`cacheMaxAgeMs`:** an entry older than this is treated as a miss (both cache-first paint and offline fallback); omit for entries that never expire (recommended for offline-first, where any last-synced data beats none).
 - **Ciphertext-at-rest by construction:** the cache stores the raw server payload, which for E2E (`delegated`) collections is the sealed ciphertext the server holds — never the decrypted form. Decryption happens in memory on read (see `SyncManager.seedFromCache`).
 - **`client.peekCache(path)`** reads the cached snapshot *without* a network round-trip — the basis for cache-first paint.

package/dist/bindings/zustand.js

@@ -264,8 +264,27 @@ var StarfishHttpError = class extends Error {
   }
 };
 
+// src/fetch.ts
+function parseRetryAfterMs(header, opts) {
+  const { fallbackMs, maxMs } = opts;
+  const trimmed = header?.trim();
+  if (trimmed) {
+    const seconds = Number(trimmed);
+    if (!isNaN(seconds)) return Math.min(seconds * 1e3, maxMs);
+    const date = Date.parse(trimmed);
+    if (!isNaN(date)) return Math.min(Math.max(date - Date.now(), 0), maxMs);
+  }
+  return Math.min(fallbackMs, maxMs);
+}
+
 // src/client.ts
 var APPEND_DEFAULT_FIELD = "items";
+var MAX_REVALIDATE_ATTEMPTS = 5;
+var REVALIDATE_INITIAL_DELAY_MS = 1e3;
+var REVALIDATE_MAX_DELAY_MS = 3e4;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function pullCacheKey(pathAndQuery) {
   const q = pathAndQuery.indexOf("?");
   return q === -1 ? pathAndQuery : pathAndQuery.slice(0, q);
@@ -292,6 +311,9 @@ var StarfishClient = class {
   fetch;
   cache;
   cacheMaxAgeMs;
+  cacheFallbackStatuses;
+  onRevalidated;
+  revalidating = /* @__PURE__ */ new Set();
   /**
    * Installed client-side plugins. Currently stored as inert data; no
    * hooks fire yet. Extensions can inspect this list if needed.
@@ -304,6 +326,8 @@ var StarfishClient = class {
     this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
     this.cache = options.cache;
     this.cacheMaxAgeMs = options.cacheMaxAgeMs;
+    this.cacheFallbackStatuses = options.cacheFallbackStatuses;
+    this.onRevalidated = options.onRevalidated;
     this.plugins = options.plugins ? [...options.plugins] : [];
   }
   /**
@@ -459,7 +483,17 @@ var StarfishClient = class {
       throw err;
     }
     if (!res.ok) {
-      throw new StarfishHttpError(res.status, await res.text());
+      const status = res.status;
+      if (cacheKey && this.cacheFallbackStatuses?.includes(status)) {
+        const retryAfterHeader = res.headers.get("Retry-After");
+        this.scheduleRevalidate(cacheKey, pathAndQuery, retryAfterHeader);
+        const cached = await this.readCache(cacheKey);
+        if (cached) {
+          void res.body?.cancel();
+          return cached;
+        }
+      }
+      throw new StarfishHttpError(status, await res.text());
     }
     const result = await res.json();
     if (appendField !== void 0) {
@@ -478,6 +512,63 @@ var StarfishClient = class {
     }
     return result;
   }
+  /** Deduplicated fire-and-forget: starts one revalidation loop per cacheKey. */
+  scheduleRevalidate(cacheKey, pathAndQuery, retryAfterHeader) {
+    if (this.revalidating.has(cacheKey)) return;
+    this.revalidating.add(cacheKey);
+    void this.revalidateLoop(cacheKey, pathAndQuery, retryAfterHeader).finally(() => {
+      this.revalidating.delete(cacheKey);
+    });
+  }
+  /**
+   * Background revalidation loop for a {@link cacheFallbackStatuses} hit.
+   * Retries the pull (honoring `Retry-After`) up to {@link MAX_REVALIDATE_ATTEMPTS}
+   * times. On a live 2xx response the fresh snapshot is written through to the
+   * cache and {@link onRevalidated} fires. Stops early on a non-fallback HTTP
+   * status (e.g. 404/403 — the server gave a genuine answer).
+   */
+  async revalidateLoop(cacheKey, pathAndQuery, firstRetryAfter) {
+    let retryAfterHeader = firstRetryAfter;
+    for (let attempt = 0; attempt < MAX_REVALIDATE_ATTEMPTS; attempt++) {
+      const delay = parseRetryAfterMs(retryAfterHeader, {
+        fallbackMs: Math.min(
+          REVALIDATE_INITIAL_DELAY_MS * Math.pow(2, attempt),
+          REVALIDATE_MAX_DELAY_MS
+        ),
+        maxMs: REVALIDATE_MAX_DELAY_MS
+      });
+      await sleep(delay);
+      try {
+        const url = `${this.baseUrl}${pathAndQuery}`;
+        const authHeaders = await this.buildAuthHeaders("GET", pathAndQuery, void 0);
+        const res = await this.fetch(url, {
+          method: "GET",
+          headers: { [HEADER_ACCEPT]: "application/json", ...authHeaders }
+        });
+        if (res.ok) {
+          const result = await res.json();
+          if (this.cache) {
+            const snapshot = {
+              data: result.data,
+              hash: result.hash,
+              timestamp: result.timestamp,
+              cachedAt: Date.now()
+            };
+            void this.cache.set(cacheKey, JSON.stringify(snapshot)).catch(() => {
+            });
+          }
+          this.onRevalidated?.(pathAndQuery, result);
+          return;
+        }
+        if (!this.cacheFallbackStatuses?.includes(res.status)) {
+          return;
+        }
+        retryAfterHeader = res.headers.get("Retry-After");
+      } catch {
+        retryAfterHeader = null;
+      }
+    }
+  }
   /**
    * Read the cached snapshot for a document `path` WITHOUT hitting the network —
    * the basis for cache-first paint (seed the UI from the last-synced snapshot,