@rangojs/router 0.0.0-experimental.135c6902 → 0.0.0-experimental.136

package/src/cache/cache-runtime.ts

@@ -20,7 +20,11 @@ import {
   encodeReply,
   createClientTemporaryReferenceSet,
 } from "@vitejs/plugin-rsc/rsc";
-import { getRequestContext } from "../server/request-context.js";
+import {
+  getRequestContext,
+  runWithRequestContext,
+} from "../server/request-context.js";
+import { isUnderTestRunner } from "../runtime-env.js";
 import {
   isTainted,
   CACHED_FN_SYMBOL,
@@ -32,22 +36,97 @@ import {
 export { isCachedFunction };
 import { serializeResult, deserializeResult } from "./segment-codec.js";
 import { createHandleStore } from "../server/handle-store.js";
-import { restoreHandles } from "./handle-snapshot.js";
+import {
+  restoreHandles,
+  encodeHandles,
+  decodeHandles,
+} from "./handle-snapshot.js";
 import { startHandleCapture, type HandleCapture } from "./handle-capture.js";
 import { sortedSearchString } from "./cache-key-utils.js";
+import { encodeKV } from "../encode-kv.js";
 import { runBackground } from "./background-task.js";
+import {
+  normalizeTags,
+  recordRequestTags,
+  runWithCacheTagScope,
+} from "./cache-tag.js";
+import { reportCacheError } from "./cache-error.js";
+import type { CacheItemResult } from "./types.js";
+
+/**
+ * DJB2 hash returning an 8-char hex string. Deterministic across runtimes
+ * (no crypto import — cache-runtime runs on the edge). Mirrors prerender's
+ * param-hash djb2Hex so binary key parts hash consistently.
+ */
+function djb2HexBytes(bytes: Uint8Array): string {
+  let hash = 5381;
+  for (let i = 0; i < bytes.length; i++) {
+    hash = ((hash << 5) + hash + bytes[i]!) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
 
 /**
  * Convert encodeReply result to a stable string key.
- * encodeReply may return string or FormData — normalize to string.
+ *
+ * encodeReply may return a string or FormData. A plain string is already
+ * deterministic for a given arg set, so return it verbatim. FormData (emitted
+ * whenever a key arg is a typed array / Blob / File / a large object React
+ * lazily chunks) carries a per-call RANDOM multipart boundary
+ * (`formdata-undici-<random>`); stringifying the whole body via
+ * `new Response(formData).text()` would therefore produce a DIFFERENT key on
+ * every call, so the cached function would always miss and the store would
+ * accumulate one duplicate entry per call (unbounded growth).
+ *
+ * Instead derive the key from the entries themselves, independent of the
+ * boundary: iterate in sorted-key order and, for each value, emit a
+ * boundary-free token — `s:<value>` for strings, `b:<size>:<type>:<name>:<hash>`
+ * for Blob/File (bytes folded via djb2 so distinct payloads of equal
+ * size/type/name still differ). Strings carry an `s:` type tag so a string whose
+ * value happens to equal a blob token (e.g. the literal `b:4::a:b:<hash>`) cannot
+ * collide with an actual Blob/File entry under the same FormData key. The
+ * user-controlled `type`/`name` are percent-encoded before joining so an embedded
+ * `:` cannot shift the field boundaries and collide two distinct files (e.g.
+ * {name:"a:b",type:""} vs {name:"b",type:":a"}). The result is stable across
+ * identical arg sets.
  */
-async function replyToCacheKey(encoded: string | FormData): Promise<string> {
+export async function replyToCacheKey(
+  encoded: string | FormData,
+): Promise<string> {
   if (typeof encoded === "string") return encoded;
-  // FormData: convert to Response body, then to string for deterministic key
-  const text = await new Response(encoded).text();
-  return text;
+
+  // Snapshot entries synchronously (forEach avoids relying on FormData's
+  // iterator typings), then fold any Blob/File bytes asynchronously.
+  const raw: [string, FormDataEntryValue][] = [];
+  encoded.forEach((value, key) => {
+    raw.push([key, value]);
+  });
+  const pairs: [string, string][] = [];
+  for (const [key, value] of raw) {
+    if (typeof value === "string") {
+      // Type-tag strings with `s:` so a string equal to a blob token (e.g.
+      // `b:4::a:b:<hash>`) cannot collide with a Blob/File entry under the same
+      // key (which carries the `b:` tag below).
+      pairs.push([key, "s:" + value]);
+    } else {
+      // Blob/File: fold the bytes into a deterministic, boundary-free token.
+      // Percent-encode the user-controlled type/name so an embedded `:` cannot
+      // shift the `:`-delimited field boundaries and collide distinct files.
+      const buf = await value.arrayBuffer();
+      const hash = djb2HexBytes(new Uint8Array(buf));
+      const name = "name" in value ? value.name : "";
+      const encType = encodeURIComponent(value.type);
+      const encName = encodeURIComponent(name);
+      pairs.push([key, `b:${value.size}:${encType}:${encName}:${hash}`]);
+    }
+  }
+  return encodeKV(pairs, { sort: true });
 }
 
+// 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>();
+
 // ============================================================================
 // Core: registerCachedFunction
 // ============================================================================
@@ -70,9 +149,38 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     const store = requestCtx?._cacheStore;
     const resolvedProfileName = profileName || "default";
 
-    // Bypass: no store or no getItem support
+    // Bypass: no store or no getItem support. Still run inside a tag scope so a
+    // cacheTag() call inside the function degrades to a no-op rather than
+    // throwing "must be called inside a use cache function" - adopting cacheTag()
+    // must not hard-fail in apps/tests without an item-capable cache configured.
+    // Note: the INSIDE_CACHE_EXEC guard (cookies()/headers()/ctx.set() rejection)
+    // is intentionally NOT stamped here. It is a cached-path-only check; in the
+    // bypass the body actually executes, so the guarded side effects take effect
+    // and nothing is lost on a (non-existent) hit. Same applies to the
+    // non-serializable-args bypass below.
     if (!store?.getItem) {
-      return fn.apply(this, args);
+      // Test-ergonomics guard: under a test runner, a "use cache" function that
+      // executes with no item-capable store seeded is exercising the UNCACHED
+      // path — a green test that proves nothing about caching. Warn once per fn
+      // id so the author knows to seed a cacheStore. Advisory (never throws), so
+      // a test that DELIBERATELY runs uncached is unaffected. Gated on the test
+      // runner (process.env.VITEST, not folded) so production never evaluates it.
+      if (isUnderTestRunner() && !warnedUncachedUnderTest.has(id)) {
+        warnedUncachedUnderTest.add(id);
+        console.warn(
+          `[rango] "use cache" function "${id}" executed but no cacheStore was ` +
+            `seeded; the cached path is NOT under test (it ran uncached). Pass ` +
+            `{ cacheStore, cacheProfiles } to runLoader/runMiddleware/renderHandler/` +
+            `runInRequestContext (or configure createRouter({ cache }) for dispatch) ` +
+            `to exercise it.`,
+        );
+      }
+      const scoped = runWithCacheTagScope(() => fn.apply(this, args));
+      const result = await scoped.result;
+      // Still record the runtime tags into the request set so a cacheTag() in an
+      // uncached function tags the document, even with no item-capable store.
+      recordRequestTags(scoped.tags, requestCtx);
+      return result;
     }
 
     // Resolve profile strictly from request-scoped config (set by the
@@ -155,47 +263,74 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
         cacheKey = `use-cache:${id}`;
       }
     } catch {
-      // Non-serializable args: run uncached
-      return fn.apply(this, args);
+      // 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.
+      const scoped = runWithCacheTagScope(() => fn.apply(this, args));
+      const result = await scoped.result;
+      recordRequestTags(scoped.tags, requestCtx);
+      return result;
     }
 
     // Cache lookup
     const cached = await store.getItem(cacheKey);
 
+    // Serve a cached entry on the hit path: deserialize the stored value,
+    // replay handle data (gated on tainted args), and surface the entry's tags
+    // to the request set (the function did not re-run, so its runtime cacheTag()
+    // tags are only available from the stored entry). Shared by the fresh-hit
+    // and stale-hit branches; the only divergence is the stale branch scheduling
+    // background revalidation, which it does after this returns.
+    const serveCached = async (entry: CacheItemResult): Promise<any> => {
+      const result = await deserializeResult(entry.value);
+      if (entry.handles && hasTaintedArgs) {
+        const handleStore = requestCtx?._handleStore;
+        if (handleStore) {
+          const r = await decodeHandles(entry.handles);
+          if (r) restoreHandles(r, handleStore);
+        }
+      }
+      recordRequestTags(entry.tags, requestCtx);
+      return result;
+    };
+
     if (cached && !cached.shouldRevalidate) {
       // Fresh hit: deserialize and return
       try {
-        const result = await deserializeResult(cached.value);
-        // Restore handle data if present
-        if (cached.handles && hasTaintedArgs) {
-          const handleStore = requestCtx?._handleStore;
-          if (handleStore) {
-            restoreHandles(cached.handles, handleStore);
-          }
-        }
-        return result;
-      } catch {
-        // Deserialization failed, fall through to fresh execution
+        return await serveCached(cached);
+      } catch (error) {
+        // The stored value is corrupt/partial (failed RSC deserialize). Report
+        // it, then fall through to fresh execution - the miss path below re-runs
+        // and setItem() overwrites the faulty entry under the same key (self-heal).
+        reportCacheError(
+          error,
+          "cache-corrupt",
+          `[use cache] "${id}" fresh-hit`,
+        );
       }
     }
 
-    if (cached?.shouldRevalidate) {
+    // foregroundOnAction (opt-in; see CacheProfile.foregroundOnAction): during an
+    // action's revalidation render, a stale entry falls through to the foreground
+    // miss path below instead of SWR. The flag is set by revalidateAfterAction.
+    const foregroundOnActionRevalidation =
+      requestCtx?._inActionRevalidation === true &&
+      profile.foregroundOnAction === true;
+    if (cached?.shouldRevalidate && !foregroundOnActionRevalidation) {
       // Stale hit: return stale value, revalidate in background
       try {
-        const result = await deserializeResult(cached.value);
-        if (cached.handles && hasTaintedArgs) {
-          const handleStore = requestCtx?._handleStore;
-          if (handleStore) {
-            restoreHandles(cached.handles, handleStore);
-          }
-        }
+        const result = await serveCached(cached);
         // Background revalidation — must capture handles if tainted args present.
         // Use an isolated handle store so background pushes don't pollute the
         // live response or throw LateHandlePushError on the completed store.
         // Same isolation pattern as route-level background-revalidation.ts.
         runBackground(requestCtx, async () => {
-          // Reuse closure-captured requestCtx instead of calling
-          // getRequestContext() — ALS context may be gone inside waitUntil.
+          // The closure-captured requestCtx is reused for the framework's own
+          // reads (handle store swap, error reporting) AND, below, to
+          // re-establish the request-context ALS around the user fn. ALS context
+          // may be gone inside waitUntil: on workerd a waitUntil task runs
+          // detached from the request's I/O context, so getRequestContext()
+          // inside the cached body would otherwise throw.
           let originalHandleStore:
             | ReturnType<typeof createHandleStore>
             | undefined;
@@ -214,11 +349,21 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
             bgStopCapture = c.stop;
           }
 
-          // Stamp tainted args and RequestContext so request-scoped
-          // reads (cookies, headers) and side effects (ctx.set, etc.)
-          // throw inside background revalidation, same as the miss path.
-          // Uses ref-counted stamp/unstamp so overlapping executions
-          // sharing the same ctx don't clear each other's guards.
+          // Stamp tainted ARGS only — not requestCtx. The args stamp guards
+          // direct ctx method calls (ctx.set, ctx.header, ctx.onResponse, etc.)
+          // which is sufficient for correctness.
+          //
+          // We intentionally skip stamping requestCtx here because:
+          // 1. runBackground starts the async task synchronously (before the
+          //    first await), so stampCacheExec would pollute the shared
+          //    requestCtx while the foreground pipeline is still running.
+          //    This causes assertNotInsideCacheExec to fire when cache-store
+          //    later calls requestCtx.onResponse().
+          // 2. requestCtx methods are closure-bound to the original ctx, so
+          //    neither Object.create() nor a proxy can isolate the stamp.
+          // 3. The foreground miss path already stamps requestCtx and catches
+          //    cookies()/headers() misuse on first execution. The background
+          //    re-runs the same function with the same request.
           const bgTaintedArgs: unknown[] = [];
           for (const arg of args) {
             if (isTainted(arg)) {
@@ -226,32 +371,55 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
               bgTaintedArgs.push(arg);
             }
           }
-          if (requestCtx) {
-            stampCacheExec(requestCtx as object);
-          }
 
           try {
-            const freshResult = await fn.apply(this, args);
+            // Re-establish the request-context ALS so a "use cache" body that
+            // reads the ambient getRequestContext() (e.g.
+            // 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.
+            const scoped = runWithRequestContext(requestCtx, () =>
+              runWithCacheTagScope(() => fn.apply(this, args)),
+            );
+            const freshResult = await scoped.result;
             bgStopCapture?.();
+            // 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 invalidate path) + dedupe.
+            const freshTags = [
+              ...new Set(
+                normalizeTags([...(profile.tags ?? []), ...scoped.tags]),
+              ),
+            ];
+            recordRequestTags(freshTags, requestCtx);
             const serialized = await serializeResult(freshResult);
             if (serialized !== null) {
+              const encodedHandles = bgCapture?.data
+                ? await encodeHandles(bgCapture.data)
+                : undefined;
               await store.setItem!(cacheKey, serialized, {
-                handles: bgCapture?.data,
+                handles: encodedHandles,
                 ttl: profile.ttl,
                 swr: profile.swr,
-                tags: profile.tags,
+                tags: freshTags.length > 0 ? freshTags : undefined,
               });
             }
           } catch (bgError) {
             bgStopCapture?.();
-            requestCtx?._reportBackgroundError?.(bgError, "stale-revalidation");
+            // 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.
+            reportCacheError(
+              bgError,
+              "stale-revalidation",
+              "[use cache] background revalidation failed",
+              requestCtx,
+            );
           } finally {
             for (const arg of bgTaintedArgs) {
               unstampCacheExec(arg as object);
             }
-            if (requestCtx) {
-              unstampCacheExec(requestCtx as object);
-            }
             // Restore original handle store
             if (originalHandleStore && requestCtx) {
               requestCtx._handleStore = originalHandleStore;
@@ -259,8 +427,14 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
           }
         });
         return result;
-      } catch {
-        // Deserialization of stale value failed, fall through
+      } catch (error) {
+        // Stale value is corrupt/partial; report and fall through to a fresh
+        // execution, which overwrites the faulty entry under the same key.
+        reportCacheError(
+          error,
+          "cache-corrupt",
+          `[use cache] "${id}" stale-hit`,
+        );
       }
     }
 
@@ -293,8 +467,10 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     }
 
     let result: any;
+    let scoped: ReturnType<typeof runWithCacheTagScope>;
     try {
-      result = await fn.apply(this, args);
+      scoped = runWithCacheTagScope(() => fn.apply(this, args));
+      result = await scoped.result;
     } finally {
       // Decrement ref count; symbol is deleted when it reaches zero
       for (const arg of taintedArgs) {
@@ -307,17 +483,28 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
       stopCapture?.();
     }
 
+    // Merge profile/DSL tags with runtime cacheTag() tags. Read scoped.tags
+    // after awaiting result so post-await cacheTag() calls are included.
+    // Normalize (drops empty profile tags, matching the invalidate path) + dedupe.
+    const allTags = [
+      ...new Set(normalizeTags([...(profile.tags ?? []), ...scoped!.tags])),
+    ];
+    recordRequestTags(allTags, requestCtx);
+
     // Serialize and store — fully non-blocking when waitUntil is available.
     // The response does not need to wait for serialization or the store write.
     const cacheWrite = async () => {
       try {
         const serialized = await serializeResult(result);
         if (serialized !== null) {
+          const encodedHandles = capture?.data
+            ? await encodeHandles(capture.data)
+            : undefined;
           await store.setItem!(cacheKey, serialized, {
-            handles: capture?.data,
+            handles: encodedHandles,
             ttl: profile.ttl,
             swr: profile.swr,
-            tags: profile.tags,
+            tags: allTags.length > 0 ? allTags : undefined,
           });
         }
       } catch (writeError) {