@rangojs/router 0.0.0-experimental.10 → 0.0.0-experimental.100

package/src/router/telemetry.ts

@@ -0,0 +1,300 @@
+/**
+ * Router Telemetry Sink
+ *
+ * Internal event model for structured lifecycle events.
+ * The sink is optional and zero-cost when not configured.
+ *
+ * Emit points:
+ *   - request.start / request.end   (match-handlers.ts)
+ *   - request.error                  (match-handlers.ts catch blocks)
+ *   - request.origin-rejected        (rsc/handler.ts origin guard)
+ *   - loader.start / loader.end / loader.error  (loader-resolution.ts)
+ *   - handler.error                  (trackHandler catch, segment-resolution/helpers.ts)
+ *   - cache.decision                 (cache-lookup middleware)
+ *   - revalidation.decision          (revalidation evaluation)
+ */
+
+// ---------------------------------------------------------------------------
+// Event types
+// ---------------------------------------------------------------------------
+
+interface BaseEvent {
+  /** Monotonic timestamp from performance.now() */
+  timestamp: number;
+  /** Request ID (from header or generated) */
+  requestId?: string;
+}
+
+export interface RequestStartEvent extends BaseEvent {
+  type: "request.start";
+  method: string;
+  pathname: string;
+  /** "match" for full document requests, "matchPartial" for navigation */
+  transaction: "match" | "matchPartial";
+  isPartial: boolean;
+}
+
+export interface RequestEndEvent extends BaseEvent {
+  type: "request.end";
+  method: string;
+  pathname: string;
+  transaction: "match" | "matchPartial";
+  durationMs: number;
+  segmentCount: number;
+  cacheHit: boolean;
+}
+
+export interface RequestErrorEvent extends BaseEvent {
+  type: "request.error";
+  method: string;
+  pathname: string;
+  transaction: "match" | "matchPartial";
+  error: Error;
+  phase: string;
+  durationMs: number;
+}
+
+export interface LoaderStartEvent extends BaseEvent {
+  type: "loader.start";
+  segmentId: string;
+  loaderName: string;
+  pathname: string;
+}
+
+export interface LoaderEndEvent extends BaseEvent {
+  type: "loader.end";
+  segmentId: string;
+  loaderName: string;
+  pathname: string;
+  durationMs: number;
+  ok: boolean;
+}
+
+export interface LoaderErrorEvent extends BaseEvent {
+  type: "loader.error";
+  segmentId: string;
+  loaderName: string;
+  pathname: string;
+  error: Error;
+  handledByBoundary: boolean;
+}
+
+export interface HandlerErrorEvent extends BaseEvent {
+  type: "handler.error";
+  segmentId?: string;
+  segmentType?: string;
+  error: Error;
+  handledByBoundary: boolean;
+  pathname?: string;
+  routeKey?: string;
+  params?: Record<string, string>;
+}
+
+export interface CacheDecisionEvent extends BaseEvent {
+  type: "cache.decision";
+  pathname: string;
+  routeKey: string;
+  hit: boolean;
+  /** Whether stale-while-revalidate was triggered */
+  shouldRevalidate: boolean;
+  source?: "runtime" | "prerender";
+}
+
+export interface RevalidationDecisionEvent extends BaseEvent {
+  type: "revalidation.decision";
+  segmentId: string;
+  pathname: string;
+  routeKey: string;
+  shouldRevalidate: boolean;
+}
+
+export interface RequestTimeoutEvent extends BaseEvent {
+  type: "request.timeout";
+  phase: import("./timeout.js").TimeoutPhase;
+  pathname: string;
+  routeKey?: string;
+  actionId?: string;
+  durationMs: number;
+  customHandler: boolean;
+}
+
+export interface OriginCheckRejectedEvent extends BaseEvent {
+  type: "request.origin-rejected";
+  method: string;
+  pathname: string;
+  phase: import("../rsc/origin-guard.js").OriginCheckPhase;
+  origin: string | null;
+  host: string | null;
+}
+
+export type TelemetryEvent =
+  | RequestStartEvent
+  | RequestEndEvent
+  | RequestErrorEvent
+  | LoaderStartEvent
+  | LoaderEndEvent
+  | LoaderErrorEvent
+  | HandlerErrorEvent
+  | CacheDecisionEvent
+  | RevalidationDecisionEvent
+  | RequestTimeoutEvent
+  | OriginCheckRejectedEvent;
+
+// ---------------------------------------------------------------------------
+// Sink interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Telemetry sink receives structured lifecycle events from the router.
+ * Implement this interface to integrate with any observability backend.
+ *
+ * All methods are fire-and-forget — exceptions are caught and logged.
+ */
+export interface TelemetrySink {
+  emit(event: TelemetryEvent): void;
+}
+
+// ---------------------------------------------------------------------------
+// No-op singleton (zero-cost disabled state)
+// ---------------------------------------------------------------------------
+
+const noopSink: TelemetrySink = {
+  emit() {},
+};
+
+/**
+ * Returns the configured sink, or the no-op singleton.
+ * Call sites use this so they don't need null checks.
+ */
+export function resolveSink(sink: TelemetrySink | undefined): TelemetrySink {
+  return sink ?? noopSink;
+}
+
+/**
+ * Safe emit — catches any error thrown by the sink to prevent
+ * telemetry failures from affecting request handling.
+ */
+export function safeEmit(sink: TelemetrySink, event: TelemetryEvent): void {
+  try {
+    sink.emit(event);
+  } catch (e) {
+    // Telemetry must never break request handling
+    if (process.env.NODE_ENV !== "production") {
+      console.error("[Router.telemetry] Sink error:", e);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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;
+
+/**
+ * Get or create a request ID for telemetry correlation.
+ * Checks standard headers first (x-rsc-router-request-id, x-request-id,
+ * cf-ray), then generates an internal ID when none is present.
+ * Generated IDs use format "t-{base36}" to distinguish from header values.
+ */
+export function getRequestId(request: Request): string {
+  const existing = requestIds.get(request);
+  if (existing) return existing;
+
+  const candidate =
+    request.headers.get("x-rsc-router-request-id") ??
+    request.headers.get("x-request-id") ??
+    request.headers.get("cf-ray");
+
+  let id: string;
+  if (candidate) {
+    const trimmed = candidate.trim();
+    id =
+      trimmed.length > 0
+        ? trimmed
+        : `t-${(++telemetryRequestCounter).toString(36)}`;
+  } else {
+    id = `t-${(++telemetryRequestCounter).toString(36)}`;
+  }
+
+  requestIds.set(request, id);
+  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.
+ */
+export function createConsoleSink(): TelemetrySink {
+  return {
+    emit(event: TelemetryEvent): void {
+      switch (event.type) {
+        case "request.start":
+          console.log(
+            `[telemetry] ${event.type} ${event.method} ${event.pathname} (${event.transaction})`,
+          );
+          break;
+        case "request.end":
+          console.log(
+            `[telemetry] ${event.type} ${event.method} ${event.pathname} ${event.durationMs.toFixed(1)}ms segments=${event.segmentCount} cache=${event.cacheHit}`,
+          );
+          break;
+        case "request.error":
+          console.log(
+            `[telemetry] ${event.type} ${event.method} ${event.pathname} phase=${event.phase} ${event.durationMs.toFixed(1)}ms`,
+            event.error.message,
+          );
+          break;
+        case "loader.start":
+          console.log(
+            `[telemetry] ${event.type} ${event.loaderName} (${event.segmentId})`,
+          );
+          break;
+        case "loader.end":
+          console.log(
+            `[telemetry] ${event.type} ${event.loaderName} ${event.durationMs.toFixed(1)}ms ok=${event.ok}`,
+          );
+          break;
+        case "loader.error":
+          console.log(
+            `[telemetry] ${event.type} ${event.loaderName} boundary=${event.handledByBoundary}`,
+            event.error.message,
+          );
+          break;
+        case "handler.error":
+          console.log(
+            `[telemetry] ${event.type} segment=${event.segmentId ?? "unknown"} boundary=${event.handledByBoundary}${event.pathname ? ` ${event.pathname}` : ""}`,
+            event.error.message,
+          );
+          break;
+        case "cache.decision":
+          console.log(
+            `[telemetry] ${event.type} ${event.pathname} hit=${event.hit} swr=${event.shouldRevalidate}${event.source ? ` source=${event.source}` : ""}`,
+          );
+          break;
+        case "revalidation.decision":
+          console.log(
+            `[telemetry] ${event.type} ${event.segmentId} revalidate=${event.shouldRevalidate}`,
+          );
+          break;
+        case "request.timeout":
+          console.log(
+            `[telemetry] ${event.type} phase=${event.phase} ${event.pathname} ${event.durationMs.toFixed(1)}ms custom=${event.customHandler}`,
+          );
+          break;
+        case "request.origin-rejected":
+          console.log(
+            `[telemetry] ${event.type} ${event.method} ${event.pathname} phase=${event.phase} origin=${event.origin ?? "none"} host=${event.host ?? "none"}`,
+          );
+          break;
+      }
+    },
+  };
+}

package/src/router/timeout.ts

@@ -0,0 +1,148 @@
+/**
+ * Router Timeout
+ *
+ * Types, resolution logic, and helpers for request-level timeouts.
+ * Timeouts wrap action execution and render-start phases with
+ * a Promise.race mechanism, returning 504 on expiry.
+ */
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface RouterTimeouts {
+  /** Timeout for server action execution (ms). */
+  actionMs?: number;
+  /** Timeout for initial render/response production (ms). */
+  renderStartMs?: number;
+  /** Timeout for idle streaming after render starts (ms). Reserved for PR 2. */
+  streamIdleMs?: number;
+}
+
+export type TimeoutPhase = "action" | "render-start" | "stream-idle";
+
+export interface TimeoutContext<TEnv = any> {
+  phase: TimeoutPhase;
+  request: Request;
+  url: URL;
+  env: TEnv;
+  routeKey?: string;
+  actionId?: string;
+  durationMs: number;
+}
+
+export type OnTimeoutCallback<TEnv = any> = (
+  ctx: TimeoutContext<TEnv>,
+) => Response | Promise<Response>;
+
+// ---------------------------------------------------------------------------
+// Internal resolved form
+// ---------------------------------------------------------------------------
+
+export interface ResolvedTimeouts {
+  actionMs: number | undefined;
+  renderStartMs: number | undefined;
+  streamIdleMs: number | undefined;
+}
+
+/**
+ * Merge the `timeout` shorthand with the structured `timeouts` object.
+ *
+ * - `timeout` applies to `actionMs` and `renderStartMs` (NOT `streamIdleMs`).
+ * - Explicit `timeouts.*` values override the shorthand.
+ * - Returns `undefined` for any phase that has no configured value.
+ */
+export function resolveTimeouts(
+  timeout?: number,
+  timeouts?: RouterTimeouts,
+): ResolvedTimeouts {
+  return {
+    actionMs: timeouts?.actionMs ?? timeout ?? undefined,
+    renderStartMs: timeouts?.renderStartMs ?? timeout ?? undefined,
+    streamIdleMs: timeouts?.streamIdleMs ?? undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Error class
+// ---------------------------------------------------------------------------
+
+export class RouterTimeoutError extends Error {
+  override name = "RouterTimeoutError" as const;
+  phase: TimeoutPhase;
+  durationMs: number;
+
+  constructor(phase: TimeoutPhase, durationMs: number) {
+    super(
+      `Request timed out during ${phase} after ${Math.round(durationMs)}ms`,
+    );
+    this.phase = phase;
+    this.durationMs = durationMs;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Race helper
+// ---------------------------------------------------------------------------
+
+type TimeoutResult<T> =
+  | { result: T; timedOut: false }
+  | { timedOut: true; durationMs: number };
+
+/**
+ * Race an operation against a deadline.
+ *
+ * Returns a discriminated union so callers handle the timeout case
+ * without try/catch. Non-timeout errors from the operation re-throw.
+ *
+ * When `timeoutMs` is `undefined` or `<= 0`, the operation runs
+ * without any deadline (pass-through).
+ */
+export async function withTimeout<T>(
+  operation: Promise<T>,
+  timeoutMs: number | undefined,
+  phase: TimeoutPhase,
+): Promise<TimeoutResult<T>> {
+  if (timeoutMs == null || timeoutMs <= 0) {
+    return { result: await operation, timedOut: false };
+  }
+
+  const start = performance.now();
+  let timer: ReturnType<typeof setTimeout>;
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      reject(new RouterTimeoutError(phase, performance.now() - start));
+    }, timeoutMs);
+  });
+
+  try {
+    const result = await Promise.race([operation, timeoutPromise]);
+    clearTimeout(timer!);
+    return { result, timedOut: false };
+  } catch (error) {
+    clearTimeout(timer!);
+    if (error instanceof RouterTimeoutError) {
+      return { timedOut: true, durationMs: error.durationMs };
+    }
+    throw error;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Default response
+// ---------------------------------------------------------------------------
+
+/**
+ * Create the default 504 response for a timed-out request.
+ * Includes `X-Rango-Timeout-Phase` header for observability.
+ */
+export function createDefaultTimeoutResponse(phase: TimeoutPhase): Response {
+  return new Response("Request timed out", {
+    status: 504,
+    headers: {
+      "Content-Type": "text/plain;charset=utf-8",
+      "X-Rango-Timeout-Phase": phase,
+    },
+  });
+}

package/src/router/trie-matching.ts

@@ -6,6 +6,7 @@
  */
 
 import type { TrieNode, TrieLeaf } from "../build/route-trie.js";
+import { safeDecodeURIComponent } from "./url-params.js";
 
 export interface TrieMatchResult {
   /** Route name */
@@ -14,7 +15,9 @@ export interface TrieMatchResult {
   sp: string;
   /** Matched route params */
   params: Record<string, string>;
-  /** Optional param names (absent params have empty string value) */
+  /** Optional param names declared on the route. Absent params are omitted
+   * from `params` (read as `undefined`), matching the
+   * `ExtractParams<"/:locale?/...">` type. */
   optionalParams?: string[];
   /** Ancestry shortCodes for layout pruning */
   ancestry: string[];
@@ -43,13 +46,22 @@ export function tryTrieMatch(
   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;
+  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(trie.r, {}, pathname, pathnameHasTrailingSlash);
+      return validateAndBuild(
+        trie.r,
+        [],
+        undefined,
+        pathname,
+        pathnameHasTrailingSlash,
+      );
     }
     return null;
   }
@@ -58,9 +70,15 @@ export function tryTrieMatch(
   const segments = normalizedPath.slice(1).split("/");
 
   // Try exact match with normalized path (no trailing slash)
-  const result = walkTrie(trie, segments, 0, {});
+  const result = walkTrie(trie, segments, 0, []);
   if (result) {
-    return validateAndBuild(result.leaf, result.params, pathname, pathnameHasTrailingSlash);
+    return validateAndBuild(
+      result.leaf,
+      result.paramValues,
+      result.wildcardValue,
+      pathname,
+      pathnameHasTrailingSlash,
+    );
   }
 
   return null;
@@ -68,7 +86,8 @@ export function tryTrieMatch(
 
 interface WalkResult {
   leaf: TrieLeaf;
-  params: Record<string, string>;
+  paramValues: string[];
+  wildcardValue?: string;
 }
 
 /**
@@ -79,57 +98,106 @@ function walkTrie(
   node: TrieNode,
   segments: string[],
   index: number,
-  params: Record<string, string>,
+  paramValues: string[],
 ): WalkResult | null {
   // All segments consumed: check for terminal
   if (index === segments.length) {
     if (node.r) {
-      return { leaf: node.r, params };
+      return { leaf: node.r, paramValues: [...paramValues] };
     }
     return null;
   }
 
   const segment = segments[index];
+  const staticChild = node.s?.[segment];
 
   // Priority 1: Static match
-  if (node.s?.[segment]) {
-    const result = walkTrie(node.s[segment], segments, index + 1, params);
+  if (staticChild) {
+    const result = walkTrie(staticChild, segments, index + 1, paramValues);
     if (result) return result;
   }
 
-  // Priority 2: Param match
+  // 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) {
+        const paramValue = segment.slice(0, -suffix.length);
+        paramValues.push(paramValue);
+        const result = walkTrie(
+          node.xp[suffix].c,
+          segments,
+          index + 1,
+          paramValues,
+        );
+        paramValues.pop();
+        if (result) return result;
+      }
+    }
+  }
+
+  // Priority 3: Param match
   if (node.p) {
-    const result = walkTrie(node.p.c, segments, index + 1, {
-      ...params,
-      [node.p.n]: segment,
-    });
+    paramValues.push(segment);
+    const result = walkTrie(node.p.c, segments, index + 1, paramValues);
+    paramValues.pop();
     if (result) return result;
   }
 
-  // Priority 3: Wildcard match (consumes rest)
+  // Priority 4: Wildcard match (consumes rest)
   if (node.w) {
-    const rest = segments.slice(index).join("/");
+    const rest = joinRemainingSegments(segments, index);
     return {
       leaf: node.w,
-      params: { ...params, [node.w.pn]: rest },
+      paramValues: [...paramValues],
+      wildcardValue: rest,
     };
   }
 
   return null;
 }
 
+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;
+}
+
 /**
  * Post-match: validate constraints and handle trailing slash logic.
  */
 function validateAndBuild(
   leaf: TrieLeaf,
-  params: Record<string, string>,
+  paramValues: string[],
+  wildcardValue: string | undefined,
   originalPathname: string,
   pathnameHasTrailingSlash: boolean,
 ): TrieMatchResult | null {
-  // Validate constraints
+  // 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++) {
+      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] =
+      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, allowed] of Object.entries(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;
@@ -137,36 +205,40 @@ function validateAndBuild(
     }
   }
 
-  // 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] = "";
-      }
-    }
-  }
+  // 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;
 
-  if (tsMode === "always" && !pathnameHasTrailingSlash && originalPathname !== "/") {
+  if (
+    tsMode === "always" &&
+    !pathnameHasTrailingSlash &&
+    originalPathname !== "/"
+  ) {
     redirectTo = originalPathname + "/";
   } else if (tsMode === "never" && pathnameHasTrailingSlash) {
     redirectTo = originalPathname.slice(0, -1);
   }
 
-  return {
+  const result: TrieMatchResult = {
     routeKey: leaf.n,
     sp: leaf.sp,
     params,
-    optionalParams: leaf.op,
     ancestry: leaf.a,
-    ...(redirectTo ? { redirectTo } : {}),
-    ...(leaf.pr ? { pr: true } : {}),
-    ...(leaf.pt ? { pt: true } : {}),
-    ...(leaf.rt ? { responseType: leaf.rt } : {}),
-    ...(leaf.nv ? { negotiateVariants: leaf.nv } : {}),
-    ...(leaf.rf ? { rscFirst: true } : {}),
   };
+
+  if (leaf.op) result.optionalParams = leaf.op;
+  if (redirectTo) result.redirectTo = redirectTo;
+  if (leaf.pr) result.pr = true;
+  if (leaf.pt) result.pt = true;
+  if (leaf.rt) result.responseType = leaf.rt;
+  if (leaf.nv) result.negotiateVariants = leaf.nv;
+  if (leaf.rf) result.rscFirst = true;
+
+  return result;
 }