@rangojs/router 0.0.0-experimental.ea6d5eec → 0.0.0-experimental.ea9f40f2

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/tracing.ts

@@ -0,0 +1,215 @@
+/**
+ * Span tracing hook (platform-agnostic).
+ *
+ * The core router emits its existing performance phases (request, middleware, action,
+ * loaders, render, ssr) as spans by calling traceSpan() at a small set of
+ * execution boundaries. When no tracing is configured the call is a direct
+ * pass-through: fn is invoked with a no-op span, with no wrapper and no
+ * allocation, so a non-traced request behaves exactly as before.
+ *
+ * A platform integration supplies a SpanRunner that wraps fn in a real span.
+ * Two runners ship: the Cloudflare one (createCloudflareTracing in
+ * src/cloudflare/tracing.ts), which bridges onto executionContext.tracing.
+ * enterSpan, and the OTel one (createOTelTracing in router/telemetry-otel.ts),
+ * which bridges onto tracer.startActiveSpan. Both wrap the actual work — not a
+ * post-hoc event — so spans nest by async context and the platform's automatic
+ * spans (KV/D1/fetch) nest under the right phase.
+ *
+ * traceSpan() below is the low-level wrap primitive. It is INTERNAL: the only
+ * caller is observePhase() (instrument.ts), the single phase-instrumentation
+ * API, which co-emits the span AND the debugPerformance perf metric from one
+ * wrap site (or just the span, for metric:false phases) so the two surfaces
+ * can't drift. Every router phase routes through observePhase via the PHASES
+ * registry; do not call traceSpan directly from new code.
+ *
+ * Phase coverage (all via observePhase): rango.request (span-only; handler:total
+ * metered directly), rango.middleware (span-only incl. intercept middleware;
+ * pre/post metered directly), rango.action (action:<id>; server-action
+ * execution, JS + no-JS/PE), rango.loader (loader:<id>; single metering site at
+ * useLoader, plus the fetchable path), rango.handler (span-only, one per segment
+ * route/layout handler execution; the handler:<id> perf metric is owned by the
+ * track() at the call site), rango.render (render:total:<route>; normal AND
+ * action-revalidation renders), rango.ssr (ssr:render-html).
+ *
+ * Span-duration caveat (best-effort, never buffers): a span ends when its
+ * callback's value (or promise) settles. For the streaming phases (request,
+ * render, ssr) that is when the Response / HTML / RSC stream is CONSTRUCTED, not
+ * when the body finishes draining — instrumentation never wraps or buffers the
+ * response body, so it cannot regress response latency or streaming. A loader /
+ * Suspense child that resolves while the body streams therefore keeps a
+ * rango.loader span that can extend past its render parent; overlapping spans are
+ * valid (the loader really did take that long). Phase spans bound the work up to
+ * stream-handoff, which is also what the co-emitted perf metric measures.
+ *
+ * Both shipped runners (Cloudflare, OTel) keep the core agnostic: the
+ * platform-specific bridge lives at the edge behind the SpanRunner contract.
+ */
+
+/**
+ * Minimal span handle passed to traced work. Structurally compatible with both
+ * Cloudflare's `Span` and OTel's `Span` (only setAttribute is used here).
+ */
+export interface TraceSpan {
+  setAttribute(key: string, value: string | number | boolean): void;
+}
+
+/**
+ * Wraps a unit of work in a span. A runner MUST invoke fn exactly once, pass it
+ * a span, return fn's result unchanged, and propagate thrown errors / rejected
+ * promises unchanged. When fn returns a promise the span ends once it settles.
+ */
+export type SpanRunner = <T>(name: string, fn: (span: TraceSpan) => T) => T;
+
+/** The router phases that can be wrapped in a span. */
+export type TracePhase =
+  | "request"
+  | "middleware"
+  | "action"
+  | "loader"
+  | "handler"
+  | "render"
+  | "ssr";
+
+/** Per-phase span toggles. Omitted phases default to enabled. */
+export interface TracePhaseToggles {
+  request?: boolean;
+  middleware?: boolean;
+  action?: boolean;
+  loader?: boolean;
+  handler?: boolean;
+  render?: boolean;
+  ssr?: boolean;
+}
+
+/**
+ * The option pair shared by every tracing factory (enabled master switch +
+ * per-phase span toggles). Extended by OTelTracingOptions,
+ * CloudflareTracingOptions, VercelTracingOptions, and RouterTracingConfig so
+ * a phase added to TracePhaseToggles propagates everywhere from one place.
+ */
+export interface TracingToggleOptions {
+  /** Master switch. Defaults to true. */
+  enabled?: boolean;
+  /** Per-phase span toggles. Omitted phases default to enabled. */
+  spans?: TracePhaseToggles;
+}
+
+/**
+ * Value passed to `createRouter({ tracing })`. Produced by a platform factory
+ * such as `createCloudflareTracing()`.
+ */
+export interface RouterTracingConfig extends TracingToggleOptions {
+  /** Platform span runner. */
+  runner: SpanRunner;
+}
+
+/**
+ * Resolved tracing state stored on the router/request context. `undefined`
+ * means tracing is fully disabled and every traceSpan() call is a pass-through.
+ */
+export interface ResolvedTracing {
+  runner: SpanRunner;
+  phases: Record<TracePhase, boolean>;
+}
+
+/** Shared no-op span. setAttribute is a no-op so disabled call sites stay free. */
+export const NOOP_TRACE_SPAN: TraceSpan = {
+  setAttribute() {},
+};
+
+const ALL_PHASES_ON: Record<TracePhase, boolean> = {
+  request: true,
+  middleware: true,
+  action: true,
+  loader: true,
+  handler: true,
+  render: true,
+  ssr: true,
+};
+
+/**
+ * Resolve a user-supplied tracing config into the fast internal form, or
+ * `undefined` when tracing is off (no config, `enabled: false`, or no runner).
+ */
+export function resolveTracing(
+  config: RouterTracingConfig | undefined,
+): ResolvedTracing | undefined {
+  if (
+    !config ||
+    config.enabled === false ||
+    typeof config.runner !== "function"
+  ) {
+    return undefined;
+  }
+  const spans = config.spans;
+  return {
+    runner: config.runner,
+    phases: spans
+      ? {
+          request: spans.request ?? true,
+          middleware: spans.middleware ?? true,
+          action: spans.action ?? true,
+          loader: spans.loader ?? true,
+          handler: spans.handler ?? true,
+          render: spans.render ?? true,
+          ssr: spans.ssr ?? true,
+        }
+      : ALL_PHASES_ON,
+  };
+}
+
+/**
+ * Wrap `fn` in a span for `phase`. When tracing is off (or the phase is
+ * disabled) fn runs directly with a no-op span — identical to the untraced
+ * path. Otherwise the platform runner wraps fn so the span covers the real
+ * work and nests by async context.
+ */
+export function traceSpan<T>(
+  tracing: ResolvedTracing | undefined,
+  phase: TracePhase,
+  name: string,
+  fn: (span: TraceSpan) => T,
+): T {
+  if (tracing === undefined || tracing.phases[phase] === false) {
+    return fn(NOOP_TRACE_SPAN);
+  }
+  return tracing.runner(name, fn);
+}
+
+/**
+ * Run `fn` once and invoke `onSettle` exactly once when it terminates — on a
+ * synchronous return, a synchronous throw, an async resolution, or an async
+ * rejection. `onSettle` receives the error (or `undefined` on success). fn's
+ * value is returned and errors propagate unchanged.
+ *
+ * Centralizes the run-once-then-settle control flow shared by the two span
+ * surfaces: observePhase records the perf metric on settle, and the OTel runner
+ * ends (or error-marks) the span on settle. The Cloudflare runner delegates
+ * settling to enterSpan, so it does not use this.
+ */
+export function runThenSettle<T>(
+  fn: () => T,
+  onSettle: (error: unknown) => void,
+): T {
+  let out: T;
+  try {
+    out = fn();
+  } catch (error) {
+    onSettle(error);
+    throw error;
+  }
+  if (out instanceof Promise) {
+    return out.then(
+      (value) => {
+        onSettle(undefined);
+        return value;
+      },
+      (error) => {
+        onSettle(error);
+        throw error;
+      },
+    ) as unknown as T;
+  }
+  onSettle(undefined);
+  return out;
+}

