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

package/src/router/telemetry-otel.ts

@@ -1,20 +1,48 @@
 /**
- * OpenTelemetry Adapter for Router Telemetry
+ * OpenTelemetry adapters for the router.
  *
- * 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.
+ * Two adapters, two surfaces — matching the split in instrument.ts:
+ *
+ *   - createOTelTracing(tracer): the OTel adapter for the `tracing` SLOT — the
+ *     canonical phase-span layer. It bridges observePhase's callback boundary
+ *     onto OTel's callback-bound `startActiveSpan`, so the router's phase spans
+ *     (rango.request/middleware/loader/render/ssr) nest by async context and the
+ *     loader's own OTel spans (db/fetch) land under rango.loader. This is the
+ *     OTel equivalent of createCloudflareTracing — pass it to
+ *     `createRouter({ tracing })`.
+ *
+ *   - createOTelSink(tracer): the OTel adapter for the `telemetry` SLOT — a
+ *     TelemetrySink for the EVENT-shaped facts (handler errors, cache decisions,
+ *     revalidation decisions, timeouts, origin rejections). It emits one instant
+ *     OTel span per fact. It deliberately does NOT emit request/loader phase
+ *     spans: those are owned by the tracing slot (createOTelTracing) so the two
+ *     layers don't produce duplicate rango.request / rango.loader spans.
+ *
+ * The core router stays OTel-agnostic — these adapters accept a standard OTel
+ * Tracer (structurally typed, no import needed) and bridge the gap.
  *
  * Usage:
  *   import { trace } from "@opentelemetry/api";
- *   import { createOTelSink } from "@rangojs/router";
+ *   import { createRouter, createOTelTracing, createOTelSink } from "@rangojs/router";
  *
+ *   const tracer = trace.getTracer("my-app");
  *   const router = createRouter({
- *     telemetry: createOTelSink(trace.getTracer("my-app")),
+ *     tracing: createOTelTracing(tracer),   // phase spans (callback-bound)
+ *     telemetry: createOTelSink(tracer),     // discrete-fact instant spans
  *   });
+ *
+ * Faithful nesting requires an OTel async context manager
+ * (AsyncLocalStorageContextManager) configured in your OTel setup — standard for
+ * any startActiveSpan-based instrumentation.
  */
 
 import type { TelemetrySink, TelemetryEvent } from "./telemetry.js";
+import { runThenSettle } from "./tracing.js";
+import type {
+  RouterTracingConfig,
+  SpanRunner,
+  TracingToggleOptions,
+} from "./tracing.js";
 
 // ---------------------------------------------------------------------------
 // Minimal OTel-compatible types (structurally typed, no import needed)
@@ -22,21 +50,21 @@ import type { TelemetrySink, TelemetryEvent } from "./telemetry.js";
 
 /**
  * Minimal Span interface compatible with @opentelemetry/api Span.
- * Only the methods used by the adapter are declared.
+ * Only the methods used by the adapters 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.
+ * Minimal Tracer interface for the EVENT sink (createOTelSink): only `startSpan`
+ * is used (one instant span per discrete fact). Kept narrow so a custom,
+ * event-only tracer that does not implement `startActiveSpan` still satisfies it.
+ * The real `@opentelemetry/api` Tracer has both methods, so it satisfies this and
+ * `OTelActiveSpanTracer` below.
  */
 export interface OTelTracer {
   startSpan(
@@ -47,194 +75,108 @@ export interface OTelTracer {
   ): OTelSpan;
 }
 
+/**
+ * Minimal Tracer interface for the PHASE-SPAN adapter (createOTelTracing): only
+ * `startActiveSpan` is used (callback-bound, so the span is active for the work
+ * and child spans nest). Declared separately from `OTelTracer` so each factory
+ * requires exactly the method it calls.
+ */
+export interface OTelActiveSpanTracer {
+  startActiveSpan<T>(name: string, fn: (span: OTelSpan) => T): T;
+}
+
 // OTel SpanStatusCode constants (mirrors @opentelemetry/api values)
-const STATUS_OK = 1;
 const STATUS_ERROR = 2;
 
 // ---------------------------------------------------------------------------
-// Span correlation helpers
+// Tracing adapter: phase spans via startActiveSpan (the `tracing` slot)
 // ---------------------------------------------------------------------------
 
-// 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}`;
-}
+/**
+ * Options for createOTelTracing. Alias of the shared {@link TracingToggleOptions}
+ * (`enabled` master switch + per-phase `spans` toggles); the name is public API.
+ */
+export type OTelTracingOptions = TracingToggleOptions;
 
