@rangojs/router 0.16.0 → 0.18.0

package/src/router/match-middleware/background-revalidation.ts

@@ -82,13 +82,13 @@
  * ISOLATION FROM RESPONSE
  * =======================
  *
- * Background revalidation creates fully isolated context:
- *   - Fresh handleStore (prevents polluting the response stream)
+ * Background revalidation re-renders through rerenderAndCacheRoute (shared
+ * with proactive caching in cache-store.ts):
+ *   - Derived request context with its own handleStore, transition({ when })
+ *     predicates and no perf metrics (the shared fields are never touched;
+ *     the foreground is still producing the page)
  *   - Fresh handlerContext + loaderPromises (prevents reusing memoized
  *     loader results from the foreground pass)
- *   - handleStore is saved/restored in try/finally
- *
- * This matches the proactive caching pattern in cache-store.ts.
  *
  *
  * FRESH RESOLUTION (NO REVALIDATION)
@@ -101,15 +101,163 @@
  */
 import type { ResolvedSegment } from "../../types.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
-import { getRouterContext } from "../router-context.js";
+import { getRouterContext, type RouterContext } from "../router-context.js";
+import type { CacheScope } from "../../cache/cache-scope.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 import { debugLog, debugWarn, getOrCreateRequestId } from "../logging.js";
 import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
+import { getContext } from "../../server/context.js";
 import {
+  createRequestContext,
   runWithRequestContext,
   type RequestContext,
 } from "../../server/request-context.js";
 
