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

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.ts

@@ -73,6 +73,7 @@ import {
   traverseBack,
 } from "./router/pattern-matching.js";
 import { resolveSink, safeEmit, getRequestId } from "./router/telemetry.js";
+import { resolveTracing } from "./router/tracing.js";
 import { evaluateRevalidation } from "./router/revalidation.js";
 import {
   type RouterContext,
@@ -152,6 +153,7 @@ export function createRouter<TEnv = any>(
     warmup: warmupOption,
     allowDebugManifest: allowDebugManifestOption = false,
     telemetry: telemetrySink,
+    tracing: tracingOption,
     ssr: ssrOption,
     timeout: timeoutShorthand,
     timeouts: timeoutsOption,
@@ -178,6 +180,10 @@ export function createRouter<TEnv = any>(
   // Resolve telemetry sink (no-op when not configured)
   const telemetry = resolveSink(telemetrySink);
 
+  // Resolve span tracing (undefined when not configured; every traceSpan() call
+  // is then a direct pass-through with zero behavior change).
+  const resolvedTracing = resolveTracing(tracingOption);
+
   // Resolve cache profiles: merge user config with the guaranteed default
   // profile. This resolved map is threaded onto each request context; the
   // "use cache: <profile>" runtime path reads it request-scoped.
@@ -968,6 +974,9 @@ export function createRouter<TEnv = any>(
     // Expose router-wide performance debugging for request-level metrics setup
     debugPerformance,
 
+    // Expose resolved span tracing for the handler (Cloudflare custom spans)
+    tracing: resolvedTracing,
+
     // Expose debug manifest flag for handler
     allowDebugManifest: allowDebugManifestOption,
 

package/src/rsc/handler.ts

@@ -46,8 +46,6 @@ import {
   createReverseFunction,
   stripInternalParams,
 } from "../router/handler-context.js";
-import { getRouterContext } from "../router/router-context.js";
-import { resolveSink, safeEmit } from "../router/telemetry.js";
 import { contextSet } from "../context-var.js";
 import {
   hasCachedManifest,
@@ -84,6 +82,7 @@ import {
   appendMetric,
   buildMetricsTiming,
 } from "../router/metrics.js";
+import { observePhase, observeEvent, PHASES } from "../router/instrument.js";
 import {
   startSSRSetup,
   getSSRSetup,
@@ -244,24 +243,16 @@ export function createRSCHandler<
       metadata: { timeout: true, phase, durationMs },
     });
 
-    try {
-      const routerCtx = getRouterContext();
-      if (routerCtx?.telemetry) {
-        safeEmit(resolveSink(routerCtx.telemetry), {
-          type: "request.timeout" as const,
-          timestamp: performance.now(),
-          requestId: routerCtx.requestId,
-          phase,
-          pathname: url.pathname,
-          routeKey,
-          actionId,
-          durationMs,
-          customHandler: !!router.onTimeout,
-        });
-      }
-    } catch {
-      // Router context may not be available
-    }
+    observeEvent({
+      type: "request.timeout",
+      timestamp: performance.now(),
+      phase,
+      pathname: url.pathname,
+      routeKey,
+      actionId,
+      durationMs,
+      customHandler: !!router.onTimeout,
+    });
 
     if (router.onTimeout) {
       try {
@@ -499,86 +490,103 @@ export function createRSCHandler<
     // Store basename on request context (scoped per-request via existing ALS)
     requestContext._basename = router.basename;
 
-    return runWithRequestContext(requestContext, async () => {
-      // Core handler logic (wrapped by middleware)
-      const coreHandler = async (): Promise<Response> => {
-        return coreRequestHandler(request, env, url, variables, nonce);
-      };
-
-      // Execute middleware chain if any, otherwise call core handler directly
-      let response: Response;
-      if (matchedMiddleware.length > 0) {
-        const mwResponse = await executeMiddleware(
-          matchedMiddleware,
-          request,
-          env,
-          variables,
-          coreHandler,
-          createReverseFunction(getRequiredRouteMap()),
-        );
+    // Resolved span tracing for this request (read at each traced phase).
+    requestContext._tracing = router.tracing;
+
+    // The "rango.request" span is opened inside the request context so the
+    // Cloudflare runner can read executionContext.tracing, and so every nested
+    // phase span (and the platform's automatic KV/D1/fetch spans) nests under
+    // it. metric:false — handler:total is metered directly below (a grand total
+    // incl. the pre-context bootstrap timings, finer than a single wrap). When
+    // tracing is off this is a direct pass-through.
+    return runWithRequestContext(requestContext, () =>
+      observePhase(PHASES.request, async (span) => {
+        span.setAttribute("http.method", request.method);
+        // The matched route template is not known until match() runs later, so
+        // emit the concrete path as url.path (low-level), NOT http.route — the
+        // latter is reserved for the low-cardinality template (OTel convention).
+        span.setAttribute("url.path", url.pathname);
+
+        // Core handler logic (wrapped by middleware)
+        const coreHandler = async (): Promise<Response> => {
+          return coreRequestHandler(request, env, url, variables, nonce);
+        };
 
-        if (
-          url.searchParams.has("_rsc_partial") ||
-          url.searchParams.has("_rsc_action")
-        ) {
-          const intercepted = interceptRedirectForPartial(
-            mwResponse,
-            createRedirectFlightResponse,
+        // Execute middleware chain if any, otherwise call core handler directly
+        let response: Response;
+        if (matchedMiddleware.length > 0) {
+          const mwResponse = await executeMiddleware(
+            matchedMiddleware,
+            request,
+            env,
+            variables,
+            coreHandler,
+            createReverseFunction(getRequiredRouteMap()),
           );
-          response = intercepted ?? finalizeResponse(mwResponse);
+
+          if (
+            url.searchParams.has("_rsc_partial") ||
+            url.searchParams.has("_rsc_action")
+          ) {
+            const intercepted = interceptRedirectForPartial(
+              mwResponse,
+              createRedirectFlightResponse,
+            );
+            response = intercepted ?? finalizeResponse(mwResponse);
+          } else {
+            response = finalizeResponse(mwResponse);
+          }
         } else {
-          response = finalizeResponse(mwResponse);
+          response = await coreHandler();
         }
-      } else {
-        response = await coreHandler();
-      }
 
-      // Finalize metrics after all middleware (including post-next work)
-      // has completed so :post spans are captured in the timeline.
-      // Handler timing parts are always emitted (even without debug metrics)
-      // so non-debug requests still get bootstrap Server-Timing entries.
-      const handlerTimingArr: string[] = variables.__handlerTiming || [];
-      // Preserve any existing Server-Timing set by response routes or middleware
-      const existingTiming = response.headers.get("Server-Timing");
-      const timingParts = existingTiming
-        ? [existingTiming, ...handlerTimingArr]
-        : [...handlerTimingArr];
-
-      const metricsStore = requestContext._metricsStore;
-      if (metricsStore) {
-        // When the store was created at handler start (earlyMetricsStore),
-        // handler:total covers the full request. When ctx.debugPerformance()
-        // created the store mid-request, use its requestStart to avoid a
-        // negative startTime offset.
-        const totalStart = earlyMetricsStore
-          ? handlerStart
-          : metricsStore.requestStart;
-        appendMetric(
-          metricsStore,
-          "handler:total",
-          totalStart,
-          performance.now() - totalStart,
-        );
-        const metricsTiming = buildMetricsTiming(
-          request.method,
-          url.pathname,
-          metricsStore,
-        );
-        if (metricsTiming) timingParts.push(metricsTiming);
-      }
+        // Finalize metrics after all middleware (including post-next work)
+        // has completed so :post spans are captured in the timeline.
+        // Handler timing parts are always emitted (even without debug metrics)
+        // so non-debug requests still get bootstrap Server-Timing entries.
+        const handlerTimingArr: string[] = variables.__handlerTiming || [];
+        // Preserve any existing Server-Timing set by response routes or middleware
+        const existingTiming = response.headers.get("Server-Timing");
+        const timingParts = existingTiming
+          ? [existingTiming, ...handlerTimingArr]
+          : [...handlerTimingArr];
+
+        const metricsStore = requestContext._metricsStore;
+        if (metricsStore) {
+          // When the store was created at handler start (earlyMetricsStore),
+          // handler:total covers the full request. When ctx.debugPerformance()
+          // created the store mid-request, use its requestStart to avoid a
+          // negative startTime offset.
+          const totalStart = earlyMetricsStore
+            ? handlerStart
+            : metricsStore.requestStart;
+          appendMetric(
+            metricsStore,
+            "handler:total",
+            totalStart,
+            performance.now() - totalStart,
+          );
+          const metricsTiming = buildMetricsTiming(
+            request.method,
+            url.pathname,
+            metricsStore,
+          );
+          if (metricsTiming) timingParts.push(metricsTiming);
+        }
 
-      const fullTiming = timingParts.join(", ");
-      if (fullTiming && !isWebSocketUpgradeResponse(response)) {
-        response.headers.set("Server-Timing", fullTiming);
-      }
+        const fullTiming = timingParts.join(", ");
+        if (fullTiming && !isWebSocketUpgradeResponse(response)) {
+          response.headers.set("Server-Timing", fullTiming);
+        }
 
-      // Single open-redirect chokepoint: every response (PE, full-page,
-      // middleware short-circuit, response-route) funnels through here, so
-      // guarding browser-followed (3xx) redirects once covers them all and any
-      // future redirect exit. Soft SPA/Flight redirects are 200/204 and pass
-      // through untouched (validated client-side instead).
-      return guardOutgoingRedirect(response, url.origin, router.basename);
-    });
+        // Single open-redirect chokepoint: every response (PE, full-page,
+        // middleware short-circuit, response-route) funnels through here, so
+        // guarding browser-followed (3xx) redirects once covers them all and any
+        // future redirect exit. Soft SPA/Flight redirects are 200/204 and pass
+        // through untouched (validated client-side instead).
+        return guardOutgoingRedirect(response, url.origin, router.basename);
+      }),
+    );
   };
 
   // Core request handling logic (separated for middleware wrapping).
@@ -715,23 +723,15 @@ export function createRSCHandler<
           },
         });
 
-        try {
-          const routerCtx = getRouterContext();
-          if (routerCtx?.telemetry) {
-            safeEmit(resolveSink(routerCtx.telemetry), {
-              type: "request.origin-rejected" as const,
-              timestamp: performance.now(),
-              requestId: routerCtx.requestId,
-              method: request.method,
-              pathname: url.pathname,
-              phase: originPhase,
-              origin: request.headers.get("origin"),
-              host: request.headers.get("host"),
-            });
-          }
-        } catch {
-          // Router context may not be available
-        }
+        observeEvent({
+          type: "request.origin-rejected",
+          timestamp: performance.now(),
+          method: request.method,
+          pathname: url.pathname,
+          phase: originPhase,
+          origin: request.headers.get("origin"),
+          host: request.headers.get("host"),
+        });
 
         return originResult;
       }
@@ -773,23 +773,15 @@ export function createRSCHandler<
         params: reqCtx.params as Record<string, string>,
         handledByBoundary: true,
       });
-      try {
-        const routerCtx = getRouterContext();
-        if (routerCtx?.telemetry) {
-          safeEmit(resolveSink(routerCtx.telemetry), {
-            type: "handler.error" as const,
-            timestamp: performance.now(),
-            requestId: routerCtx.requestId,
-            error,
-            handledByBoundary: true,
-            pathname: url.pathname,
-            routeKey: reqCtx._routeName,
-            params: reqCtx.params as Record<string, string>,
-          });
-        }
-      } catch {
-        // Router context may not be available (e.g. prerender path)
-      }
+      observeEvent({
+        type: "handler.error",
+        timestamp: performance.now(),
+        error,
+        handledByBoundary: true,
+        pathname: url.pathname,
+        routeKey: reqCtx._routeName,
+        params: reqCtx.params as Record<string, string>,
+      });
     };
 
     // Set route params early so all execution paths can access ctx.params.
