@rangojs/router 0.0.0-experimental.14 → 0.0.0-experimental.141

package/src/router/request-classification.ts

@@ -0,0 +1,278 @@
+/**
+ * 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";
+
+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 AppSwitchReloadPlan {
+  mode: "app-switch";
+  /** Clean target URL (internal _rsc_* params stripped) to navigate to. */
+  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>
+  | AppSwitchReloadPlan
+  | ResponseRoutePlan<TEnv>
+  | LoaderFetchPlan<TEnv>
+  | PeRenderPlan<TEnv>
+  | ActionPlan<TEnv>
+  | FullRenderPlan<TEnv>
+  | PartialRenderPlan<TEnv>;
+
+/**
+ * Plans that have passed the terminal-check gate (version-mismatch and
+ * app-switch reloads handled) and are ready for execution. Always have a
+ * `route` field.
+ */
+export type ExecutableRequestPlan<TEnv = any> = Exclude<
+  RequestPlan<TEnv>,
+  VersionMismatchPlan<TEnv> | AppSwitchReloadPlan
+>;
+
+/**
+ * Re-export individual plan types for consumers that need to narrow.
+ */
+export type {
+  RedirectPlan,
+  VersionMismatchPlan,
+  ResponseRoutePlan,
+  LoaderFetchPlan,
+  PeRenderPlan,
+  ActionPlan,
+  FullRenderPlan,
+  PartialRenderPlan,
+};
+
+export interface ClassifyRequestDeps<TEnv = any> {
+  findMatch: (
+    pathname: string,
+  ) => RouteMatchResult<TEnv> | null | Promise<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");
+
+  const clientVersion = url.searchParams.get("_rsc_v");
+  if (
+    deps.routerVersion &&
+    clientVersion &&
+    clientVersion !== deps.routerVersion
+  ) {
+    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 {}
+      }
+    }
+
+    return {
+      mode: "version-mismatch",
+      reloadUrl,
+    };
+  }
+
+  const clientRouterId = url.searchParams.get("_rsc_rid");
+  if (
+    clientRouterId &&
+    clientRouterId !== deps.routerId &&
+    url.searchParams.has("_rsc_partial")
+  ) {
+    return {
+      mode: "app-switch",
+      reloadUrl: stripInternalParams(url).toString(),
+    };
+  }
+
+  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 },
+    });
+  }
+
+  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;
+
+  const responseResult = await classifyResponseRoute(
+    request,
+    pathname,
+    snapshot,
+  );
+  if (responseResult) {
+    return responseResult;
+  }
+
+  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 };
+  }
+
+  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 };
+  }
+
+  if (url.searchParams.has("_rsc_partial")) {
+    return { mode: "partial-render", route: snapshot, negotiated };
+  }
+
+  return { mode: "full-render", route: snapshot, negotiated };
+}
+
+/**
+ * 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 negotiation = await negotiateRoute(request, pathname, snapshot);
+  return negotiation
+    ? { mode: "response", route: snapshot, ...negotiation }
+    : null;
+}

package/src/router/revalidation.ts

@@ -4,9 +4,63 @@
  * Evaluates whether segments should revalidate based on params, actions, and custom functions.
  */
 
-import type { ResolvedSegment, HandlerContext } from "../types";
+import type { ResolvedSegment, HandlerContext, ActionRef } from "../types";
 import type { ActionContext } from "./types";
