@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.140

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

@@ -30,23 +30,15 @@
  *         |
  *         v (async, doesn't block response)
  *   +---------------------------+
- *   | Create fresh handleStore |  Isolate from response stream
+ *   | Create fresh context     |  Fresh handleStore, handlerContext,
+ *   | (full isolation)         |  and loaderPromises map
  *   +---------------------------+
  *         |
  *         v
- *   +---------------------+
- *   | isFullMatch?        |
- *   +---------------------+
- *         |
- *   +-----+-----+
- *   |           |
- *  yes          no
- *   |           |
- *   v           v
- * resolveAll  resolveWithRevalidation
- * Segments    + resolveIntercepts
- *   |           |
- *   +-----------+
+ *   +---------------------------+
+ *   | resolveAllSegments()    |  Fresh resolution (no revalidation)
+ *   | + resolveIntercepts()   |  Ensures complete components
+ *   +---------------------------+
  *         |
  *         v
  *   +---------------------------+
@@ -90,33 +82,33 @@
  * ISOLATION FROM RESPONSE
  * =======================
  *
- * The background revalidation creates a fresh handleStore:
- *
- *   requestCtx._handleStore = createHandleStore();
+ * Background revalidation creates fully isolated context:
+ *   - Fresh handleStore (prevents polluting the response stream)
+ *   - Fresh handlerContext + loaderPromises (prevents reusing memoized
+ *     loader results from the foreground pass)
+ *   - handleStore is saved/restored in try/finally
  *
- * This prevents background handle.push() calls from:
- *   - Polluting the current response stream
- *   - Causing duplicate data in the client
- *   - Creating race conditions
+ * This matches the proactive caching pattern in cache-store.ts.
  *
  *
- * FULL VS PARTIAL REVALIDATION
- * ============================
+ * FRESH RESOLUTION (NO REVALIDATION)
+ * ===================================
  *
- * Full Match (document request):
- *   - Simple resolveAllSegments()
- *   - No need to compare with previous state
- *
- * Partial Match (navigation):
- *   - resolveAllSegmentsWithRevalidation()
- *   - Also resolves intercept segments if applicable
- *   - More complex but handles all scenarios
+ * Both full and partial requests use resolveAllSegments() (without
+ * revalidation logic) to ensure all segments have complete components.
+ * Using revalidation-aware resolution would produce null components
+ * for skipped segments, which would corrupt the cache entry.
  */
 import type { ResolvedSegment } from "../../types.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
-import { debugLog, debugWarn } from "../logging.js";
+import { debugLog, debugWarn, getOrCreateRequestId } from "../logging.js";
+import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
+import {
+  runWithRequestContext,
+  type RequestContext,
+} from "../../server/request-context.js";
 
 /**
  * Creates background revalidation middleware
@@ -128,10 +120,10 @@ import { debugLog, debugWarn } from "../logging.js";
  */
 export function withBackgroundRevalidation<TEnv>(
   ctx: MatchContext<TEnv>,
-  state: MatchPipelineState
+  state: MatchPipelineState,
 ): GeneratorMiddleware<ResolvedSegment> {
   return async function* (
-    source: AsyncGenerator<ResolvedSegment>
+    source: AsyncGenerator<ResolvedSegment>,
   ): AsyncGenerator<ResolvedSegment> {
     // Pass through all segments unchanged
     for await (const segment of source) {
@@ -148,95 +140,127 @@ export function withBackgroundRevalidation<TEnv>(
     const {
       getRequestContext,
       createHandleStore,
-      resolveAllSegmentsWithRevalidation,
+      createHandlerContext,
+      setupLoaderAccess,
       resolveAllSegments,
       resolveInterceptEntry,
     } = getRouterContext<TEnv>();
 
     const requestCtx = 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,
       });
-      try {
-        // Create a fresh handleStore for background revalidation
-        // to avoid polluting the current response's handle stream
-        if (requestCtx) {
-          requestCtx._handleStore = createHandleStore();
-        }
 
-        let freshSegments: ResolvedSegment[];
+      // 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();
 
-        if (ctx.isFullMatch) {
-          // Full match (document request) - simple resolution
-          freshSegments = await resolveAllSegments(
-            ctx.entries,
-            ctx.routeKey,
-            ctx.matched.params,
-            ctx.handlerContext,
-            ctx.loaderPromises
-          );
-        } else {
-          // Partial match (navigation) - resolution with revalidation
-          const freshResult = await resolveAllSegmentsWithRevalidation(
-            ctx.entries,
-            ctx.routeKey,
-            ctx.matched.params,
-            ctx.handlerContext,
-            ctx.clientSegmentSet,
-            ctx.prevParams,
-            ctx.request,
-            ctx.prevUrl,
-            ctx.url,
-            ctx.loaderPromises,
-            ctx.actionContext,
-            ctx.interceptResult,
-            ctx.localRouteName,
-            ctx.pathname
-          );
+      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);
 
-          freshSegments = freshResult.segments;
+        // 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(
+          requestCtx as RequestContext<TEnv>,
+          () =>
+            ctx.Store.run(() =>
+              resolveAllSegments(
+                ctx.entries,
+                ctx.routeKey,
+                ctx.matched.params,
+                freshHandlerContext,
+                freshLoaderPromises,
+                { skipLoaders: true },
+              ),
+            ),
+        );
 
-          // For intercept revalidation, also resolve fresh intercept segments
-          if (ctx.interceptResult) {
-            const freshInterceptSegments = await resolveInterceptEntry(
-              ctx.interceptResult.intercept,
-              ctx.interceptResult.entry,
-              ctx.matched.params,
-              ctx.handlerContext,
-              true,
-              {
-                clientSegmentIds: ctx.clientSegmentSet,
-                prevParams: ctx.prevParams,
-                request: ctx.request,
-                prevUrl: ctx.prevUrl,
-                nextUrl: ctx.url,
-                routeKey: ctx.routeKey,
-                actionContext: ctx.actionContext,
-                stale: false,
-              }
-            );
-            freshSegments = [...freshSegments, ...freshInterceptSegments];
-          }
+        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,
-          freshSegments,
-          ctx.isIntercept
+          completeSegments,
+          ctx.isIntercept,
         );
+        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}`,
+          );
+        }
         debugLog("backgroundRevalidation", "revalidation complete", {
           pathname: ctx.pathname,
         });
       } catch (error) {
+        if (INTERNAL_RANGO_DEBUG) {
+          const dur = performance.now() - start;
+          console.log(
+            `[RSC Background][req:${reqId}] SWR revalidation ${ctx.pathname} FAILED (${dur.toFixed(2)}ms) error=${String(error)}`,
+          );
+        }
         debugWarn("backgroundRevalidation", "revalidation failed", {
           pathname: ctx.pathname,
           error: String(error),
         });
+      } finally {
+        requestCtx._handleStore = originalHandleStore;
+        ctx.Store.metrics = savedMetrics;
       }
     });
   };