@rangojs/router 0.0.0-experimental.25 → 0.0.0-experimental.25dbaac3

package/src/router/request-classification.ts

@@ -0,0 +1,310 @@
+/**
+ * Request Classification
+ *
+ * Replaces the implicit "preview then match again" model with a clean
+ * two-stage architecture:
+ *
+ * 1. Classification — classifyRequest() produces a RequestPlan that answers
+ *    all routing questions once: target route, request mode, route middleware,
+ *    response-route info, negotiation state.
+ *
+ * 2. Execution — executeRequest() dispatches on the plan to the appropriate
+ *    handler (response route, loader fetch, full render, partial render,
+ *    action revalidation, PE render).
+ *
+ * Builds on RouteSnapshot from route-snapshot.ts.
+ */
+
+import { RouteNotFoundError } from "../errors.js";
+import type { EntryData } from "../server/context.js";
+import type { CollectedMiddleware } from "./middleware-types.js";
+import type { RouteMatchResult } from "./pattern-matching.js";
+import { negotiateRoute } from "./content-negotiation.js";
+import { stripInternalParams } from "./handler-context.js";
+import { resolveRoute, type RouteSnapshot } from "./route-snapshot.js";
+
+// ---------------------------------------------------------------------------
+// RequestPlan — discriminated union
+// ---------------------------------------------------------------------------
+
+interface RedirectPlan<TEnv = any> {
+  mode: "redirect";
+  route: RouteSnapshot<TEnv>;
+  redirectUrl: string;
+}
+
+interface VersionMismatchPlan<TEnv = any> {
+  mode: "version-mismatch";
+  /** May be undefined when version mismatch is detected before route resolution */
+  route?: RouteSnapshot<TEnv>;
+  reloadUrl: string;
+}
+
+interface ResponseRoutePlan<TEnv = any> {
+  mode: "response";
+  route: RouteSnapshot<TEnv>;
+  handler: Function;
+  responseType: string;
+  negotiated: boolean;
+  manifestEntry: EntryData;
+  routeMiddleware: CollectedMiddleware[];
+}
+
+interface LoaderFetchPlan<TEnv = any> {
+  mode: "loader";
+  route: RouteSnapshot<TEnv>;
+}
+
+interface PeRenderPlan<TEnv = any> {
+  mode: "pe-render";
+  route: RouteSnapshot<TEnv>;
+}
+
+interface ActionPlan<TEnv = any> {
+  mode: "action";
+  route: RouteSnapshot<TEnv>;
+  actionId: string;
+  negotiated: boolean;
+}
+
+interface FullRenderPlan<TEnv = any> {
+  mode: "full-render";
+  route: RouteSnapshot<TEnv>;
+  negotiated: boolean;
+}
+
+interface PartialRenderPlan<TEnv = any> {
+  mode: "partial-render";
+  route: RouteSnapshot<TEnv>;
+  negotiated: boolean;
+}
+
+/**
+ * The output of request classification. A discriminated union where each
+ * variant carries exactly the fields needed for its execution path.
+ */
+export type RequestPlan<TEnv = any> =
+  | RedirectPlan<TEnv>
+  | VersionMismatchPlan<TEnv>
+  | ResponseRoutePlan<TEnv>
+  | LoaderFetchPlan<TEnv>
+  | PeRenderPlan<TEnv>
+  | ActionPlan<TEnv>
+  | FullRenderPlan<TEnv>
+  | PartialRenderPlan<TEnv>;
+
+/**
+ * Plans that have passed the terminal-check gate (version-mismatch handled)
+ * and are ready for execution. Always have a `route` field.
+ */
+export type ExecutableRequestPlan<TEnv = any> = Exclude<
+  RequestPlan<TEnv>,
+  VersionMismatchPlan<TEnv>
+>;
+
+/**
+ * Re-export individual plan types for consumers that need to narrow.
+ */
+export type {
+  RedirectPlan,
+  VersionMismatchPlan,
+  ResponseRoutePlan,
+  LoaderFetchPlan,
+  PeRenderPlan,
+  ActionPlan,
+  FullRenderPlan,
+  PartialRenderPlan,
+};
+
+// ---------------------------------------------------------------------------
+// classifyRequest — the single authoritative classification step
+// ---------------------------------------------------------------------------
+
+export interface ClassifyRequestDeps<TEnv = any> {
+  findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
+  routerVersion: string;
+  routerId: string;
+}
+
+/**
+ * Classify an incoming request into a RequestPlan.
+ *
+ * This is the single source of truth for request mode detection. It replaces
+ * the scattered previewMatch + isAction/isLoaderFetch/isPartial checks in
+ * handler.ts.
+ *
+ * Classification order:
+ * 1. Route resolution (findMatch + loadManifest via resolveRoute lite)
+ * 2. Redirect detection
+ * 3. Version mismatch
+ * 4. Response route + content negotiation
+ * 5. Mode detection from headers/params
+ */
+export async function classifyRequest<TEnv = any>(
+  request: Request,
+  url: URL,
+  deps: ClassifyRequestDeps<TEnv>,
+): Promise<RequestPlan<TEnv>> {
+  const pathname = url.pathname;
+  const isAction =
+    request.headers.has("rsc-action") || url.searchParams.has("_rsc_action");
+
+  // Version mismatch — runs BEFORE route resolution so stale clients
+  // requesting removed routes get a reload, not a 404.
+  const clientVersion = url.searchParams.get("_rsc_v");
+  if (
+    deps.routerVersion &&
+    clientVersion &&
+    clientVersion !== deps.routerVersion
+  ) {
+    // Strip internal _rsc_* params so the browser reloads to a clean URL
+    let reloadUrl = stripInternalParams(url).toString();
+    if (isAction) {
+      const referer = request.headers.get("referer");
+      if (referer) {
+        try {
+          const refererUrl = new URL(referer);
+          if (refererUrl.origin === url.origin) {
+            reloadUrl = referer;
+          }
+        } catch {
+          // Malformed referer, fall back to stripped url
+        }
+      }
+    }
+
+    return {
+      mode: "version-mismatch",
+      reloadUrl,
+    };
+  }
+
+  // No metricsStore — classification is a lightweight gating step.
+  // Route-matching and manifest-loading metrics belong in the match path
+  // (createMatchContextForFull/Partial) which runs the authoritative resolution.
+  const result = await resolveRoute<TEnv>(pathname, {
+    findMatch: deps.findMatch,
+    lite: true,
+  });
+
+  if (!result) {
+    throw new RouteNotFoundError(`No route matched for ${pathname}`, {
+      cause: { pathname, method: request.method },
+    });
+  }
+
+  // Redirect
+  if (result.type === "redirect") {
+    const snapshot: RouteSnapshot<TEnv> = {
+      matched: result as any,
+      manifestEntry: null as any,
+      entries: [],
+      routeKey: "",
+      localRouteName: "",
+      params: {},
+      routeMiddleware: [],
+      cacheScope: null,
+      isPassthrough: false,
+    };
+    return {
+      mode: "redirect",
+      route: snapshot,
+      redirectUrl: result.redirectTo + url.search,
+    };
+  }
+
+  const snapshot = result.snapshot;
+
+  // Response route — non-RSC short-circuit (JSON, streaming, etc.)
+  const responseResult = await classifyResponseRoute(
+    request,
+    pathname,
+    snapshot,
+  );
+  if (responseResult) {
+    return responseResult;
+  }
+
+  // Mode detection from request signals
+  const actionId =
+    request.headers.get("rsc-action") || url.searchParams.get("_rsc_action");
+  const isLoaderFetch = url.searchParams.has("_rsc_loader");
+
+  const hasVariants =
+    snapshot.matched.negotiateVariants &&
+    snapshot.matched.negotiateVariants.length > 0;
+  const negotiated = !!hasVariants;
+
+  if (isAction && actionId) {
+    return { mode: "action", route: snapshot, actionId, negotiated };
+  }
+
+  if (isLoaderFetch) {
+    return { mode: "loader", route: snapshot };
+  }
+
+  // PE detection: POST with form content-type, but not a server action
+  const contentType = request.headers.get("content-type") || "";
+  const isFormSubmission =
+    contentType.includes("multipart/form-data") ||
+    contentType.includes("application/x-www-form-urlencoded");
+  if (request.method === "POST" && !isAction && isFormSubmission) {
+    return { mode: "pe-render", route: snapshot };
+  }
+
+  // App switch: client's routerId doesn't match this router
+  const clientRouterId = url.searchParams.get("_rsc_rid");
+  const isAppSwitch = !!(clientRouterId && clientRouterId !== deps.routerId);
+  const isPartial = url.searchParams.has("_rsc_partial") && !isAppSwitch;
+
+  if (isPartial) {
+    return { mode: "partial-render", route: snapshot, negotiated };
+  }
+
+  return { mode: "full-render", route: snapshot, negotiated };
+}
+
+// ---------------------------------------------------------------------------
+// Content negotiation for response routes
+// ---------------------------------------------------------------------------
+
+/**
+ * Check if the route is a response route and perform content negotiation
+ * if negotiate variants exist. Returns a ResponseRoutePlan if the route
+ * is a response route, null otherwise (RSC route).
+ */
+async function classifyResponseRoute<TEnv>(
+  request: Request,
+  pathname: string,
+  snapshot: RouteSnapshot<TEnv>,
+): Promise<ResponseRoutePlan<TEnv> | null> {
+  const { manifestEntry, responseType } = snapshot;
+
+  const negotiation = await negotiateRoute(request, pathname, snapshot);
+  if (negotiation) {
+    return {
+      mode: "response",
+      route: snapshot,
+      ...negotiation,
+    };
+  }
+
+  // Non-negotiated response route (no variants, or RSC won negotiation)
+  if (responseType) {
+    const handler =
+      manifestEntry.type === "route" ? manifestEntry.handler : undefined;
+    if (handler) {
+      return {
+        mode: "response",
+        route: snapshot,
+        handler,
+        responseType,
+        negotiated: false,
+        manifestEntry,
+        routeMiddleware: snapshot.routeMiddleware,
+      };
+    }
+  }
+
+  return null;
+}

