@rangojs/router 0.5.0 → 0.5.2

package/skills/use-cache/SKILL.md

@@ -307,6 +307,53 @@ intercept("@modal", ".product", async (ctx) => {
 }),
 ```
 
+## Embedding server actions in cached components
+
+A cached function may return a component that creates an inline `"use server"`
+action. The canonical case is a cached list whose items each carry an action --
+e.g. a cached article list where every row has a like button:
+
+```typescript
+export async function ArticleList() {
+  "use cache: articles";
+  const articles = await db.query("SELECT id, title FROM articles");
+  return (
+    <ul>
+      {articles.map((a) => {
+        const articleId = a.id; // captured -> frozen with the cache entry
+        async function like() {
+          "use server";
+          // runs live on click, in the CURRENT request scope
+          const user = cookies().get("session")?.value;
+          if (user) await db.like(articleId, user);
+        }
+        return <LikeButton key={a.id} title={a.title} action={like} />;
+      })}
+    </ul>
+  );
+}
+```
+
+Three behaviors, locked by `use-cache-inline-action.test.ts` (dev + prod):
+
+| What                                            | Behavior                  | Why                                                                                                                                                                           |
+| ----------------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Values the action **closes over** (`articleId`) | **Frozen** at cache-write | The closure compiles to encrypted bound args, snapshotted when the entry is written and replayed verbatim on a hit. Correct for stable identities; wrong for volatile values. |
+| The action **body**                             | **Runs live** every call  | Once invoked it is an ordinary server function: fresh computation and live request context. `cookies()` / `headers()` work here (the body executes in the live request).      |
+| Invocability on a **cache hit**                 | **Works**                 | The action survives serialize -> cache -> deserialize and stays callable.                                                                                                     |
+
+Rule of thumb: **capture stable identities, read volatile/request-scoped values
+live in the body.** Do not close over a per-request token, the current user, or
+the current time and expect freshness -- those are frozen at cache-write. The
+`cookies()`/`headers()` read guard applies to the cached function body, NOT to an
+inline action's body.
+
+Deploy note: captured values are encrypted with a per-build key by default. If
+cache entries can outlive a deploy (a persistent store such as the Cloudflare
+cache store), set `RANGO_ENCRYPTION_KEY` (base64-encoded 32 bytes) in the build
+environment so actions embedded in entries written by a previous deploy still
+decrypt; without it they fail until the entry expires or revalidates.
+
 ## Vite Transform
 
 The `rango:use-cache` Vite plugin detects the directive and wraps exports with

package/src/browser/event-controller.ts

@@ -234,6 +234,12 @@ export interface EventController {
     listener: ActionStateListener,
   ): () => void;
   subscribeToHandles(listener: HandleListener): () => void;
+  /**
+   * Deliver queued location, params, navigation, and handle notifications now.
+   * NavigationProvider calls this inside the payload update so React assigns
+   * every route-state hook update to the same normal or transition lane.
+   */
+  flushRouteState(): void;
 
   // Handle operations
   setHandleData(
@@ -367,19 +373,32 @@ function matchesActionId(
   return entryActionId.endsWith(`#${subscriptionId}`);
 }
 
