@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.131

package/src/router/telemetry.ts

@@ -0,0 +1,377 @@
+/**
+ * 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)
+ */
+
+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>;
+}
+
+/**
+ * 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;
+  routeKey: string;
+  hit: boolean;
+  /** 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 {
+  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;
+
+// ---------------------------------------------------------------------------
+// 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.
+ *
+ * All methods are fire-and-forget — exceptions are caught and logged.
+ */
+export interface TelemetrySink {
+  emit(event: TelemetryEvent): void;
+}
+
+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);
+    }
+  }
+}
+
+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;
+}
+
+/**
+ * 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,128 @@
+/**
+ * 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.
+ */
+
+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>;
+
+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,
+  };
+}
+
+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;
+  }
+}
+
+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;
+  }
+}
+
+/**
+ * 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/tracing.ts

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