package/src/router/revalidation.ts

@@ -59,6 +59,14 @@ interface EvaluateRevalidationOptions<TEnv> {
   stale?: boolean;
   /** Trace source hint for the revalidation trace */
   traceSource?: RevalidationTraceEntry["source"];
+  /**
+   * Override the segment-type-derived default. When set, the value is used as
+   * the seed `defaultShouldRevalidate` passed to user revalidate fns and the
+   * reason flows into the trace. Callers use this when client-knowledge
+   * (e.g. parallel slot not in clientSegmentIds) should dictate the seed
+   * instead of the params/method-based heuristic.
+   */
+  defaultOverride?: { value: boolean; reason: string };
 }
 
 /**
@@ -81,9 +89,11 @@ export async function evaluateRevalidation<TEnv>(
     actionContext,
     stale,
     traceSource,
+    defaultOverride,
   } = options;
   const nextParams = segment.params || {};
   const paramsChanged = !paramsEqual(nextParams, prevParams);
+  const searchChanged = prevUrl.search !== nextUrl.search;
 
   // Trace helper: push a structured entry to the request-scoped trace buffer.
   // Guarded by isTraceActive() so object construction is skipped in production.
@@ -109,7 +119,12 @@ export async function evaluateRevalidation<TEnv>(
   let defaultShouldRevalidate: boolean;
   let defaultReason: string;
 
-  if (request.method === "POST") {
+  if (defaultOverride) {
+    // Caller injected the seed (e.g. parallel slot not in clientSegmentIds).
+    // Skip the type-derived heuristic — caller knows better in this context.
+    defaultShouldRevalidate = defaultOverride.value;
+    defaultReason = defaultOverride.reason;
+  } else if (request.method === "POST") {
     // Actions: revalidate segments that belong to the route, skip parent chain
     if (segment.type === "route") {
       // Route segment always revalidates on actions
@@ -134,19 +149,38 @@ export async function evaluateRevalidation<TEnv>(
     // Only the route segment revalidates by default - all others require explicit opt-in
 
     if (segment.type === "route") {
-      // Route segments revalidate when params change
-      // Routes are the primary param-dependent content and always need updates
-      defaultShouldRevalidate = paramsChanged;
+      // Route segments revalidate when path params OR search params change.
+      // Search params (e.g., ?page=2&sort=price) are server-parsed via ctx.search,
+      // so the handler must re-execute to produce updated content.
+      const routeChanged = paramsChanged || searchChanged;
+      defaultShouldRevalidate = routeChanged;
       defaultReason = paramsChanged
         ? "nav:params-changed"
-        : "nav:params-unchanged";
-      if (paramsChanged) {
-        debugLog("revalidation", "route params changed, revalidating", {
+        : searchChanged
+          ? "nav:search-changed"
+          : "nav:params-unchanged";
+      if (routeChanged) {
+        debugLog("revalidation", "route revalidating", {
           segmentId: segment.id,
+          paramsChanged,
+          searchChanged,
         });
       }
+    } else if (segment.belongsToRoute && (paramsChanged || searchChanged)) {
+      // Children of the route path (loaders, orphan layouts/parallels)
+      // revalidate when path params or search params change
+      defaultShouldRevalidate = true;
+      defaultReason = paramsChanged
+        ? "nav:route-child-params-changed"
+        : "nav:route-child-search-changed";
+      debugLog("revalidation", "route child revalidating", {
+        segmentId: segment.id,
+        segmentType: segment.type,
+        paramsChanged,
+        searchChanged,
+      });
     } else {
-      // Layouts and parallels default to no revalidation
+      // Parent layouts and parallels default to no revalidation
       // Cannot assume these segments depend on params without explicit declaration
       // Use custom revalidation functions to opt-in when needed
       defaultShouldRevalidate = false;

package/src/router/route-snapshot.ts

@@ -0,0 +1,245 @@
+/**
+ * Route Snapshot
+ *
+ * Pure data type representing the fully-resolved state of a single route match.
+ * Consolidates the duplicated findMatch + loadManifest + collectRouteMiddleware +
+ * cacheScope derivation that previously lived separately in preview-match.ts
+ * and match-api.ts.
+ *
+ * resolveRoute() is the factory: given a pathname and dependencies, it returns
+ * a RouteSnapshot (or redirect/null). Consumers (createMatchContextForFull,
+ * createMatchContextForPartial, previewMatch) read snapshot fields instead of
+ * re-deriving them.
+ */
+
+import type { CacheScope } from "../cache/cache-scope.js";
+import { createCacheScope } from "../cache/cache-scope.js";
+import type { EntryData, MetricsStore } from "../server/context.js";
+import { loadManifest } from "./manifest.js";
+import { collectRouteMiddleware } from "./middleware.js";
+import type { CollectedMiddleware } from "./middleware-types.js";
+import { traverseBack } from "./pattern-matching.js";
+import type { RouteMatchResult } from "./pattern-matching.js";
+
+/**
+ * Immutable snapshot of a resolved route match.
+ *
+ * Contains everything derivable from (pathname, findMatch, loadManifest)
+ * without request context, navigation state, or intercept logic.
+ */
+export interface RouteSnapshot<TEnv = any> {
+  /** Raw match result from the trie/pattern matcher */
+  matched: RouteMatchResult<TEnv>;
+  /** Resolved manifest entry (with loaded handler, loader, etc.) */
+  manifestEntry: EntryData;
+  /** All entries in the route chain (from traverseBack) */
+  entries: EntryData[];
+  /** Canonical route key (e.g. "blog.detail") */
+  routeKey: string;
+  /** Last segment of a dotted route key (e.g. "detail" from "blog.detail") */
+  localRouteName: string;
+  /** Extracted route params */
+  params: Record<string, string>;
+  /** Collected route-level middleware from the entry tree */
+  routeMiddleware: CollectedMiddleware[];
+  /** Merged cache scope from the entry chain */
+  cacheScope: CacheScope | null;
+  /** Whether the matched route is a passthrough route */
+  isPassthrough: boolean;
+  /** Response type for non-RSC routes (e.g. "application/json") */
+  responseType?: string;
+}
+
+export type ResolveRouteResult<TEnv = any> =
+  | { type: "match"; snapshot: RouteSnapshot<TEnv> }
+  | { type: "redirect"; redirectTo: string }
+  | null;
+
+export interface ResolveRouteDeps<TEnv = any> {
+  findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
+  metricsStore?: MetricsStore;
+  isSSR?: boolean;
+  /**
+   * When true, skip entries array and cacheScope chain construction.
+   * Used by previewMatch which only needs matched, manifestEntry,
+   * routeMiddleware, and responseType — avoids an extra traverseBack
+   * allocation and cacheScope composition on the hot classification path.
+   */
+  lite?: boolean;
+  /**
+   * When true, skip pushing the "route-matching" metric internally.
+   * Used by createMatchContextForPartial on the fresh path (no snapshot
+   * reuse) so it can measure current + prev + intercept-source findMatch
+   * calls under one combined "route-matching" metric. On the reuse path,
+   * the partial path emits "route-matching:nav" for the prev +
+   * intercept-source lookups only (current-route resolution was done
+   * during classification without metrics).
+   */
+  skipRouteMatchMetric?: boolean;
+}
+
+/**
+ * Resolve a pathname into a RouteSnapshot.
+ *
+ * This is the single source of truth for route derivation. It performs:
+ * 1. findMatch(pathname)
+ * 2. Redirect check
+ * 3. loadManifest
+ * 4. Passthrough detection
+ * 5. collectRouteMiddleware
+ * 6. Cache scope chain
+ * 7. responseType + localRouteName extraction
+ *
+ * Metrics timing is preserved identically to the previous inline code.
+ */
+export async function resolveRoute<TEnv = any>(
+  pathname: string,
+  deps: ResolveRouteDeps<TEnv>,
+): Promise<ResolveRouteResult<TEnv>> {
+  const {
+    metricsStore,
+    isSSR = false,
+    lite = false,
+    skipRouteMatchMetric = false,
+  } = deps;
+
+  const routeMatchStart =
+    metricsStore && !skipRouteMatchMetric ? performance.now() : 0;
+  const matched = deps.findMatch(pathname);
+  if (metricsStore && !skipRouteMatchMetric) {
+    metricsStore.metrics.push({
+      label: "route-matching",
+      duration: performance.now() - routeMatchStart,
+      startTime: routeMatchStart - metricsStore.requestStart,
+    });
+  }
+
+  if (!matched) {
+    return null;
+  }
+
+  if (matched.redirectTo) {
+    return { type: "redirect", redirectTo: matched.redirectTo };
+  }
+
+  const manifestStart = metricsStore ? performance.now() : 0;
+  const manifestEntry = await loadManifest(
+    matched.entry,
+    matched.routeKey,
+    pathname,
+    metricsStore,
+    isSSR,
+  );
+  if (metricsStore) {
+    metricsStore.metrics.push({
+      label: "manifest-loading",
+      duration: performance.now() - manifestStart,
+      startTime: manifestStart - metricsStore.requestStart,
+    });
+  }
+
+  const isPassthrough =
+    manifestEntry.type === "route" && manifestEntry.isPassthrough === true;
+
+  let entries: EntryData[];
+  let cacheScope: CacheScope | null = null;
+  if (lite) {
+    entries = [];
+  } else {
+    ({ entries, cacheScope } = buildEntriesAndCacheScope(manifestEntry));
+  }
+
+  const routeMiddleware = collectRouteMiddleware(
+    lite ? traverseBack(manifestEntry) : entries,
+    matched.params,
+  );
+
+  const responseType =
+    matched.responseType ||
+    (manifestEntry.type === "route" ? manifestEntry.responseType : undefined);
+
+  const localRouteName = matched.routeKey.includes(".")
+    ? matched.routeKey.split(".").pop()!
+    : matched.routeKey;
+
+  return {
+    type: "match",
+    snapshot: {
+      matched,
+      manifestEntry,
+      entries,
+      routeKey: matched.routeKey,
+      localRouteName,
+      params: matched.params,
+      routeMiddleware,
+      cacheScope,
+      isPassthrough,
+      responseType,
+    },
+  };
+}
+
+/**
+ * Fill in the entries and cacheScope fields on a lite snapshot.
+ *
+ * When classifyRequest produces a lite snapshot (entries=[], cacheScope=null),
+ * this function computes the missing fields from manifestEntry without
+ * re-running findMatch, loadManifest, or collectRouteMiddleware.
+ *
+ * If the snapshot already has entries, returns it as-is.
+ */
+export function ensureFullRouteSnapshot<TEnv = any>(
+  snapshot: RouteSnapshot<TEnv>,
+): RouteSnapshot<TEnv> {
+  if (snapshot.entries.length > 0) {
+    return snapshot;
+  }
+
+  const { entries, cacheScope } = buildEntriesAndCacheScope(
+    snapshot.manifestEntry,
+  );
+  return { ...snapshot, entries, cacheScope };
+}
+
+/**
+ * Materialize the entry chain and derive the merged cache scope.
+ * Shared by resolveRoute (non-lite) and ensureFullRouteSnapshot.
+ */
+function buildEntriesAndCacheScope(manifestEntry: EntryData): {
+  entries: EntryData[];
+  cacheScope: CacheScope | null;
+} {
+  const entries = [...traverseBack(manifestEntry)];
+  let cacheScope: CacheScope | null = null;
+  for (const entry of entries) {
+    if (entry.cache) {
+      cacheScope = createCacheScope(entry.cache, cacheScope);
+    }
+  }
+  return { entries, cacheScope };
+}
+
+/**
+ * Test helper: create a RouteSnapshot with sensible defaults and overrides.
+ */
+export function createRouteSnapshot<TEnv = any>(
+  overrides?: Partial<RouteSnapshot<TEnv>>,
+): RouteSnapshot<TEnv> {
+  return {
+    matched: {
+      entry: {} as any,
+      routeKey: "test",
+      params: {},
+      optionalParams: new Set(),
+    } as RouteMatchResult<TEnv>,
+    manifestEntry: { type: "route", shortCode: "R0", parent: null } as any,
+    entries: [],
+    routeKey: "test",
+    localRouteName: "test",
+    params: {},
+    routeMiddleware: [],
+    cacheScope: null,
+    isPassthrough: false,
+    ...overrides,
+  };
+}

package/src/router/router-context.ts

@@ -138,6 +138,7 @@ export interface RouterContext<TEnv = any> {
     interceptResult: InterceptResult | null,
     localRouteName: string,
     pathname: string,
+    stale?: boolean,
   ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
 
   // Generator-based segment resolution (for pipeline)
@@ -188,7 +189,10 @@ export interface RouterContext<TEnv = any> {
       | "cache-hit"
       | "loader"
       | "parallel"
-      | "orphan-layout";
+      | "orphan-layout"
+      | "route-handler"
+      | "layout-handler"
+      | "intercept-loader";
   }) => Promise<boolean>;
 
   // Request context
@@ -206,6 +210,7 @@ export interface RouterContext<TEnv = any> {
     params: Record<string, string>,
     handlerContext: HandlerContext<any, TEnv>,
     loaderPromises: Map<string, Promise<any>>,
+    options?: { skipLoaders?: boolean },
   ) => Promise<ResolvedSegment[]>;
 
   // Generator-based simple resolution