@rangojs/router 0.0.0-experimental.0f44aca1

package/src/router/match-context.ts

@@ -0,0 +1,266 @@
+/**
+ * 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: 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;
+
+  // 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>>;
+
+  // Route map for server-side ctx.reverse() resolution
+  routeMap: Record<string, string>;
+
+  // 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;
+
+  // Source of cache hit ("runtime" or "prerender")
+  cacheSource?: "runtime" | "prerender";
+
+  // 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 createRouter(). The implementation will live in router.ts initially
+// and call getRouterContext() to access these dependencies.

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,
+  };
+}