@rangojs/router 0.0.0-experimental.0f44aca1

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

@@ -0,0 +1,223 @@
+/**
+ * Background Revalidation Middleware
+ *
+ * Implements SWR (stale-while-revalidate) pattern.
+ * Triggers background refresh when cached data is stale.
+ *
+ * FLOW DIAGRAM
+ * ============
+ *
+ *   source (from cache-store)
+ *         |
+ *         v
+ *   +---------------------------+
+ *   | yield* source            |  Pure pass-through
+ *   | (no modifications)       |
+ *   +---------------------------+
+ *         |
+ *         v
+ *   +---------------------+
+ *   | Should revalidate?  |
+ *   | - shouldRevalidate  |──no───> return
+ *   | - cacheHit          |
+ *   | - cacheScope        |
+ *   +---------------------+
+ *         | yes
+ *         v
+ *   +---------------------------+
+ *   | requestCtx.waitUntil()   |  Non-blocking background task
+ *   +---------------------------+
+ *         |
+ *         v (async, doesn't block response)
+ *   +---------------------------+
+ *   | Create fresh context     |  Fresh handleStore, handlerContext,
+ *   | (full isolation)         |  and loaderPromises map
+ *   +---------------------------+
+ *         |
+ *         v
+ *   +---------------------------+
+ *   | resolveAllSegments()    |  Fresh resolution (no revalidation)
+ *   | + resolveIntercepts()   |  Ensures complete components
+ *   +---------------------------+
+ *         |
+ *         v
+ *   +---------------------------+
+ *   | cacheScope.cacheRoute()  |  Update cache with fresh data
+ *   +---------------------------+
+ *
+ *
+ * SWR PATTERN
+ * ===========
+ *
+ * Stale-While-Revalidate provides fast responses with eventual consistency:
+ *
+ *   Timeline:
+ *   ---------
+ *   T0: Request arrives
+ *   T1: Cache lookup finds stale entry
+ *   T2: Return stale data immediately (fast!)
+ *   T3: Response sent to client
+ *   T4: waitUntil() triggers background revalidation
+ *   T5: Fresh data resolved
+ *   T6: Cache updated with fresh data
+ *   T7: Next request gets fresh data from cache
+ *
+ * Benefits:
+ *   - Fast initial response (cached data)
+ *   - Eventually consistent (background refresh)
+ *   - No blocking on revalidation
+ *
+ *
+ * WHEN IS CACHE STALE?
+ * ====================
+ *
+ * The cache-lookup middleware sets state.shouldRevalidate based on:
+ *   - TTL (time-to-live) expiration
+ *   - Cache entry metadata
+ *   - Configured staleness rules
+ *
+ * This middleware only acts on the flag, it doesn't determine staleness.
+ *
+ *
+ * ISOLATION FROM RESPONSE
+ * =======================
+ *
+ * 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 matches the proactive caching pattern in cache-store.ts.
+ *
+ *
+ * FRESH RESOLUTION (NO REVALIDATION)
+ * ===================================
+ *
+ * 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";
+
+/**
+ * Creates background revalidation middleware
+ *
+ * If cache was stale (state.shouldRevalidate === true):
+ * - Triggers background resolution via waitUntil
+ * - Observes segments but doesn't modify them
+ * - Updates cache with fresh segments after revalidation completes
+ */
+export function withBackgroundRevalidation<TEnv>(
+  ctx: MatchContext<TEnv>,
+  state: MatchPipelineState,
+): GeneratorMiddleware<ResolvedSegment> {
+  return async function* (
+    source: AsyncGenerator<ResolvedSegment>,
+  ): AsyncGenerator<ResolvedSegment> {
+    // Pass through all segments unchanged
+    for await (const segment of source) {
+      yield segment;
+    }
+
+    // Only trigger background revalidation if:
+    // 1. Cache was hit and stale
+    // 2. Cache scope exists
+    if (!state.shouldRevalidate || !state.cacheHit || !ctx.cacheScope) {
+      return;
+    }
+
+    const {
+      getRequestContext,
+      createHandleStore,
+      createHandlerContext,
+      setupLoaderAccess,
+      resolveAllSegments,
+      resolveInterceptEntry,
+    } = getRouterContext<TEnv>();
+
+    const requestCtx = getRequestContext();
+    const cacheScope = ctx.cacheScope;
+
+    requestCtx?.waitUntil(async () => {
+      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 {
+        // Create fresh handler context and loader promises to avoid
+        // reusing memoized results from the foreground pass
+        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);
+
+        // Resolve all segments fresh (without revalidation logic)
+        // to ensure complete components for caching
+        const freshSegments = await ctx.Store.run(() =>
+          resolveAllSegments(
+            ctx.entries,
+            ctx.routeKey,
+            ctx.matched.params,
+            freshHandlerContext,
+            freshLoaderPromises,
+          ),
+        );
+
+        // Also resolve intercept segments fresh if applicable
+        let freshInterceptSegments: ResolvedSegment[] = [];
+        if (ctx.interceptResult) {
+          freshInterceptSegments = await ctx.Store.run(() =>
+            resolveInterceptEntry(
+              ctx.interceptResult!.intercept,
+              ctx.interceptResult!.entry,
+              ctx.matched.params,
+              freshHandlerContext,
+              true,
+            ),
+          );
+        }
+
+        const completeSegments = [...freshSegments, ...freshInterceptSegments];
+        requestCtx._handleStore.seal();
+        await cacheScope.cacheRoute(
+          ctx.pathname,
+          ctx.matched.params,
+          completeSegments,
+          ctx.isIntercept,
+        );
+        debugLog("backgroundRevalidation", "revalidation complete", {
+          pathname: ctx.pathname,
+        });
+      } catch (error) {
+        debugWarn("backgroundRevalidation", "revalidation failed", {
+          pathname: ctx.pathname,
+          error: String(error),
+        });
+      } finally {
+        requestCtx._handleStore = originalHandleStore;
+      }
+    });
+  };
+}