@rangojs/router 0.0.0-experimental.15 → 0.0.0-experimental.151

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

package/src/router/route-snapshot.ts

@@ -0,0 +1,256 @@
+/**
+ * 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;
+  /**
+   * The isSSR flag the manifest was resolved with. Recorded so consumers can
+   * decide whether the snapshot is reusable: a snapshot resolved with isSSR
+   * differs (loading({ ssr: false }) entries) and is cached under a different
+   * manifest partition, so the full (document) path only reuses an isSSR:true
+   * snapshot and the partial path only reuses a non-isSSR one. Undefined on
+   * inline snapshots (redirect / not-found) that are never reused.
+   */
+  isSSR?: boolean;
+}
+
+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 | Promise<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 = await 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,
+      isSSR,
+    },
+  };
+}
+
+/**
+ * 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: {},
+    } as RouteMatchResult<TEnv>,
+    manifestEntry: { type: "route", shortCode: "R0", parent: null } as any,
+    entries: [],
+    routeKey: "test",
+    localRouteName: "test",
+    params: {},
+    routeMiddleware: [],
+    cacheScope: null,
+    isPassthrough: false,
+    ...overrides,
+  };
+}