-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);
-}
+/**
+ * Create the tracing config that maps the router's phases onto OTel spans via
+ * `tracer.startActiveSpan`, which runs the work inside the span's active context
+ * (so child spans nest) and returns the work's value unchanged. The span ends
+ * when that value — or, for async work, the returned promise — settles, matching
+ * observePhase's contract. When the work throws or rejects, the exception is
+ * recorded and the span status is set to ERROR before it ends, so a failed phase
+ * stays visible in the trace (the old createOTelSink error path is preserved here
+ * now that phase spans live in this adapter). Pass the result to
+ * `createRouter({ tracing })`.
+ *
+ * @see createCloudflareTracing (`@rangojs/router/cloudflare`) for the same slot
+ *   using Cloudflare Workers native custom spans.
+ */
+export function createOTelTracing(
+  tracer: OTelActiveSpanTracer,
+  options: OTelTracingOptions = {},
+): RouterTracingConfig {
+  const runner: SpanRunner = <T>(name: string, fn: (span: OTelSpan) => T): T =>
+    tracer.startActiveSpan(
+      name,
+      (span): T =>
+        runThenSettle(
+          () => fn(span),
+          (error) => {
+            // On failure record the exception + ERROR status before ending, so a
+            // failed phase stays visible in the trace.
+            if (error !== undefined) {
+              if (error instanceof Error) {
+                span.recordException(error);
+                span.setStatus({ code: STATUS_ERROR, message: error.message });
+              } else {
+                span.setStatus({ code: STATUS_ERROR });
+              }
+            }
+            span.end();
+          },
+        ),
+    );
 
-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;
+  return {
+    runner,
+    enabled: options.enabled ?? true,
+    spans: options.spans,
+  };
 }
 
 // ---------------------------------------------------------------------------
