@ivogt/rsc-router 0.0.0-experimental.1

package/src/router/manifest.ts

@@ -0,0 +1,116 @@
+/**
+ * Router Manifest Loading
+ *
+ * Handles lazy loading and validation of route manifests.
+ */
+
+import { invariant, RouteNotFoundError } from "../errors";
+import { getContext, type EntryData, type MetricsStore } from "../server/context";
+import type { RouteEntry } from "../types";
+
+/**
+ * Module-level cache for manifests per mount index.
+ * Only used in production - dev mode skips caching for HMR support.
+ */
+const manifestCache = new Map<number, Map<string, EntryData>>();
+
+/**
+ * Load manifest from route entry with AsyncLocalStorage context
+ * Handles lazy imports, unwrapping, and validation
+ */
+export async function loadManifest(
+  entry: RouteEntry<any>,
+  routeKey: string,
+  path: string,
+  metricsStore?: MetricsStore,
+  isSSR?: boolean
+): Promise<EntryData> {
+  const mountIndex = entry.mountIndex;
+  const isDev = process.env.NODE_ENV !== "production";
+
+  // In production, check cache first
+  if (!isDev) {
+    const cachedManifest = manifestCache.get(mountIndex);
+    if (cachedManifest && cachedManifest.has(routeKey)) {
+      return cachedManifest.get(routeKey)!;
+    }
+  }
+
+  const Store = getContext().getOrCreateStore(routeKey);
+
+  // Set mount index in store for unique shortCode prefixes
+  Store.mountIndex = mountIndex;
+
+  // Set isSSR flag so loading() can check if we're in SSR
+  Store.isSSR = isSSR;
+
+  // Attach metrics store to context if provided
+  if (metricsStore) {
+    Store.metrics = metricsStore;
+  }
+
+  // Clear manifest before rebuilding to prevent stale entry mutations
+  Store.manifest.clear();
+
+  try {
+    // Include mountIndex in namespace to ensure unique cache keys per mount
+    const namespaceWithMount = mountIndex !== undefined
+      ? `#router.M${mountIndex}`
+      : "#router";
+
+    const useItems = await getContext().runWithStore(
+      Store,
+      Store.namespace || namespaceWithMount,
+      Store.parent,
+      async () => {
+        const load = await entry.handler();
+        if (
+          load &&
+          load !== null &&
+          typeof load === "object" &&
+          "default" in load
+        ) {
+          return load.default();
+        }
+        if (typeof load === "function") {
+          return load();
+        }
+        return load;
+      }
+    );
+
+    invariant(
+      useItems && useItems.length > 0,
+      "Did not receive any handler from router.map()"
+    );
+    invariant(
+      useItems.some((item) => item.type === "layout"),
+      "Top-level handler must be a layout"
+    );
+
+    invariant(
+      Store.manifest.has(routeKey),
+      `Route must be registered for ${routeKey}`
+    );
+
+    // Cache manifest in production after successful build
+    if (!isDev) {
+      manifestCache.set(mountIndex, new Map(Store.manifest));
+    }
+
+    return Store.manifest.get(routeKey)!;
+  } catch (e) {
+    throw new RouteNotFoundError(
+      `Failed to load route handlers for ${path}: ${(e as Error).message}`,
+      {
+        cause: {
+          error: e,
+          state: {
+            path,
+            routeKey,
+          },
+        },
+      }
+    );
+  }
+}

package/src/router/match-context.ts