+/**
+ * Re-render a cached route in the background and write it with
+ * cacheScope.cacheRoute: the stale-hit refresh below and proactive caching
+ * (cache-store.ts). Returns the number of segments written.
+ *
+ * A render whose status is not 200 (an error or notFound boundary resolved)
+ * is not written and returns 0, as a non-200 MISS is not cached
+ * (cache-store.ts): the entry it would replace keeps serving until a later
+ * refresh succeeds or it expires. Nothing is held in process; a store's own
+ * revalidation marker (CFCacheStore's REVALIDATING) re-arms after
+ * MAX_REVALIDATION_INTERVAL, as after a refresh that throws.
+ *
+ * Runs on a DERIVED request context that owns the per-render state the
+ * foreground reads while it is still producing the page (a stale HIT re-runs
+ * its loaders; a proactive render starts once the Response exists, while its
+ * body streams):
+ *   - _handleStore: read late (loader pushes and aux-lane tracking in
+ *     loader-resolution.ts, nested cache restores and captures in
+ *     cache-scope.ts), so a swap sent live pushes into this render.
+ *     setupLoaderAccess binds the store at setup, so it runs inside the
+ *     derived context too.
+ *   - _transitionWhen: fresh resolution appends transition({ when })
+ *     predicates; the foreground's gateTransitions reads the array after the
+ *     match, and a stale HIT (which replays the stored transition) must not
+ *     evaluate this render's predicates.
+ *   - _metricsStore: undefined, and the DSL store below has `metrics` unset
+ *     (track() reads that one), so nothing lands on the foreground's perf
+ *     timeline. ctx.Store.run closes over ctx.Store, so the derived store
+ *     needs its own run.
+ *   - response writes (headers, cookies, status, onResponse callbacks) go to
+ *     a throwaway context (whose status gates the write, above) and are
+ *     dropped: a layout above the cache() boundary is outside the header
+ *     guard and an error boundary sets a status, so they would otherwise
+ *     reach the live response.
+ * runWithRequestContext also re-establishes the request ALS, which a waitUntil
+ * task on workerd loses; the DSL store is a different ALS (build context).
+ */
+export async function rerenderAndCacheRoute<TEnv>(
+  ctx: MatchContext<TEnv>,
+  requestCtx: RequestContext<TEnv>,
+  cacheScope: CacheScope,
+  routerCtx: RouterContext<TEnv>,
+): Promise<number> {
+  const handleStore = routerCtx.createHandleStore();
+  // Response writes land in a throwaway context nothing merges or drains. Its
+  // mutators are closures over its own stub, and they keep the same guards.
+  const sink = createRequestContext({
+    env: ctx.env,
+    request: ctx.request,
+    url: ctx.url,
+    variables: {},
+    themeConfig: requestCtx._themeConfig,
+  });
+  const renderCtx: RequestContext<TEnv> = Object.assign(
+    Object.create(requestCtx, {
+      res: Object.getOwnPropertyDescriptor(sink, "res")!,
+    }),
+    {
+      _handleStore: handleStore,
+      _transitionWhen: [],
+      _metricsStore: undefined,
+      _onResponseCallbacks: [],
+      header: sink.header,
+      setCookie: sink.setCookie,
+      deleteCookie: sink.deleteCookie,
+      setStatus: sink.setStatus,
+      _setStatus: sink._setStatus,
+      setTheme: sink.setTheme,
+      _rotateStateCookie: sink._rotateStateCookie,
+      _setKeepCacheDirective: sink._setKeepCacheDirective,
+    },
+  );
+  const store = Object.assign(Object.create(ctx.Store), { metrics: undefined });
+  const runInStore = <T>(fn: () => T): T =>
+    getContext().runWithStore(
+      store,
+      store.namespace || "#router",
+      store.parent,
+      fn,
+    );
+  return runWithRequestContext(renderCtx, async () => {
+    const handlerContext = routerCtx.createHandlerContext(
+      ctx.matched.params,
+      ctx.request,
+      ctx.url.searchParams,
+      ctx.pathname,
+      ctx.url,
+      ctx.env,
+      ctx.routeMap,
+      ctx.matched.routeKey,
+      ctx.matched.responseType,
+      ctx.matched.pt === true,
+    );
+    const loaderPromises = new Map<string, Promise<any>>();
+    routerCtx.setupLoaderAccess(handlerContext, loaderPromises);
+
+    const segments = await runInStore(() =>
+      routerCtx.resolveAllSegments(
+        ctx.entries,
+        ctx.routeKey,
+        ctx.matched.params,
+        handlerContext,
+        loaderPromises,
+        { skipLoaders: true },
+      ),
+    );
+    if (ctx.interceptResult) {
+      segments.push(
+        ...(await runInStore(() =>
+          routerCtx.resolveInterceptEntry(
+            ctx.interceptResult!.intercept,
+            ctx.interceptResult!.entry,
+            ctx.matched.params,
+            handlerContext,
+            true, // belongsToRoute
+            undefined, // no revalidationContext: render fresh
+            // Skip intercept middleware: the foreground already ran it.
+            // Re-running it here would double its side effects, and a
+            // short-circuit Response would abort the write.
+            { skipMiddleware: true },
+          ),
+        )),
+      );
+    }
+
+    handleStore.seal();
+    // Boundaries set 500/404 through _setStatus (catchSegmentError), which
+    // lands on the sink.
+    if (sink.res.status !== 200) {
+      debugLog("backgroundRevalidation", "skipping cache for non-200 render", {
+        status: sink.res.status,
+        pathname: ctx.pathname,
+      });
+      return 0;
+    }
+    await cacheScope.cacheRoute(
+      ctx.pathname,
+      ctx.matched.params,
+      segments,
+      ctx.isIntercept,
+    );
+    return segments.length;
+  });
+}
+
 /**
  * Creates background revalidation middleware
  *
@@ -137,111 +285,31 @@ export function withBackgroundRevalidation<TEnv>(
       return;
     }
 
-    const {
-      getRequestContext,
-      createHandleStore,
-      createHandlerContext,
-      setupLoaderAccess,
-      resolveAllSegments,
-      resolveInterceptEntry,
-    } = getRouterContext<TEnv>();
-
-    const requestCtx = getRequestContext();
+    const routerCtx = getRouterContext<TEnv>();
+    const requestCtx = routerCtx.getRequestContext();
     const cacheScope = ctx.cacheScope;
     const reqId = INTERNAL_RANGO_DEBUG
       ? getOrCreateRequestId(ctx.request)
       : undefined;
 
     requestCtx?.waitUntil(async () => {
-      // Prevent background metrics from polluting foreground timeline.
-      // The foreground uses its own metricsStore reference directly (via
-      // appendMetric), so nulling Store.metrics only affects track() calls
-      // inside this background Store.run() scope.
-      const savedMetrics = ctx.Store.metrics;
-      ctx.Store.metrics = undefined;
-
       const start = performance.now();
       debugLog("backgroundRevalidation", "revalidating stale route", {
         pathname: ctx.pathname,
         fullMatch: ctx.isFullMatch,
       });
 
-      // Save and replace handleStore to avoid polluting the response stream.
-      // Restore in finally (same pattern as proactive caching in cache-store).
-      const originalHandleStore = requestCtx._handleStore;
-      requestCtx._handleStore = createHandleStore();
-
       try {
-        const freshHandlerContext = createHandlerContext(
-          ctx.matched.params,
-          ctx.request,
-          ctx.url.searchParams,
-          ctx.pathname,
-          ctx.url,
-          ctx.env,
-          ctx.routeMap,
-          ctx.matched.routeKey,
-          ctx.matched.responseType,
-          ctx.matched.pt === true,
-        );
-        const freshLoaderPromises = new Map<string, Promise<any>>();
-        setupLoaderAccess(freshHandlerContext, freshLoaderPromises);
-
-        // Re-establish the request-context ALS around the re-render. ctx.Store
-        // is a different ALS (DSL build context); on workerd a waitUntil task
-        // runs detached from the request's I/O context, so a handler/component
-        // that reads the ambient getRequestContext() during this background
-        // re-render would otherwise throw "called outside of a request context".
-        const freshSegments = await runWithRequestContext(
+        const count = await rerenderAndCacheRoute(
+          ctx,
           requestCtx as RequestContext<TEnv>,
-          () =>
-            ctx.Store.run(() =>
-              resolveAllSegments(
-                ctx.entries,
-                ctx.routeKey,
-                ctx.matched.params,
-                freshHandlerContext,
-                freshLoaderPromises,
-                { skipLoaders: true },
-              ),
-            ),
-        );
-
-        let freshInterceptSegments: ResolvedSegment[] = [];
-        if (ctx.interceptResult) {
-          freshInterceptSegments = await runWithRequestContext(
-            requestCtx as RequestContext<TEnv>,
-            () =>
-              ctx.Store.run(() =>
-                resolveInterceptEntry(
-                  ctx.interceptResult!.intercept,
-                  ctx.interceptResult!.entry,
-                  ctx.matched.params,
-                  freshHandlerContext,
-                  true,
-                  undefined,
-                  // Skip intercept middleware: this is a post-response background
-                  // re-render to refresh a stale cached route. The foreground
-                  // already ran the middleware; re-running it would double its
-                  // side effects and a short-circuit Response would abort the write.
-                  { skipMiddleware: true },
-                ),
-              ),
-          );
-        }
-
-        const completeSegments = [...freshSegments, ...freshInterceptSegments];
-        requestCtx._handleStore.seal();
-        await cacheScope.cacheRoute(
-          ctx.pathname,
-          ctx.matched.params,
-          completeSegments,
-          ctx.isIntercept,
+          cacheScope,
+          routerCtx,
         );
         if (INTERNAL_RANGO_DEBUG) {
           const dur = performance.now() - start;
           console.log(
-            `[RSC Background][req:${reqId}] SWR revalidation ${ctx.pathname} (${dur.toFixed(2)}ms) segments=${completeSegments.length}`,
+            `[RSC Background][req:${reqId}] SWR revalidation ${ctx.pathname} (${dur.toFixed(2)}ms) segments=${count}`,
           );
         }
         debugLog("backgroundRevalidation", "revalidation complete", {
@@ -258,9 +326,6 @@ export function withBackgroundRevalidation<TEnv>(
           pathname: ctx.pathname,
           error: String(error),
         });
-      } finally {
-        requestCtx._handleStore = originalHandleStore;
-        ctx.Store.metrics = savedMetrics;
       }
     });
   };

package/src/router/match-middleware/cache-lookup.ts

@@ -91,7 +91,7 @@
  *   - Request object
  *   - Action context (if POST)
  */
