@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.8a4d0430

package/src/router/match-handlers.ts

@@ -0,0 +1,440 @@
+import type { ReactNode } from "react";
+import { sanitizeError } from "../errors";
+import type { ErrorInfo, ErrorPhase, MatchResult } from "../types";
+import type {
+  EntryData,
+  InterceptEntry,
+  InterceptSelectorContext,
+} from "../server/context";
+import type { MatchApiDeps } from "./types.js";
+import type { RouterContext } from "./router-context.js";
+import { runWithRouterContext } from "./router-context.js";
+import {
+  type ActionContext,
+  type MatchContext,
+  createPipelineState,
+} from "./match-context.js";
+import { createMatchPartialPipeline } from "./match-pipelines.js";
+import { collectMatchResult } from "./match-result.js";
+import {
+  createMatchContextForFull as _createMatchContextForFull,
+  createMatchContextForPartial as _createMatchContextForPartial,
+  matchError as _matchError,
+} from "./match-api.js";
+import { previewMatch as _previewMatch } from "./preview-match.js";
+import {
+  runWithRouterLogContext,
+  withRouterLogScope,
+  isRouterDebugEnabled,
+  startRevalidationTrace,
+  flushRevalidationTrace,
+} from "./logging.js";
+import type { ErrorBoundaryHandler, NotFoundBoundaryHandler } from "../types";
+import type { MiddlewareFn } from "./middleware.js";
+import {
+  type TelemetrySink,
+  safeEmit,
+  resolveSink,
+  getRequestId,
+} from "./telemetry.js";
+
+export interface MatchHandlerDeps<TEnv = any> {
+  buildRouterContext: () => RouterContext<TEnv>;
+  callOnError: (error: unknown, phase: ErrorPhase, context: any) => void;
+  matchApiDeps: MatchApiDeps<TEnv>;
+  defaultErrorBoundary: ReactNode | ErrorBoundaryHandler | undefined;
+  findMatch: (pathname: string, ms?: any) => any;
+  findInterceptForRoute: (
+    routeKey: string,
+    parentEntry: EntryData | null,
+    selectorContext: InterceptSelectorContext | null,
+    isAction: boolean,
+  ) => { intercept: InterceptEntry; entry: EntryData } | null;
+  telemetry?: TelemetrySink;
+}
+
+export interface MatchHandlers<TEnv = any> {
+  match: (request: Request, env: TEnv) => Promise<MatchResult>;
+  matchPartial: (
+    request: Request,
+    context: TEnv,
+    actionContext?: ActionContext,
+  ) => Promise<MatchResult | null>;
+  matchError: (
+    request: Request,
+    _context: TEnv,
+    error: unknown,
+    segmentType?: ErrorInfo["segmentType"],
+  ) => Promise<MatchResult | null>;
+  previewMatch: (
+    request: Request,
+    _context: TEnv,
+  ) => Promise<{
+    routeMiddleware?: Array<{
+      handler: MiddlewareFn;
+      params: Record<string, string>;
+    }>;
+    responseType?: string;
+    handler?: Function;
+    params?: Record<string, string>;
+    negotiated?: boolean;
+    manifestEntry?: EntryData;
+  } | null>;
+  createMatchContextForFull: (
+    request: Request,
+    env: TEnv,
+  ) => Promise<MatchContext<TEnv> | { type: "redirect"; redirectUrl: string }>;
+  createMatchContextForPartial: (
+    request: Request,
+    env: TEnv,
+    actionContext?: {
+      actionId?: string;
+      actionUrl?: URL;
+      actionResult?: any;
+      formData?: FormData;
+    },
+  ) => Promise<MatchContext<TEnv> | null>;
+}
+
+/**
+ * Create match handler functions bound to router closure state.
+ * These are the main request-handling entry points for SSR, navigation,
+ * error recovery, and preview matching.
+ */
+export function createMatchHandlers<TEnv = any>(
+  deps: MatchHandlerDeps<TEnv>,
+): MatchHandlers<TEnv> {
+  const {
+    buildRouterContext,
+    callOnError,
+    matchApiDeps,
+    defaultErrorBoundary,
+    findInterceptForRoute,
+  } = deps;
+  const hasTelemetry = !!deps.telemetry;
+  const telemetry = resolveSink(deps.telemetry);
+
+  async function createMatchContextForFull(
+    request: Request,
+    env: TEnv,
+  ): Promise<MatchContext<TEnv> | { type: "redirect"; redirectUrl: string }> {
+    return _createMatchContextForFull(
+      request,
+      env,
+      matchApiDeps,
+      findInterceptForRoute,
+    );
+  }
+
+  async function createMatchContextForPartial(
+    request: Request,
+    env: TEnv,
+    actionContext?: {
+      actionId?: string;
+      actionUrl?: URL;
+      actionResult?: any;
+      formData?: FormData;
+    },
+  ): Promise<MatchContext<TEnv> | null> {
+    return _createMatchContextForPartial(
+      request,
+      env,
+      matchApiDeps,
+      findInterceptForRoute,
+      actionContext,
+    );
+  }
+
+  /**
+   * Match request and return segments (document/SSR requests)
+   *
+   * Uses generator middleware pipeline for clean separation of concerns:
+   * - cache-lookup: Check cache first
+   * - segment-resolution: Resolve segments on cache miss
+   * - cache-store: Store results in cache
+   * - background-revalidation: SWR revalidation
+   */
+  async function match(request: Request, env: TEnv): Promise<MatchResult> {
+    const requestId = hasTelemetry ? getRequestId(request) : undefined;
+    return runWithRouterLogContext({ request, transaction: "match" }, () => {
+      const routerCtx = buildRouterContext();
+      routerCtx.requestId = requestId;
+      return runWithRouterContext(routerCtx, async () =>
+        withRouterLogScope("match", async () => {
+          const matchStart = performance.now();
+          const pathname = new URL(request.url).pathname;
+          if (hasTelemetry) {
+            safeEmit(telemetry, {
+              type: "request.start",
+              timestamp: matchStart,
+              requestId,
+              method: request.method,
+              pathname,
+              transaction: "match",
+              isPartial: false,
+            });
+          }
+
+          const result = await createMatchContextForFull(request, env);
+
+          // Handle redirect case
+          if ("type" in result && result.type === "redirect") {
+            if (hasTelemetry) {
+              safeEmit(telemetry, {
+                type: "request.end",
+                timestamp: performance.now(),
+                requestId,
+                method: request.method,
+                pathname,
+                transaction: "match",
+                durationMs: performance.now() - matchStart,
+                segmentCount: 0,
+                cacheHit: false,
+              });
+            }
+            return {
+              segments: [],
+              matched: [],
+              diff: [],
+              params: {},
+              redirect: result.redirectUrl,
+            };
+          }
+
+          const ctx = result as MatchContext<TEnv>;
+
+          try {
+            const state = createPipelineState();
+            const pipeline = createMatchPartialPipeline(ctx, state);
+            const matchResult = await collectMatchResult(pipeline, ctx, state);
+            if (hasTelemetry) {
+              safeEmit(telemetry, {
+                type: "cache.decision",
+                timestamp: performance.now(),
+                requestId,
+                pathname,
+                routeKey: ctx.routeKey,
+                hit: state.cacheHit,
+                shouldRevalidate: !!state.shouldRevalidate,
+                source: state.cacheSource,
+              });
+              safeEmit(telemetry, {
+                type: "request.end",
+                timestamp: performance.now(),
+                requestId,
+                method: request.method,
+                pathname,
+                transaction: "match",
+                durationMs: performance.now() - matchStart,
+                segmentCount: matchResult.segments.length,
+                cacheHit: state.cacheHit,
+              });
+            }
+            return matchResult;
+          } catch (error) {
+            if (hasTelemetry) {
+              const errorObj =
+                error instanceof Error ? error : new Error(String(error));
+              safeEmit(telemetry, {
+                type: "request.error",
+                timestamp: performance.now(),
+                requestId,
+                method: request.method,
+                pathname,
+                transaction: "match",
+                error: errorObj,
+                phase: error instanceof Response ? "redirect" : "routing",
+                durationMs: performance.now() - matchStart,
+              });
+            }
+            if (error instanceof Response) throw error;
+            // Report unhandled errors during full match pipeline
+            callOnError(error, "routing", {
+              request,
+              url: ctx.url,
+              env,
+              isPartial: false,
+              handledByBoundary: false,
+            });
+            throw sanitizeError(error);
+          }
+        }),
+      );
+    });
+  }
+
+  async function matchError(
+    request: Request,
+    _context: TEnv,
+    error: unknown,
+    segmentType: ErrorInfo["segmentType"] = "route",
+  ): Promise<MatchResult | null> {
+    return runWithRouterLogContext({ request, transaction: "matchError" }, () =>
+      withRouterLogScope("matchError", () =>
+        _matchError(
+          request,
+          _context,
+          error,
+          matchApiDeps,
+          defaultErrorBoundary,
+          segmentType,
+        ),
+      ),
+    );
+  }
+
+  /**
+   * Match partial request with revalidation
+   *
+   * Uses generator middleware pipeline for clean separation of concerns:
+   * - cache-lookup: Check cache first
+   * - segment-resolution: Resolve segments on cache miss
+   * - intercept-resolution: Handle intercept routes
+   * - cache-store: Store results in cache
+   * - background-revalidation: SWR revalidation
+   */
+  async function matchPartial(
+    request: Request,
+    context: TEnv,
+    actionContext?: ActionContext,
+  ): Promise<MatchResult | null> {
+    const partialRequestId = hasTelemetry ? getRequestId(request) : undefined;
+    return runWithRouterLogContext(
+      { request, transaction: "matchPartial" },
+      () => {
+        const routerCtx = buildRouterContext();
+        routerCtx.requestId = partialRequestId;
+        return runWithRouterContext(routerCtx, async () =>
+          withRouterLogScope("matchPartial", async () => {
+            const matchStart = performance.now();
+            const pathname = new URL(request.url).pathname;
+            if (hasTelemetry) {
+              safeEmit(telemetry, {
+                type: "request.start",
+                timestamp: matchStart,
+                requestId: partialRequestId,
+                method: request.method,
+                pathname,
+                transaction: "matchPartial",
+                isPartial: true,
+              });
+            }
+
+            const ctx = await createMatchContextForPartial(
+              request,
+              context,
+              actionContext,
+            );
+            if (!ctx) {
+              if (hasTelemetry) {
+                safeEmit(telemetry, {
+                  type: "request.end",
+                  timestamp: performance.now(),
+                  requestId: partialRequestId,
+                  method: request.method,
+                  pathname,
+                  transaction: "matchPartial",
+                  durationMs: performance.now() - matchStart,
+                  segmentCount: 0,
+                  cacheHit: false,
+                });
+              }
+              return null;
+            }
+
+            if (isRouterDebugEnabled()) {
+              startRevalidationTrace({
+                method: request.method,
+                prevUrl: ctx.prevUrl.href,
+                nextUrl: ctx.url.href,
+                routeKey: ctx.routeKey,
+                isAction: !!actionContext,
+                stale: ctx.stale || undefined,
+              });
+            }
+
+            try {
+              const state = createPipelineState();
+              const pipeline = createMatchPartialPipeline(ctx, state);
+              const matchResult = await collectMatchResult(
+                pipeline,
+                ctx,
+                state,
+              );
+              flushRevalidationTrace();
+              if (hasTelemetry) {
+                safeEmit(telemetry, {
+                  type: "cache.decision",
+                  timestamp: performance.now(),
+                  requestId: partialRequestId,
+                  pathname,
+                  routeKey: ctx.routeKey,
+                  hit: state.cacheHit,
+                  shouldRevalidate: !!state.shouldRevalidate,
+                  source: state.cacheSource,
+                });
+                safeEmit(telemetry, {
+                  type: "request.end",
+                  timestamp: performance.now(),
+                  requestId: partialRequestId,
+                  method: request.method,
+                  pathname,
+                  transaction: "matchPartial",
+                  durationMs: performance.now() - matchStart,
+                  segmentCount: matchResult.segments.length,
+                  cacheHit: state.cacheHit,
+                });
+              }
+              return matchResult;
+            } catch (error) {
+              flushRevalidationTrace();
+              if (hasTelemetry) {
+                const errorObj =
+                  error instanceof Error ? error : new Error(String(error));
+                const phase = actionContext ? "action" : "revalidation";
+                safeEmit(telemetry, {
+                  type: "request.error",
+                  timestamp: performance.now(),
+                  requestId: partialRequestId,
+                  method: request.method,
+                  pathname,
+                  transaction: "matchPartial",
+                  error: errorObj,
+                  phase: error instanceof Response ? "redirect" : phase,
+                  durationMs: performance.now() - matchStart,
+                });
+              }
+              if (error instanceof Response) throw error;
+              // Report unhandled errors during partial match pipeline
+              callOnError(error, actionContext ? "action" : "revalidation", {
+                request,
+                url: ctx.url,
+                env: context,
+                actionId: actionContext?.actionId,
+                isPartial: true,
+                handledByBoundary: false,
+              });
+              throw sanitizeError(error);
+            }
+          }),
+        );
+      },
+    );
+  }
+
+  async function previewMatch(
+    request: Request,
+    _context: TEnv,
+  ): ReturnType<typeof _previewMatch> {
+    return _previewMatch(request, _context, { findMatch: deps.findMatch });
+  }
+
+  return {
+    match: match,
+    matchPartial: matchPartial,
+    matchError: matchError,
+    previewMatch: previewMatch,
+    createMatchContextForFull: createMatchContextForFull,
+    createMatchContextForPartial: createMatchContextForPartial,
+  };
+}

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