-// Adapter factory
+// Telemetry sink: discrete-fact instant spans (the `telemetry` slot)
 // ---------------------------------------------------------------------------
 
 /**
- * Create a TelemetrySink that maps router lifecycle events to OTel spans.
+ * Create a TelemetrySink that maps the router's discrete-fact events to instant
+ * OTel spans. One span per fact; no duration spans.
+ *
+ * Fact mapping:
+ *   - handler.error              -> "rango.handler.error" (error)
+ *   - cache.decision             -> "rango.cache.decision"
+ *   - revalidation.decision      -> "rango.revalidation.decision"
+ *   - request.timeout            -> "rango.request.timeout" (error)
+ *   - request.origin-rejected    -> "rango.request.origin-rejected" (error)
  *
- * 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
+ * Request and loader PHASE spans are intentionally NOT emitted here — they are
+ * owned by the tracing slot (createOTelTracing) so the two layers cannot produce
+ * duplicate rango.request / rango.loader spans. request.start/end and
+ * loader.start/end events are no-ops for this sink.
  *
  * 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[]>();
+  const instant = (
+    name: string,
+    attributes: Record<string, string | number | boolean>,
+  ): OTelSpan => tracer.startSpan(name, { attributes });
 
   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,
@@ -244,23 +186,16 @@ export function createOTelSink(tracer: OTelTracer): TelemetrySink {
             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) {
+          if (event.params)
             attrs["rango.params"] = JSON.stringify(event.params);
-          }
 
-          const span = tracer.startSpan("rango.handler.error", {
-            attributes: attrs,
-          });
+          const span = instant("rango.handler.error", 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,
@@ -269,30 +204,55 @@ export function createOTelSink(tracer: OTelTracer): TelemetrySink {
             "rango.cache.should_revalidate": event.shouldRevalidate,
           };
           if (event.source) attrs["rango.cache.source"] = event.source;
+          instant("rango.cache.decision", attrs).end();
+          break;
+        }
 
-          const span = tracer.startSpan("rango.cache.decision", {
-            attributes: attrs,
+        case "revalidation.decision": {
+          instant("rango.revalidation.decision", {
+            "rango.segment_id": event.segmentId,
+            "http.route": event.pathname,
+            "rango.route_key": event.routeKey,
+            "rango.revalidate": event.shouldRevalidate,
+          }).end();
+          break;
+        }
+
+        case "request.timeout": {
+          const attrs: Record<string, string | number | boolean> = {
+            "rango.phase": event.phase,
+            "http.route": event.pathname,
+            "rango.duration_ms": event.durationMs,
+            "rango.timeout.custom_handler": event.customHandler,
+          };
+          if (event.routeKey) attrs["rango.route_key"] = event.routeKey;
+          if (event.actionId) attrs["rango.action_id"] = event.actionId;
+          const span = instant("rango.request.timeout", attrs);
+          span.setStatus({
+            code: STATUS_ERROR,
+            message: `timeout: ${event.phase}`,
           });
           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,
-            },
-          });
+        case "request.origin-rejected": {
+          const attrs: Record<string, string | number | boolean> = {
+            "http.method": event.method,
+            "http.route": event.pathname,
+            "rango.phase": event.phase,
+          };
+          if (event.origin) attrs["rango.origin"] = event.origin;
+          if (event.host) attrs["http.host"] = event.host;
+          const span = instant("rango.request.origin-rejected", attrs);
+          span.setStatus({ code: STATUS_ERROR, message: "origin rejected" });
           span.end();
           break;
         }
+
+        // request.start/end/error and loader.start/end/error are phase events;
+        // their spans are owned by the tracing slot (createOTelTracing), so this
+        // sink ignores them to avoid duplicate rango.request / rango.loader spans.
       }
     },
   };

package/src/router/telemetry.ts

@@ -14,10 +14,6 @@
  *   - revalidation.decision          (revalidation evaluation)
  */
 
-// ---------------------------------------------------------------------------
-// Event types
-// ---------------------------------------------------------------------------
-
 interface BaseEvent {
   /** Monotonic timestamp from performance.now() */
   timestamp: number;
@@ -42,6 +38,14 @@ export interface RequestEndEvent extends BaseEvent {
   durationMs: number;
   segmentCount: number;
   cacheHit: boolean;
+  /**
+   * HTTP status when a Response ended the transaction — a thrown-Response
+   * short-circuit (redirect / auth gate carries the Response's status, e.g. 302),
+   * or dispatch()'s final response status. Absent for a normal render completion:
+   * the Response is built after match(), so match()/matchPartial() have no status
+   * to stamp there. Lets a sink split 3xx short-circuits from 2xx completions.
+   */
+  status?: number;
 }
 
 export interface RequestErrorEvent extends BaseEvent {
@@ -90,6 +94,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 +130,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 +179,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 +253,6 @@ export interface TelemetrySink {
   emit(event: TelemetryEvent): void;
 }
 
-// ---------------------------------------------------------------------------
-// No-op singleton (zero-cost disabled state)
-// ---------------------------------------------------------------------------
-
 const noopSink: TelemetrySink = {
   emit() {},
 };
@@ -185,12 +280,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 +313,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.
@@ -243,7 +328,7 @@ export function createConsoleSink(): TelemetrySink {
           break;
         case "request.end":
           console.log(
-            `[telemetry] ${event.type} ${event.method} ${event.pathname} ${event.durationMs.toFixed(1)}ms segments=${event.segmentCount} cache=${event.cacheHit}`,
+            `[telemetry] ${event.type} ${event.method} ${event.pathname} ${event.durationMs.toFixed(1)}ms segments=${event.segmentCount} cache=${event.cacheHit}${event.status !== undefined ? ` status=${event.status}` : ""}`,
           );
           break;
         case "request.error":