@rangojs/router 0.0.0-experimental.122 → 0.0.0-experimental.125

package/src/router/telemetry.ts

@@ -14,10 +14,6 @@
  *   - revalidation.decision          (revalidation evaluation)
  */
 
-// ---------------------------------------------------------------------------
-// Event types
-// ---------------------------------------------------------------------------
-
 interface BaseEvent {
   /** Monotonic timestamp from performance.now() */
   timestamp: number;
@@ -90,6 +86,34 @@ export interface HandlerErrorEvent extends BaseEvent {
   params?: Record<string, string>;
 }
 
+/**
+ * Per-segment (or coarse route-level) cache status carried on the
+ * cache.decision telemetry event and the X-Rango-Cache debug header.
+ *
+ * v1 is COARSE: the router's pipeline tracks cache decisions at the
+ * route/entry level (cacheHit/cacheSource/shouldRevalidate), not per
+ * individual segment. The `segments` array therefore contains a single
+ * route-level entry keyed by the route key. The shape is forward-compatible
+ * with genuine per-segment status if the pipeline later exposes it.
+ */
+export type CacheSegmentStatus =
+  | "hit"
+  | "miss"
+  | "stale"
+  | "prerendered"
+  | "passthrough";
+
+export interface CacheSegmentSignal {
+  /** Segment id (v1: the route key, since status is route-level). */
+  id: string;
+  /** Segment type (v1: "route" for the coarse route-level entry). */
+  type: string;
+  /** Resolved cache status for this segment. */
+  cacheStatus: CacheSegmentStatus;
+  /** Whether stale-while-revalidate was triggered for this segment. */
+  shouldRevalidate?: boolean;
+}
+
 export interface CacheDecisionEvent extends BaseEvent {
   type: "cache.decision";
   pathname: string;
@@ -98,6 +122,12 @@ export interface CacheDecisionEvent extends BaseEvent {
   /** Whether stale-while-revalidate was triggered */
   shouldRevalidate: boolean;
   source?: "runtime" | "prerender";
+  /**
+   * Optional per-segment (v1: coarse route-level) cache status. Present only
+   * when telemetry or the debug cache signal is enabled. Optional so existing
+   * sinks are unaffected.
+   */
+  segments?: CacheSegmentSignal[];
 }
 
 export interface RevalidationDecisionEvent extends BaseEvent {
@@ -141,9 +171,70 @@ export type TelemetryEvent =
   | OriginCheckRejectedEvent;
 
 // ---------------------------------------------------------------------------
-// Sink interface
+// Cache signal derivation (coarse, route-level)
 // ---------------------------------------------------------------------------
 
+/**
+ * Derive the coarse, route-level cache status from pipeline cache state.
+ *
+ * v1 mapping (route-level — see CacheSegmentSignal):
+ *   - prerender hit                         -> "prerendered"
+ *   - runtime hit + shouldRevalidate (SWR)  -> "stale"
+ *   - runtime hit                           -> "hit"
+ *   - no hit                                -> "miss"
+ *
+ * Note: "passthrough" is a build-time prerender concept (a route opts out of
+ * being prerendered for some params). At runtime a passthrough route renders
+ * fresh and is indistinguishable from a normal miss in the pipeline state, so
+ * v1 reports it as "miss". The "passthrough" status remains in the type union
+ * for forward compatibility.
+ */
+export function deriveCacheStatus(state: {
+  cacheHit: boolean;
+  cacheSource?: "runtime" | "prerender";
+  shouldRevalidate?: boolean;
+}): CacheSegmentStatus {
+  if (state.cacheHit) {
+    if (state.cacheSource === "prerender") return "prerendered";
+    if (state.shouldRevalidate) return "stale";
+    return "hit";
+  }
+  return "miss";
+}
+
+/**
+ * Build the coarse route-level cache signal array (a single entry keyed by
+ * the route key). Used for both the cache.decision telemetry event and the
+ * X-Rango-Cache debug header.
+ */
+export function buildCacheSignalSegments(
+  routeKey: string,
+  state: {
+    cacheHit: boolean;
+    cacheSource?: "runtime" | "prerender";
+    shouldRevalidate?: boolean;
+  },
+): CacheSegmentSignal[] {
+  return [
+    {
+      id: routeKey,
+      type: "route",
+      cacheStatus: deriveCacheStatus(state),
+      shouldRevalidate: !!state.shouldRevalidate,
+    },
+  ];
+}
+
+/**
+ * Serialize cache signal segments into the X-Rango-Cache header value:
+ * `<segId>=<status>, <segId2>=<status2>`.
+ */
+export function formatCacheSignalHeader(
+  segments: CacheSegmentSignal[],
+): string {
+  return segments.map((s) => `${s.id}=${s.cacheStatus}`).join(", ");
+}
+
 /**
  * Telemetry sink receives structured lifecycle events from the router.
  * Implement this interface to integrate with any observability backend.
@@ -154,10 +245,6 @@ export interface TelemetrySink {
   emit(event: TelemetryEvent): void;
 }
 
-// ---------------------------------------------------------------------------
-// No-op singleton (zero-cost disabled state)
-// ---------------------------------------------------------------------------
-
 const noopSink: TelemetrySink = {
   emit() {},
 };
@@ -185,12 +272,6 @@ export function safeEmit(sink: TelemetrySink, event: TelemetryEvent): void {
   }
 }
 
-// ---------------------------------------------------------------------------
-// Request ID extraction (for span correlation)
-// ---------------------------------------------------------------------------
-
-// Per-request memoization so the same Request object always maps to the
-// same ID. WeakMap allows GC when the Request is no longer referenced.
 const requestIds = new WeakMap<Request, string>();
 let telemetryRequestCounter = 0;
 
@@ -224,10 +305,6 @@ export function getRequestId(request: Request): string {
   return id;
 }
 
-// ---------------------------------------------------------------------------
-// Console sink (built-in, replaces ad-hoc console.log debug traces)
-// ---------------------------------------------------------------------------
-
 /**
  * Built-in console sink that logs events in a structured format.
  * Designed as the default sink for development / debugging.

package/src/router/timeout.ts

@@ -6,10 +6,6 @@
  * a Promise.race mechanism, returning 504 on expiry.
  */
 
-// ---------------------------------------------------------------------------
-// Public types
-// ---------------------------------------------------------------------------
-
 export interface RouterTimeouts {
   /** Timeout for server action execution (ms). */
   actionMs?: number;
@@ -35,10 +31,6 @@ export type OnTimeoutCallback<TEnv = any> = (
   ctx: TimeoutContext<TEnv>,
 ) => Response | Promise<Response>;
 
-// ---------------------------------------------------------------------------
-// Internal resolved form
-// ---------------------------------------------------------------------------
-
 export interface ResolvedTimeouts {
   actionMs: number | undefined;
   renderStartMs: number | undefined;
@@ -63,10 +55,6 @@ export function resolveTimeouts(
   };
 }
 
-// ---------------------------------------------------------------------------
-// Error class
-// ---------------------------------------------------------------------------
-
 export class RouterTimeoutError extends Error {
   override name = "RouterTimeoutError" as const;
   phase: TimeoutPhase;
@@ -81,10 +69,6 @@ export class RouterTimeoutError extends Error {
   }
 }
 
-// ---------------------------------------------------------------------------
-// Race helper
-// ---------------------------------------------------------------------------
-
 type TimeoutResult<T> =
   | { result: T; timedOut: false }
   | { timedOut: true; durationMs: number };
@@ -129,10 +113,6 @@ export async function withTimeout<T>(
   }
 }
 
-// ---------------------------------------------------------------------------
-// Default response
-// ---------------------------------------------------------------------------
-
 /**
  * Create the default 504 response for a timed-out request.
  * Includes `X-Rango-Timeout-Phase` header for observability.

package/src/router/trie-matching.ts

@@ -43,14 +43,12 @@ export function tryTrieMatch(
 ): TrieMatchResult | null {
   if (!trie) return null;
 
-  // Split pathname into segments, filtering empty strings from leading/trailing slashes
   const pathnameHasTrailingSlash =
     pathname.length > 1 && pathname.endsWith("/");
   const normalizedPath = pathnameHasTrailingSlash
     ? pathname.slice(0, -1)
     : pathname;
 
-  // Handle root path
   if (normalizedPath === "" || normalizedPath === "/") {
     if (trie.r) {
       return validateAndBuild(
@@ -77,10 +75,8 @@ export function tryTrieMatch(
     return null;
   }
 
-  // Remove leading slash and split
   const segments = normalizedPath.slice(1).split("/");
 
-  // Try exact match with normalized path (no trailing slash)
   const result = walkTrie(trie, segments, 0, []);
   if (result) {
     return validateAndBuild(
@@ -102,8 +98,58 @@ interface WalkResult {
 }
 
 /**
- * Walk the trie by segments with priority: static > param > wildcard.
- * Uses backtracking to try all possible matches.
+ * Check a leaf's constraints (leaf.cv) against already-resolved named params.
+ * Empty/undefined values are exempt (optional params that were not bound).
+ */
+function constraintsSatisfied(
+  leaf: TrieLeaf,
+  params: Record<string, string>,
+): boolean {
+  if (!leaf.cv) return true;
+  for (const paramName in leaf.cv) {
+    const allowed = leaf.cv[paramName]!;
+    const value = params[paramName];
+    if (value !== undefined && value !== "" && !allowed.includes(value)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Constraint check for a candidate terminal DURING the walk. Builds the named
+ * params from positional walk values (decoded the same way validateAndBuild
+ * does) and validates leaf.cv. Returning false lets walkTrie unwind to a
+ * lower-priority sibling instead of committing to a leaf that would only be
+ * rejected post-walk — that post-walk rejection is what forced the regex
+ * fallback (and its false "trie gap" R3 warning) for perfectly valid configs.
+ */
+function leafConstraintsPass(
+  leaf: TrieLeaf,
+  paramValues: string[],
+  wildcardValue: string | undefined,
+): boolean {
+  if (!leaf.cv) return true;
+  const params: Record<string, string> = {};
+  if (leaf.pa) {
+    for (let i = 0; i < leaf.pa.length && i < paramValues.length; i++) {
+      params[leaf.pa[i]] = safeDecodeURIComponent(paramValues[i]);
+    }
+  }
+  if (wildcardValue !== undefined && "pn" in leaf) {
+    params[(leaf as TrieLeaf & { pn: string }).pn] =
+      safeDecodeURIComponent(wildcardValue);
+  }
+  return constraintsSatisfied(leaf, params);
+}
+
+/**
+ * Walk the trie by segments with priority: static > suffix-param > param >
+ * wildcard (Priority 1-4 below; matches the canonical M4 ordering in
+ * docs/internal/matching-and-lazy-discovery.md).
+ * Uses backtracking to try all possible matches. Per-leaf constraints are
+ * enforced at each candidate terminal so a constraint miss backtracks to a
+ * lower-priority sibling rather than aborting the whole match.
  */
 function walkTrie(
   node: TrieNode,
@@ -111,9 +157,8 @@ function walkTrie(
   index: number,
   paramValues: string[],
 ): WalkResult | null {
-  // All segments consumed: check for terminal
   if (index === segments.length) {
-    if (node.r) {
+    if (node.r && leafConstraintsPass(node.r, paramValues, undefined)) {
       return { leaf: node.r, paramValues: [...paramValues] };
     }
     // A wildcard at this node matches the bare prefix with an empty remainder
@@ -122,7 +167,7 @@ function walkTrie(
     // so without this a request to the wildcard's own prefix misses the trie
     // and the regex fallback emits a corrupt redirect. A static terminal
     // (node.r) still wins.
-    if (node.w) {
+    if (node.w && leafConstraintsPass(node.w, paramValues, "")) {
       return { leaf: node.w, paramValues: [...paramValues], wildcardValue: "" };
     }
     return null;
@@ -131,13 +176,11 @@ function walkTrie(
   const segment = segments[index];
   const staticChild = node.s?.[segment];
 
-  // Priority 1: Static match
   if (staticChild) {
     const result = walkTrie(staticChild, segments, index + 1, paramValues);
     if (result) return result;
   }
 
-  // Priority 2: Suffix-param match (e.g., :productId.html)
   if (node.xp) {
     for (const suffix in node.xp) {
       if (segment.endsWith(suffix) && segment.length > suffix.length) {
@@ -155,7 +198,6 @@ function walkTrie(
     }
   }
 
-  // Priority 3: Param match
   if (node.p) {
     paramValues.push(segment);
     const result = walkTrie(node.p.c, segments, index + 1, paramValues);
@@ -163,14 +205,15 @@ function walkTrie(
     if (result) return result;
   }
 
-  // Priority 4: Wildcard match (consumes rest)
   if (node.w) {
     const rest = joinRemainingSegments(segments, index);
-    return {
-      leaf: node.w,
-      paramValues: [...paramValues],
-      wildcardValue: rest,
-    };
+    if (leafConstraintsPass(node.w, paramValues, rest)) {
+      return {
+        leaf: node.w,
+        paramValues: [...paramValues],
+        wildcardValue: rest,
+      };
+    }
   }
 
   return null;
@@ -196,10 +239,6 @@ function validateAndBuild(
   originalPathname: string,
   pathnameHasTrailingSlash: boolean,
 ): TrieMatchResult | null {
-  // Build named params by zipping leaf.pa with positional paramValues.
-  // Params are URL-decoded at this boundary so ctx.params holds the values
-  // apps expect (matching Express/React Router) and round-trip cleanly
-  // through ctx.reverse.
   const params: Record<string, string> = {};
   if (leaf.pa) {
     for (let i = 0; i < leaf.pa.length && i < paramValues.length; i++) {
@@ -207,31 +246,15 @@ function validateAndBuild(
     }
   }
 
-  // Add wildcard param (wildcard leaves have pn from TrieNode.w type)
   if (wildcardValue !== undefined && "pn" in leaf) {
     params[(leaf as TrieLeaf & { pn: string }).pn] =
       safeDecodeURIComponent(wildcardValue);
   }
 
-  // Validate constraints against decoded values so constraint lists can be
-  // written in decoded form (e.g. ["en-GB", "en US"]).
-  if (leaf.cv) {
-    for (const paramName in leaf.cv) {
-      const allowed = leaf.cv[paramName]!;
-      const value = params[paramName];
-      if (value !== undefined && value !== "" && !allowed.includes(value)) {
-        return null;
-      }
-    }
+  if (!constraintsSatisfied(leaf, params)) {
+    return null;
   }
 
-  // Optional params that weren't matched are left absent from `params` so
-  // `ctx.params.locale` reads as `undefined`, matching the
-  // `ExtractParams<"/:locale?/...">` type (`{ locale?: string }`). Both
-  // internal consumers — the constraint check above and `reverse()` —
-  // already treat missing/undefined as the absent form.
-
-  // Trailing slash handling
   const tsMode = leaf.ts as "never" | "always" | "ignore" | undefined;
   let redirectTo: string | undefined;
 

package/src/router/types.ts

@@ -22,27 +22,11 @@ import type {
   ShouldRevalidateFn,
 } from "../types";
 
-/**
- * Result of resolving loaders with revalidation
- * Contains both segments to render and all matched segment IDs
- */
-export interface LoaderRevalidationResult {
-  segments: ResolvedSegment[];
-  matchedIds: string[];
-}
-
-/**
- * Result of resolving segments with revalidation
- * Contains both segments to render and all matched segment IDs
- */
 export interface SegmentRevalidationResult {
   segments: ResolvedSegment[];
   matchedIds: string[];
 }
 
-/**
- * Action context type for revalidation
- */
 export type ActionContext = {
   actionId?: string;
   actionUrl?: URL;
@@ -50,23 +34,6 @@ export type ActionContext = {
   formData?: FormData;
 };
 
-/**
- * Dependencies passed to segment resolution functions
- * These are created within createRouter and passed to extracted utilities
- */
-export interface RouterDependencies<TEnv> {
-  findNearestErrorBoundary: (
-    entry: EntryData | null,
-  ) => ReactNode | ErrorBoundaryHandler | null;
-  findNearestNotFoundBoundary: (
-    entry: EntryData | null,
-  ) => ReactNode | NotFoundBoundaryHandler | null;
-}
-
-/**
- * Dependencies injected from createRouter closure into extracted segment resolution functions.
- * These are the closure-bound helpers that cannot be imported directly.
- */
 export interface SegmentResolutionDeps<TEnv = any> {
   wrapLoaderPromise: <T>(
     promise: Promise<T>,
@@ -108,21 +75,6 @@ export interface SegmentResolutionDeps<TEnv = any> {
   viewTransitionDefault?: "auto" | false;
 }
 
-/**
- * Dependencies injected from createRouter closure into extracted intercept resolution functions.
- */
-export interface InterceptResolutionDeps<TEnv = any> {
-  wrapLoaderPromise: SegmentResolutionDeps<TEnv>["wrapLoaderPromise"];
-  evaluateInterceptWhen: (
-    intercept: InterceptEntry,
-    selectorContext: InterceptSelectorContext | null,
-    isAction: boolean,
-  ) => boolean;
-}
-
-/**
- * Dependencies injected from createRouter closure into extracted match API functions.
- */
 export interface MatchApiDeps<TEnv = any> {
   findMatch: (pathname: string, ms?: any) => any;
   getMetricsStore: () => any;
@@ -137,23 +89,13 @@ export interface MatchApiDeps<TEnv = any> {
   getRouteMap: () => Record<string, string>;
 }
 
-/**
- * Title descriptor types for template support
- */
 export type TitleDescriptor =
   | string
   | { template: string; default: string } // For layouts - template applied to child titles
-  | { absolute: string }; // Bypass parent template
+  | { absolute: string };
 
-/**
- * Unset descriptor to remove inherited meta
- * Key format matches getMetaKey output: "title", "name:description", "property:og:image"
- */
 export type UnsetDescriptor = { unset: string };
 
-/**
- * Base meta descriptor types (sync values)
- */
 export type MetaDescriptorBase =
   | { charSet: "utf-8" }
   | { title: TitleDescriptor }
@@ -165,10 +107,6 @@ export type MetaDescriptorBase =
   | UnsetDescriptor
   | { [name: string]: unknown };
 
-/**
- * Meta descriptor that can be sync or async.
- * Use Promise<MetaDescriptorBase> for streaming meta that resolves after initial render.
- */
 export type MetaDescriptor = MetaDescriptorBase | Promise<MetaDescriptorBase>;
 
 type LdJsonObject = { [Key in string]: LdJsonValue } & {

package/src/router/url-params.ts

@@ -25,11 +25,6 @@ export function safeDecodeURIComponent(raw: string): string {
   }
 }
 
-// encodeURIComponent over-encodes for path segments. After running it,
-// un-encode the pchar sub-delims + (`:` / `@`) so the resulting URL
-// keeps human-readable characters that are legal in a path segment.
-// Everything dangerous — `/ ? # %` and space/control/non-ASCII — stays
-// encoded.
 const PATH_SAFE_ESCAPES: Record<string, string> = {
   "%3A": ":",
   "%40": "@",

package/src/router.ts

@@ -57,6 +57,7 @@ import { buildDebugManifest } from "./router/debug-manifest.js";
 
 import type { SegmentResolutionDeps, MatchApiDeps } from "./router/types.js";
 import { createHandlerContext } from "./router/handler-context.js";
+import { normalizeBasename } from "./router/basename.js";
 import {
   setupLoaderAccess,
   setupLoaderAccessSilent,
@@ -110,6 +111,7 @@ import {
   matchForPrerender as _matchForPrerender,
   renderStaticSegment as _renderStaticSegment,
 } from "./router/prerender-match.js";
+import { resolveStateCookieName } from "./router/state-cookie-name.js";
 
 // Re-export public types and values from extracted modules
 export { RSC_ROUTER_BRAND, RouterRegistry } from "./router/router-registry.js";
@@ -149,6 +151,7 @@ export function createRouter<TEnv = any>(
     nonce,
     version,
     prefetchCacheTTL: prefetchCacheTTLOption,
+    stateCookiePrefix: stateCookiePrefixOption,
     warmup: warmupOption,
     allowDebugManifest: allowDebugManifestOption = false,
     telemetry: telemetrySink,
@@ -158,14 +161,22 @@ export function createRouter<TEnv = any>(
     onTimeout,
     originCheck: originCheckOption,
     viewTransition: viewTransitionOption = "auto",
+    debugCacheSignal: debugCacheSignalOption = false,
   } = options;
 
+  // Debug cache signal gate (DEVELOPMENT/TEST ONLY). Enabled by the
+  // debugCacheSignal option OR the RANGO_TEST_SIGNALS=1 env flag. When off,
+  // no X-Rango-Cache header is emitted and output is byte-identical.
+  const cacheSignalEnabled =
+    debugCacheSignalOption ||
+    (typeof process !== "undefined" &&
+      (process as { env?: Record<string, string | undefined> }).env
+        ?.RANGO_TEST_SIGNALS === "1");
+
   // Normalize basename: ensure leading slash, strip trailing slash.
-  // A bare "/" is equivalent to no basename.
-  const basename =
-    basenameOption && basenameOption.replace(/^\/+|\/+$/g, "")
-      ? "/" + basenameOption.replace(/^\/+|\/+$/g, "")
-      : undefined;
+  // A bare "/" is equivalent to no basename. Shared with the testing
+  // primitives via normalizeBasename so they can never drift.
+  const basename = normalizeBasename(basenameOption);
 
   // Resolve telemetry sink (no-op when not configured)
   const telemetry = resolveSink(telemetrySink);
@@ -209,6 +220,14 @@ export function createRouter<TEnv = any>(
   const routerId =
     userProvidedId ?? injectedId ?? `router_${nextRouterAutoId()}`;
 
+  // Resolve the rango state cookie name once, here, so the two cookie writers
+  // (the client document.cookie writer and the server Set-Cookie writer)
+  // consume one pre-composed name and cannot drift.
+  const resolvedStateCookieName = resolveStateCookieName(
+    stateCookiePrefixOption,
+    routerId,
+  );
+
   // Resolve prefetch cache TTL (default: 300 seconds / 5 minutes)
   // Clamp to a non-negative integer for valid Cache-Control max-age.
   const rawTTL =
@@ -255,9 +274,14 @@ export function createRouter<TEnv = any>(
     invokeOnError(onError, error, phase, context, "Router");
   }
 
-  // Validate document is a client component
+  // Validate document is a client component. Under a test runner the "use
+  // client" transform has not run, so a real exported document has no marker;
+  // allowServerInTest lets the router construct in a bare unit test (for
+  // dispatch / assertGeneratedRoutesMatch) while a real build still throws.
   if (documentOption !== undefined) {
-    assertClientComponent(documentOption, "document");
+    assertClientComponent(documentOption, "document", {
+      allowServerInTest: true,
+    });
   }
 
   // Use default document if none provided (keeps internal name as rootLayout)
@@ -667,6 +691,7 @@ export function createRouter<TEnv = any>(
     findMatch,
     findInterceptForRoute,
     telemetry: telemetrySink,
+    cacheSignalEnabled,
   });
 
   const { match, matchPartial, matchError, previewMatch } = matchHandlers;
@@ -938,6 +963,10 @@ export function createRouter<TEnv = any>(
     prefetchCacheControl,
     prefetchCacheTTL,
 
+    // Expose the resolved rango state cookie name for the server-side writer
+    // (invalidateClientCache) and for shipping to the client in metadata.
+    resolvedStateCookieName,
+
     // Expose warmup enabled flag for handler and client
     warmupEnabled,
 
@@ -1029,8 +1058,10 @@ export function createRouter<TEnv = any>(
         if (!handler) {
           // Lazy import deferred to first request to avoid dev mode issues
           const { createRSCHandler } = await import("./rsc/handler.js");
-          // Cast: handler.ts still accepts (request, env) — will be updated
-          // separately to accept RouterRequestInput.
+          // Cast: createRSCHandler receives `router as any`, which erases TEnv
+          // and infers its handler as RouterRequestInput<unknown>. Re-narrow the
+          // returned handler to RouterRequestInput<TEnv> so the call below stays
+          // typed. (The handler already accepts (request, RouterRequestInput).)
           handler = createRSCHandler({
             router: router as any,
             cache,