@rangojs/router 0.27.0 → 0.29.0

package/src/cache/cf/cf-kv-utils.ts

@@ -71,7 +71,7 @@ export async function kvKeyDigest(value: string): Promise<string> {
  * of restarting it -- copying set()'s original full-window max-age would reset
  * CF's retention clock on every re-arm and pin a perpetually-stale entry forever.
  * An entry lacking a valid deadline (legacy/tampered) floors to max-age=1, so it
- * hard-expires in ~1s and self-heals via KV. Mirrors promoteSegmentToL1's math.
+ * hard-expires in ~1s and self-heals via KV. Mirrors promoteToL1's math.
  * @internal
  */
 export function remainingCacheControl(headers: Headers, now: number): string {

package/src/cache/document-cache.ts

@@ -14,17 +14,18 @@
  */
 
 import { requestHeaders } from "../server/request-headers.js";
-import { FILL_PARAM, STALE_PARAM } from "../prefetch-markers.js";
 import type { MiddlewareFn, MiddlewareContext } from "../router/middleware.js";
 import {
   documentCacheStoresRender,
   shouldCacheResponse,
 } from "./document-cache-policy.js";
 import {
+  createRequestContext,
   getRequestContext,
-  runWithRequestContext,
+  runAsBackgroundWork,
   type RequestContext,
 } from "../server/request-context.js";
+import { deriveRenderPass } from "../server/render-pass.js";
 import { mayNeedSSR } from "../rsc/ssr-setup.js";
 import { requestKeyBase } from "./cache-key-utils.js";
 import { runBackground } from "./background-task.js";
@@ -45,6 +46,7 @@ import {
   SEGMENT_FRAGMENT_CAPABILITY_HEADER,
   SEGMENT_FRAGMENT_RECOVERY_HEADER,
 } from "../segment-fragments.js";
+import { WIRE } from "../wire-params.js";
 
 export { documentCacheStoresRender };
 
@@ -229,12 +231,12 @@ export function createDocumentCacheMiddleware<TEnv = any>(
     }
 
     // Skip RSC action requests (mutations shouldn't be cached)
-    if (rawUrl.searchParams.has("_rsc_action")) {
+    if (rawUrl.searchParams.has(WIRE.action)) {
       return next();
     }
 
     // Skip loader requests (have their own caching)
-    if (rawUrl.searchParams.has("_rsc_loader")) {
+    if (rawUrl.searchParams.has(WIRE.loader)) {
       return next();
     }
 
@@ -245,9 +247,9 @@ export function createDocumentCacheMiddleware<TEnv = any>(
     // the key cannot see. Partial only: _rsc params leave the key, so a
     // document GET carrying them must not force an origin render.
     if (
-      rawUrl.searchParams.has("_rsc_partial") &&
-      (rawUrl.searchParams.has(FILL_PARAM) ||
-        rawUrl.searchParams.get(STALE_PARAM) === "true")
+      rawUrl.searchParams.has(WIRE.partial) &&
+      (rawUrl.searchParams.has(WIRE.fill) ||
+        rawUrl.searchParams.get(WIRE.stale) === "true")
     ) {
       return next();
     }
@@ -283,7 +285,7 @@ export function createDocumentCacheMiddleware<TEnv = any>(
     // Determine request type for cache key differentiation.
     // Uses rawUrl for _rsc* param checks and mayNeedSSR for Accept-based
     // detection. Full-document RSC fetches must not share the HTML cache slot.
-    const isPartial = rawUrl.searchParams.has("_rsc_partial");
+    const isPartial = rawUrl.searchParams.has(WIRE.partial);
     const isRscRequest = !mayNeedSSR(ctx.request, rawUrl);
     const typeLabel = isRscRequest ? "RSC" : "HTML";
 
@@ -296,7 +298,7 @@ export function createDocumentCacheMiddleware<TEnv = any>(
       // gracefully to the origin handler instead of rejecting the request.
       // This is a deliberate fail-open-to-origin policy: the fallback is
       // "serve uncached from origin", not "use a different cache key".
-      const clientSegments = rawUrl.searchParams.get("_rsc_segments") || "";
+      const clientSegments = rawUrl.searchParams.get(WIRE.segments) || "";
       const segmentHash =
         isPartial && clientSegments ? `:${hashSegmentIds(clientSegments)}` : "";
       // Fragment envelopes require a capable Rango decoder. Keep that wire
@@ -359,26 +361,46 @@ export function createDocumentCacheMiddleware<TEnv = any>(
           `[DocumentCache] STALE ${typeLabel}: ${url.pathname} (revalidating)`,
         );
 
-        runBackground(requestCtx, async () => {
-          try {
-            // Re-establish the request-context ALS around the whole background
-            // task: next() re-runs the full handler pipeline, and on workerd a
-            // waitUntil task runs detached from the request's I/O context, so a
-            // handler/component reading getRequestContext() would otherwise
-            // throw. Same fix as the route-level/use-cache background
-            // revalidation paths. The rango.background span (kind=
-            // document-revalidation) wraps the re-render AND the store write so
-            // the task's spans — the re-run's own rango.* set and the drain/put
-            // platform spans — nest under one explanatory parent instead of
-            // dangling under the ended foreground phases. Running the put
-            // inside the ALS matches the MISS path, where putResponse already
-            // executes within the foreground request context.
-            await runWithRequestContext(requestCtx, () =>
-              observePhase(
+        // The re-run renders on its own pass (render-pass.ts). Its response
+        // writes go to a sink that starts from this request's response stub
+        // as of now, as a MISS's render would: they build the re-run's own
+        // response, never the visitor's, and the visitor's later writes stay
+        // off it.
+        const rerunCtx = deriveRenderPass(requestCtx, "document-revalidation", {
+          handleStore: requestCtx._handleStore,
+          sink: createRequestContext({
+            env: ctx.env,
+            request: ctx.request,
+            url,
+            variables: {},
+            initialResponse: requestCtx.res,
+            themeConfig: requestCtx._themeConfig,
+          }),
+        });
+
+        // Re-establish the request-context ALS around the whole background
+        // task: next() re-runs the full handler pipeline, and on workerd a
+        // waitUntil task runs detached from the request's I/O context, so a
+        // handler/component reading getRequestContext() would otherwise
+        // throw. Same fix as the route-level/use-cache background
+        // revalidation paths. The rango.background span (kind=
+        // document-revalidation) wraps the re-render AND the store write so
+        // the task's spans — the re-run's own rango.* set and the drain/put
+        // platform spans — nest under one explanatory parent instead of
+        // dangling under the ended foreground phases. Running the put
+        // inside the ALS matches the MISS path, where putResponse already
+        // executes within the foreground request context. No visitor made
+        // the invalidations the re-run makes: the pass's fresh-reads
+        // writer is the sink's, which sets nothing. onError marks the
+        // re-run's errors `background`, the failure caught below included.
+        runBackground(requestCtx, () =>
+          runAsBackgroundWork(rerunCtx, async () => {
+            try {
+              await observePhase(
                 PHASES.background("document-revalidation"),
                 async () => {
                   const fresh = await next();
-                  const directives = shouldCacheResponse(fresh, requestCtx);
+                  const directives = shouldCacheResponse(fresh, rerunCtx);
 
                   if (!directives || !fresh.body) return;
 
@@ -386,10 +408,10 @@ export function createDocumentCacheMiddleware<TEnv = any>(
                   // drain the fresh render fully before snapshotting tags
                   // (same render-complete barrier as the miss path).
                   const body = await new Response(fresh.body).arrayBuffer();
-                  throwIfRenderErrored(requestCtx);
+                  throwIfRenderErrored(rerunCtx);
                   // Not written when one of its tags was invalidated since
                   // the render started (#977).
-                  const tags = collectRequestTags(requestCtx);
+                  const tags = collectRequestTags(rerunCtx);
                   if (await predatesInvalidation(store, tags, start)) return;
                   await store.putResponse!(
                     cacheKey,
@@ -404,24 +426,20 @@ export function createDocumentCacheMiddleware<TEnv = any>(
                     `[DocumentCache] REVALIDATED ${typeLabel}: ${url.pathname}`,
                   );
                 },
-              ),
-            );
-          } catch (error) {
-            // The route now rewrites (route middleware): nothing to refresh
-            // this entry with.
-            if (isRewrite(error)) return;
-            // Pass requestCtx explicitly: this runs in a detached waitUntil task
-            // where the ALS context is gone, so onError only fires if we hand it
-            // the captured context (reportCacheError falls back to _getRequestContext
-            // otherwise, which is null here).
-            reportCacheError(
-              error,
-              "cache-write",
-              "[DocumentCache] revalidation",
-              requestCtx,
-            );
-          }
-        });
+              );
+            } catch (error) {
+              // The route now rewrites (route middleware): nothing to refresh
+              // this entry with.
+              if (isRewrite(error)) return;
+              reportCacheError(
+                error,
+                "cache-write",
+                "[DocumentCache] revalidation",
+                requestCtx,
+              );
+            }
+          }),
+        );
 
         return drainOnResponseCallbacks(
           addCacheStatusHeader(cached.response, "STALE"),

package/src/cache/handle-snapshot.ts

@@ -14,7 +14,7 @@ import type { HandleOwners, SegmentHandleData } from "./types.js";
 // in plain node/vitest). It is imported LAZILY inside the two async encode/decode
 // helpers below so that modules which import handle-snapshot only for the
 // plugin-rsc-free captureHandles/restoreHandles (e.g. cache-scope, on dispatch's
-// lazy response-route cache path) do not pull plugin-rsc at module load. Behavior
+// response-route path) do not pull plugin-rsc at module load. Behavior
 // is unchanged: both helpers are async and already awaited the codec.
 
 const HANDLE_ENCODE_TIMEOUT_MS = 5000;
@@ -100,7 +100,7 @@ export async function decodeHandleValue<T>(encoded: string): Promise<T | null> {
  *
  * DSL-loader pushes stay out of the CACHE WRITE: a HIT runs loaders exactly
  * as an uncached render of the same request would (cache-lookup.ts
- * resolveFreshLoadersAndYield), so replaying a recorded copy would duplicate
+ * serveStoredSegments), so replaying a recorded copy would duplicate
  * the live push. Handler pushes, including
  * handler-invoked ctx.use(Loader) bodies (skipped with their handler on a
  * HIT), are kept. The store tags loader pushes by array position at push
@@ -179,29 +179,39 @@ export type OwnedPushDelivery = (loaderId: string) => RecordAuthority;
  * owner. Neither claims its loader, so the loader's own cache() HIT still
  * delivers (the pushes holding a promise a restored copy lets through, or its
  * entry's pushes in a placeholder's place).
+ *
+ * `sent` (a partial request) names the segments the response sends. Any
+ * other segment is kept with its handler's values, as on a live walk: only
+ * its loaders' copies are restored, which follow their loader as above.
  */
 export function restoreHandles(
   handles: Record<string, SegmentHandleData>,
   handleStore: HandleStore,
   owners?: HandleOwners,
   owned?: OwnedPushDelivery,
+  sent?: ReadonlySet<string>,
 ): void {
   for (const [segId, segHandles] of Object.entries(handles)) {
     if (Object.keys(segHandles).length === 0) continue;
     const segOwners = owners?.[segId];
+    const kept = sent !== undefined && !sent.has(segId);
     if (!segOwners) {
-      handleStore.replaySegmentData(segId, segHandles);
+      if (!kept) handleStore.replaySegmentData(segId, segHandles);
       continue;
     }
     const cleared: SegmentHandleData = {};
-    for (const handleName in segHandles) cleared[handleName] = [];
+    for (const handleName in segHandles) {
+      if (!kept || segOwners[handleName]?.some(Boolean)) {
+        cleared[handleName] = [];
+      }
+    }
     handleStore.replaySegmentData(segId, cleared);
     for (const [handleName, values] of Object.entries(segHandles)) {
       const valueOwners = segOwners[handleName];
       for (let i = 0; i < values.length; i++) {
         const owner = valueOwners?.[i];
         if (!owner) {
-          handleStore.push(handleName, segId, values[i]);
+          if (!kept) handleStore.push(handleName, segId, values[i]);
           continue;
         }
         const authority = owned?.(owner);
@@ -220,13 +230,15 @@ export function restoreHandles(
  * (with or without a handles blob: a pinned loader whose capture pushed
  * nothing has no copy, and its run must still add no settled push), then
  * decode and restoreHandles. `keepIds` limits the restore to the segments a
- * boundary-scoped scope serves. A decode failure skips the restore.
+ * boundary-scoped scope serves; `sent` is restoreHandles'. A decode failure
+ * skips the restore.
  */
 export async function restoreRecordHandles(
   handleStore: HandleStore,
   record: { handles?: string; handleOwners?: HandleOwners },
   owned: OwnedPushDelivery | undefined,
   keepIds?: ReadonlySet<string>,
+  sent?: ReadonlySet<string>,
 ): Promise<void> {
   if (owned) handleStore.setRecordAuthority(owned);
   if (!record.handles) return;
@@ -237,7 +249,7 @@ export async function restoreRecordHandles(
       if (!keepIds.has(id)) delete decoded[id];
     }
   }
-  restoreHandles(decoded, handleStore, record.handleOwners, owned);
+  restoreHandles(decoded, handleStore, record.handleOwners, owned, sent);
 }
 
 /**

package/src/cache/read-through-swr.ts

@@ -117,29 +117,31 @@ export async function readThroughItem<T>(
       // span cover the write too (a slow or failing store write is part of
       // the revalidation, not an untraced tail). The foreground miss below
       // stays unwrapped: its context is already established.
+      // Reported inside the task, within wrapBackground's frame, so onError
+      // marks it `background`; rethrown so the span records the failure.
       const revalidateTask = async () => {
-        const fresh = await execute();
-        const serialized = await serialize(fresh);
-        if (serialized !== null) {
-          await setItem(key, serialized, storeOptions);
+        try {
+          const fresh = await execute();
+          const serialized = await serialize(fresh);
+          if (serialized !== null) {
+            await setItem(key, serialized, storeOptions);
+          }
+        } catch (error) {
+          reportCacheError(
+            error,
+            "stale-revalidation",
+            "[read-through] background revalidation",
+            host ?? undefined,
+          );
+          throw error;
         }
       };
       runBackground(
         host,
-        async () => {
-          try {
-            await (wrapBackground
-              ? wrapBackground(revalidateTask)
-              : revalidateTask());
-          } catch (error) {
-            reportCacheError(
-              error,
-              "stale-revalidation",
-              "[read-through] background revalidation",
-              host ?? undefined,
-            );
-          }
-        },
+        () =>
+          (wrapBackground ? wrapBackground(revalidateTask) : revalidateTask())
+            // Reported above.
+            .catch(() => {}),
         true,
       );
       return data;

package/src/cache/segment-codec.ts

@@ -129,6 +129,61 @@ export async function serializeResult(
   }
 }
 
+/** The Flight encode of a value and a decoded copy of it (teeResult). */
+export interface TeedResult {
+  /** The copy: settles when the root row arrives; later rows stream in. */
+  decoded: Promise<unknown>;
+  /** The whole encoded text, or null when the stream failed. */
+  serialized: Promise<string | null>;
+}
+
+/**
+ * Encode `value` once and decode a copy of it as the encode streams, so a
+ * "use cache" miss renders the copy as a hit renders a stored entry, and
+ * stores the same bytes. Null when the encode could not start.
+ */
+export function teeResult(
+  value: unknown,
+  onError?: (error: unknown) => void,
+): TeedResult | null {
+  try {
+    const stream = renderToReadableStream(value, {
+      temporaryReferences: createTemporaryReferenceSet(),
+      onError,
+    });
+    const [toCopy, toStore] = stream.tee();
+    const decoded = Promise.resolve(
+      createFromReadableStream(
+        toCopy,
+        { temporaryReferences: createTemporaryReferenceSet() },
+        PRESERVE_SERVER_REFS,
+      ),
+    );
+    // Awaited by the caller only after the write is scheduled.
+    decoded.catch(() => {});
+    return { decoded, serialized: streamToString(toStore).catch(() => null) };
+  } catch (error) {
+    if (INTERNAL_RANGO_DEBUG) {
+      console.warn("[segment-codec] teeResult failed:", error);
+    }
+    return null;
+  }
+}
+
+/**
+ * Flight's refusal of a value it cannot encode (a function, an `on*`
+ * function, a class instance, a local symbol), by the message its server
+ * throws; the development build words a function in a children position on
+ * its own. A component that throws, or a "use cache" guard refusal, is not
+ * one.
+ */
+const UNSUPPORTED_VALUE =
+  /^(Only plain objects|Functions cannot be passed directly to Client Components|Functions are not valid as a child of Client Components|Event handlers cannot be passed to Client Component props|Only global symbols)/;
+
+export function isUnsupportedValueError(error: unknown): boolean {
+  return error instanceof Error && UNSUPPORTED_VALUE.test(error.message);
+}
+
 /**
  * RSC-deserialize a cached result string.
  * Counterpart to serializeResult() — always receives a non-empty string.

package/src/cache/shell-snapshot.ts

@@ -383,7 +383,7 @@ export interface ShellLoaderSeedEntry {
 
 /**
  * A pin's loader. A pin is stored under its loader segment id,
- * `${shortCode}D${index}.${loaderId}` (fresh.ts resolveLoaders), and a
+ * `${shortCode}D${index}.${loaderId}` (resolveOwnerLoaders), and a
  * shortCode holds no "D" and no "." (server/context.ts getShortCode: M, L, P,
  * R, C, I and digits), so the first `D<index>.` ends it. A loader id can hold
  * both.
@@ -462,7 +462,7 @@ export const SHELL_HANDLES_RECORD_KEY = "handles";
 
 /**
  * The `handles` record of a prerender-served entry, which a HIT tail restores
- * after the prerender store's handles (cache-lookup.ts yieldFromStore), or
+ * after the prerender store's handles (cache-lookup.ts decodeStoredEntry), or
  * undefined: an entry with a doc record, or one written before the record
  * existed (v0.21), which serves as it did.
  */

package/src/cache/tag-invalidation.ts

@@ -36,7 +36,10 @@
  * predatesInvalidation, and docs/design/caching.md "Read-your-own-writes".
  */
 
-import { _getRequestContext } from "../server/request-context.js";
+import {
+  _getRequestContext,
+  isBackgroundWork,
+} from "../server/request-context.js";
 import { reportingAsync } from "./cache-error.js";
 import { normalizeTags } from "./cache-tag.js";
 import type { SegmentCacheStore } from "./types.js";
@@ -136,7 +139,8 @@ function warnPartialTagStore(fn: string, incapable: number): void {
  */
 function markFreshReads(stores: SegmentCacheStore[]): void {
   const ctx = _getRequestContext();
-  if (!ctx?._setFreshReadsCookie) return;
+  // No visitor made an invalidation in background work (runAsBackgroundWork).
+  if (!ctx?._setFreshReadsCookie || isBackgroundWork()) return;
   let windowMs = 0;
   for (const store of stores) {
     windowMs = Math.max(windowMs, store.freshReadsWindowMs ?? 0);

package/src/cache/taint.ts

@@ -21,9 +21,11 @@ export function isTainted(value: unknown): boolean {
 }
 
 /**
- * Symbol stamped on tainted ctx objects PASSED AS ARGUMENTS to a "use cache"
- * function during its execution. ctx.set(), ctx.header(), etc. check this
- * flag and throw if present — those side effects are lost on cache hit.
+ * Symbol stamped on tainted handler and middleware ctx objects PASSED AS
+ * ARGUMENTS to a "use cache" function during its execution. ctx.set(),
+ * ctx.header(), etc. check this flag and throw if present — those side
+ * effects are lost on cache hit. A request context passed as an argument is
+ * not stamped (registerCachedFunction in cache-runtime.ts).
  *
  * Argument objects only. Ambient access (cookies()/headers() and ctx methods
  * reached via getRequestContext()) is guarded by the AsyncLocalStorage scope

package/src/cache/types.ts

@@ -96,10 +96,14 @@ export interface SegmentCacheStore<TEnv = unknown> {
    * Return value becomes the final cache key (unless route overrides with `key` option).
    *
    * Resolution priority:
-   * 1. Route-level `key` function (full override)
+   * 1. Route-level `key` function (replaces the URL part; the request kind stays)
    * 2. Store-level `keyGenerator` (modifies default key)
    * 3. Default key generation (prefix:pathname:params)
    *
+   * Keep `defaultKey` in the result: its prefix names the request kind (a
+   * document, a navigation or an intercept navigation), whose records hold
+   * different segments. A result without it gives every kind one record.
+   *
    * Return `defaultKey` unchanged to leave a request unpartitioned. An empty
    * string is not a key: where the result partitions a nested cache() on
    * another store, or a ppr shell, it fails key resolution, so the request
@@ -293,7 +297,7 @@ export interface SegmentCacheStore<TEnv = unknown> {
   /**
    * Declares the shell family present-but-inert: getShell/putShell exist but
    * no-op (a custom store whose backing tier is conditionally unavailable).
-   * scheduleShellCapture skips captures whose only write target is inert —
+   * planShellCapture skips captures whose only write target is inert —
    * the background render would be dead work that still occupies the
    * per-isolate serialized capture queue (a promise-heavy route bakes for
    * seconds per MISS with nothing stored). Absent/false means the family,
@@ -659,7 +663,7 @@ export type ShellSnapshotFamily = "segment" | "loader" | "handles";
  * format (CachedEntryData `handles` + `handleOwners`). A Prerender + ppr
  * route's handler layer comes from the prerender store, whose build-time
  * entry has no loader push, so the entry keeps these for the HIT to restore
- * as a doc record's (issue #1057, yieldFromStore in cache-lookup.ts). An
+ * as a doc record's (issue #1057, decodeStoredEntry in cache-lookup.ts). An
  * entry written before it (v0.21) has none and serves as it did.
  */
 export type ShellSnapshotHandlesValue = Pick<