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

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,
+  TracePhaseToggles,
+} 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,182 +75,110 @@ 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. */
+export interface OTelTracingOptions {
+  /** Master switch. Defaults to true. */
+  enabled?: boolean;
+  /** Per-phase span toggles. Omitted phases default to enabled. */
+  spans?: TracePhaseToggles;
 }
 
-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) {
-        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;
-        }
-
-        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;
-        }
-
         case "handler.error": {
           const attrs: Record<string, string | number | boolean> = {
             "rango.handled_by_boundary": event.handledByBoundary,
@@ -232,13 +188,10 @@ 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();
@@ -253,26 +206,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;
         }
 
-        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/tracing.ts

@@ -0,0 +1,198 @@
+/**
+ * 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.render (render:total:<route>; normal AND
+ * action-revalidation renders), rango.ssr (ssr:render-html).
+ *
+ * Span-duration caveat: 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. Loader/Suspense work that settles during stream drain extends past
+ * the parent span's end, so parent durations under-report streamed time and a
+ * rango.loader child can end after its parent. This is the streaming + end-on-
+ * settle contract, not a defect; phase spans bound setup-to-stream-handoff.
+ *
+ * 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"
+  | "render"
+  | "ssr";
+
+/** Per-phase span toggles. Omitted phases default to enabled. */
+export interface TracePhaseToggles {
+  request?: boolean;
+  middleware?: boolean;
+  action?: boolean;
+  loader?: boolean;
+  render?: boolean;
+  ssr?: boolean;
+}
+
+/**
+ * Value passed to `createRouter({ tracing })`. Produced by a platform factory
+ * such as `createCloudflareTracing()`.
+ */
+export interface RouterTracingConfig {
+  /** Platform span runner. */
+  runner: SpanRunner;
+  /** Master switch. Defaults to true when a config object is provided. */
+  enabled?: boolean;
+  /** Per-phase span toggles. */
+  spans?: TracePhaseToggles;
+}
+
+/**
+ * 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,
+  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,
+          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

@@ -15,10 +15,6 @@ export interface TrieMatchResult {
   sp: string;
   /** Matched route params */
   params: Record<string, string>;
-  /** Optional param names declared on the route. Absent params are omitted
-   * from `params` (read as `undefined`), matching the
-   * `ExtractParams<"/:locale?/...">` type. */
-  optionalParams?: string[];
   /** Redirect target if trailing slash requires it */
   redirectTo?: string;
   /** Route has pre-rendered data available */
@@ -182,6 +178,9 @@ function walkTrie(
   }
 
   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);
@@ -274,7 +273,6 @@ function validateAndBuild(
     params,
   };
 
-  if (leaf.op) result.optionalParams = leaf.op;
   if (redirectTo) result.redirectTo = redirectTo;
   if (leaf.pr) result.pr = true;
   if (leaf.pt) result.pt = true;