@@ -894,14 +886,20 @@ export function createRSCHandler<
     if (plan.mode === "action") {
       let actionContinuation: ActionContinuation | undefined;
       try {
+        // Instrument the action execution as its own phase (action:<actionId> +
+        // rango.action), so a POST shows the mutation time AND which action ran,
+        // not just the downstream revalidation render. The action's own
+        // loaders/fetches nest under rango.action.
         const actionOutcome = await withTimeout(
-          executeServerAction(
-            handlerCtx,
-            request,
-            env,
-            url,
-            plan.actionId,
-            handleStore,
+          observePhase(PHASES.action(plan.actionId), () =>
+            executeServerAction(
+              handlerCtx,
+              request,
+              env,
+              url,
+              plan.actionId,
+              handleStore,
+            ),
           ),
           router.timeouts.actionMs,
           "action",

package/src/rsc/loader-fetch.ts

@@ -14,6 +14,7 @@
 import { getLoaderLazy } from "../server/loader-registry.js";
 import { executeLoaderMiddleware } from "../router/middleware.js";
 import { requireRequestContext } from "../server/request-context.js";
+import { observePhase, PHASES } from "../router/instrument.js";
 import {
   createReverseFunction,
   stripInternalParams,
@@ -162,7 +163,12 @@ export async function handleLoaderFetch<TEnv>(
             ...(loaderFormData ? { formData: loaderFormData } : {}),
           };
 
-          const result = await fn(loaderCtx);
+          // Meter the fetchable-loader execution via observePhase, the sole
+          // funnel for this path (fn is called directly, not via ctx.use).
+          // depth:1 — a fetchable request has no render-phase parent.
+          const result = await observePhase(PHASES.loader(loaderId, 1), () =>
+            fn(loaderCtx),
+          );
 
           interface LoaderPayload {
             loaderResult: unknown;

package/src/rsc/progressive-enhancement.ts

@@ -13,6 +13,7 @@ import {
 import { getSSRSetup } from "./ssr-setup.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 import { executeMiddleware } from "../router/middleware.js";
+import { observePhase, PHASES } from "../router/instrument.js";
 import type { RscPayload, ReactFormState } from "./types.js";
 import {
   createResponseWithMergedHeaders,
@@ -124,7 +125,11 @@ export async function handleProgressiveEnhancement<TEnv>(
       const boundAction = await ctx.decodeAction(formData);
       // React's custom .bind() preserves $$id on server references.
       useActionStateId = (boundAction as { $$id?: string }).$$id ?? undefined;
-      actionResult = await boundAction();
+      // Meter the no-JS form action as the action phase, same as the JS path.
+      actionResult = await observePhase(
+        PHASES.action(useActionStateId ?? "useActionState"),
+        () => boundAction(),
+      );
     } catch (error) {
       // Handle thrown redirect (e.g., throw redirect('/path'))
       const redirectResponse = extractRedirectResponse(error);
@@ -172,7 +177,9 @@ export async function handleProgressiveEnhancement<TEnv>(
 
     try {
       const loadedAction = await ctx.loadServerAction(directActionId);
-      actionResult = await loadedAction.apply(null, args);
+      actionResult = await observePhase(PHASES.action(directActionId), () =>
+        loadedAction.apply(null, args),
+      );
     } catch (error) {
       // Handle thrown redirect (e.g., throw redirect('/path'))
       const redirectResponse = extractRedirectResponse(error);