@rangojs/router 0.0.0-experimental.b9cb8739 → 0.0.0-experimental.bd6e11bc

package/src/router/match-api.ts

@@ -22,10 +22,10 @@ import { collectRouteMiddleware } from "./middleware.js";
 import { traverseBack } from "./pattern-matching.js";
 import { DefaultErrorFallback } from "../default-error-boundary.js";
 import {
-  EntryData,
-  LoaderEntry,
+  type EntryData,
+  type LoaderEntry,
   getContext,
-  InterceptSelectorContext,
+  type InterceptSelectorContext,
 } from "../server/context";
 import type { ErrorBoundaryHandler, ErrorInfo, MatchResult } from "../types";
 import type { ReactNode } from "react";
@@ -36,7 +36,14 @@ import {
   setRequestContextPrevRouteKey,
 } from "../server/request-context.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
+import type { DefaultRouteName } from "../types/global-namespace.js";
 import { debugLog, debugWarn } from "./logging.js";
+import {
+  resolveRoute,
+  ensureFullRouteSnapshot,
+  type RouteSnapshot,
+} from "./route-snapshot.js";
+import { resolveNavigation } from "./navigation-snapshot.js";
 
 /**
  * Create match context for full requests (document/SSR).
@@ -52,57 +59,36 @@ export async function createMatchContextForFull<TEnv>(
 
   const metricsStore = deps.getMetricsStore();
 
-  const routeMatchStart = metricsStore ? performance.now() : 0;
-  const matched = deps.findMatch(pathname, metricsStore);
-  if (metricsStore) {
-    metricsStore.metrics.push({
-      label: "route-matching",
-      duration: performance.now() - routeMatchStart,
-      startTime: routeMatchStart - metricsStore.requestStart,
-    });
-  }
+  // Full renders always resolve fresh with isSSR: true because loadManifest
+  // keys its cache on isSSR and stamps Store.isSSR for downstream behavior.
+  const result = await resolveRoute<TEnv>(pathname, {
+    findMatch: (p) => deps.findMatch(p, metricsStore),
+    metricsStore,
+    isSSR: true,
+  });
 
-  if (!matched) {
+  if (!result) {
     throw new RouteNotFoundError(`No route matched for ${pathname}`, {
       cause: { pathname, method: request.method },
     });
   }
 
-  if (matched.redirectTo) {
+  if (result.type === "redirect") {
     return {
       type: "redirect",
-      redirectUrl: matched.redirectTo + url.search,
+      redirectUrl: result.redirectTo + url.search,
     };
   }
 
-  const manifestStart = metricsStore ? performance.now() : 0;
-  const manifestEntry = await loadManifest(
-    matched.entry,
-    matched.routeKey,
-    pathname,
-    metricsStore,
-    true,
-  );
-  if (metricsStore) {
-    metricsStore.metrics.push({
-      label: "manifest-loading",
-      duration: performance.now() - manifestStart,
-      startTime: manifestStart - metricsStore.requestStart,
-    });
-  }
+  const snapshot = result.snapshot;
 
-  if (
-    manifestEntry.type === "route" &&
-    manifestEntry.prerenderDef?.options?.passthrough === true
-  ) {
+  const { matched } = snapshot;
+
+  // Backward compat: downstream middleware reads matched.pt
+  if (snapshot.isPassthrough) {
     matched.pt = true;
   }
 
-  const routeMiddleware = collectRouteMiddleware(
-    traverseBack(manifestEntry),
-    matched.params,
-  );
-
   // Clean URL without internal _rsc* params for userland access
   const cleanUrl = stripInternalParams(url);
 
@@ -134,14 +120,6 @@ export async function createMatchContextForFull<TEnv>(
     Store.metrics = metricsStore;
   }
 
-  const entries = [...traverseBack(manifestEntry)];
-  let cacheScope: CacheScope | null = null;
-  for (const entry of entries) {
-    if (entry.cache) {
-      cacheScope = createCacheScope(entry.cache, cacheScope);
-    }
-  }
-
   return {
     request,
     url: cleanUrl,
@@ -154,12 +132,10 @@ export async function createMatchContextForFull<TEnv>(
     prevParams: {},
     prevMatch: null,
     matched,
-    manifestEntry,
-    entries,
+    manifestEntry: snapshot.manifestEntry,
+    entries: snapshot.entries,
     routeKey: matched.routeKey,
-    localRouteName: matched.routeKey.includes(".")
-      ? matched.routeKey.split(".").pop()!
-      : matched.routeKey,
+    localRouteName: snapshot.localRouteName,
     handlerContext,
     loaderPromises,
     routeMap: deps.getRouteMap(),
@@ -175,16 +151,16 @@ export async function createMatchContextForFull<TEnv>(
       segments: { path: [], ids: [] },
       toRouteName:
         matched.routeKey && !isAutoGeneratedRouteName(matched.routeKey)
-          ? matched.routeKey
+          ? (matched.routeKey as DefaultRouteName)
           : undefined,
     },
     isSameRouteNavigation: false,
     interceptResult: null,
-    cacheScope,
+    cacheScope: snapshot.cacheScope,
     isIntercept: false,
     actionContext: undefined,
     isAction: false,
-    routeMiddleware,
+    routeMiddleware: snapshot.routeMiddleware,
     isFullMatch: true,
   };
 }
@@ -204,103 +180,85 @@ export async function createMatchContextForPartial<TEnv>(
 
   const metricsStore = deps.getMetricsStore();
 
-  const clientSegmentIds =
-    url.searchParams.get("_rsc_segments")?.split(",").filter(Boolean) || [];
-  const stale = url.searchParams.get("_rsc_stale") === "true";
-  const previousUrl =
-    request.headers.get("X-RSC-Router-Client-Path") ||
-    request.headers.get("Referer");
-  const interceptSourceUrl = request.headers.get(
-    "X-RSC-Router-Intercept-Source",
-  );
+  const isHmr = !!request.headers.get("X-RSC-HMR");
 
   // HMR: clear manifest cache so stale handler references are discarded
-  if (request.headers.get("X-RSC-HMR")) {
+  if (isHmr) {
     clearManifestCache();
   }
 
-  if (!previousUrl) {
-    return null;
-  }
-
-  let prevUrl: URL;
-  try {
-    prevUrl = new URL(previousUrl, url.origin);
-  } catch {
-    return null;
-  }
+  // Reuse the classified snapshot when available and not invalidated by HMR.
+  // classifyRequest already called resolveRoute(lite) with isSSR=false, which
+  // matches the partial path. On HMR, discard to pick up manifest changes.
+  const classifiedRoute = isHmr
+    ? undefined
+    : getRequestContext()?._classifiedRoute;
+
+  // Time route matching. On the reuse path, only nav findMatch calls are new
+  // (current-route findMatch and manifest-loading were already timed during
+  // classifyRequest via its metricsStore). On the fresh path, all findMatch
+  // calls are measured together.
+  const routeMatchStart = metricsStore ? performance.now() : 0;
 
-  let interceptContextUrl: URL;
-  try {
-    interceptContextUrl = interceptSourceUrl
-      ? new URL(interceptSourceUrl, url.origin)
-      : prevUrl;
-  } catch {
-    interceptContextUrl = prevUrl;
-  }
+  let snapshot: RouteSnapshot<TEnv>;
+  if (classifiedRoute && classifiedRoute.manifestEntry) {
+    snapshot = ensureFullRouteSnapshot(classifiedRoute);
+  } else {
+    const result = await resolveRoute<TEnv>(pathname, {
+      findMatch: (p) => deps.findMatch(p, metricsStore),
+      metricsStore,
+      isSSR: false,
+      skipRouteMatchMetric: true,
+    });
 
-  const routeMatchStart = metricsStore ? performance.now() : 0;
-  const prevMatch = deps.findMatch(prevUrl.pathname);
-  const prevParams = prevMatch?.params || {};
-  const interceptContextMatch = interceptSourceUrl
-    ? deps.findMatch(interceptContextUrl.pathname)
-    : prevMatch;
+    if (!result) {
+      throw new RouteNotFoundError(`No route matched for ${pathname}`, {
+        cause: { pathname, method: request.method },
+      });
+    }
 
-  const matched = deps.findMatch(pathname, metricsStore);
+    if (result.type === "redirect") {
+      return null;
+    }
 
-  if (metricsStore) {
-    metricsStore.metrics.push({
-      label: "route-matching",
-      duration: performance.now() - routeMatchStart,
-      startTime: routeMatchStart - metricsStore.requestStart,
-    });
+    snapshot = result.snapshot;
   }
 
-  if (!matched) {
-    throw new RouteNotFoundError(`No route matched for ${pathname}`, {
-      cause: { pathname, method: request.method, previousUrl },
-    });
-  }
+  const { matched } = snapshot;
 
-  if (matched.redirectTo) {
-    return null;
+  // Backward compat: downstream middleware reads matched.pt
+  if (snapshot.isPassthrough) {
+    matched.pt = true;
   }
 
-  if (prevMatch && prevMatch.entry !== matched.entry && !matched.pr) {
-    debugLog("matchPartial", "route group changed", {
-      from: prevMatch.routeKey,
-      to: matched.routeKey,
-    });
+  // Navigation state (prev + intercept-source findMatch calls)
+  const nav = resolveNavigation(request, url, matched.routeKey, {
+    findMatch: deps.findMatch,
+  });
+  if (!nav) {
+    return null;
   }
 
-  const manifestStart = metricsStore ? performance.now() : 0;
-  const manifestEntry = await loadManifest(
-    matched.entry,
-    matched.routeKey,
-    pathname,
-    metricsStore,
-    false,
-  );
+  // Push route-matching metric. On the fresh path this covers all findMatch
+  // calls (current + prev + intercept-source). On the reuse path, current-route
+  // findMatch was already timed during classification, so this only covers
+  // the nav lookups (prev + intercept-source).
   if (metricsStore) {
+    const isReuse = !!classifiedRoute;
     metricsStore.metrics.push({
-      label: "manifest-loading",
-      duration: performance.now() - manifestStart,
-      startTime: manifestStart - metricsStore.requestStart,
+      label: isReuse ? "route-matching:nav" : "route-matching",
+      duration: performance.now() - routeMatchStart,
+      startTime: routeMatchStart - metricsStore.requestStart,
     });
   }
 
-  if (
-    manifestEntry.type === "route" &&
-    manifestEntry.prerenderDef?.options?.passthrough === true
-  ) {
-    matched.pt = true;
+  if (nav.prevMatch && nav.prevMatch.entry !== matched.entry && !matched.pr) {
+    debugLog("matchPartial", "route group changed", {
+      from: nav.prevMatch.routeKey,
+      to: matched.routeKey,
+    });
   }
 
-  const routeMiddleware = collectRouteMiddleware(
-    traverseBack(manifestEntry),
-    matched.params,
-  );
-
   // Clean URL without internal _rsc* params for userland access
   const cleanUrl = stripInternalParams(url);
 
@@ -317,9 +275,8 @@ export async function createMatchContextForPartial<TEnv>(
     matched.pt === true,
   );
 
-  const clientSegmentSet = new Set(clientSegmentIds);
   debugLog("matchPartial", "client segments", {
-    segments: Array.from(clientSegmentSet),
+    segments: Array.from(nav.clientSegmentSet),
   });
 
   const loaderPromises = new Map<string, Promise<any>>();
@@ -337,100 +294,78 @@ export async function createMatchContextForPartial<TEnv>(
     Store.metrics = metricsStore;
   }
 
-  const isSameRouteNavigation = !!(
-    interceptContextMatch && interceptContextMatch.routeKey === matched.routeKey
-  );
-
-  if (interceptSourceUrl) {
+  if (nav.hasInterceptSource) {
     debugLog("matchPartial.intercept", "intercept context detected", {
       currentUrl: pathname,
-      interceptSource: interceptSourceUrl,
-      contextRoute: interceptContextMatch?.routeKey,
+      interceptSource: nav.interceptContextUrl.href,
+      contextRoute: nav.interceptContextMatch?.routeKey,
       currentRoute: matched.routeKey,
-      sameRouteNavigation: isSameRouteNavigation,
+      sameRouteNavigation: nav.isSameRouteNavigation,
     });
   }
 
-  const localRouteName = matched.routeKey.includes(".")
-    ? matched.routeKey.split(".").pop()!
-    : matched.routeKey;
-
-  const filteredSegmentIds = clientSegmentIds.filter((id) => {
-    if (id.includes(".@")) return false;
-    if (/D\d+\./.test(id)) return false;
-    return true;
-  });
-  const effectiveFromUrl = interceptSourceUrl ? interceptContextUrl : prevUrl;
-  const effectiveFromMatch = interceptSourceUrl
-    ? interceptContextMatch
-    : prevMatch;
-
   // Store previous route key on the request context for revalidation
   // fromRouteName. Uses effectiveFromMatch so intercept-source navigations
   // see the intercept origin route, not the plain previous URL route.
-  setRequestContextPrevRouteKey(effectiveFromMatch?.routeKey);
+  setRequestContextPrevRouteKey(nav.effectiveFromMatch?.routeKey);
 
   const interceptSelectorContext: InterceptSelectorContext = {
-    from: effectiveFromUrl,
+    from: nav.effectiveFromUrl,
     to: cleanUrl,
     params: matched.params,
     request,
     env,
     segments: {
-      path: effectiveFromUrl.pathname.split("/").filter(Boolean),
-      ids: filteredSegmentIds,
+      path: nav.effectiveFromUrl.pathname.split("/").filter(Boolean),
+      ids: nav.filteredSegmentIds,
     },
     fromRouteName:
-      effectiveFromMatch?.routeKey &&
-      !isAutoGeneratedRouteName(effectiveFromMatch.routeKey)
-        ? effectiveFromMatch.routeKey
+      nav.effectiveFromMatch?.routeKey &&
+      !isAutoGeneratedRouteName(nav.effectiveFromMatch.routeKey)
+        ? (nav.effectiveFromMatch.routeKey as DefaultRouteName)
         : undefined,
     toRouteName:
       matched.routeKey && !isAutoGeneratedRouteName(matched.routeKey)
-        ? matched.routeKey
+        ? (matched.routeKey as DefaultRouteName)
         : undefined,
   };
   const isAction = !!actionContext;
 
-  const clientHasInterceptSegments = [...clientSegmentSet].some((id) =>
+  const clientHasInterceptSegments = [...nav.clientSegmentSet].some((id) =>
     id.includes(".@"),
   );
   const skipInterceptForAction = isAction && !clientHasInterceptSegments;
   const interceptResult =
-    isSameRouteNavigation || skipInterceptForAction
+    nav.isSameRouteNavigation || skipInterceptForAction
       ? null
       : findInterceptForRoute(
           matched.routeKey,
-          manifestEntry.parent,
+          snapshot.manifestEntry.parent,
           interceptSelectorContext,
           isAction,
         ) ||
-        (localRouteName !== matched.routeKey
+        (snapshot.localRouteName !== matched.routeKey
           ? findInterceptForRoute(
-              localRouteName,
-              manifestEntry.parent,
+              snapshot.localRouteName,
+              snapshot.manifestEntry.parent,
               interceptSelectorContext,
               isAction,
             )
           : null);
 
+  // Make a mutable copy of clientSegmentSet so we can delete entries
+  // for same-route navigation forcing
+  const clientSegmentSet = new Set(nav.clientSegmentSet);
+
   if (
-    isSameRouteNavigation &&
-    manifestEntry.type === "route" &&
-    interceptSourceUrl
+    nav.isSameRouteNavigation &&
+    snapshot.manifestEntry.type === "route" &&
+    nav.hasInterceptSource
   ) {
     debugLog("matchPartial.intercept", "forcing route segment render", {
-      segmentId: manifestEntry.shortCode,
+      segmentId: snapshot.manifestEntry.shortCode,
     });
-    clientSegmentSet.delete(manifestEntry.shortCode);
-  }
-
-  const entries = [...traverseBack(manifestEntry)];
-  let cacheScope: CacheScope | null = null;
-  for (const entry of entries) {
-    if (entry.cache) {
-      cacheScope = createCacheScope(entry.cache, cacheScope);
-    }
+    clientSegmentSet.delete(snapshot.manifestEntry.shortCode);
   }
 
   const isIntercept = !!interceptResult;
@@ -440,31 +375,31 @@ export async function createMatchContextForPartial<TEnv>(
     url: cleanUrl,
     pathname,
     env,
-    clientSegmentIds,
+    clientSegmentIds: nav.clientSegmentIds,
     clientSegmentSet,
-    stale,
-    prevUrl,
-    prevParams,
-    prevMatch,
+    stale: nav.stale,
+    prevUrl: nav.prevUrl,
+    prevParams: nav.prevParams,
+    prevMatch: nav.prevMatch,
     matched,
-    manifestEntry,
-    entries,
+    manifestEntry: snapshot.manifestEntry,
+    entries: snapshot.entries,
     routeKey: matched.routeKey,
-    localRouteName,
+    localRouteName: snapshot.localRouteName,
     handlerContext,
     loaderPromises,
     routeMap: deps.getRouteMap(),
     metricsStore,
     Store,
-    interceptContextMatch,
+    interceptContextMatch: nav.interceptContextMatch,
     interceptSelectorContext,
-    isSameRouteNavigation,
+    isSameRouteNavigation: nav.isSameRouteNavigation,
     interceptResult,
-    cacheScope,
+    cacheScope: snapshot.cacheScope,
     isIntercept,
     actionContext,
     isAction,
-    routeMiddleware,
+    routeMiddleware: snapshot.routeMiddleware,
     isFullMatch: false,
   };
 }
@@ -615,6 +550,7 @@ export async function matchError<TEnv>(
     segments: [errorSegment],
     matched: matchedIds,
     diff: [errorSegment.id],
+    resolvedIds: [errorSegment.id],
     params: matched.params,
   };
 }

package/src/router/match-handlers.ts

@@ -33,10 +33,13 @@ import type { ErrorBoundaryHandler, NotFoundBoundaryHandler } from "../types";
 import type { MiddlewareFn } from "./middleware.js";
 import {
   type TelemetrySink,
+  type CacheSegmentSignal,
   safeEmit,
   resolveSink,
   getRequestId,
+  buildCacheSignalSegments,
 } from "./telemetry.js";
+import { _getRequestContext } from "../server/request-context.js";
 
 export interface MatchHandlerDeps<TEnv = any> {
   buildRouterContext: () => RouterContext<TEnv>;
@@ -51,6 +54,12 @@ export interface MatchHandlerDeps<TEnv = any> {
     isAction: boolean,
   ) => { intercept: InterceptEntry; entry: EntryData } | null;
   telemetry?: TelemetrySink;
+  /**
+   * DEVELOPMENT/TEST ONLY gate for the X-Rango-Cache debug header. When true,
+   * match/matchPartial stash a coarse route-level cache signal on the request
+   * context for the response-finalization path to emit. Default off.
+   */
+  cacheSignalEnabled?: boolean;
 }
 
 export interface MatchHandlers<TEnv = any> {
@@ -113,6 +122,25 @@ export function createMatchHandlers<TEnv = any>(
   } = deps;
   const hasTelemetry = !!deps.telemetry;
   const telemetry = resolveSink(deps.telemetry);
+  const cacheSignalEnabled = !!deps.cacheSignalEnabled;
+  // Compute the coarse cache signal when EITHER telemetry needs it (for the
+  // cache.decision event) OR the debug header gate is on. When neither is set,
+  // this is never called — zero extra work on the hot path.
+  const buildSignal = (
+    routeKey: string,
+    state: {
+      cacheHit: boolean;
+      cacheSource?: "runtime" | "prerender";
+      shouldRevalidate?: boolean;
+    },
+  ): CacheSegmentSignal[] => buildCacheSignalSegments(routeKey, state);
+  // Stash the signal on the request context for the response path to emit as
+  // the X-Rango-Cache header. Only when the debug gate is on.
+  const recordSignalIfEnabled = (segments: CacheSegmentSignal[]): void => {
+    if (!cacheSignalEnabled) return;
+    const reqCtx = _getRequestContext();
+    if (reqCtx) reqCtx._cacheSignal = segments;
+  };
 
   async function createMatchContextForFull(
     request: Request,
@@ -196,6 +224,7 @@ export function createMatchHandlers<TEnv = any>(
               segments: [],
               matched: [],
               diff: [],
+              resolvedIds: [],
               params: {},
               redirect: result.redirectUrl,
             };
@@ -207,17 +236,24 @@ export function createMatchHandlers<TEnv = any>(
             const state = createPipelineState();
             const pipeline = createMatchPartialPipeline(ctx, state);
             const matchResult = await collectMatchResult(pipeline, ctx, state);
+            if (hasTelemetry || cacheSignalEnabled) {
+              const signalSegments = buildSignal(ctx.routeKey, state);
+              recordSignalIfEnabled(signalSegments);
+              if (hasTelemetry) {
+                safeEmit(telemetry, {
+                  type: "cache.decision",
+                  timestamp: performance.now(),
+                  requestId,
+                  pathname,
+                  routeKey: ctx.routeKey,
+                  hit: state.cacheHit,
+                  shouldRevalidate: !!state.shouldRevalidate,
+                  source: state.cacheSource,
+                  segments: signalSegments,
+                });
+              }
+            }
             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(),
@@ -362,17 +398,24 @@ export function createMatchHandlers<TEnv = any>(
                 state,
               );
               flushRevalidationTrace();
+              if (hasTelemetry || cacheSignalEnabled) {
+                const signalSegments = buildSignal(ctx.routeKey, state);
+                recordSignalIfEnabled(signalSegments);
+                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,
+                    segments: signalSegments,
+                  });
+                }
+              }
               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(),