@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.25dbaac3

package/src/router/segment-resolution/static-store.ts

@@ -6,7 +6,7 @@
  */
 
 import type { ReactNode } from "react";
-import { getRequestContext } from "../../server/request-context.js";
+import { _getRequestContext } from "../../server/request-context.js";
 import type { StaticStore } from "../../prerender/store.js";
 
 // Lazy-initialized static store for production Static handler interception.
@@ -57,7 +57,7 @@ export async function tryStaticLookup(
   // The data was keyed by handlerId at build time; replay under segmentId
   // so it matches the segment order used by useHandle on the client.
   if (entry.handles && Object.keys(entry.handles).length > 0) {
-    const handleStore = getRequestContext()?._handleStore;
+    const handleStore = _getRequestContext()?._handleStore;
     if (handleStore) {
       handleStore.replaySegmentData(segmentId, entry.handles);
     }

package/src/router/segment-resolution.ts

@@ -1,12 +1,11 @@
 // Barrel re-export -- see segment-resolution/ for implementations.
+export { handleHandlerResult } from "./segment-resolution/helpers.js";
 export {
-  handleHandlerResult,
   resolveLoaders,
   type ResolveSegmentOptions,
   resolveSegment,
   resolveOrphanLayout,
   resolveParallelEntry,
-  resolveWithErrorHandling,
   resolveAllSegments,
   resolveLoadersOnly,
 } from "./segment-resolution/fresh.js";
@@ -18,6 +17,5 @@ export {
   resolveEntryHandlerWithRevalidation,
   resolveSegmentWithRevalidation,
   resolveOrphanLayoutWithRevalidation,
-  resolveWithRevalidationErrorHandling,
   resolveAllSegmentsWithRevalidation,
 } from "./segment-resolution/revalidation.js";

package/src/router/segment-wrappers.ts

@@ -50,6 +50,7 @@ export interface SegmentWrappers<TEnv = any> {
       actionResult?: any;
       formData?: FormData;
     },
+    stale?: boolean,
   ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
   buildEntryRevalidateMap: (
     entries: EntryData[],
@@ -158,6 +159,7 @@ export function createSegmentWrappers<TEnv = any>(
       actionResult?: any;
       formData?: FormData;
     },
+    stale?: boolean,
   ): ReturnType<typeof _resolveLoadersOnlyWithRevalidation> {
     return _resolveLoadersOnlyWithRevalidation(
       entries,
@@ -170,6 +172,7 @@ export function createSegmentWrappers<TEnv = any>(
       routeKey,
       segmentDeps,
       actionContext,
+      stale,
     );
   }
 
@@ -201,6 +204,7 @@ export function createSegmentWrappers<TEnv = any>(
     interceptResult: { intercept: InterceptEntry; entry: EntryData } | null,
     localRouteName: string,
     pathname: string,
+    stale?: boolean,
   ): ReturnType<typeof _resolveAllSegmentsWithRevalidation> {
     return _resolveAllSegmentsWithRevalidation(
       entries,
@@ -218,6 +222,7 @@ export function createSegmentWrappers<TEnv = any>(
       localRouteName,
       pathname,
       segmentDeps,
+      stale,
     );
   }
 

package/src/router/telemetry-otel.ts

@@ -0,0 +1,299 @@
+/**
+ * OpenTelemetry Adapter for Router Telemetry
+ *
+ * Maps internal TelemetrySink events to OTel spans. The core router
+ * remains OTel-agnostic — this adapter bridges the gap by accepting
+ * a standard OTel Tracer and producing spans/events from it.
+ *
+ * Usage:
+ *   import { trace } from "@opentelemetry/api";
+ *   import { createOTelSink } from "@rangojs/router";
+ *
+ *   const router = createRouter({
+ *     telemetry: createOTelSink(trace.getTracer("my-app")),
+ *   });
+ */
+
+import type { TelemetrySink, TelemetryEvent } from "./telemetry.js";
+
+// ---------------------------------------------------------------------------
+// Minimal OTel-compatible types (structurally typed, no import needed)
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal Span interface compatible with @opentelemetry/api Span.
+ * Only the methods used by the adapter are declared.
+ */
+export interface OTelSpan {
+  setAttribute(key: string, value: string | number | boolean): OTelSpan | void;
+  addEvent(
+    name: string,
+    attributes?: Record<string, string | number | boolean>,
+  ): OTelSpan | void;
+  setStatus(status: { code: number; message?: string }): OTelSpan | void;
+  recordException(exception: Error): void;
+  end(): void;
+}
+
+/**
+ * Minimal Tracer interface compatible with @opentelemetry/api Tracer.
+ */
+export interface OTelTracer {
+  startSpan(
+    name: string,
+    options?: {
+      attributes?: Record<string, string | number | boolean>;
+    },
+  ): OTelSpan;
+}
+
+// OTel SpanStatusCode constants (mirrors @opentelemetry/api values)
+const STATUS_OK = 1;
+const STATUS_ERROR = 2;
+
+// ---------------------------------------------------------------------------
+// Span correlation helpers
+// ---------------------------------------------------------------------------
+
+// Build correlation keys using requestId.
+// getRequestId() always returns a value (generated internally when no
+// header is present), so concurrent requests to the same path each get
+// their own correlation key and never mis-correlate.
+
+function requestKey(event: {
+  requestId?: string;
+  pathname: string;
+  transaction: string;
+}): string {
+  return `${event.requestId ?? ""}:${event.pathname}:${event.transaction}`;
+}
+
+function loaderKey(event: {
+  requestId?: string;
+  segmentId: string;
+  loaderName: string;
+  pathname: string;
+}): string {
+  return `${event.requestId ?? ""}:${event.segmentId}:${event.loaderName}:${event.pathname}`;
+}
+
+function pushSpan(
+  map: Map<string, OTelSpan[]>,
+  key: string,
+  span: OTelSpan,
+): void {
+  let stack = map.get(key);
+  if (!stack) {
+    stack = [];
+    map.set(key, stack);
+  }
+  stack.push(span);
+}
+
+function popSpan(
+  map: Map<string, OTelSpan[]>,
+  key: string,
+): OTelSpan | undefined {
+  const stack = map.get(key);
+  if (!stack || stack.length === 0) return undefined;
+  const span = stack.pop()!;
+  if (stack.length === 0) map.delete(key);
+  return span;
+}
+
+// ---------------------------------------------------------------------------
+// Adapter factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a TelemetrySink that maps router lifecycle events to OTel spans.
+ *
+ * Span mapping:
+ *   - request.start / request.end / request.error  → "rango.request" span
+ *   - loader.start / loader.end / loader.error      → "rango.loader" span
+ *   - handler.error                                  → "rango.handler.error" instant span
+ *   - cache.decision                                 → "rango.cache.decision" instant span
+ *   - revalidation.decision                          → "rango.revalidation.decision" instant span
+ *
+ * Attributes use the `rango.*` namespace for router-specific data and
+ * `http.method` / `http.route` for HTTP semantics.
+ */
+export function createOTelSink(tracer: OTelTracer): TelemetrySink {
+  const requestSpans = new Map<string, OTelSpan[]>();
+  const loaderSpans = new Map<string, OTelSpan[]>();
+
+  return {
+    emit(event: TelemetryEvent): void {
+      switch (event.type) {
+        // -----------------------------------------------------------------
+        // Request lifecycle
+        // -----------------------------------------------------------------
+
+        case "request.start": {
+          const span = tracer.startSpan("rango.request", {
+            attributes: {
+              "http.method": event.method,
+              "http.route": event.pathname,
+              "rango.transaction": event.transaction,
+              "rango.is_partial": event.isPartial,
+            },
+          });
+          pushSpan(requestSpans, requestKey(event), span);
+          break;
+        }
+
+        case "request.end": {
+          const span = popSpan(requestSpans, requestKey(event));
+          if (span) {
+            span.setAttribute("rango.duration_ms", event.durationMs);
+            span.setAttribute("rango.segment_count", event.segmentCount);
+            span.setAttribute("rango.cache.hit", event.cacheHit);
+            span.setStatus({ code: STATUS_OK });
+            span.end();
+          }
+          break;
+        }
+
+        case "request.error": {
+          const span = popSpan(requestSpans, requestKey(event));
+          if (span) {
+            span.setAttribute("rango.duration_ms", event.durationMs);
+            span.setAttribute("rango.phase", event.phase);
+            span.recordException(event.error);
+            span.setStatus({
+              code: STATUS_ERROR,
+              message: event.error.message,
+            });
+            span.end();
+          }
+          break;
+        }
+
+        // -----------------------------------------------------------------
+        // Loader lifecycle
+        // -----------------------------------------------------------------
+
+        case "loader.start": {
+          const span = tracer.startSpan("rango.loader", {
+            attributes: {
+              "rango.segment_id": event.segmentId,
+              "rango.loader_name": event.loaderName,
+              "http.route": event.pathname,
+            },
+          });
+          pushSpan(loaderSpans, loaderKey(event), span);
+          break;
+        }
+
+        case "loader.end": {
+          const key = loaderKey(event);
+          const span = popSpan(loaderSpans, key);
+          if (span) {
+            span.setAttribute("rango.duration_ms", event.durationMs);
+            span.setAttribute("rango.loader.ok", event.ok);
+            span.setStatus({ code: event.ok ? STATUS_OK : STATUS_ERROR });
+            span.end();
+          }
+          break;
+        }
+
+        case "loader.error": {
+          const key = loaderKey(event);
+          const span = popSpan(loaderSpans, key);
+          if (span) {
+            span.setAttribute(
+              "rango.handled_by_boundary",
+              event.handledByBoundary,
+            );
+            span.recordException(event.error);
+            span.setStatus({
+              code: STATUS_ERROR,
+              message: event.error.message,
+            });
+            span.end();
+          } else {
+            // No matching start — create a standalone error span
+            const errorSpan = tracer.startSpan("rango.loader", {
+              attributes: {
+                "rango.segment_id": event.segmentId,
+                "rango.loader_name": event.loaderName,
+                "http.route": event.pathname,
+                "rango.handled_by_boundary": event.handledByBoundary,
+              },
+            });
+            errorSpan.recordException(event.error);
+            errorSpan.setStatus({
+              code: STATUS_ERROR,
+              message: event.error.message,
+            });
+            errorSpan.end();
+          }
+          break;
+        }
+
+        // -----------------------------------------------------------------
+        // Handler errors (instant span)
+        // -----------------------------------------------------------------
+
+        case "handler.error": {
+          const attrs: Record<string, string | number | boolean> = {
+            "rango.handled_by_boundary": event.handledByBoundary,
+          };
+          if (event.segmentId) attrs["rango.segment_id"] = event.segmentId;
+          if (event.segmentType)
+            attrs["rango.segment_type"] = event.segmentType;
+          if (event.pathname) attrs["http.route"] = event.pathname;
+          if (event.routeKey) attrs["rango.route_key"] = event.routeKey;
+          if (event.params) {
+            attrs["rango.params"] = JSON.stringify(event.params);
+          }
+
+          const span = tracer.startSpan("rango.handler.error", {
+            attributes: attrs,
+          });
+          span.recordException(event.error);
+          span.setStatus({ code: STATUS_ERROR, message: event.error.message });
+          span.end();
+          break;
+        }
+
+        // -----------------------------------------------------------------
+        // Cache decision (instant span)
+        // -----------------------------------------------------------------
+
+        case "cache.decision": {
+          const attrs: Record<string, string | number | boolean> = {
+            "http.route": event.pathname,
+            "rango.route_key": event.routeKey,
+            "rango.cache.hit": event.hit,
+            "rango.cache.should_revalidate": event.shouldRevalidate,
+          };
+          if (event.source) attrs["rango.cache.source"] = event.source;
+
+          const span = tracer.startSpan("rango.cache.decision", {
+            attributes: attrs,
+          });
+          span.end();
+          break;
+        }
+
+        // -----------------------------------------------------------------
+        // Revalidation decision (instant span)
+        // -----------------------------------------------------------------
+
+        case "revalidation.decision": {
+          const span = tracer.startSpan("rango.revalidation.decision", {
+            attributes: {
+              "rango.segment_id": event.segmentId,
+              "http.route": event.pathname,
+              "rango.route_key": event.routeKey,
+              "rango.revalidate": event.shouldRevalidate,
+            },
+          });
+          span.end();
+          break;
+        }
+      }
+    },
+  };
+}

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