-import type { ResolvedSegment } from "../../types.js";
+import type { InternalHandlerContext, ResolvedSegment } from "../../types.js";
 import type { EntryData } from "../../server/context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext, type RouterContext } from "../router-context.js";
@@ -103,7 +103,11 @@ import {
   _getRequestContext,
   type RequestContext,
 } from "../../server/request-context.js";
-import { createShellImplicitDocScope } from "../../cache/cache-scope.js";
+import {
+  createShellImplicitDocScope,
+  type CacheScope,
+} from "../../cache/cache-scope.js";
+import { ShellRecordUnavailableError } from "../../cache/shell-snapshot.js";
 import { prerenderStoreShortCircuits } from "../navigation-snapshot.js";
 import { paramsEqual } from "../params-util.js";
 
@@ -160,6 +164,7 @@ async function ensurePrerenderDeps() {
 // awaits before reaching this point (workerd can disrupt ALS mid-pipeline).
 async function* resolveFreshLoadersAndYield<TEnv>(
   ctx: MatchContext<TEnv>,
+  entries: EntryData[],
   state: MatchPipelineState,
   pipelineStart: number,
   ms: MatchContext<TEnv>["metricsStore"],
@@ -171,7 +176,7 @@ async function* resolveFreshLoadersAndYield<TEnv>(
   if (ctx.isFullMatch) {
     if (resolveLoadersOnly) {
       const loaderSegments = await ctx.Store.run(() =>
-        resolveLoadersOnly(ctx.entries, ctx.handlerContext),
+        resolveLoadersOnly(entries, ctx.handlerContext),
       );
       state.matchedIds = state.cachedMatchedIds!;
       for (const segment of loaderSegments) {
@@ -184,7 +189,7 @@ async function* resolveFreshLoadersAndYield<TEnv>(
     if (resolveLoadersOnlyWithRevalidation) {
       const loaderResult = await ctx.Store.run(() =>
         resolveLoadersOnlyWithRevalidation(
-          ctx.entries,
+          entries,
           ctx.handlerContext,
           ctx.clientSegmentSet,
           ctx.prevParams,
@@ -301,6 +306,7 @@ async function* yieldFromStore<TEnv>(
   // Resolve loaders fresh (loaders are never pre-rendered/cached).
   yield* resolveFreshLoadersAndYield(
     ctx,
+    ctx.entries,
     state,
     pipelineStart,
     ctx.metricsStore,
@@ -448,6 +454,8 @@ export function withCacheLookup<TEnv>(
       buildEntryRevalidateMap,
       resolveLoadersOnlyWithRevalidation,
       resolveLoadersOnly,
+      resolveAllSegments,
+      resolveAllSegmentsWithRevalidation,
     } = getRouterContext<TEnv>();
 
     if (prerenderStoreShortCircuits(ctx.matched.pr, ctx.request)) {
@@ -501,6 +509,15 @@ export function withCacheLookup<TEnv>(
       }
     }
 
+    // A document HIT tail replays the handler layer through the implicit doc
+    // scope and never runs a handler: without that scope (a context that lost
+    // the marker before the scope resolved), fail like a lookup miss instead
+    // of falling through to the handlers below.
+    const tailMarker = pipelineReqCtx?._shellImplicitCache;
+    if (tailMarker?.docTail && !ctx.cacheScope?.isShellImplicitDocScope) {
+      throw new ShellRecordUnavailableError(tailMarker.fixedDocKey);
+    }
+
     if (ctx.isAction || !ctx.cacheScope?.enabled) {
       yield* source;
       if (ms) {
@@ -513,13 +530,20 @@ export function withCacheLookup<TEnv>(
       return;
     }
 
+    // A record's loader-owned handle values claim their loader, so its own
+    // cache() HIT does not replay them again (restoreHandles).
+    const claimLoaderPushes = (ctx.handlerContext as InternalHandlerContext)
+      ._claimLoaderPushes;
     const explicitLookup = await ctx.cacheScope.lookupRouteDetailed(
       ctx.pathname,
       ctx.matched.params,
       ctx.isIntercept,
+      claimLoaderPushes,
     );
     let cacheResult =
       explicitLookup.status === "hit" ? explicitLookup.result : null;
+    // The scope whose record answered decides which entries it covers.
+    let hitScope: CacheScope = ctx.cacheScope;
 
     // PPR navigation replay composed with a route-derived cache() scope. The
     // explicit tier stays authoritative: its hit serves under its own
@@ -553,9 +577,13 @@ export function withCacheLookup<TEnv>(
         // no-eligible-snapshot path purely for truthful status) inert: a
         // store-less marker minting a doc scope here would resolve the APP
         // store and read the REAL doc: partition — a cross-partition serve.
-        cacheResult = await createShellImplicitDocScope(
-          replayMarker,
-        ).lookupRoute(ctx.pathname, ctx.matched.params, ctx.isIntercept);
+        hitScope = createShellImplicitDocScope(replayMarker);
+        cacheResult = await hitScope.lookupRoute(
+          ctx.pathname,
+          ctx.matched.params,
+          ctx.isIntercept,
+          claimLoaderPushes,
+        );
       } else if (explicitLookup.status === "bypass") {
         // condition() refused at lookup time (the gate only pre-decides the
         // static cache(false) case) — report cache-disabled truthfully.
@@ -567,6 +595,13 @@ export function withCacheLookup<TEnv>(
     }
 
     if (!cacheResult) {
+      // A document shell HIT tail replays the handler layer from the entry's
+      // doc record and must never run a handler behind the committed prelude:
+      // a record that did not hit (it failed to decode, or the entry lost it)
+      // ends the tail here; serveShellHit degrades the response.
+      if (replayMarker?.docTail) {
+        throw new ShellRecordUnavailableError(replayMarker.fixedDocKey);
+      }
       yield* source;
       if (ms) {
         ms.metrics.push({
@@ -578,11 +613,68 @@ export function withCacheLookup<TEnv>(
       return;
     }
 
+    // Entries above the cache() boundary are not in the record: resolve them
+    // fresh, exactly as an uncached render of this request would.
+    const boundaryIndex =
+      hitScope.boundary === undefined
+        ? 0
+        : Math.max(
+            0,
+            ctx.entries.findIndex((e) => e.shortCode === hitScope.boundary),
+          );
+    let liveSegments: ResolvedSegment[] = [];
+    let liveMatchedIds: string[] = [];
+    if (boundaryIndex > 0) {
+      const liveEntries = ctx.entries.slice(0, boundaryIndex);
+      const live: { segments: ResolvedSegment[]; matchedIds: string[] } =
+        await ctx.Store.run(async () => {
+          if (!ctx.isFullMatch) {
+            return resolveAllSegmentsWithRevalidation(
+              liveEntries,
+              ctx.routeKey,
+              ctx.matched.params,
+              ctx.handlerContext,
+              ctx.clientSegmentSet,
+              ctx.prevParams,
+              ctx.request,
+              ctx.prevUrl,
+              ctx.url,
+              ctx.actionContext,
+              ctx.interceptResult,
+              ctx.localRouteName,
+              ctx.pathname,
+              ctx.stale,
+              ctx.entries,
+            );
+          }
+          // The full chain keeps a bare cache() marker, which also sits in
+          // its layout's orphan list, out of the live pass: the record
+          // supplies it and its subtree (issue #918).
+          const segments = await resolveAllSegments(
+            liveEntries,
+            ctx.routeKey,
+            ctx.matched.params,
+            ctx.handlerContext,
+            ctx.loaderPromises,
+            { chain: ctx.entries },
+          );
+          return { segments, matchedIds: segments.map((s) => s.id) };
+        });
+      // The record supplies every covered segment.
+      liveSegments = live.segments.filter(
+        (s) => !hitScope.covers(s.id, s.namespace),
+      );
+      liveMatchedIds = live.matchedIds.filter((id) => !hitScope.covers(id));
+    }
+
     state.cacheHit = true;
     state.cacheSource = "runtime";
     state.shouldRevalidate = cacheResult.shouldRevalidate;
     state.cachedSegments = cacheResult.segments;
-    state.cachedMatchedIds = cacheResult.segments.map((s) => s.id);
+    state.cachedMatchedIds = [
+      ...liveMatchedIds,
+      ...cacheResult.segments.map((s) => s.id),
+    ];
     const pprTransitionDecisions = pipelineReqCtx?._pprTransitionDecisions;
 
     const canCheckSegmentRevalidation =
@@ -593,6 +685,8 @@ export function withCacheLookup<TEnv>(
       ? buildEntryRevalidateMap(ctx.entries)
       : undefined;
 
+    yield* liveSegments;
+
     for (const segment of cacheResult.segments) {
       if (!ctx.clientSegmentSet.has(segment.id)) {
         if (isTraceActive()) {
@@ -708,13 +802,19 @@ export function withCacheLookup<TEnv>(
       if (barrierReqCtx._treeHasStreaming === undefined) {
         barrierReqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
       }
-      barrierReqCtx._resolveRenderBarrier(cacheResult.segments);
+      barrierReqCtx._resolveRenderBarrier(
+        liveSegments.length > 0
+          ? [...liveSegments, ...cacheResult.segments]
+          : cacheResult.segments,
+      );
     }
 
     // Resolve loaders fresh (loaders are never cached). Shared with the
-    // prerender-store path via resolveFreshLoadersAndYield.
+    // prerender-store path via resolveFreshLoadersAndYield. The live pass
+    // already resolved the loaders of the entries above the boundary.
     yield* resolveFreshLoadersAndYield(
       ctx,
+      ctx.entries.slice(boundaryIndex),
       state,
       pipelineStart,
       ms,