@rangojs/router 0.16.0 → 0.18.0

package/src/cache/cache-runtime.ts

@@ -35,14 +35,14 @@ import {
 
 export { isCachedFunction };
 import { serializeResult, deserializeResult } from "./segment-codec.js";
-import { createHandleStore } from "../server/handle-store.js";
 import {
-  restoreHandles,
+  appendHandles,
   encodeHandles,
   decodeHandles,
 } from "./handle-snapshot.js";
-import { startHandleCapture, type HandleCapture } from "./handle-capture.js";
-import { sortedSearchString } from "./cache-key-utils.js";
+import { startHandleCapture, useCacheRecordKey } from "./handle-capture.js";
+import { isHandle } from "../handle.js";
+import { cacheKeyBase, sortedSearchString } from "./cache-key-utils.js";
 import { encodeKV } from "../encode-kv.js";
 import { runBackground } from "./background-task.js";
 import { observePhase, PHASES } from "../router/instrument.js";
@@ -51,9 +51,16 @@ import {
   recordRequestTags,
   runWithCacheTagScope,
 } from "./cache-tag.js";
-import { runWithCacheExecScope } from "./cache-exec-scope.js";
+import {
+  createCacheExecScope,
+  isInCacheExecChain,
+  runWithCacheExecScope,
+  type CacheExecScope,
+} from "./cache-exec-scope.js";
 import { reportCacheError } from "./cache-error.js";
+import { currentCacheSeq, invalidatedSince } from "./tag-invalidation.js";
 import type { CacheItemResult } from "./types.js";
+import type { InternalHandlerContext } from "../types.js";
 
 /**
  * DJB2 hash returning an 8-char hex string. Deterministic across runtimes
@@ -125,10 +132,74 @@ export async function replyToCacheKey(
   return encodeKV(pairs, { sort: true });
 }
 
+/**
+ * An unescaped temporary-reference token in an encodeReply part. A user
+ * string "$T" encodes as "$$T", a quote inside a string is escaped, and an
+ * object key "$T" is followed by ":".
+ */
+const TEMPORARY_REFERENCE_TOKEN = /(?<!\\)"\$T"(?!:)/g;
+
+const REACT_ELEMENT_TYPE = Symbol.for("react.transitional.element");
+const CLIENT_REFERENCE_TYPE = Symbol.for("react.client.reference");
+const SERVER_REFERENCE_TYPE = Symbol.for("react.server.reference");
+
+function countTemporaryReferences(encoded: string | FormData): number {
+  if (typeof encoded === "string") {
+    return encoded.match(TEMPORARY_REFERENCE_TOKEN)?.length ?? 0;
+  }
+  let count = 0;
+  encoded.forEach((value) => {
+    if (typeof value === "string") {
+      count += value.match(TEMPORARY_REFERENCE_TOKEN)?.length ?? 0;
+    }
+  });
+  return count;
+}
+
+/** A React element, or a client or server reference function. */
+function isRenderSlot(value: unknown): boolean {
+  if (typeof value === "object" && value !== null) {
+    return (value as { $$typeof?: unknown }).$$typeof === REACT_ELEMENT_TYPE;
+  }
+  if (typeof value === "function") {
+    const tag = (value as { $$typeof?: unknown }).$$typeof;
+    return tag === CLIENT_REFERENCE_TYPE || tag === SERVER_REFERENCE_TYPE;
+  }
+  return false;
+}
+
+/**
+ * Whether encodeReply wrote "$T" for a value that cannot be keyed. Given a
+ * temporary-reference set it does not throw on a value it cannot serialize:
+ * it writes "$T", so distinct arguments would share one key (issue #924).
+ * React elements and client/server references are render slots, left out of
+ * the key on purpose (the interleave route, e2e/use-cache-streaming.test.ts);
+ * a function, a symbol or a class instance is not.
+ *
+ * The set is the Map encodeReply fills: one entry per "$T" it writes, plus
+ * every object it visits. So more tokens than slot entries means a non-slot
+ * "$T", with no traversal of the arguments. Runs only on the encoder path.
+ */
+function hasUnkeyableReference(
+  encoded: string | FormData,
+  tempRefs: unknown,
+): boolean {
+  const tokens = countTemporaryReferences(encoded);
+  if (tokens === 0) return false;
+  let slots = 0;
+  for (const value of (tempRefs as Map<string, unknown>).values()) {
+    if (isRenderSlot(value)) slots++;
+  }
+  return tokens > slots;
+}
+
 // Cached-fn ids already warned about running uncached under a test runner, so
 // the test-ergonomics warning fires once per fn rather than once per call.
 const warnedUncachedUnderTest = new Set<string>();
 
+// Cached-fn ids already warned about arguments that cannot be keyed (dev only).
+const warnedUnkeyableArgs = new Set<string>();
+
 /**
  * Fast-path cache-key builder for JSON-safe key args. Returns a deterministic
  * string (object keys recursively sorted so insertion order can't change the
@@ -222,7 +293,10 @@ interface CacheEnvelope {
  */
 interface InFlightExecution {
   promise: Promise<CacheEnvelope>;
+  /** Date.now() at registration, for IN_FLIGHT_LEADER_MAX_WAIT_MS. */
   registeredAt: number;
+  /** currentCacheSeq() at registration, for invalidatedSince (#973). */
+  startSeq: number;
 }
 
 const inFlightExecutions = new Map<string, InFlightExecution>();
@@ -264,6 +338,30 @@ function raceLeader(
   });
 }
 