@@ -0,0 +1,261 @@
+/**
+ * Match Context for Router Pipeline
+ *
+ * Encapsulates all state needed by the match pipeline middleware.
+ * Created once at the start of match()/matchPartial() and passed through the pipeline.
+ *
+ * DATA FLOW ARCHITECTURE
+ * ======================
+ *
+ * The router uses two complementary data structures:
+ *
+ *   MatchContext (ctx)        - Immutable request state
+ *   MatchPipelineState (state) - Mutable pipeline state
+ *
+ *
+ *   Request
+ *      |
+ *      v
+ *   +-------------------+
+ *   | Create Context    |  ctx = immutable snapshot of request
+ *   +-------------------+
+ *      |
+ *      v
+ *   +-------------------+
+ *   | Create State      |  state = mutable accumulator
+ *   +-------------------+
+ *      |
+ *      +---> [Pipeline Middleware]
+ *      |           |
+ *      |     ctx: read-only
+ *      |     state: read/write
+ *      |           |
+ *      +<----------+
+ *      |
+ *      v
+ *   +-------------------+
+ *   | Build Result      |  Merge ctx + state into MatchResult
+ *   +-------------------+
+ *
+ *
+ * MATCHCONTEXT FIELDS
+ * ===================
+ *
+ * Request Info:
+ *   - request, url, pathname: The incoming HTTP request
+ *
+ * Environment:
+ *   - env, bindings: Server environment (Cloudflare bindings, etc.)
+ *
+ * Client State (from RSC request headers):
+ *   - clientSegmentIds: Segments the client currently has
+ *   - clientSegmentSet: Set version for O(1) lookup
+ *   - stale: Whether client considers its cache stale
+ *
+ * Navigation State:
+ *   - prevUrl, prevParams, prevMatch: Previous navigation for comparison
+ *
+ * Current Match:
+ *   - matched: Route match result (params, route key)
+ *   - manifestEntry: Resolved manifest data
+ *   - entries: All route entries (layouts, loaders, etc.)
+ *   - routeKey, localRouteName: Route identifiers
+ *
+ * Handler Context:
+ *   - handlerContext: Context passed to loaders
+ *   - loaderPromises: Memoized loader promises
+ *
+ * Intercepts:
+ *   - interceptResult: Detected intercept (if soft navigation)
+ *   - interceptSelectorContext: Context for intercept matching
+ *
+ * Cache:
+ *   - cacheScope: Cache configuration and methods
+ *   - isIntercept: Whether this is an intercept request
+ *
+ * Flags:
+ *   - isAction: POST/mutation request
+ *   - isFullMatch: Document request vs navigation
+ *
+ *
+ * MATCHPIPELINESTATE FIELDS
+ * =========================
+ *
+ * State flags (set by middleware, read by others):
+ *   - cacheHit: Cache lookup succeeded
+ *   - shouldRevalidate: SWR revalidation needed
+ *
+ * Segment accumulation:
+ *   - segments: Resolved segments from pipeline
+ *   - matchedIds: All segment IDs in match order
+ *   - cachedSegments: Segments from cache (if hit)
+ *
+ * Intercept data:
+ *   - interceptSegments: Segments for modal slots
+ *   - slots: Named slot data for client
+ *
+ *
+ * IMMUTABILITY CONTRACT
+ * =====================
+ *
+ * MatchContext is treated as immutable after creation.
+ * Middleware should NEVER modify ctx properties.
+ *
+ * MatchPipelineState is explicitly mutable.
+ * Middleware communicate by setting state flags.
+ *
+ * This separation ensures:
+ *   - Request data is consistent across all middleware
+ *   - Pipeline state changes are explicit and trackable
+ *   - No hidden side effects in request handling
+ */
+import type { CacheScope } from "../cache/cache-scope.js";
+import type {
+  EntryData,
+  InterceptSelectorContext,
+  MetricsStore,
+} from "../server/context.js";
+import type { HandlerContext, ResolvedSegment } from "../types.js";
+import type { RouteMatchResult } from "./pattern-matching.js";
+import type { InterceptResult } from "./router-context.js";
+
+/**
+ * Action context passed to matchPartial
+ */
+export interface ActionContext {
+  actionId?: string;
+  actionUrl?: URL;
+  actionResult?: any;
+  formData?: FormData;
+}
+
+/**
+ * Match context containing all state for the match pipeline
+ */
+export interface MatchContext<TEnv = any> {
+  // Request info
+  request: Request;
+  url: URL;
+  pathname: string;
+
+  // Environment
+  env: TEnv;
+  bindings: TEnv;
+
+  // Client state
+  clientSegmentIds: string[];
+  clientSegmentSet: Set<string>;
+  stale: boolean;
+
+  // Previous navigation state
+  prevUrl: URL;
+  prevParams: Record<string, string>;
+  prevMatch: RouteMatchResult | null;
+
+  // Current route match
+  matched: RouteMatchResult;
+  manifestEntry: EntryData;
+  entries: EntryData[];
+  routeKey: string;
+  localRouteName: string;
+
+  // Handler context (for loaders)
+  handlerContext: HandlerContext<any, TEnv>;
+  loaderPromises: Map<string, Promise<any>>;
+
+  // Metrics
+  metricsStore: MetricsStore | undefined;
+
+  // Store for running within context
+  Store: any;
+
+  // Intercept detection
+  interceptContextMatch: RouteMatchResult | null;
+  interceptSelectorContext: InterceptSelectorContext;
+  isSameRouteNavigation: boolean;
+  interceptResult: InterceptResult | null;
+
+  // Cache
+  cacheScope: CacheScope | null;
+  isIntercept: boolean;
+
+  // Action context (if this is an action)
+  actionContext?: ActionContext;
+  isAction: boolean;
+
+  // Route middleware
+  routeMiddleware: Array<{
+    handler: any;
+    params: Record<string, string>;
+  }>;
+
+  // Full match flag (document requests vs partial/navigation requests)
+  // When true, uses simpler resolution without revalidation logic
+  isFullMatch: boolean;
+}
+
+/**
+ * Mutable state that flows through the pipeline
+ */
+export interface MatchPipelineState {
+  // Whether cache was hit
+  cacheHit: boolean;
+
+  // Cached segments (if cache hit)
+  cachedSegments?: ResolvedSegment[];
+  cachedMatchedIds?: string[];
+
+  // Whether cache should be revalidated (SWR)
+  shouldRevalidate?: boolean;
+
+  // Resolved segments from pipeline
+  segments: ResolvedSegment[];
+  matchedIds: string[];
+
+  // Intercept segments
+  interceptSegments: ResolvedSegment[];
+
+  // Slots state
+  slots: Record<
+    string,
+    {
+      active: boolean;
+      segments: ResolvedSegment[];
+    }
+  >;
+}
+
+/**
+ * Create initial pipeline state
+ */
+export function createPipelineState(): MatchPipelineState {
+  return {
+    cacheHit: false,
+    segments: [],
+    matchedIds: [],
+    interceptSegments: [],
+    slots: {},
+  };
+}
+
+/**
+ * Input parameters for createMatchContext
+ */
+export interface CreateMatchContextInput<TEnv = any> {
+  request: Request;
+  env: TEnv;
+  actionContext?: ActionContext;
+}
+
+/**
+ * Result from createMatchContext - either a context or null (fall back to full match)
+ */
+export type CreateMatchContextResult<TEnv = any> =
+  | { type: "context"; ctx: MatchContext<TEnv> }
+  | { type: "fallback"; reason: string }
+  | { type: "error"; error: Error };
+
+// Note: createMatchContext() will be implemented in Step J10 when we wire everything together.
+// It requires access to RouterContext (findMatch, loadManifest, etc.) which are closure
+// functions from createRSCRouter(). The implementation will live in router.ts initially
+// and call getRouterContext() to access these dependencies.

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