package/src/router/trie-matching.ts

@@ -5,7 +5,12 @@
  * Falls back to null when no match is found (caller uses regex fallback).
  */
 
-import type { TrieNode, TrieLeaf } from "../build/route-trie.js";
+import type {
+  TrieNode,
+  TrieLeaf,
+  NegotiateVariant,
+} from "../build/route-trie.js";
+import { safeDecodeURIComponent } from "./url-params.js";
 
 export interface TrieMatchResult {
   /** Route name */
@@ -14,10 +19,6 @@ export interface TrieMatchResult {
   sp: string;
   /** Matched route params */
   params: Record<string, string>;
-  /** Optional param names (absent params have empty string value) */
-  optionalParams?: string[];
-  /** Ancestry shortCodes for layout pruning */
-  ancestry: string[];
   /** Redirect target if trailing slash requires it */
   redirectTo?: string;
   /** Route has pre-rendered data available */
@@ -27,7 +28,7 @@ export interface TrieMatchResult {
   /** Response type for non-RSC routes (json, text, image, any) */
   responseType?: string;
   /** Negotiate variants: response-type routes sharing this path */
-  negotiateVariants?: Array<{ routeKey: string; responseType: string }>;
+  negotiateVariants?: NegotiateVariant[];
   /** RSC-first: RSC route was defined before response-type variants */
   rscFirst?: true;
 }
@@ -42,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(
@@ -60,13 +59,25 @@ export function tryTrieMatch(
         pathnameHasTrailingSlash,
       );
     }
+    // A root-level wildcard ("/*") matches "/" with an empty remainder, the
+    // same value the regex matcher produces for the bare prefix. Without this
+    // the trie misses, the regex fallback runs, and its no-config branch emits
+    // a corrupt slice-off redirect. The static terminal still wins above.
+    // A one-or-more catch-all (`w1`, from `:name+`) rejects this empty case.
+    if (trie.w && !trie.w.w1) {
+      return validateAndBuild(
+        trie.w,
+        [],
+        "",
+        pathname,
+        pathnameHasTrailingSlash,
+      );
+    }
     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(
@@ -75,6 +86,7 @@ export function tryTrieMatch(
       result.wildcardValue,
       pathname,
       pathnameHasTrailingSlash,
+      result.validatedParams,
     );
   }
 
@@ -85,11 +97,75 @@ interface WalkResult {
   leaf: TrieLeaf;
   paramValues: string[];
   wildcardValue?: string;
+  /**
+   * For a constraint-bearing leaf (leaf.cv set), the params map that
+   * leafConstraintsPass already decoded AND validated during the walk. Carried
+   * forward so validateAndBuild reuses it instead of re-decoding paramValues and
+   * re-running constraintsSatisfied a second time on the winning leaf. Undefined
+   * for unconstrained leaves (no decode/validate happened in the walk).
+   */
+  validatedParams?: Record<string, string>;
 }
 
 /**
- * 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 null 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.
+ *
+ * On success returns the built+validated params for a constraint-bearing leaf so
+ * walkTrie can carry them to validateAndBuild (avoiding a second decode + a
+ * second constraintsSatisfied pass on the winner); returns the shared EMPTY_PASS
+ * sentinel for an unconstrained leaf (no work was done, nothing to carry).
+ */
+const EMPTY_PASS: Record<string, string> = {};
+function leafConstraintsPass(
+  leaf: TrieLeaf,
+  paramValues: string[],
+  wildcardValue: string | undefined,
+): Record<string, string> | null {
+  if (!leaf.cv) return EMPTY_PASS;
+  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) ? params : null;
+}
+
+/**
+ * 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,
@@ -97,10 +173,38 @@ function walkTrie(
   index: number,
   paramValues: string[],
 ): WalkResult | null {
-  // All segments consumed: check for terminal
   if (index === segments.length) {
     if (node.r) {
-      return { leaf: node.r, paramValues: [...paramValues] };
+      const validatedParams = leafConstraintsPass(
+        node.r,
+        paramValues,
+        undefined,
+      );
+      if (validatedParams) {
+        return {
+          leaf: node.r,
+          paramValues: [...paramValues],
+          validatedParams,
+        };
+      }
+    }
+    // A wildcard at this node matches the bare prefix with an empty remainder
+    // (e.g. "/files" against "/files/*"), mirroring the regex matcher's `*=""`.
+    // walkTrie otherwise only reaches node.w in the index<length branch below,
+    // 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. A one-or-more catch-all (`w1`, from `:name+`) rejects
+    // this empty case — it requires at least one trailing segment.
+    if (node.w && !node.w.w1) {
+      const validatedParams = leafConstraintsPass(node.w, paramValues, "");
+      if (validatedParams) {
+        return {
+          leaf: node.w,
+          paramValues: [...paramValues],
+          wildcardValue: "",
+          validatedParams,
+        };
+      }
     }
     return null;
   }
@@ -108,14 +212,15 @@ 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) {
+    // node.xp keys are pre-sorted longest-suffix-first at build time
+    // (route-trie.ts sortSuffixParams), so the first match is the most specific
+    // suffix: `/app.min.js` matches `:file.min.js` before `:file.js`.
     for (const suffix in node.xp) {
       if (segment.endsWith(suffix) && segment.length > suffix.length) {
         const paramValue = segment.slice(0, -suffix.length);
@@ -132,22 +237,36 @@ function walkTrie(
     }
   }
 
-  // Priority 3: Param match
-  if (node.p) {
+  // A required single-segment param captures 1+ chars (the regex matcher emits
+  // `([^/]+)`), so an empty path segment from a double slash (`/a//b`) must NOT
+  // bind `:s` to "". Reject it here so the trie matches the regex contract and
+  // a malformed URL 404s instead of running the handler with an empty param.
+  // The suffix-param branch above already requires `segment.length > suffix`,
+  // and node.w may legitimately be empty, so only this branch needs the guard.
+  if (node.p && segment !== "") {
     paramValues.push(segment);
     const result = walkTrie(node.p.c, segments, index + 1, paramValues);
     paramValues.pop();
     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,
-    };
+    // A one-or-more catch-all (`w1`, from `:name+`) requires at least one
+    // non-empty trailing segment. `rest` can still be "" here on a malformed
+    // double-slash URL (e.g. `/docs//` splits to a trailing "" segment), so
+    // guard this in-path site the same way the root and base-case sites are.
+    if (!(node.w.w1 && rest === "")) {
+      const validatedParams = leafConstraintsPass(node.w, paramValues, rest);
+      if (validatedParams) {
+        return {
+          leaf: node.w,
+          paramValues: [...paramValues],
+          wildcardValue: rest,
+          validatedParams,
+        };
+      }
+    }
   }
 
   return null;
@@ -155,16 +274,20 @@ function walkTrie(
 
 function joinRemainingSegments(segments: string[], start: number): string {
   if (start >= segments.length) return "";
-
-  let rest = segments[start]!;
-  for (let i = start + 1; i < segments.length; i++) {
-    rest += "/" + segments[i]!;
-  }
-  return rest;
+  return segments.slice(start).join("/");
 }
 
 /**
  * Post-match: validate constraints and handle trailing slash logic.
+ *
+ * `validatedParams` is the params map walkTrie already decoded AND validated via
+ * leafConstraintsPass for a constraint-bearing winning leaf. When present (and
+ * non-empty) we reuse it verbatim and SKIP the second decode + the second
+ * constraintsSatisfied pass — both are byte-identical to the walk-time work.
+ * When absent (unconstrained leaf, or the root-path call sites that never walk)
+ * we still BUILD the params here (that is not redundant — they must be returned)
+ * and run constraintsSatisfied for safety; an unconstrained leaf's check is a
+ * cheap early `!leaf.cv` return.
  */
 function validateAndBuild(
   leaf: TrieLeaf,
@@ -172,41 +295,32 @@ function validateAndBuild(
   wildcardValue: string | undefined,
   originalPathname: string,
   pathnameHasTrailingSlash: boolean,
+  validatedParams?: Record<string, string>,
 ): TrieMatchResult | null {
-  // Build named params by zipping leaf.pa with positional paramValues
-  const params: Record<string, string> = {};
-  if (leaf.pa) {
-    for (let i = 0; i < leaf.pa.length && i < paramValues.length; i++) {
-      params[leaf.pa[i]] = paramValues[i];
+  let params: Record<string, string>;
+  // EMPTY_PASS (the unconstrained sentinel) and undefined both mean "nothing was
+  // pre-validated"; only a populated map carried from a constraint-bearing leaf
+  // lets us skip the rebuild + re-check.
+  if (validatedParams && validatedParams !== EMPTY_PASS) {
+    params = validatedParams;
+  } else {
+    params = {};
+    if (leaf.pa) {
+      for (let i = 0; i < leaf.pa.length && i < paramValues.length; i++) {
+        params[leaf.pa[i]] = safeDecodeURIComponent(paramValues[i]);
+      }
     }
-  }
 
-  // Add wildcard param (wildcard leaves have pn from TrieNode.w type)
-  if (wildcardValue !== undefined && "pn" in leaf) {
-    params[(leaf as TrieLeaf & { pn: string }).pn] = wildcardValue;
-  }
-
-  // Validate constraints
-  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 (wildcardValue !== undefined && "pn" in leaf) {
+      params[(leaf as TrieLeaf & { pn: string }).pn] =
+        safeDecodeURIComponent(wildcardValue);
     }
-  }
 
-  // Fill in empty strings for optional params that weren't matched
-  if (leaf.op) {
-    for (const name of leaf.op) {
-      if (!(name in params)) {
-        params[name] = "";
-      }
+    if (!constraintsSatisfied(leaf, params)) {
+      return null;
     }
   }
 
-  // Trailing slash handling
   const tsMode = leaf.ts as "never" | "always" | "ignore" | undefined;
   let redirectTo: string | undefined;
 
@@ -224,10 +338,8 @@ function validateAndBuild(
     routeKey: leaf.n,
     sp: leaf.sp,
     params,
-    ancestry: leaf.a,
   };
 
-  if (leaf.op) result.optionalParams = leaf.op;
   if (redirectTo) result.redirectTo = redirectTo;
   if (leaf.pr) result.pr = true;
   if (leaf.pt) result.pt = true;