@@ -30,23 +30,15 @@
  *         |
  *         v (async, doesn't block response)
  *   +---------------------------+
- *   | Create fresh handleStore |  Isolate from response stream
+ *   | Create fresh context     |  Fresh handleStore, handlerContext,
+ *   | (full isolation)         |  and loaderPromises map
  *   +---------------------------+
  *         |
  *         v
- *   +---------------------+
- *   | isFullMatch?        |
- *   +---------------------+
- *         |
- *   +-----+-----+
- *   |           |
- *  yes          no
- *   |           |
- *   v           v
- * resolveAll  resolveWithRevalidation
- * Segments    + resolveIntercepts
- *   |           |
- *   +-----------+
+ *   +---------------------------+
+ *   | resolveAllSegments()    |  Fresh resolution (no revalidation)
+ *   | + resolveIntercepts()   |  Ensures complete components
+ *   +---------------------------+
  *         |
  *         v
  *   +---------------------------+
@@ -90,32 +82,28 @@
  * ISOLATION FROM RESPONSE
  * =======================
  *
- * The background revalidation creates a fresh handleStore:
- *
- *   requestCtx._handleStore = createHandleStore();
+ * 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 prevents background handle.push() calls from:
- *   - Polluting the current response stream
- *   - Causing duplicate data in the client
- *   - Creating race conditions
+ * This matches the proactive caching pattern in cache-store.ts.
  *
  *
- * FULL VS PARTIAL REVALIDATION
- * ============================
+ * FRESH RESOLUTION (NO 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
+ * 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
@@ -127,10 +115,10 @@ import type { GeneratorMiddleware } from "./cache-lookup.js";
  */
 export function withBackgroundRevalidation<TEnv>(
   ctx: MatchContext<TEnv>,
-  state: MatchPipelineState
+  state: MatchPipelineState,
 ): GeneratorMiddleware<ResolvedSegment> {
   return async function* (
-    source: AsyncGenerator<ResolvedSegment>
+    source: AsyncGenerator<ResolvedSegment>,
   ): AsyncGenerator<ResolvedSegment> {
     // Pass through all segments unchanged
     for await (const segment of source) {
@@ -147,7 +135,8 @@ export function withBackgroundRevalidation<TEnv>(
     const {
       getRequestContext,
       createHandleStore,
-      resolveAllSegmentsWithRevalidation,
+      createHandlerContext,
+      setupLoaderAccess,
       resolveAllSegments,
       resolveInterceptEntry,
     } = getRouterContext<TEnv>();
@@ -155,81 +144,79 @@ export function withBackgroundRevalidation<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();
-        }
+      debugLog("backgroundRevalidation", "revalidating stale route", {
+        pathname: ctx.pathname,
+        fullMatch: ctx.isFullMatch,
+      });
 
-        let freshSegments: ResolvedSegment[];
+      // 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();
 
-        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(
+      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,
-            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;
+            freshHandlerContext,
+            freshLoaderPromises,
+          ),
+        );
 
-          // For intercept revalidation, also resolve fresh intercept segments
-          if (ctx.interceptResult) {
-            const freshInterceptSegments = await resolveInterceptEntry(
-              ctx.interceptResult.intercept,
-              ctx.interceptResult.entry,
+        // 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,
-              ctx.handlerContext,
+              freshHandlerContext,
               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];
-          }
+            ),
+          );
         }
 
+        const completeSegments = [...freshSegments, ...freshInterceptSegments];
+        requestCtx._handleStore.seal();
         await cacheScope.cacheRoute(
           ctx.pathname,
           ctx.matched.params,
-          freshSegments,
-          ctx.isIntercept
+          completeSegments,
+          ctx.isIntercept,
         );
-        console.log(`${logPrefix} Revalidation complete: ${ctx.pathname}`);
+        debugLog("backgroundRevalidation", "revalidation complete", {
+          pathname: ctx.pathname,
+        });
       } catch (error) {
-        console.error(`${logPrefix} Revalidation failed:`, error);
+        debugWarn("backgroundRevalidation", "revalidation failed", {
+          pathname: ctx.pathname,
+          error: String(error),
+        });
+      } finally {
+        requestCtx._handleStore = originalHandleStore;
       }
     });
   };