+/**
+ * A stale refresh's view of a handler ctx: loader reads run on their own
+ * executor (setupLoaderAccess _runLoaderIsolated), and an inner HIT replays in
+ * full without claiming. The refresh diverts its pushes, so the request's
+ * memoized run of a loader would take that loader's live pushes off the page,
+ * and a claim would starve the page's own replay of it.
+ */
+function refreshView(arg: unknown): unknown {
+  const ctx = arg as InternalHandlerContext<any, any>;
+  const runIsolated = isTainted(arg) ? ctx._runLoaderIsolated : undefined;
+  if (!runIsolated) return arg;
+  const runs = new Map<string, Promise<any>>();
+  const use = (item: any) => {
+    if (isHandle(item)) return ctx.use(item);
+    let run = runs.get(item.$$id);
+    if (!run) runs.set(item.$$id, (run = runIsolated(item)));
+    return run;
+  };
+  return Object.create(ctx, {
+    use: { value: use },
+    _claimLoaderPushes: { value: undefined },
+  });
+}
+
 // ============================================================================
 // Core: registerCachedFunction
 // ============================================================================
@@ -333,17 +431,33 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       );
     }
 
-    // Separate tainted args (ctx, env, req) from key-generating args.
-    // For tainted objects that carry route context (params, pathname,
-    // searchParams), extract serializable values into the key so
-    // different routes, param combinations, and query variants produce
-    // distinct cache entries.
+    // Separate request-scoped args (ctx, a Request, the request's env) from
+    // key-generating args. For those that carry route context (ctx params,
+    // pathname, searchParams; a Request's URL), extract serializable values
+    // into the key so different routes, param combinations, and query
+    // variants produce distinct cache entries.
     const keyArgs: unknown[] = [];
     let hasTaintedArgs = false;
