@rangojs/router 0.0.0-experimental.10

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

@@ -0,0 +1,382 @@
+/**
+ * Cache Lookup Middleware
+ *
+ * First middleware in the pipeline. Checks cache before segment resolution.
+ *
+ * FLOW DIAGRAM
+ * ============
+ *
+ *   source (empty)
+ *         |
+ *         v
+ *   +---------------------+
+ *   | Is action request?  |──yes──> yield* source (pass through)
+ *   +---------------------+
+ *         | no
+ *         v
+ *   +---------------------+
+ *   | Cache enabled?      |──no───> yield* source (pass through)
+ *   +---------------------+
+ *         | yes
+ *         v
+ *   +---------------------+
+ *   | Lookup cache        |
+ *   | (pathname, params)  |
+ *   +---------------------+
+ *         |
+ *   +-----+-----+
+ *   |           |
+ *  miss        hit
+ *   |           |
+ *   v           v
+ * yield*    Set state.cacheHit = true
+ * source    Set state.shouldRevalidate
+ *   |           |
+ *   |           v
+ *   |    +---------------------------+
+ *   |    | For each cached segment:  |
+ *   |    |  - Apply revalidation     |
+ *   |    |  - Set component = null   |
+ *   |    |    if client has it       |
+ *   |    +---------------------------+
+ *   |           |
+ *   |           v
+ *   |    +---------------------------+
+ *   |    | Resolve fresh loaders     |  <-- Loaders are NEVER cached
+ *   |    | (always fresh data)       |
+ *   |    +---------------------------+
+ *   |           |
+ *   |           v
+ *   |    yield cached segments
+ *   |    yield fresh loader segments
+ *   |           |
+ *   +-----------+
+ *         |
+ *         v
+ *      next middleware
+ *
+ *
+ * CACHE BEHAVIOR
+ * ==============
+ *
+ * Cache HIT:
+ *   - state.cacheHit = true signals downstream middleware to skip
+ *   - Cached segments have their components nullified if client already has them
+ *   - Loaders are always re-resolved for fresh data
+ *   - state.shouldRevalidate triggers background SWR if cache was stale
+ *
+ * Cache MISS:
+ *   - Passes through to segment-resolution middleware
+ *   - No segments yielded from this middleware
+ *
+ * Loaders:
+ *   - NEVER cached by design
+ *   - Always resolved fresh on every request
+ *   - Ensures data freshness even with cached UI components
+ *
+ *
+ * REVALIDATION RULES
+ * ==================
+ *
+ * Each cached segment is evaluated against its revalidation rules:
+ *
+ *   1. No rules defined -> use default (skip if client has segment)
+ *   2. Rules return false -> skip re-render (nullify component)
+ *   3. Rules return true -> re-render (keep component)
+ *
+ * Revalidation context includes:
+ *   - Previous/next URL and params
+ *   - Request object
+ *   - Action context (if POST)
+ */
+import type { ResolvedSegment } from "../../types.js";
+import type { MatchContext, MatchPipelineState } from "../match-context.js";
+import { getRouterContext } from "../router-context.js";
+import type { PrerenderStore } from "../../prerender/store.js";
+
+// Lazily initialized prerender store singleton and dynamically imported deps.
+// Dynamic imports prevent pulling in @vitejs/plugin-rsc/rsc virtual module at
+// top-level, which breaks vitest (only URLs with file:, data:, node: schemes).
+let prerenderStoreInstance: PrerenderStore | null | undefined;
+let _deserializeSegments: typeof import("../../cache/cache-scope.js").deserializeSegments | undefined;
+let _hashParams: typeof import("../../prerender/param-hash.js").hashParams | undefined;
+let _getRequestContext: typeof import("../../server/request-context.js").getRequestContext | undefined;
+
+async function ensurePrerenderDeps() {
+  if (!_deserializeSegments) {
+    const [cache, paramHash, reqCtx, store] = await Promise.all([
+      import("../../cache/cache-scope.js"),
+      import("../../prerender/param-hash.js"),
+      import("../../server/request-context.js"),
+      import("../../prerender/store.js"),
+    ]);
+    _deserializeSegments = cache.deserializeSegments;
+    _hashParams = paramHash.hashParams;
+    _getRequestContext = reqCtx.getRequestContext;
+    if (prerenderStoreInstance === undefined) {
+      prerenderStoreInstance = store.createPrerenderStore();
+    }
+  }
+}
+
+/**
+ * Async generator middleware type
+ */
+export type GeneratorMiddleware<T> = (
+  source: AsyncGenerator<T>
+) => AsyncGenerator<T>;
+
+/**
+ * Creates cache lookup middleware
+ *
+ * Checks cache for segments. If cache hit:
+ * - Applies revalidation to determine which segments need re-rendering
+ * - Resolves loaders fresh (loaders are NOT cached by design)
+ * - Sets state.cacheHit = true
+ * - Sets state.shouldRevalidate if SWR needed
+ * - Yields cached segments + fresh loader segments
+ *
+ * If cache miss:
+ * - Passes through to next middleware
+ */
+export function withCacheLookup<TEnv>(
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState
+): GeneratorMiddleware<ResolvedSegment> {
+  return async function* (
+    source: AsyncGenerator<ResolvedSegment>
+  ): AsyncGenerator<ResolvedSegment> {
+    const pipelineStart = performance.now();
+    const ms = ctx.metricsStore;
+
+    const {
+      evaluateRevalidation,
+      buildEntryRevalidateMap,
+      resolveLoadersOnlyWithRevalidation,
+      resolveLoadersOnly,
+    } = getRouterContext<TEnv>();
+
+    // Prerender lookup: check build-time cached data before runtime cache.
+    // Prerender data is available regardless of runtime cache configuration.
+    if (!ctx.isAction && ctx.matched.pr) {
+      await ensurePrerenderDeps();
+      if (prerenderStoreInstance) {
+        const paramHash = _hashParams!(ctx.matched.params);
+        const entry = prerenderStoreInstance.get(ctx.matched.routeKey, paramHash);
+        if (entry) {
+          const segments = await _deserializeSegments!(entry.segments);
+
+          // Replay handle data (same as runtime cache hit path)
+          const handleStore = _getRequestContext!()?._handleStore;
+          if (handleStore) {
+            for (const [segId, segHandles] of Object.entries(entry.handles)) {
+              if (Object.keys(segHandles).length > 0) {
+                handleStore.replaySegmentData(segId, segHandles);
+              }
+            }
+          }
+
+          state.cacheHit = true;
+          state.cachedSegments = segments;
+          state.cachedMatchedIds = segments.map((s) => s.id);
+
+          // Yield prerendered segments (same flow as cache hit)
+          // For partial navigation, nullify components the client already has
+          // so parent layouts stay live (client keeps its existing versions).
+          for (const segment of segments) {
+            if (!ctx.isFullMatch && ctx.clientSegmentSet.has(segment.id)) {
+              segment.component = null;
+              segment.loading = undefined;
+            }
+            yield segment;
+          }
+
+          // Resolve loaders fresh (loaders are never pre-rendered)
+          if (ctx.isFullMatch) {
+            if (resolveLoadersOnly) {
+              const loaderSegments = await ctx.Store.run(() =>
+                resolveLoadersOnly(ctx.entries, ctx.handlerContext),
+              );
+              state.matchedIds = state.cachedMatchedIds!;
+              for (const segment of loaderSegments) {
+                yield segment;
+              }
+            } else {
+              state.matchedIds = state.cachedMatchedIds!;
+            }
+          } else {
+            if (resolveLoadersOnlyWithRevalidation) {
+              const loaderResult = await ctx.Store.run(() =>
+                resolveLoadersOnlyWithRevalidation(
+                  ctx.entries,
+                  ctx.handlerContext,
+                  ctx.clientSegmentSet,
+                  ctx.prevParams,
+                  ctx.request,
+                  ctx.prevUrl,
+                  ctx.url,
+                  ctx.routeKey,
+                  ctx.actionContext,
+                ),
+              );
+              state.matchedIds = [
+                ...state.cachedMatchedIds!,
+                ...loaderResult.matchedIds,
+              ];
+              for (const segment of loaderResult.segments) {
+                yield segment;
+              }
+            } else {
+              state.matchedIds = state.cachedMatchedIds!;
+            }
+          }
+
+          if (ms) {
+            ms.metrics.push({ label: "pipeline:cache-lookup", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+          }
+          return;
+        }
+      }
+    }
+
+    // Skip cache during actions
+    if (ctx.isAction || !ctx.cacheScope?.enabled) {
+      // Cache miss - pass through to segment resolution
+      yield* source;
+      if (ms) {
+        ms.metrics.push({ label: "pipeline:cache-lookup", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+      }
+      return;
+    }
+
+    // Lookup cache
+    const cacheResult = await ctx.cacheScope.lookupRoute(
+      ctx.pathname,
+      ctx.matched.params,
+      ctx.isIntercept
+    );
+
+    if (!cacheResult) {
+      // Cache miss - pass through to segment resolution
+      yield* source;
+      if (ms) {
+        ms.metrics.push({ label: "pipeline:cache-lookup", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+      }
+      return;
+    }
+
+    // Cache HIT
+    state.cacheHit = true;
+    state.shouldRevalidate = cacheResult.shouldRevalidate;
+    state.cachedSegments = cacheResult.segments;
+    state.cachedMatchedIds = cacheResult.segments.map((s) => s.id);
+
+    // Apply revalidation to cached segments
+    const entryRevalidateMap = buildEntryRevalidateMap?.(ctx.entries);
+
+    for (const segment of cacheResult.segments) {
+      // Skip segments client doesn't have - they need their component
+      if (!ctx.clientSegmentSet.has(segment.id)) {
+        yield segment;
+        continue;
+      }
+
+      // Skip intercept segments - they're handled separately
+      if (segment.namespace?.startsWith("intercept:")) {
+        yield segment;
+        continue;
+      }
+
+      // Look up revalidation rules for this segment
+      const entryInfo = entryRevalidateMap?.get(segment.id);
+      if (!entryInfo || entryInfo.revalidate.length === 0) {
+        // No revalidation rules, use default behavior (skip if client has)
+        segment.component = null;
+        segment.loading = undefined;
+        yield segment;
+        continue;
+      }
+
+      // Evaluate revalidation rules
+      const shouldRevalidate = await evaluateRevalidation({
+        segment,
+        prevParams: ctx.prevParams,
+        getPrevSegment: null,
+        request: ctx.request,
+        prevUrl: ctx.prevUrl,
+        nextUrl: ctx.url,
+        revalidations: entryInfo.revalidate.map((fn, i) => ({
+          name: `revalidate${i}`,
+          fn,
+        })),
+        routeKey: ctx.routeKey,
+        context: ctx.handlerContext,
+        actionContext: ctx.actionContext,
+      });
+
+      if (!shouldRevalidate) {
+        // Client has it, no revalidation needed
+        segment.component = null;
+        segment.loading = undefined;
+      }
+
+      yield segment;
+    }
+
+    // Resolve loaders fresh (loaders are NOT cached by default)
+    // This ensures fresh data even on cache hit
+    const Store = ctx.Store;
+
+    if (ctx.isFullMatch) {
+      // Full match (document request) - simple loader resolution without revalidation
+      if (resolveLoadersOnly) {
+        const loaderSegments = await Store.run(() =>
+          resolveLoadersOnly(ctx.entries, ctx.handlerContext)
+        );
+
+        // Update state - full match doesn't track matchedIds separately
+        state.matchedIds = state.cachedMatchedIds!;
+
+        // Yield fresh loader segments
+        for (const segment of loaderSegments) {
+          yield segment;
+        }
+      } else {
+        state.matchedIds = state.cachedMatchedIds!;
+      }
+    } else {
+      // Partial match (navigation) - loader resolution with revalidation
+      if (resolveLoadersOnlyWithRevalidation) {
+        const loaderResult = await Store.run(() =>
+          resolveLoadersOnlyWithRevalidation(
+            ctx.entries,
+            ctx.handlerContext,
+            ctx.clientSegmentSet,
+            ctx.prevParams,
+            ctx.request,
+            ctx.prevUrl,
+            ctx.url,
+            ctx.routeKey,
+            ctx.actionContext
+          )
+        );
+
+        // Update state with fresh loader matchedIds
+        state.matchedIds = [
+          ...state.cachedMatchedIds!,
+          ...loaderResult.matchedIds,
+        ];
+
+        // Yield fresh loader segments
+        for (const segment of loaderResult.segments) {
+          yield segment;
+        }
+      } else {
+        state.matchedIds = state.cachedMatchedIds!;
+      }
+    }
+    if (ms) {
+      ms.metrics.push({ label: "pipeline:cache-lookup", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+    }
+  };
+}

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

@@ -0,0 +1,276 @@
+/**
+ * Cache Store Middleware
+ *
+ * Stores resolved segments in cache for future requests.
+ * Implements proactive caching for partial navigation scenarios.
+ *
+ * FLOW DIAGRAM
+ * ============
+ *
+ *   source (from intercept-resolution)
+ *         |
+ *         v
+ *   +---------------------------+
+ *   | Collect + yield all      |  Observer pattern: pass through
+ *   | allSegments[]            |
+ *   +---------------------------+
+ *         |
+ *         v
+ *   +---------------------+
+ *   | Should skip cache?  |
+ *   | - !cacheScope       |──yes──> return
+ *   | - isAction          |
+ *   | - cacheHit          |
+ *   | - method !== GET    |
+ *   +---------------------+
+ *         | no
+ *         v
+ *   +-------------------------------+
+ *   | Any null components?          |
+ *   | (client already has segment)  |
+ *   +-------------------------------+
+ *         |
+ *   +-----+-----+
+ *   |           |
+ *  yes          no
+ *   |           |
+ *   v           v
+ * PROACTIVE   DIRECT
+ * CACHE       CACHE
+ *   |           |
+ *   v           v
+ * waitUntil()  cacheRoute()
+ * re-render    immediately
+ * fresh        |
+ *   |           |
+ *   +-----------+
+ *         |
+ *         v
+ *      next middleware
+ *
+ *
+ * CACHING STRATEGIES
+ * ==================
+ *
+ * 1. Direct Cache (all components present):
+ *    - Immediate cacheRoute() call
+ *    - All segments have valid components
+ *    - Used for fresh full-page renders
+ *
+ * 2. Proactive Cache (null components present):
+ *    - Background re-render via waitUntil()
+ *    - Creates fresh context to avoid polluting response
+ *    - Re-resolves ALL segments without revalidation
+ *    - Ensures cache has complete components for future requests
+ *
+ *
+ * WHY PROACTIVE CACHING?
+ * ======================
+ *
+ * During partial navigation, some segments have null components:
+ *
+ *   Request: /products/123 -> /products/456
+ *   Segments: [ProductLayout(null), ProductPage(component)]
+ *
+ * The null means "client already has this, don't re-send."
+ * But if we cache these null components, future document requests
+ * would fail (no component to render).
+ *
+ * Solution: Background re-render all segments fresh, then cache.
+ * This ensures the cache always has complete, renderable segments.
+ *
+ *
+ * PROACTIVE CACHE FLOW
+ * ====================
+ *
+ *   1. Current request returns (fast, with nulls)
+ *   2. waitUntil() triggers background work
+ *   3. Create fresh handler context (silent, no stream pollution)
+ *   4. Re-resolve all entries without revalidation logic
+ *   5. Also resolve intercept segments if applicable
+ *   6. Store complete segments in cache
+ *
+ *
+ * SKIP CONDITIONS
+ * ===============
+ *
+ * Caching is skipped when:
+ *   - Cache scope disabled (no caching configured)
+ *   - This is an action request (mutations shouldn't cache)
+ *   - Cache was already hit (no need to re-cache same data)
+ *   - Non-GET request (only GET requests are cacheable)
+ */
+import type { ResolvedSegment } from "../../types.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 cache store middleware
+ *
+ * Observes all segments passing through and stores them in cache after pipeline completes.
+ * Handles proactive caching for null-component segments.
+ */
+export function withCacheStore<TEnv>(
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState,
+): GeneratorMiddleware<ResolvedSegment> {
+  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)
+    if (
+      !ctx.cacheScope?.enabled ||
+      ctx.isAction ||
+      state.cacheHit ||
+      ctx.request.method !== "GET"
+    ) {
+      if (ms) {
+        ms.metrics.push({ label: "pipeline:cache-store", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+      }
+      return;
+    }
+
+    const {
+      createHandlerContext,
+      setupLoaderAccessSilent,
+      resolveAllSegments,
+      resolveInterceptEntry,
+    } = getRouterContext<TEnv>();
+
+    // Combine main segments with intercept segments
+    const allSegmentsToCache = [...allSegments, ...state.interceptSegments];
+
+    // 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",
+    );
+
+    const requestCtx = getRequestContext();
+    if (!requestCtx) return;
+
+    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)
+    requestCtx.onResponse((response) => {
+      // Only cache successful responses
+      if (response.status !== 200) {
+        console.log(
+          `[CacheStore] Skipping cache: non-200 status ${response.status} for ${ctx.pathname}`,
+        );
+        return response;
+      }
+
+      if (hasNullComponents) {
+        // Proactive caching: render all segments fresh in background
+        // This ensures cache has complete components for future requests
+        requestCtx.waitUntil(async () => {
+          console.log(
+            `[Router.matchPartial] Proactive caching: ${ctx.pathname} (rendering null-component segments)`,
+          );
+          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.routeMap,
+              ctx.matched.routeKey
+            );
+            const proactiveLoaderPromises = new Map<string, Promise<any>>();
+
+            // Set up loader access that ignores handle pushes
+            setupLoaderAccessSilent(
+              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,
+              ),
+            );
+
+            // 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
+                ),
+              );
+            }
+
+            const completeSegments = [
+              ...freshSegments,
+              ...freshInterceptSegments,
+            ];
+            await cacheScope.cacheRoute(
+              ctx.pathname,
+              ctx.matched.params,
+              completeSegments,
+              ctx.isIntercept,
+            );
+            console.log(
+              `[Router.matchPartial] Proactive caching complete: ${ctx.pathname}`,
+            );
+          } catch (error) {
+            console.error(
+              `[Router.matchPartial] Proactive caching failed:`,
+              error,
+            );
+          }
+        });
+      } else {
+        // All segments have components - cache directly
+        // Schedule caching in waitUntil since cacheRoute is now async (key resolution)
+        requestCtx.waitUntil(async () => {
+          await cacheScope.cacheRoute(
+            ctx.pathname,
+            ctx.matched.params,
+            allSegmentsToCache,
+            ctx.isIntercept,
+          );
+        });
+      }
+
+      return response;
+    });
+
+    if (ms) {
+      ms.metrics.push({ label: "pipeline:cache-store", duration: performance.now() - pipelineStart, startTime: pipelineStart - ms.requestStart });
+    }
+  };
+}