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

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

@@ -101,10 +101,14 @@
  *   - Non-GET request (only GET requests are cacheable)
  */
 import type { ResolvedSegment } from "../../types.js";
-import { getRequestContext } from "../../server/request-context.js";
+import {
+  getRequestContext,
+  runWithRequestContext,
+} from "../../server/request-context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
-import { debugLog, debugWarn } from "../logging.js";
+import { debugLog, debugWarn, getOrCreateRequestId } from "../logging.js";
+import { INTERNAL_RANGO_DEBUG } from "../../internal-debug.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 
 /**
@@ -120,21 +124,16 @@ export function withCacheStore<TEnv>(
   return async function* (
     source: AsyncGenerator<ResolvedSegment>,
   ): AsyncGenerator<ResolvedSegment> {
-    const pipelineStart = performance.now();
     const ms = ctx.metricsStore;
 
-    // Collect all segments while passing them through
     const allSegments: ResolvedSegment[] = [];
     for await (const segment of source) {
       allSegments.push(segment);
       yield segment;
     }
 
-    // Skip caching if:
-    // 1. Cache miss but cache scope is disabled
-    // 2. This is an action (actions don't cache)
-    // 3. Cache was already hit (no need to re-cache)
-    // 4. Non-GET request (only cache GET requests)
+    const ownStart = performance.now();
+
     if (
       !ctx.cacheScope?.enabled ||
       ctx.isAction ||
@@ -142,25 +141,39 @@ export function withCacheStore<TEnv>(
       ctx.request.method !== "GET"
     ) {
       if (ms) {
-        ms.metrics.push({ label: "pipeline:cache-store", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+        ms.metrics.push({
+          label: "pipeline:cache-store",
+          duration: performance.now() - ownStart,
+          startTime: ownStart - ms.requestStart,
+        });
       }
       return;
     }
 
     const {
       createHandlerContext,
-      setupLoaderAccessSilent,
+      setupLoaderAccess,
       resolveAllSegments,
       resolveInterceptEntry,
+      createHandleStore,
     } = getRouterContext<TEnv>();
 
-    // Combine main segments with intercept segments
-    const allSegmentsToCache = [...allSegments, ...state.interceptSegments];
+    // On a fresh intercept miss the intercept slot segments flow through
+    // `source` into allSegments AND are also recorded on state.interceptSegments.
+    // Dedup by id so each segment is cached once — cacheRoute serializes the
+    // array verbatim (no id-dedup), so an un-deduped append doubles the intercept
+    // segment in the cached entry, re-rendering the slot twice on the next hit.
+    const seenSegmentIds = new Set(allSegments.map((s) => s.id));
+    const allSegmentsToCache = [
+      ...allSegments,
+      ...state.interceptSegments.filter((s) => !seenSegmentIds.has(s.id)),
+    ];
 
-    // Check if any non-loader segments have null components
-    // This happens when client already had those segments (partial navigation)
     const hasNullComponents = allSegmentsToCache.some(
-      (s) => s.component === null && s.type !== "loader",
+      (s) =>
+        s.component === null &&
+        s.type !== "loader" &&
+        ctx.clientSegmentSet.has(s.id),
     );
 
     const requestCtx = getRequestContext();
@@ -168,10 +181,22 @@ export function withCacheStore<TEnv>(
 
     const cacheScope = ctx.cacheScope;
 
-    // Register onResponse callback to skip caching for non-200 responses
-    // Note: error/notFound status codes are set elsewhere (not caching-specific)
+    // Record the route's segment-DSL cache tags into the request tag union NOW,
+    // synchronously in the pipeline. The actual store write (cacheRoute) runs in
+    // requestCtx.waitUntil() below — and the proactive path re-resolves the whole
+    // tree first — so cacheRoute's own tag recording races the document cache's
+    // post-body-drain snapshot of _requestTags. On a first-write miss the document
+    // tag union could miss these tags and revalidateTag()/updateTag() would not
+    // invalidate the cached document. Recording here (before the snapshot) closes
+    // the window for both the direct and proactive write paths; the duplicate
+    // record inside cacheRoute is idempotent.
+    cacheScope.recordTags(requestCtx);
+
+    const reqId = INTERNAL_RANGO_DEBUG
+      ? getOrCreateRequestId(ctx.request)
+      : undefined;
+
     requestCtx.onResponse((response) => {
-      // Only cache successful responses
       if (response.status !== 200) {
         debugLog("cacheStore", "skipping cache for non-200 response", {
           status: response.status,
@@ -181,57 +206,74 @@ export function withCacheStore<TEnv>(
       }
 
       if (hasNullComponents) {
-        // Proactive caching: render all segments fresh in background
-        // This ensures cache has complete components for future requests
         requestCtx.waitUntil(async () => {
+          const savedMetrics = ctx.Store.metrics;
+          ctx.Store.metrics = undefined;
+
+          const start = performance.now();
           debugLog("cacheStore", "proactive caching started", {
             pathname: ctx.pathname,
           });
+          const originalHandleStore = requestCtx._handleStore;
+          requestCtx._handleStore = createHandleStore();
           try {
-            // Create fresh context for proactive caching
-            // This prevents handle data from polluting the response stream
             const proactiveHandlerContext = createHandlerContext(
               ctx.matched.params,
               ctx.request,
               ctx.url.searchParams,
               ctx.pathname,
               ctx.url,
-              ctx.bindings,
+              ctx.env,
               ctx.routeMap,
-              ctx.matched.routeKey
+              ctx.matched.routeKey,
+              ctx.matched.responseType,
+              ctx.matched.pt === true,
             );
             const proactiveLoaderPromises = new Map<string, Promise<any>>();
 
-            // Set up loader access that ignores handle pushes
-            setupLoaderAccessSilent(
-              proactiveHandlerContext,
-              proactiveLoaderPromises,
-            );
+            setupLoaderAccess(proactiveHandlerContext, proactiveLoaderPromises);
 
-            // Re-resolve ALL segments without revalidation
             const Store = ctx.Store;
-            const freshSegments = await Store.run(() =>
-              resolveAllSegments(
-                ctx.entries,
-                ctx.routeKey,
-                ctx.matched.params,
-                proactiveHandlerContext,
-                proactiveLoaderPromises,
+            // Re-establish the request-context ALS around the re-render. 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, () =>
+              Store.run(() =>
+                resolveAllSegments(
+                  ctx.entries,
+                  ctx.routeKey,
+                  ctx.matched.params,
+                  proactiveHandlerContext,
+                  proactiveLoaderPromises,
+                  { skipLoaders: true },
+                ),
               ),
             );
 
-            // Also resolve intercept segments fresh if applicable
             let freshInterceptSegments: ResolvedSegment[] = [];
             if (ctx.interceptResult) {
-              freshInterceptSegments = await Store.run(() =>
-                resolveInterceptEntry(
-                  ctx.interceptResult!.intercept,
-                  ctx.interceptResult!.entry,
-                  ctx.matched.params,
-                  proactiveHandlerContext,
-                  true, // belongsToRoute
-                  // No revalidationContext = render fresh
-                ),
+              freshInterceptSegments = await runWithRequestContext(
+                requestCtx,
+                () =>
+                  Store.run(() =>
+                    resolveInterceptEntry(
+                      ctx.interceptResult!.intercept,
+                      ctx.interceptResult!.entry,
+                      ctx.matched.params,
+                      proactiveHandlerContext,
+                      true, // belongsToRoute
+                      // No revalidationContext = render fresh
+                      undefined,
+                      // Skip intercept middleware: the foreground already ran it
+                      // before the response was sent. Re-running here (post-
+                      // response, background) would fire side effects twice and a
+                      // short-circuit Response would silently abort this write.
+                      { skipMiddleware: true },
+                    ),
+                  ),
               );
             }
 
@@ -239,32 +281,58 @@ export function withCacheStore<TEnv>(
               ...freshSegments,
               ...freshInterceptSegments,
             ];
+            requestCtx._handleStore.seal();
             await cacheScope.cacheRoute(
               ctx.pathname,
               ctx.matched.params,
               completeSegments,
               ctx.isIntercept,
             );
+            if (INTERNAL_RANGO_DEBUG) {
+              const dur = performance.now() - start;
+              console.log(
+                `[RSC Background][req:${reqId}] Proactive cache ${ctx.pathname} (${dur.toFixed(2)}ms) segments=${completeSegments.length}`,
+              );
+            }
             debugLog("cacheStore", "proactive caching complete", {
               pathname: ctx.pathname,
             });
           } catch (error) {
+            if (INTERNAL_RANGO_DEBUG) {
+              const dur = performance.now() - start;
+              console.log(
+                `[RSC Background][req:${reqId}] Proactive cache ${ctx.pathname} FAILED (${dur.toFixed(2)}ms) error=${String(error)}`,
+              );
+            }
             debugWarn("cacheStore", "proactive caching failed", {
               pathname: ctx.pathname,
               error: String(error),
             });
+          } finally {
+            requestCtx._handleStore = originalHandleStore;
+            ctx.Store.metrics = savedMetrics;
           }
         });
       } else {
-        // All segments have components - cache directly
-        // Schedule caching in waitUntil since cacheRoute is now async (key resolution)
+        if (INTERNAL_RANGO_DEBUG) {
+          console.log(
+            `[RSC CacheStore][req:${reqId}] Direct cache path: scheduling cacheRoute for ${ctx.pathname} (${allSegmentsToCache.length} segments, hasNullComponents=${hasNullComponents})`,
+          );
+        }
         requestCtx.waitUntil(async () => {
+          const start = performance.now();
           await cacheScope.cacheRoute(
             ctx.pathname,
             ctx.matched.params,
             allSegmentsToCache,
             ctx.isIntercept,
           );
+          if (INTERNAL_RANGO_DEBUG) {
+            const dur = performance.now() - start;
+            console.log(
+              `[RSC Background][req:${reqId}] Cache store ${ctx.pathname} (${dur.toFixed(2)}ms) segments=${allSegmentsToCache.length}`,
+            );
+          }
         });
       }
 
@@ -272,7 +340,11 @@ export function withCacheStore<TEnv>(
     });
 
     if (ms) {
-      ms.metrics.push({ label: "pipeline:cache-store", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+      ms.metrics.push({
+        label: "pipeline:cache-store",
+        duration: performance.now() - ownStart,
+        startTime: ownStart - ms.requestStart,
+      });
     }
   };
 }

package/src/router/match-middleware/intercept-resolution.ts

@@ -118,51 +118,51 @@ import { debugLog } from "../logging.js";
  */
 export function withInterceptResolution<TEnv>(
   ctx: MatchContext<TEnv>,
-  state: MatchPipelineState
+  state: MatchPipelineState,
 ): GeneratorMiddleware<ResolvedSegment> {
   return async function* (
-    source: AsyncGenerator<ResolvedSegment>
+    source: AsyncGenerator<ResolvedSegment>,
   ): AsyncGenerator<ResolvedSegment> {
-    const pipelineStart = performance.now();
     const ms = ctx.metricsStore;
 
-    // First, yield all segments from the source (main segment resolution or cache)
     const segments: ResolvedSegment[] = [];
     for await (const segment of source) {
       segments.push(segment);
       yield segment;
     }
 
-    // Skip intercept resolution for full match (document requests don't have intercepts)
+    const ownStart = performance.now();
+
     if (ctx.isFullMatch) {
       if (ms) {
-        ms.metrics.push({ label: "pipeline:intercept", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+        ms.metrics.push({
+          label: "pipeline:intercept",
+          duration: performance.now() - ownStart,
+          startTime: ownStart - ms.requestStart,
+        });
       }
       return;
     }
 
-    // Skip intercept resolution if:
-    // 1. No intercept result
-    // 2. Already have intercept segments (from cache hit with intercept key)
-    // 3. Cache hit with intercept key
     const skipInterceptResolution =
       !ctx.interceptResult ||
       state.interceptSegments.length > 0 ||
       (state.cacheHit && ctx.isIntercept);
 
     if (skipInterceptResolution) {
-      // For cache hit with intercept, extract intercept segments from cached data for slots
-      // and re-resolve loaders for fresh data
       if (ctx.interceptResult && state.cacheHit && ctx.isIntercept) {
         await handleCacheHitIntercept(ctx, state, segments);
       }
       if (ms) {
-        ms.metrics.push({ label: "pipeline:intercept", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+        ms.metrics.push({
+          label: "pipeline:intercept",
+          duration: performance.now() - ownStart,
+          startTime: ownStart - ms.requestStart,
+        });
       }
       return;
     }
 
-    // Resolve intercept segments
     const { resolveInterceptEntry } = getRouterContext<TEnv>();
 
     const slotName = ctx.interceptResult!.intercept.slotName;
@@ -171,7 +171,6 @@ export function withInterceptResolution<TEnv>(
       slotName,
     });
 
-    // Resolve intercept entry (middleware, loaders, handler)
     const Store = ctx.Store;
     const interceptSegments = await Store.run(() =>
       resolveInterceptEntry(
@@ -189,37 +188,34 @@ export function withInterceptResolution<TEnv>(
           routeKey: ctx.routeKey,
           actionContext: ctx.actionContext,
           stale: ctx.stale,
-        }
-      )
+        },
+      ),
     );
 
-    // Update state
     state.interceptSegments = interceptSegments;
     state.slots[slotName] = {
       active: true,
       segments: interceptSegments,
     };
 
-    // Yield intercept segments
     for (const segment of interceptSegments) {
       yield segment;
     }
 
     if (ms) {
-      ms.metrics.push({ label: "pipeline:intercept", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+      ms.metrics.push({
+        label: "pipeline:intercept",
+        duration: performance.now() - ownStart,
+        startTime: ownStart - ms.requestStart,
+      });
     }
   };
 }
 
-/**
- * Handle cache hit with intercept scenario
- *
- * Extract intercept segments from cached data and re-resolve loaders for fresh data.
- */
 async function handleCacheHitIntercept<TEnv>(
   ctx: MatchContext<TEnv>,
   state: MatchPipelineState,
-  segments: ResolvedSegment[]
+  segments: ResolvedSegment[],
 ): Promise<void> {
   if (!ctx.interceptResult) return;
 
@@ -227,14 +223,11 @@ async function handleCacheHitIntercept<TEnv>(
 
   const slotName = ctx.interceptResult.intercept.slotName;
 
-  // Find intercept segments from cached segments (namespace starts with "intercept:")
   const interceptSegments = segments.filter((s) =>
-    s.namespace?.startsWith("intercept:")
+    s.namespace?.startsWith("intercept:"),
   );
   state.interceptSegments = interceptSegments;
 
-  // Re-resolve intercept loaders for fresh data on cache hit
-  // This keeps cached component/layout but fetches fresh loader data
   if (resolveInterceptLoadersOnly) {
     const Store = ctx.Store;
     const freshLoaderResult = await Store.run(() =>
@@ -253,28 +246,36 @@ async function handleCacheHitIntercept<TEnv>(
           routeKey: ctx.routeKey,
           actionContext: ctx.actionContext,
           stale: ctx.stale,
-        }
-      )
+        },
+      ),
     );
 
-    // Update intercept segment's loaderDataPromise with fresh data
     if (freshLoaderResult) {
       const interceptMainSegment = interceptSegments.find(
-        (s) => s.type === "parallel" && s.slot
+        (s) => s.type === "parallel" && s.slot,
       );
       if (interceptMainSegment) {
-        interceptMainSegment.loaderDataPromise = freshLoaderResult.loaderDataPromise;
+        interceptMainSegment.loaderDataPromise =
+          freshLoaderResult.loaderDataPromise;
         interceptMainSegment.loaderIds = freshLoaderResult.loaderIds;
-        debugLog("matchPartial.intercept", "cache hit with fresh intercept loaders", {
-          routeName: ctx.localRouteName,
-          slotName,
-        });
+        debugLog(
+          "matchPartial.intercept",
+          "cache hit with fresh intercept loaders",
+          {
+            routeName: ctx.localRouteName,
+            slotName,
+          },
+        );
       }
     } else {
-      debugLog("matchPartial.intercept", "cache hit without intercept loader revalidation", {
-        routeName: ctx.localRouteName,
-        slotName,
-      });
+      debugLog(
+        "matchPartial.intercept",
+        "cache hit without intercept loader revalidation",
+        {
+          routeName: ctx.localRouteName,
+          slotName,
+        },
+      );
     }
   }
 

package/src/router/match-middleware/segment-resolution.ts

@@ -87,62 +87,96 @@
  *   if (state.cacheHit) return;   // Now we can check
  */
 import type { ResolvedSegment } from "../../types.js";
+import type { EntryData } from "../../server/context.js";
+import { _getRequestContext } from "../../server/request-context.js";
 import type { MatchContext, MatchPipelineState } from "../match-context.js";
 import { getRouterContext } from "../router-context.js";
 import type { GeneratorMiddleware } from "./cache-lookup.js";
 
-/**
- * Creates segment resolution middleware
- *
- * Only runs on cache miss (state.cacheHit === false).
- * Uses resolveAllSegmentsWithRevalidation from RouterContext to resolve segments.
- */
+export function treeHasStreaming(entries: EntryData[]): boolean {
+  for (const entry of entries) {
+    if (
+      "loading" in entry &&
+      entry.loading !== undefined &&
+      entry.loading !== false
+    )
+      return true;
+    if (entry.layout) {
+      if (treeHasStreaming(entry.layout)) return true;
+    }
+    if (entry.parallel) {
+      for (const key in entry.parallel) {
+        const parallelEntry = entry.parallel[key as `@${string}`];
+        if (parallelEntry) {
+          if (
+            "loading" in parallelEntry &&
+            parallelEntry.loading !== undefined &&
+            parallelEntry.loading !== false
+          )
+            return true;
+          if (parallelEntry.layout) {
+            if (treeHasStreaming(parallelEntry.layout)) return true;
+          }
+        }
+      }
+    }
+  }
+  return false;
+}
+
 export function withSegmentResolution<TEnv>(
   ctx: MatchContext<TEnv>,
-  state: MatchPipelineState
+  state: MatchPipelineState,
 ): GeneratorMiddleware<ResolvedSegment> {
   return async function* (
-    source: AsyncGenerator<ResolvedSegment>
+    source: AsyncGenerator<ResolvedSegment>,
   ): AsyncGenerator<ResolvedSegment> {
-    const pipelineStart = performance.now();
     const ms = ctx.metricsStore;
 
-    // IMPORTANT: Always iterate source first to give cache-lookup a chance
-    // to run and set state.cacheHit. Without this, cache-lookup never executes!
     for await (const segment of source) {
       yield segment;
     }
 
-    // If cache hit, segments were already yielded by cache lookup
+    const ownStart = performance.now();
+
     if (state.cacheHit) {
       if (ms) {
-        ms.metrics.push({ label: "pipeline:segment-resolve", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+        ms.metrics.push({
+          label: "pipeline:segment-resolve",
+          duration: performance.now() - ownStart,
+          startTime: ownStart - ms.requestStart,
+        });
       }
       return;
     }
 
+    const reqCtx = _getRequestContext();
+    if (reqCtx && reqCtx._treeHasStreaming === undefined) {
+      reqCtx._treeHasStreaming = treeHasStreaming(ctx.entries);
+    }
+
     const { resolveAllSegmentsWithRevalidation, resolveAllSegments } =
       getRouterContext<TEnv>();
 
     const Store = ctx.Store;
 
     if (ctx.isFullMatch) {
-      // Full match (document request) - simple resolution without revalidation
       const segments = await Store.run(() =>
         resolveAllSegments(
           ctx.entries,
           ctx.routeKey,
           ctx.matched.params,
           ctx.handlerContext,
-          ctx.loaderPromises
-        )
+          ctx.loaderPromises,
+        ),
       );
 
-      // Update state with resolved segments
       state.segments = segments;
       state.matchedIds = segments.map((s: { id: string }) => s.id);
 
-      // Yield all resolved segments
+      if (reqCtx) {
+        reqCtx._resolveRenderBarrier(segments);
+      }
       for (const segment of segments) {
         yield segment;
       }
@@ -159,18 +193,22 @@ export function withSegmentResolution<TEnv>(
           ctx.request,
           ctx.prevUrl,
           ctx.url,
-          ctx.loaderPromises,
           ctx.actionContext,
           ctx.interceptResult,
           ctx.localRouteName,
-          ctx.pathname
-        )
+          ctx.pathname,
+          ctx.stale,
+        ),
       );
 
       // Update state with resolved segments
       state.segments = result.segments;
       state.matchedIds = result.matchedIds;
 
+      if (reqCtx) {
+        reqCtx._resolveRenderBarrier(result.segments);
+      }
+
       // Yield all resolved segments
       for (const segment of result.segments) {
         yield segment;
@@ -178,7 +216,11 @@ export function withSegmentResolution<TEnv>(
     }
 
     if (ms) {
-      ms.metrics.push({ label: "pipeline:segment-resolve", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+      ms.metrics.push({
+        label: "pipeline:segment-resolve",
+        duration: performance.now() - ownStart,
+        startTime: ownStart - ms.requestStart,
+      });
     }
   };
 }