+    // The calling segment, read synchronously as ctx.use(Handle) does: a HIT
+    // replays into it. A route's layouts and page share one handler ctx and
+    // so one key; the recorded ids are the first caller's. Its ctx's claim
+    // keeps a replayed loader's pushes to one copy per request.
+    let callerSegmentId: string | undefined;
+    let claimLoaderPushes: ((loaderId: string) => boolean) | undefined;
+    // A fetchable loader's request body (loader-fetch.ts) is an input the
+    // route fields leave out: such a call runs uncached (#940).
+    let hasBodyCtx = false;
     for (const arg of args) {
       if (isTainted(arg)) {
         hasTaintedArgs = true;
         const ctx = arg as any;
+        if (ctx.body !== undefined || ctx.formData !== undefined) {
+          hasBodyCtx = true;
+        }
+        if (callerSegmentId === undefined) {
+          callerSegmentId = ctx._currentSegmentId;
+          claimLoaderPushes = ctx._claimLoaderPushes;
+        }
         if (ctx.params && typeof ctx.params === "object") {
           // Include host to prevent cross-host cache collisions (same
           // pattern as route-level cache-scope.ts key generation).
@@ -373,6 +487,22 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             }
           }
         }
+      } else if (arg instanceof Request) {
+        // A raw Request (ctx.request) is request-scoped like ctx: fold in its
+        // URL with the same host-namespacing and search normalization.
+        const url = new URL(arg.url);
+        keyArgs.push(
+          cacheKeyBase(
+            url.host,
+            url.pathname,
+            url.searchParams,
+            undefined,
+            requestCtx?._searchParamsFilter,
+          ),
+        );
+      } else if (arg != null && arg === requestCtx?.env) {
+        // The request's env is left out: constant per deployment, and its
+        // bindings are not serializable.
       } else {
         keyArgs.push(arg);
       }
@@ -383,7 +513,7 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // gone. Throw early rather than silently dropping handle side effects.
     if (hasTaintedArgs && !requestCtx?._handleStore) {
       throw new Error(
-        `[use cache] "${id}" receives a tainted argument (ctx/env/req) but the ` +
+        `[use cache] "${id}" receives a ctx argument but the ` +
           `HandleStore is not available. This typically happens when a "use cache" ` +
           `function with ctx runs outside the request context (e.g., during late ` +
           `streaming after AsyncLocalStorage context is lost). Move the "use cache" ` +
@@ -391,10 +521,16 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           `use the route-level cache() DSL instead.`,
       );
     }
+    // Records group pushes by owning loader (useCacheRecordKey) and replay
+    // into the caller's segment; a caller without one records segment ids.
+    const ownerKeyed = callerSegmentId !== undefined;
 
     // Generate cache key
     let cacheKey: string;
     try {
+      if (hasBodyCtx) {
+        throw new Error("ctx carries a request body");
+      }
       if (keyArgs.length > 0) {
         // Fast path: when every key arg is JSON-safe, build the key with a
         // deterministic stable-stringify and skip encodeReply (the Flight reply
@@ -410,6 +546,9 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           const encoded = await encodeReply(keyArgs as unknown[], {
             temporaryReferences: tempRefs,
           });
+          if (hasUnkeyableReference(encoded, tempRefs)) {
+            throw new Error("unserializable key argument");
+          }
           const argsKey = await replyToCacheKey(encoded);
           cacheKey = `use-cache:${id}:${argsKey}`;
         }
@@ -420,6 +559,19 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       // Non-serializable args: run uncached (within a tag scope so cacheTag()
       // still does not throw). Record runtime tags so the document union still
       // sees them even though this call is not itself cached.
+      if (
+        process.env.NODE_ENV !== "production" &&
+        !warnedUnkeyableArgs.has(id)
+      ) {
+        warnedUnkeyableArgs.add(id);
+        console.warn(
+          `[use cache] "${id}" ran uncached: an argument, or a value nested in ` +
+            `one, cannot be serialized into the cache key (a function, class ` +
+            `instance or symbol, or a loader ctx carrying a request body). ` +
+            `Pass serializable values; ctx, a Request, the request's env and ` +
+            `React elements are handled.`,
+        );
+      }
       const scoped = runWithCacheTagScope(() => fn.apply(this, args));
       const result = await scoped.result;
       recordRequestTags(scoped.tags, requestCtx);
@@ -441,7 +593,9 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         const handleStore = requestCtx?._handleStore;
         if (handleStore) {
           const r = await decodeHandles(entry.handles);
-          if (r) restoreHandles(r, handleStore);
+          if (r) {
+            appendHandles(r, handleStore, callerSegmentId, claimLoaderPushes);
+          }
         }
       }
       recordRequestTags(entry.tags, requestCtx);