-// Batch rapid notifications into one microtask to prevent render storms
-function makeDebouncedNotifier(listeners: Set<() => void>): () => void {
+interface DebouncedNotifier {
+  schedule(): void;
+  flush(): void;
+}
+
+// Batch rapid notifications into one task to prevent render storms. The
+// explicit flush lets a React update owner preserve its scheduling lane.
+function makeDebouncedNotifier(listeners: Set<() => void>): DebouncedNotifier {
   let timeout: ReturnType<typeof setTimeout> | null = null;
-  return () => {
-    if (timeout !== null) clearTimeout(timeout);
-    timeout = setTimeout(() => {
-      timeout = null;
-      notifyListeners(
-        [...listeners],
-        (listener) => listener(),
-        (listener) => listeners.has(listener),
-      );
-    }, 0);
+  const flush = () => {
+    if (timeout === null) return;
+    clearTimeout(timeout);
+    timeout = null;
+    notifyListeners(
+      [...listeners],
+      (listener) => listener(),
+      (listener) => listeners.has(listener),
+    );
+  };
+
+  return {
+    schedule() {
+      if (timeout !== null) clearTimeout(timeout);
+      timeout = setTimeout(flush, 0);
+    },
+    flush,
   };
 }
 
@@ -459,7 +478,7 @@ export function createEventController(
 
   function notify(): void {
     cachedDerivedState = null;
-    notifyStateListeners();
+    notifyStateListeners.schedule();
   }
 
   const actionNotifyTimeouts = new Map<string, ReturnType<typeof setTimeout>>();
@@ -517,6 +536,11 @@ export function createEventController(
 
   const notifyHandles = makeDebouncedNotifier(handleListeners);
 
+  function flushRouteState(): void {
+    notifyStateListeners.flush();
+    notifyHandles.flush();
+  }
+
   function getState(): DerivedNavigationState {
     if (cachedDerivedState) return cachedDerivedState;
 
@@ -1001,7 +1025,7 @@ export function createEventController(
     handleSegmentOrder = newSegmentOrder;
     routeSegmentIds = newRouteSegmentIds;
 
-    notifyHandles();
+    notifyHandles.schedule();
   }
 
   function getHandleState(): HandleState {
@@ -1021,7 +1045,7 @@ export function createEventController(
       return;
     }
     routeSegmentIds = next;
-    notifyHandles();
+    notifyHandles.schedule();
   }
 
   // ========================================================================
@@ -1102,6 +1126,7 @@ export function createEventController(
     subscribe,
     subscribeToAction,
     subscribeToHandles,
+    flushRouteState,
 
     // Direct access
     getCurrentNavigation: () => currentNavigation,

package/src/browser/partial-update.ts

@@ -421,10 +421,8 @@ export function createPartialUpdater(
         // forceAwait unwraps the ROUTER loader promises during render so they
         // land without a loading()/fallback frame. A fully-prefetched nav has
         // its router data already resolved (the prefetch stream drained), so
-        // awaiting it here is free and lets us commit NORMALLY (not in a
-        // transition) below — a normal commit still shows fallbacks for any
-        // CLIENT component that suspends on mount, which a transition would
-        // wrongly suppress by holding the old UI until that suspense settles.
+        // awaiting it here is free; the commit below then runs in a transition
+        // (fullyPrefetched branch) so nothing router-owned can flash.
         forceAwait: mode.type === "stale-revalidation" || fullyPrefetched,
         interceptSegments:
           reconciled.interceptSegments.length > 0
@@ -549,14 +547,31 @@ export function createPartialUpdater(
             scroll: scrollPayload,
           });
         });
+      } else if (fullyPrefetched) {
+        // Fully-prefetched nav: the payload is fully resolved (forceAwait
+        // above), so commit inside a transition to hold the current UI across
+        // the synchronous resolution — no fallback flash. No addTransitionType:
+        // this is the React content-hold, not a view transition. Deliberate
+        // trade-off (#622 introduced, #624 reverted, then reinstated): a client
+        // component that suspends during its FIRST render (use() of a promise
+        // created at mount — see ClientMountSuspense in the e2e test-app) under
+        // an ALREADY-REVEALED boundary holds the old content until it resolves
+        // instead of revealing that boundary's fallback; its render happens
+        // pre-commit inside the transition, so userland effects cannot run
+        // first. Boundaries newly mounted by this nav still reveal their
+        // fallbacks (React shows new boundaries inside transitions).
+        startTransition(() => {
+          onUpdate({
+            root: newTree,
+            metadata: payload.metadata!,
+            scroll: scrollPayload,
+          });
+        });
       } else {
-        // Normal commit for ALL navs here, never a transition (see the
-        // forceAwait comment above for why prefetched router data lands
-        // without fallback frames). A transition would hold the OLD UI until
-        // every suspense in the new tree settles — including a client
-        // component that only starts fetching post-mount, retaining the
-        // previous page indefinitely. Explicit transition() routes keep the
-        // content-hold via the hasTransition branch above (the opt-in).
+        // Cold/partially-prefetched nav: normal commit so fallbacks stream
+        // like a first load and the click has visible feedback. Explicit
+        // transition() routes keep the content-hold via the hasTransition
+        // branch above (the opt-in).
         onUpdate({
           root: newTree,
           metadata: payload.metadata!,

package/src/browser/prefetch/cache.ts

@@ -72,8 +72,31 @@ export interface DecodedPrefetch {
    * tell a FULLY warmed prefetch (payload commits without suspending → safe to
    * commit in a startTransition, no fallback flash) from a partially-warmed one
    * (still streaming → stream its fallbacks like a cold load). Starts false.
+   *
+   * On a respawned entry (see `respawn`) this starts true: the buffered bytes
+   * are a complete stream by construction.
    */
   complete: boolean;
+  /**
+   * Re-create this entry from its buffered raw Flight bytes. Attached (by
+   * `executePrefetchFetch`) only after the stream ended cleanly AND the eager
+   * decode succeeded — a truncated or failed prefetch must stay one-shot.
+   *
+   * Why bytes and not the decoded payload: the revived payload is a live graph
+   * with one-shot stream edges (the handle stream is an async generator drained
+   * during commit; userland payloads may embed serialized ReadableStreams).
+   * Re-decoding from the wire bytes manufactures fresh instances of every
+   * stream, which no amount of cloning the revived graph can do. Each call tees
+   * the reserve branch, so the replacement entry carries its own `respawn` —
+   * one prefetch serves unlimited adoptions within TTL/state validity.
+   */
+  respawn?: () => DecodedPrefetch;
+  /**
+   * Release the buffered reserve bytes. Called when the entry is evicted
+   * without being consumed (expiry, FIFO, sweep, cache clear) so the tee
+   * buffer is dropped promptly instead of waiting for GC.
+   */
+  dispose?: () => void;
 }
 
 let cacheTTL = 300_000;
@@ -208,6 +231,7 @@ export function hasPrefetch(key: string): boolean {
   const entry = cache.get(key);
   if (!entry) return false;
   if (Date.now() - entry.timestamp > cacheTTL) {
+    entry.entry.dispose?.();
     cache.delete(key);
     return false;
   }
@@ -216,22 +240,34 @@ export function hasPrefetch(key: string): boolean {
 
 /**
  * Consume a cached, eagerly-decoded prefetch. Returns null if not found or
- * expired. One-time consumption: the entry is deleted after retrieval.
- * Returns null when caching is disabled (TTL <= 0).
+ * expired. Returns null when caching is disabled (TTL <= 0).
+ *
+ * A decoded payload is single-render (its handle stream is drained during the
+ * commit), so the returned entry is never served twice. When the entry carries
+ * `respawn` (clean-EOF prefetch with buffered bytes), the slot is re-armed in
+ * place with a fresh decode of those bytes — the ORIGINAL timestamp is kept so
+ * TTL bounds the age of the data, not of the latest adoption. Without
+ * `respawn` the entry is deleted (legacy one-shot behavior).
  *
  * Does NOT check in-flight prefetches — use consumeInflightPrefetch()
  * for that (returns a Promise instead of a resolved entry).
  */
 export function consumePrefetch(key: string): DecodedPrefetch | null {
   if (cacheTTL <= 0) return null;
-  const entry = cache.get(key);
-  if (!entry) return null;
-  if (Date.now() - entry.timestamp > cacheTTL) {
+  const cached = cache.get(key);
+  if (!cached) return null;
+  if (Date.now() - cached.timestamp > cacheTTL) {
+    cached.entry.dispose?.();
     cache.delete(key);
     return null;
   }
-  cache.delete(key);
-  return entry.entry;
+  const entry = cached.entry;
+  if (entry.respawn) {
+    cached.entry = entry.respawn();
+  } else {
+    cache.delete(key);
+  }
+  return entry;
 }
 
 /**
@@ -301,6 +337,7 @@ export function storePrefetch(
     let min = Infinity;
     for (const [k, cached] of cache) {
       if (now - cached.timestamp > cacheTTL) {
+        cached.entry.dispose?.();
         cache.delete(k);
       } else if (cached.timestamp < min) {
         min = cached.timestamp;
@@ -312,7 +349,10 @@ export function storePrefetch(
   // FIFO eviction if at capacity
   if (cache.size >= maxPrefetchCacheSize) {
     const oldest = cache.keys().next().value;
-    if (oldest) cache.delete(oldest);
+    if (oldest) {
+      cache.get(oldest)?.entry.dispose?.();
+      cache.delete(oldest);
+    }
   }
 
   cache.set(key, { entry, timestamp: now });
@@ -335,7 +375,10 @@ export function storePrefetch(
  * entry.
  */
 export function removePrefetch(key: string, entry: DecodedPrefetch): void {
-  if (cache.get(key)?.entry === entry) cache.delete(key);
+  if (cache.get(key)?.entry === entry) {
+    entry.dispose?.();
+    cache.delete(key);
+  }
 }
 
 /**
@@ -405,6 +448,7 @@ export function clearPrefetchCache(rotateRangoState = true): void {
   inflightPromises.clear();
   inflightAliases.clear();
   adoptedKeys.clear();
+  for (const cached of cache.values()) cached.entry.dispose?.();
   cache.clear();
   earliestTimestamp = Infinity;
   abortAllPrefetches();

package/src/browser/prefetch/fetch.ts

@@ -70,6 +70,49 @@ export function setPrefetchDecoder(fn: PrefetchDecoder): void {
   decoder = fn;
 }
 
+/**
+ * Build the respawn closure for a cleanly-completed prefetch entry. Each call
+ * tees the reserve byte branch: one side feeds a fresh decode — a fresh handle
+ * stream and fresh serialized-stream instances, which no cloning of the
+ * revived payload graph could produce — and the other becomes the next
+ * reserve, so the replacement entry can respawn again. `streamComplete`
+ * resolves immediately and `complete` starts true: the buffered bytes are a
+ * finished stream by construction. The chunk imports the decode triggers are
+ * already in the module cache from the original eager decode, so a respawn
+ * costs ~ms with no network.
+ */
+function makeRespawn(
+  storageKey: string,
+  reserve: ReadableStream<Uint8Array>,
+  scope: "source" | "wildcard",
+): () => DecodedPrefetch {
+  return () => {
+    const [body, nextReserve] = reserve.tee();
+    // decoder is non-null here: respawn is only armed after a successful
+    // eager decode, which requires the decoder to have been set.
+    const payload = decoder!(Promise.resolve(new Response(body)));
+    payload.catch(() => {});
+    const entry: DecodedPrefetch = {
+      payload,
+      streamComplete: Promise.resolve(),
+      scope,
+      complete: true,
+      dispose: () => {
+        // Rejects (caught) instead of throwing if the branch is already
+        // locked by a later respawn — cache eviction never races adoption on
+        // the same entry object, so this is belt-and-braces.
+        nextReserve.cancel().catch(() => {});
+      },
+    };
+    entry.respawn = makeRespawn(storageKey, nextReserve, scope);
+    // Parity with the original path: a rejected decode must not stay
+    // consumable. Clean bytes should never fail to decode, but if they do,
+    // evict (identity-guarded) so navigation refetches instead.
+    payload.catch(() => removePrefetch(storageKey, entry));
+    return entry;
+  };
+}
+
 /**
  * Check if a URL resolves to the current page (same pathname + search).
  * Used to prevent same-page prefetching, which produces a trivial diff
@@ -271,9 +314,23 @@ function executePrefetchFetch(
         true,
       );
 
+      // Split the decode branch: one side feeds the eager decoder (unchanged —
+      // client chunks still import at prefetch time), the other stays unread as
+      // a reserve of the raw Flight bytes. A decoded payload is single-render
+      // (its handle stream drains during commit), so adoption would otherwise
+      // spend the entry; the reserve lets a cleanly-completed entry respawn a
+      // fresh decode per adoption instead (see makeRespawn).
+      let decodeSource: Response = tracked;
+      let reserve: ReadableStream<Uint8Array> | undefined;
+      if (tracked.body) {
+        const [decodeBody, reserveBody] = tracked.body.tee();
+        decodeSource = new Response(decodeBody, { headers: tracked.headers });
+        reserve = reserveBody;
+      }
+
       // Eager decode: parsing the Flight stream imports the route's client
       // chunks now, not on click.
-      const payload = decoder(Promise.resolve(tracked));
+      const payload = decoder(Promise.resolve(decodeSource));
       // Mark handled so an unconsumed prefetch decode error stays quiet; the
       // error is still surfaced to navigation if it consumes the entry.
       payload.catch(() => {});
@@ -283,6 +340,11 @@ function executePrefetchFetch(
         streamComplete,
         scope,
         complete: false,
+        ...(reserve && {
+          dispose: () => {
+            reserve.cancel().catch(() => {});
+          },
+        }),
       };
       storePrefetch(storageKey, entry, gen);
       // The stall timeout now owns the body stream: arm eviction (publishedKey)
@@ -301,10 +363,29 @@ function executePrefetchFetch(
       streamComplete.then(() => {
         if (!endedCleanly) removePrefetch(storageKey, entry);
       });
-      // Mark complete ONLY on a fully-healthy prefetch (decode resolved AND clean EOF).
+      // Mark complete ONLY on a fully-healthy prefetch (decode resolved AND
+      // clean EOF) — and only then arm respawn: a truncated or failed stream's
+      // reserve would replay broken bytes, so it stays one-shot (and its
+      // buffered reserve is released via the removePrefetch dispose above).
       Promise.allSettled([payload, streamComplete]).then(([decode]) => {
         if (decode.status === "fulfilled" && endedCleanly) {
           entry.complete = true;
+          if (reserve) {
+            entry.respawn = makeRespawn(storageKey, reserve, scope);
+            // Refill after an early adoption. A click that lands before this
+            // point adopts the entry with respawn unarmed and leaves the slot
+            // empty — via either path: pre-headers inflight adoption makes
+            // storePrefetch skip publication (adoptedKeys), and a mid-stream
+            // cache adoption deletes the incomplete entry. Now that the bytes
+            // proved themselves complete, publish a respawned sibling so the
+            // revisit is warm. Guards: hasPrefetch skips when the slot is
+            // live again (our own un-adopted entry, a fresh entry, or a new
+            // in-flight prefetch), and storePrefetch's generation check drops
+            // the sibling if the cache was invalidated since the fetch began.
+            if (!hasPrefetch(storageKey)) {
+              storePrefetch(storageKey, entry.respawn(), gen);
+            }
+          }
         }
         clearTimeout(timeoutId);
       });

package/src/browser/react/NavigationProvider.tsx

@@ -456,6 +456,13 @@ export function NavigationProvider({
           cached === undefined ? update.metadata.resolvedIds : undefined,
         );
       }
+
+      // tx.commit() and the metadata updates above mutate the controller
+      // synchronously, but its ordinary notifications are task-debounced. Flush
+      // them here so hook setState calls inherit this payload update's lane. In
+      // a transition that suspends, the source tree therefore keeps its source
+      // pathname/params until the destination payload commits with them.
+      eventController.flushRouteState();
     });
 
     return unsubscribe;

package/src/cache/cache-runtime.ts

@@ -205,8 +205,63 @@ interface CacheEnvelope {
  * singleton), and cleared for a key as soon as the leader settles: a rejected
  * leader (function threw, or the result was not serializable) propagates to
  * current waiters, which then retry fresh.
+ *
+ * A leader that NEVER settles must not hang followers (scar tissue, autobarn
+ * pilot outage): a background shell capture's render became leader, awaited a
+ * tarpitting upstream fetch, and workerd killed the capture's waitUntil context
+ * — orphaning the leader promise as permanently pending, its map entry never
+ * cleared. Every later document render calling the same cached function (an
+ * isolate-global key for plain-args calls) awaited it forever before first
+ * byte: isolate-wide TTFB-0 until redeploy. Followers therefore trust an entry
+ * only for {@link IN_FLIGHT_LEADER_MAX_WAIT_MS} from registration; past it
+ * they evict the entry and run fresh — bounded duplicate upstream work instead
+ * of an unbounded hang. Eviction is age-based off `registeredAt`, so it also
+ * heals entries stranded by a killed context (no timer in that context needs
+ * to survive).
+ */
+interface InFlightExecution {
+  promise: Promise<CacheEnvelope>;
+  registeredAt: number;
+}
+
+const inFlightExecutions = new Map<string, InFlightExecution>();
+
+/**
+ * How long a follower trusts an in-flight leader before evicting it and
+ * running fresh. High enough that a slow-but-healthy upstream never triggers
+ * duplicate work (a legitimate cached call taking >15s is already pathological);
+ * low enough to bound the blast radius of a wedged leader to seconds, not the
+ * isolate lifetime. Aligned with SHELL_CAPTURE_MAX_WAIT_MS.
+ */
+const IN_FLIGHT_LEADER_MAX_WAIT_MS = 15_000;
+
+/** Distinguishes a leader timeout from a leader rejection in raceLeader. */
+const LEADER_TIMED_OUT = Symbol("leader-timed-out");
+
+/**
+ * Await a leader's envelope for at most `remainingMs`. Resolves with the
+ * envelope, `undefined` on leader rejection (the leader already cleared its
+ * entry — caller falls through to a fresh run), or {@link LEADER_TIMED_OUT}
+ * when the window expires first (caller must evict the entry itself).
  */
-const inFlightExecutions = new Map<string, Promise<CacheEnvelope>>();
+function raceLeader(
+  promise: Promise<CacheEnvelope>,
+  remainingMs: number,
+): Promise<CacheEnvelope | undefined | typeof LEADER_TIMED_OUT> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(LEADER_TIMED_OUT), remainingMs);
+    promise.then(
+      (envelope) => {
+        clearTimeout(timer);
+        resolve(envelope);
+      },
+      () => {
+        clearTimeout(timer);
+        resolve(undefined);
+      },
+    );
+  });
+}
 
 // ============================================================================
 // Core: registerCachedFunction
@@ -541,20 +596,34 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // requests. The store write stays exactly once (the leader's).
     const existing = inFlightExecutions.get(cacheKey);
     if (existing) {
-      let envelope: CacheEnvelope | undefined;
-      try {
-        envelope = await existing;
-      } catch {
-        // Leader rejected (function threw or its result was not serializable);
-        // its map entry is already cleared, so fall through to a fresh run.
-        envelope = undefined;
-      }
-      if (envelope) {
+      const remainingMs =
+        IN_FLIGHT_LEADER_MAX_WAIT_MS - (Date.now() - existing.registeredAt);
+      const raced =
+        remainingMs <= 0
+          ? LEADER_TIMED_OUT
+          : await raceLeader(existing.promise, remainingMs);
+      if (raced === LEADER_TIMED_OUT) {
+        // Wedged (or context-orphaned) leader: evict so this call and every
+        // later one run fresh. Guard the delete so a newer leader's entry is
+        // never removed; the stale leader's own clearSelf is identity-guarded
+        // the same way, so it can't evict our replacement if it settles late.
+        if (inFlightExecutions.get(cacheKey) === existing) {
+          inFlightExecutions.delete(cacheKey);
+        }
+        reportCacheError(
+          new Error(
+            `in-flight leader did not settle within ${IN_FLIGHT_LEADER_MAX_WAIT_MS}ms; evicted — executing fresh`,
+          ),
+          "cache-read",
+          `[use cache] "${id}" inflight-timeout`,
+        );
+        // Fall through to a fresh execution below (this call becomes leader).
+      } else if (raced) {
         try {
           return await serveCached({
-            value: envelope.serialized,
-            handles: envelope.handles,
-            tags: envelope.tags,
+            value: raced.serialized,
+            handles: raced.handles,
+            tags: raced.tags,
             shouldRevalidate: false,
           });
         } catch (error) {
@@ -566,6 +635,8 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           // Fall through to a fresh execution below.
         }
       }
+      // raced === undefined: leader rejected; its map entry is already
+      // cleared, so fall through to a fresh run.
     }
 
     // This call becomes the leader. Register a deferred envelope so concurrent
@@ -582,9 +653,12 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // Followers attach their own catch; guard the map's own reference so a
     // rejected envelope with no waiter is not an unhandled rejection.
     envelopePromise.catch(() => {});
-    inFlightExecutions.set(cacheKey, envelopePromise);
+    inFlightExecutions.set(cacheKey, {
+      promise: envelopePromise,
+      registeredAt: Date.now(),
+    });
     const clearSelf = (): void => {
-      if (inFlightExecutions.get(cacheKey) === envelopePromise) {
+      if (inFlightExecutions.get(cacheKey)?.promise === envelopePromise) {
         inFlightExecutions.delete(cacheKey);
       }
     };

package/src/cache/cf/cf-cache-constants.ts

@@ -85,8 +85,15 @@ export const MAX_REVALIDATION_INTERVAL = 30;
  *
  * This is the default; override per store via
  * `CFCacheStoreOptions.edgeLookupTimeoutMs` (<= 0 disables the budget).
+ *
+ * 25ms, raised from 10: production Workers logs (autobarn pilot) showed the
+ * 10ms budget firing frequently on cold colos where the first Cache API touch
+ * is slow but healthy — each false positive downgrades a warm L1 HIT to an
+ * L2/render round trip that costs far more than the 15ms of extra patience.
+ * A genuinely degraded colo still gets cut off; tune per store for
+ * shell-critical routes.
  */
-export const EDGE_LOOKUP_TIMEOUT_MS = 10;
+export const EDGE_LOOKUP_TIMEOUT_MS = 25;
 
 /**
  * Maximum time (ms) to wait for the BODY of a matched L1 entry to be read