-import { debugLog } from "./logging.js";
+import {
+  debugLog,
+  pushRevalidationTraceEntry,
+  isTraceActive,
+} from "./logging.js";
+import type { RevalidationTraceEntry } from "./logging.js";
+import { _getRequestContext } from "../server/request-context.js";
+import { isAutoGeneratedRouteName } from "../route-name.js";
+import { paramsEqual } from "./params-util.js";
+
+/**
+ * Resolve a server-action reference's stable id, mirroring how the action
+ * boundary derives `actionContext.actionId` in `rsc/server-action.ts`
+ * (`$id ?? $$id`): the file-path `$id` set by the expose-action-id plugin in a
+ * production RSC build when present, otherwise React's `$$id`. Resolving both
+ * the incoming `actionId` and the reference with the same precedence makes
+ * `isAction()` form-agnostic across dev and production.
+ */
+function resolveActionRefId(ref: unknown): string | undefined {
+  if (ref == null) return undefined;
+  const r = ref as { $id?: unknown; $$id?: unknown };
+  if (typeof r.$id === "string") return r.$id;
+  if (typeof r.$$id === "string") return r.$$id;
+  return undefined;
+}
+
+/**
+ * Build the `isAction()` helper bound to the current action's id. Called with no
+ * arguments it answers "is this request an action at all?" (any action) — `true`
+ * during action handling, `false` on plain navigation. Called with one or more
+ * action references it narrows to those: a single imported action, several
+ * (variadic), or any export of a namespace import (`import * as Mod`). Returns
+ * `false` when there is no action (plain navigation) or nothing matches.
+ */
+function makeIsAction(
+  currentActionId: string | undefined,
+): (...actions: ActionRef[]) => boolean {
+  return (...actions: ActionRef[]): boolean => {
+    if (!currentActionId) return false;
+    // Bare isAction(): an action is in flight (currentActionId is set) and the
+    // caller did not narrow to a specific action, so this is "any action".
+    if (actions.length === 0) return true;
+    for (const action of actions) {
+      if (typeof action === "function") {
+        if (resolveActionRefId(action) === currentActionId) return true;
+      } else if (action && typeof action === "object") {
+        // Namespace import: match any export of the module.
+        for (const value of Object.values(action)) {
+          if (resolveActionRefId(value) === currentActionId) return true;
+        }
+      }
+    }
+    return false;
+  };
+}
 
 /**
  * Options for revalidation evaluation
@@ -34,6 +88,16 @@ interface EvaluateRevalidationOptions<TEnv> {
   actionContext?: ActionContext;
   /** If true, this is a stale cache revalidation request */
   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 };
 }
 
 /**
@@ -41,7 +105,7 @@ interface EvaluateRevalidationOptions<TEnv> {
  * Optimized to use prevParams directly and avoid building previous segments
  */
 export async function evaluateRevalidation<TEnv>(
-  options: EvaluateRevalidationOptions<TEnv>
+  options: EvaluateRevalidationOptions<TEnv>,
 ): Promise<boolean> {
   const {
     segment,
@@ -55,51 +119,81 @@ export async function evaluateRevalidation<TEnv>(
     context,
     actionContext,
     stale,
+    traceSource,
+    defaultOverride,
   } = options;
   const nextParams = segment.params || {};
-  const paramsChanged =
-    Object.keys(nextParams).length !== Object.keys(prevParams).length ||
-    Object.keys(nextParams).some(
-      (key) => nextParams[key] !== prevParams[key]
-    );
+  const paramsChanged = !paramsEqual(nextParams, prevParams);
+  const searchChanged = prevUrl.search !== nextUrl.search;
+
+  function pushTrace(
+    defaultVal: boolean,
+    finalVal: boolean,
+    reason: string,
+  ): void {
+    if (!isTraceActive()) return;
+    pushRevalidationTraceEntry({
+      segmentId: segment.id,
+      segmentType: segment.type,
+      belongsToRoute: segment.belongsToRoute ?? false,
+      source: traceSource ?? "segment-resolution",
+      defaultShouldRevalidate: defaultVal,
+      finalShouldRevalidate: finalVal,
+      reason,
+      customRevalidators: revalidations.length || undefined,
+    });
+  }
 
-  // Calculate default revalidation based on segment type and request method
   let defaultShouldRevalidate: boolean;
+  let defaultReason: string;
 
-  if (request.method === "POST") {
-    // Actions: revalidate segments that belong to the route, skip parent chain
+  if (defaultOverride) {
+    defaultShouldRevalidate = defaultOverride.value;
+    defaultReason = defaultOverride.reason;
+  } else if (request.method === "POST") {
     if (segment.type === "route") {
-      // Route segment always revalidates on actions
       defaultShouldRevalidate = true;
+      defaultReason = "action:route-segment";
     } else if (segment.type === "loader") {
-      // Loaders always revalidate on actions - they often contain action-sensitive data
-      // (e.g., cart count after add-to-cart action)
       defaultShouldRevalidate = true;
+      defaultReason = "action:loader-segment";
     } else if (segment.belongsToRoute) {
-      // Segment belongs to route (orphan layouts/parallels) - revalidate
       defaultShouldRevalidate = true;
+      defaultReason = "action:belongs-to-route";
     } else {
-      // Parent chain segment (shared layouts/parallels) - don't revalidate
       defaultShouldRevalidate = false;
+      defaultReason = "action:parent-chain-skip";
     }
   } else {
-    // Navigation (GET): Conservative defaults to minimize unnecessary revalidations
-    // 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;
-      if (paramsChanged) {
-        debugLog("revalidation", "route params changed, revalidating", {
+      const routeChanged = paramsChanged || searchChanged;
+      defaultShouldRevalidate = routeChanged;
+      defaultReason = paramsChanged
+        ? "nav:params-changed"
+        : searchChanged
+          ? "nav:search-changed"
+          : "nav:params-unchanged";
+      if (routeChanged) {
+        debugLog("revalidation", "route revalidating", {
           segmentId: segment.id,
+          paramsChanged,
+          searchChanged,
         });
       }
+    } else if (segment.belongsToRoute && (paramsChanged || searchChanged)) {
+      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
-      // Cannot assume these segments depend on params without explicit declaration
-      // Use custom revalidation functions to opt-in when needed
       defaultShouldRevalidate = false;
+      defaultReason = "nav:non-route-skip";
       debugLog("revalidation", "non-route segment skipped by default", {
         segmentId: segment.id,
         segmentType: segment.type,
@@ -107,7 +201,6 @@ export async function evaluateRevalidation<TEnv>(
     }
   }
 
-  // No custom revalidations defined - return default behavior without prev segment
   if (revalidations.length === 0) {
     if (defaultShouldRevalidate) {
       debugLog("revalidation", "default revalidate=true", {
@@ -120,57 +213,103 @@ export async function evaluateRevalidation<TEnv>(
         segmentId: segment.id,
       });
     }
+    pushTrace(defaultShouldRevalidate, defaultShouldRevalidate, defaultReason);
     return defaultShouldRevalidate;
   }
 
-  // Custom revalidations exist - may need full prev segment
-  // Lazy load prev segment only if getPrevSegment provided
   const prevSegment = getPrevSegment ? await getPrevSegment() : null;
 
-  // Execute revalidation functions with soft/hard decision pattern
   let currentSuggestion = defaultShouldRevalidate;
 
+  const toRouteName =
+    routeKey && !isAutoGeneratedRouteName(routeKey) ? routeKey : undefined;
+  const reqCtx = _getRequestContext();
+  const prevRouteKey = reqCtx?._prevRouteKey;
+  const fromRouteName =
+    prevRouteKey && !isAutoGeneratedRouteName(prevRouteKey)
+      ? prevRouteKey
+      : undefined;
+
   for (const { name, fn } of revalidations) {
-    const result = fn({
-      currentParams: prevSegment?.params || prevParams, // Use segment params if available, else route params
-      currentUrl: prevUrl,
-      nextParams,
-      nextUrl,
-      defaultShouldRevalidate: currentSuggestion,
-      context,
-      // Segment metadata (which segment is being evaluated)
-      segmentType: segment.type,
-      layoutName: segment.layoutName,
-      slotName: segment.slot,
-      // Action context (only populated when triggered by server action)
-      actionId: actionContext?.actionId,
-      actionUrl: actionContext?.actionUrl,
-      actionResult: actionContext?.actionResult,
-      formData: actionContext?.formData,
-      method: request.method, // GET for navigation, POST for actions
-      routeName: routeKey, // User-friendly route name (e.g., "products.detail")
-      // Stale cache context (only true for background revalidation after stale cache render)
-      stale,
-    });
+    let result: any;
+    try {
+      result = fn({
+        currentParams: prevSegment?.params || prevParams, // Use segment params if available, else route params
+        currentUrl: prevUrl,
+        nextParams,
+        nextUrl,
+        defaultShouldRevalidate: currentSuggestion,
+        context,
+        // Segment metadata (which segment is being evaluated)
+        segmentType: segment.type,
+        layoutName: segment.layoutName,
+        slotName: segment.slot,
+        // Action context (only populated when triggered by server action)
+        actionId: actionContext?.actionId,
+        isAction: makeIsAction(actionContext?.actionId),
+        actionUrl: actionContext?.actionUrl,
+        actionResult: actionContext?.actionResult,
+        formData: actionContext?.formData,
+        method: request.method,
+        routeName: toRouteName,
+        fromRouteName,
+        toRouteName,
+        stale,
+      });
+    } catch (error) {
+      // A thrown Response is control flow (e.g. `throw redirect(...)`), not a
+      // failure: re-throw it so the handler chokepoint (match-handlers.ts)
+      // turns it into the intended redirect/response. This mirrors how that
+      // catch special-cases `error instanceof Response`.
+      if (error instanceof Response) throw error;
+      // Fail open for genuine errors: a buggy user revalidate fn must not
+      // collapse the whole entry's loader batch into a failed partial render.
+      // Mirror the dynamic-tags fail-open in cache/cache-policy.ts: log and
+      // defer to the current default decision, leaving currentSuggestion
+      // unchanged. TODO: route through callOnError(phase "revalidation") once
+      // evaluateRevalidation is given the onError seam (today the error only
+      // reaches onError via the entry-collapse path in match-handlers.ts).
+      console.error(
+        `[revalidate] "${name}" threw for segment "${segment.id}"; using default decision:`,
+        error,
+      );
+      continue;
+    }
+
+    // The revalidate fn contract (handler-context.ts) is SYNCHRONOUS: it must
+    // return a boolean, a { defaultShouldRevalidate } object, or null/undefined.
+    // A Promise-returning (async) fn matches none of the decision branches below
+    // and silently falls through keeping the current default — a hard-to-find
+    // misuse. We do NOT await it (that would change the sync contract); instead
+    // we surface it as a dev-mode warning so the silent drop is diagnosable.
+    // Mirrors defer.ts: gated to dev, stripped from production builds.
+    if (
+      process.env.NODE_ENV !== "production" &&
+      result != null &&
+      typeof (result as { then?: unknown }).then === "function"
+    ) {
+      console.warn(
+        `[rango] revalidate fn "${name}" returned a Promise; revalidate ` +
+          `functions must be synchronous (return a boolean, ` +
+          `{ defaultShouldRevalidate }, or null/undefined). The async result ` +
+          `was IGNORED and the default (${currentSuggestion}) was kept. ` +
+          `Move async work into a loader instead.`,
+      );
+    }
 
-    // Check return type:
-    // - boolean: hard decision, short-circuit immediately
-    // - { defaultShouldRevalidate: boolean }: soft decision, update suggestion and continue
-    // - null/undefined: use default behavior (equivalent to returning { defaultShouldRevalidate })
     if (typeof result === "boolean") {
-      // Hard decision - short-circuit
       debugLog("revalidation", "hard decision", {
         segmentId: segment.id,
         revalidator: name,
         revalidate: result,
       });
+      pushTrace(defaultShouldRevalidate, result, `hard:${name}`);
       return result;
     } else if (
       result &&
       typeof result === "object" &&
       "defaultShouldRevalidate" in result
     ) {
-      // Soft decision - update suggestion and continue
       currentSuggestion = result.defaultShouldRevalidate;
       debugLog("revalidation", "soft decision", {
         segmentId: segment.id,
@@ -178,21 +317,23 @@ export async function evaluateRevalidation<TEnv>(
         revalidate: currentSuggestion,
       });
     } else if (result === null || result === undefined) {
-      // Defer to default - equivalent to { defaultShouldRevalidate: currentSuggestion }
-      // This means "I don't care, use whatever the default is"
       debugLog("revalidation", "deferred to current default", {
         segmentId: segment.id,
         revalidator: name,
         revalidate: currentSuggestion,
       });
-      // currentSuggestion stays the same, continue to next function
     }
   }
 
-  // All revalidators completed - use final suggestion
   debugLog("revalidation", "final decision", {
     segmentId: segment.id,
     revalidate: currentSuggestion,
   });
+  const softNames = revalidations.map((r) => r.name).join(",");
+  pushTrace(
+    defaultShouldRevalidate,
+    currentSuggestion,
+    `soft-chain:${softNames}`,
+  );
   return currentSuggestion;
 }