@@ -474,34 +628,29 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       // Stale hit: return stale value, revalidate in background
       try {
         const result = await serveCached(cached);
+        const liveStore = hasTaintedArgs ? requestCtx?._handleStore : undefined;
+        const recordKey = ownerKeyed ? useCacheRecordKey() : undefined;
         // Background revalidation — must capture handles if tainted args present.
         runBackground(requestCtx, async () => {
-          // The background body runs under a DERIVED context with an OWN
-          // _handleStore (the shell-capture isolation pattern —
-          // shell-capture.ts attemptCapture): its handle pushes land in the
-          // isolated store (captured below, persisted with the entry) while
-          // the foreground keeps pushing into the ORIGINAL store, untouched.
-          // Derivation matters because the foreground is STILL RENDERING here
-          // — runBackground/waitUntil starts the task on the next microtask,
-          // not after the response. The previous shape swapped
-          // requestCtx._handleStore in place (restore in finally), which
-          // routed the whole overlap window's foreground pushes into the
-          // background store: lost from the live document AND persisted into
-          // the revalidated entry (issue #684, plan 010).
-          const bgHandleStore =
-            hasTaintedArgs && requestCtx ? createHandleStore() : undefined;
-          const bgCtx: typeof requestCtx = bgHandleStore
-            ? Object.assign(Object.create(requestCtx), {
-                _handleStore: bgHandleStore,
+          // The background body's handle pushes belong to the refreshed entry
+          // only: the foreground already replayed the stale entry's. They
+          // reach the REQUEST's store (a handler ctx.use(Handle) binds it at
+          // setupLoaderAccess, so a derived context with its own store never
+          // sees them), so the capture accepts only this body's chain and
+          // diverts what it records away from the live store. The foreground
+          // is still rendering here (runBackground starts on the next
+          // microtask), and its concurrent pushes are neither recorded nor
+          // diverted (issue #684, plan 010). A root scope: the task is
+          // detached, so an outer "use cache" body that scheduled it must not
+          // record the refresh's pushes.
+          const bgScope: CacheExecScope = {};
+          const bgCapture = liveStore
+            ? startHandleCapture(liveStore, {
+                accept: () => isInCacheExecChain(bgScope),
+                divert: true,
+                key: recordKey,
               })
-            : requestCtx;
-          let bgCapture: HandleCapture | undefined;
-          let bgStopCapture: (() => void) | undefined;
-          if (bgHandleStore) {
-            const c = startHandleCapture(bgHandleStore);
-            bgCapture = c.capture;
-            bgStopCapture = c.stop;
-          }
+            : undefined;
 
           // Tainted args are NOT stamped here, in contrast to the foreground
           // miss path below. The args include the live HandlerContext the
@@ -522,23 +671,27 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             // getRequestContext().env.ApiKey) resolves during the background
             // revalidation instead of throwing "called outside of a request
             // context". runWithRequestContext sets the store for fn's
-            // synchronous kickoff; its async continuations inherit it. The
-            // DERIVED context goes in, so ambient _handleStore reads inside
-            // the body resolve to the isolated store.
+            // synchronous kickoff; its async continuations inherit it.
             //
             // The span opens inside the request ALS and wraps the WHOLE task —
             // fn kickoff through the store write — so its platform spans nest
             // under rango.background and a slow or failing setItem is part of
             // the traced revalidation, not an untraced tail.
-            await runWithRequestContext(bgCtx, () =>
+            await runWithRequestContext(requestCtx, () =>
               observePhase(
                 PHASES.background("use-cache-revalidation"),
                 async () => {
+                  const refreshArgs = args.map(refreshView);
+                  // The refresh reads its data from here on (#973).
+                  const startSeq = currentCacheSeq();
                   const scoped = runWithCacheTagScope(() =>
-                    runWithCacheExecScope(() => fn.apply(this, args)),
+                    runWithCacheExecScope(
+                      () => fn.apply(this, refreshArgs),
+                      bgScope,
+                    ),
                   );
                   const freshResult = await scoped.result;
-                  bgStopCapture?.();
+                  bgCapture?.stop();
                   // Merge profile/DSL tags with runtime cacheTag() tags, read
                   // after awaiting so post-await cacheTag() calls are included.
                   // Normalize (drops empty profile tags, matching the
@@ -549,11 +702,30 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
                     ),
                   ];
                   recordRequestTags(freshTags, requestCtx);
-                  const serialized = await serializeResult(freshResult);
+                  const flightErrors: unknown[] = [];
+                  const onFlightError = (error: unknown): void => {
+                    flightErrors.push(error);
+                  };
+                  const serialized = await serializeResult(
+                    freshResult,
+                    onFlightError,
+                  );
                   if (serialized !== null) {
-                    const encodedHandles = bgCapture?.data
-                      ? await encodeHandles(bgCapture.data)
+                    const encodedHandles = bgCapture
+                      ? await encodeHandles(
+                          bgCapture.capture.data,
+                          onFlightError,
+                        )
                       : undefined;
+                    // An error row would replace the stale entry; the catch
+                    // below reports it and the stale entry keeps serving.
+                    if (flightErrors.length > 0) throw flightErrors[0];
+                    // The request invalidated one of the refreshed value's
+                    // tags after the refresh started: the value may predate
+                    // it, and written now it would outlive it.
+                    if (invalidatedSince(requestCtx, freshTags, startSeq)) {
+                      return;
+                    }
                     await store.setItem!(cacheKey, serialized, {
                       handles: encodedHandles,
                       ttl: profile.ttl,
@@ -565,7 +737,7 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
               ),
             );
           } catch (bgError) {
-            bgStopCapture?.();
+            bgCapture?.stop();
             // Pass requestCtx explicitly: this runs in a detached background
             // task where the ALS context is gone, so onError can only fire if
             // we hand it the context captured up front.
@@ -576,8 +748,6 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
               requestCtx,
             );
           }
-          // No finally: nothing shared was mutated — the derived context and
-          // its handle store are garbage after the task settles.
         });
         return result;
       } catch (error) {
@@ -599,8 +769,8 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // against its OWN handle store (gated on ITS hasTaintedArgs), and records
     // tags into its OWN request — no deserialized result is shared across
     // requests. The store write stays exactly once (the leader's).
-    const existing = inFlightExecutions.get(cacheKey);
-    if (existing) {
+    let existing = inFlightExecutions.get(cacheKey);
+    while (existing) {
       const remainingMs =
         IN_FLIGHT_LEADER_MAX_WAIT_MS - (Date.now() - existing.registeredAt);
       const raced =
@@ -622,8 +792,12 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           "cache-read",
           `[use cache] "${id}" inflight-timeout`,
         );
-        // Fall through to a fresh execution below (this call becomes leader).
-      } else if (raced) {
+        break; // This call becomes the leader below.
+      }
+      // Leader rejected: its map entry is already cleared; run fresh.
+      if (!raced) break;
+      // Checked after the wait, so an invalidation made meanwhile counts too.
+      if (!invalidatedSince(requestCtx, raced.tags, existing.startSeq)) {
         try {
           return await serveCached({
             value: raced.serialized,
@@ -637,11 +811,16 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             "cache-corrupt",
             `[use cache] "${id}" inflight-hit`,
           );
-          // Fall through to a fresh execution below.
+          break; // Run fresh below.
         }
       }
-      // raced === undefined: leader rejected; its map entry is already
-      // cleared, so fall through to a fresh run.
+      // This request invalidated one of the leader's tags after it started
+      // (#973): its value may predate the invalidation. The leader cleared
+      // its entry before resolving, so an entry now is a newer execution
+      // (another caller that made this same decision): join it rather than
+      // start one more.
+      const next = inFlightExecutions.get(cacheKey);
+      existing = next !== existing ? next : undefined;
     }
 
     // This call becomes the leader. Register a deferred envelope so concurrent
@@ -658,9 +837,11 @@ 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(() => {});
+    const startSeq = currentCacheSeq();
     inFlightExecutions.set(cacheKey, {
       promise: envelopePromise,
       registeredAt: Date.now(),
+      startSeq,
     });
     const clearSelf = (): void => {
       if (inFlightExecutions.get(cacheKey)?.promise === envelopePromise) {
@@ -669,14 +850,17 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     };
 
     // execute, serialize, store
+    // Record only this execution's pushes (and cached functions it calls):
+    // the handler and loaders push into the same store concurrently, and they
+    // re-run on a hit.
     const handleStore = hasTaintedArgs ? requestCtx?._handleStore : undefined;
-    let capture: HandleCapture | undefined;
-    let stopCapture: (() => void) | undefined;
-    if (handleStore && hasTaintedArgs) {
-      const c = startHandleCapture(handleStore);
-      capture = c.capture;
-      stopCapture = c.stop;
-    }
+    const execScope = createCacheExecScope();
+    const capture = handleStore
+      ? startHandleCapture(handleStore, {
+          accept: () => isInCacheExecChain(execScope),
+          key: ownerKeyed ? useCacheRecordKey() : undefined,
+        })
+      : undefined;
 
     // Stamp tainted args so ctx.set(), ctx.header(), etc. throw if called
     // inside the cached function body (those side effects are lost on hit).
@@ -702,7 +886,7 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     let scoped: ReturnType<typeof runWithCacheTagScope>;
     try {
       scoped = runWithCacheTagScope(() =>
-        runWithCacheExecScope(() => fn.apply(this, args)),
+        runWithCacheExecScope(() => fn.apply(this, args), execScope),
       );
       result = await scoped.result;
     } catch (execError) {
@@ -717,7 +901,7 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         unstampCacheExec(arg as object);
       }
       // Remove this capture token (order-independent, safe for concurrent use)
-      stopCapture?.();
+      capture?.stop();
     }
 
     // Merge profile/DSL tags with runtime cacheTag() tags. Read scoped.tags
@@ -735,11 +919,19 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     const finalizeAndWrite = async (): Promise<void> => {
       let serialized: string | null;
       let encodedHandles: string | undefined;
+      const flightErrors: unknown[] = [];
+      const onFlightError = (error: unknown): void => {
+        flightErrors.push(error);
+      };
       try {
-        serialized = await serializeResult(result);
-        encodedHandles = capture?.data
-          ? await encodeHandles(capture.data)
+        serialized = await serializeResult(result, onFlightError);
+        encodedHandles = capture
+          ? await encodeHandles(capture.capture.data, onFlightError)
           : undefined;
+        // Flight encodes an async component that throws, or a rejected
+        // promise in the result or a handle value, as an error row and
+        // completes normally; stored, every hit would serve that error.
+        if (flightErrors.length > 0) throw flightErrors[0];
       } catch (buildError) {
         // Serialize/handle-encode failed: no envelope for followers (they run
         // fresh) and nothing to write.
@@ -762,6 +954,10 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       // Hand followers the envelope before the store write so a slow/failed
       // write never stalls them.
       resolveEnvelope({ serialized, tags: allTags, handles: encodedHandles });
+      // This request invalidated one of the value's tags after the execution
+      // started (#973): the value may predate the invalidation, and written
+      // now it would outlive it. Skip the write; the next read runs fresh.
+      if (invalidatedSince(requestCtx, allTags, startSeq)) return;
       try {
         await store.setItem!(cacheKey, serialized, {
           handles: encodedHandles,