@@ -0,0 +1,236 @@
+/**
+ * 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 handleStore |  Isolate from response stream
+ *   +---------------------------+
+ *         |
+ *         v
+ *   +---------------------+
+ *   | isFullMatch?        |
+ *   +---------------------+
+ *         |
+ *   +-----+-----+
+ *   |           |
+ *  yes          no
+ *   |           |
+ *   v           v
+ * resolveAll  resolveWithRevalidation
+ * Segments    + resolveIntercepts
+ *   |           |
+ *   +-----------+
+ *         |
+ *         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
+ * =======================
+ *
+ * The background revalidation creates a fresh handleStore:
+ *
+ *   requestCtx._handleStore = createHandleStore();
+ *
+ * This prevents background handle.push() calls from:
+ *   - Polluting the current response stream
+ *   - Causing duplicate data in the client
+ *   - Creating race conditions
+ *
+ *
+ * FULL VS PARTIAL 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
+ */
+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";
+
+/**
+ * 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,
+      resolveAllSegmentsWithRevalidation,
+      resolveAllSegments,
+      resolveInterceptEntry,
+    } = getRouterContext<TEnv>();
+
+    const requestCtx = getRequestContext();
+    const cacheScope = ctx.cacheScope;
+
+    const logPrefix = ctx.isFullMatch ? "[Router.match]" : "[Router.matchPartial]";
+
+    requestCtx?.waitUntil(async () => {
+      console.log(`${logPrefix} Revalidating stale route: ${ctx.pathname}`);
+      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[];
+
+        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
+          );
+
+          freshSegments = freshResult.segments;
+
+          // 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];
+          }
+        }
+
+        await cacheScope.cacheRoute(
+          ctx.pathname,
+          ctx.matched.params,
+          freshSegments,
+          ctx.isIntercept
+        );
+        console.log(`${logPrefix} Revalidation complete: ${ctx.pathname}`);
+      } catch (error) {
+        console.error(`${logPrefix} Revalidation failed:`, error);
+      }
+    });
+  };
+}