@ivogt/rsc-router 0.0.0-experimental.1

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

@@ -0,0 +1,261 @@
+/**
+ * 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";
+
+/**
+ * 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 {
+      evaluateRevalidation,
+      buildEntryRevalidateMap,
+      resolveLoadersOnlyWithRevalidation,
+      resolveLoadersOnly,
+    } = getRouterContext<TEnv>();
+
+    // Skip cache during actions
+    if (ctx.isAction || !ctx.cacheScope?.enabled) {
+      // Cache miss - pass through to segment resolution
+      yield* source;
+      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;
+      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!;
+      }
+    }
+  };
+}

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

@@ -0,0 +1,250 @@
+/**
+ * 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> {
+    // 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") {
+      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
+            );
+            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;
+    });
+  };
+}

package/src/router/match-middleware/index.ts

@@ -0,0 +1,81 @@
+/**
+ * Match Middleware
+ *
+ * Async generator middleware for the match pipeline.
+ * Each middleware transforms or enriches the segment stream.
+ *
+ * MIDDLEWARE OVERVIEW
+ * ===================
+ *
+ * The pipeline consists of 5 middleware layers, each with a specific role:
+ *
+ * +-------------------------------------------------------------------------+
+ * |                         MIDDLEWARE PIPELINE                             |
+ * +-------------------------------------------------------------------------+
+ * |                                                                         |
+ * |  [1] CACHE LOOKUP (innermost)                                           |
+ * |      Purpose: Check cache before resolving                              |
+ * |      On hit:  Yield cached segments + fresh loaders                     |
+ * |      On miss: Pass through to segment resolution                        |
+ * |      Side effects: Sets state.cacheHit, state.shouldRevalidate          |
+ * |                                                                         |
+ * |  [2] SEGMENT RESOLUTION                                                 |
+ * |      Purpose: Resolve segments when cache misses                        |
+ * |      Skips if: state.cacheHit === true                                  |
+ * |      Produces: All route segments (layouts, routes, loaders)            |
+ * |      Two modes: Full (simple) vs Partial (with revalidation)            |
+ * |                                                                         |
+ * |  [3] INTERCEPT RESOLUTION                                               |
+ * |      Purpose: Resolve intercept segments (modal slots)                  |
+ * |      Triggers: When ctx.interceptResult exists                          |
+ * |      Produces: Additional segments for named slots                      |
+ * |      Updates: state.slots[slotName] with intercept segments             |
+ * |                                                                         |
+ * |  [4] CACHE STORE                                                        |
+ * |      Purpose: Store segments in cache for future requests               |
+ * |      Skips if: Cache hit, actions, or cache disabled                    |
+ * |      Strategy: Direct cache if all components present                   |
+ * |                Proactive cache if null components (via waitUntil)       |
+ * |                                                                         |
+ * |  [5] BACKGROUND REVALIDATION (outermost)                                |
+ * |      Purpose: SWR - serve stale, revalidate in background               |
+ * |      Triggers: When state.shouldRevalidate === true                     |
+ * |      Action: Async resolution via waitUntil(), updates cache            |
+ * |                                                                         |
+ * +-------------------------------------------------------------------------+
+ *
+ *
+ * MIDDLEWARE INTERACTION PATTERNS
+ * ===============================
+ *
+ * Pattern 1: Producer Middleware (cache-lookup, segment-resolution)
+ *   - Yields segments into the stream
+ *   - Creates new data for downstream middleware
+ *
+ * Pattern 2: Transformer Middleware (intercept-resolution)
+ *   - Passes through existing segments
+ *   - Adds additional segments (intercepts)
+ *
+ * Pattern 3: Observer Middleware (cache-store, background-revalidation)
+ *   - Passes through all segments unchanged
+ *   - Triggers side effects based on state
+ *
+ *
+ * STATE FLAGS
+ * ===========
+ *
+ * The middleware communicate through MatchPipelineState:
+ *
+ *   state.cacheHit        - Set by cache-lookup, read by others to skip work
+ *   state.shouldRevalidate - Set by cache-lookup, triggers bg-revalidation
+ *   state.segments        - Accumulated segments from pipeline
+ *   state.interceptSegments - Segments for intercept slots
+ *   state.slots           - Named slot data for client
+ */
+
+export { withCacheLookup } from "./cache-lookup.js";
+export { withSegmentResolution } from "./segment-resolution.js";
+export { withInterceptResolution } from "./intercept-resolution.js";
+export { withCacheStore } from "./cache-store.js";
+export { withBackgroundRevalidation } from "./background-revalidation.js";
+export type { GeneratorMiddleware } from "./cache-lookup.js";