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

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,12 @@ import {
   appendMetric,
   buildMetricsTiming,
 } from "../router/metrics.js";
+import {
+  observePhase,
+  observeRequestPhase,
+  observeEvent,
+  PHASES,
+} from "../router/instrument.js";
 import {
   startSSRSetup,
   getSSRSetup,
@@ -244,24 +248,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 +495,106 @@ 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. observeRequestPhase owns the drain barrier: it instruments the final
+    // response body so this span (and the streaming inner phases) stay open
+    // until the body drains, keeping the tree valid. metric:false — handler:total
+    // is metered directly below (a grand total incl. the pre-context bootstrap
+    // timings) and stays construction-bound (it ships as a Server-Timing header,
+    // flushed before drain). When no surface is active this is a pass-through.
+    return runWithRequestContext(requestContext, () =>
+      observeRequestPhase(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 +731,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 +781,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 +894,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);

package/src/rsc/rsc-rendering.ts

@@ -11,6 +11,7 @@ import {
   setRequestContextParams,
 } from "../server/request-context.js";
 import { appendMetric } from "../router/metrics.js";
+import { observeStreamingPhase, PHASES } from "../router/instrument.js";
 import { getSSRSetup, isRscRequest } from "./ssr-setup.js";
 import type { RscPayload } from "./types.js";
 import type { MatchResult } from "../types.js";
@@ -21,7 +22,34 @@ import {
 } from "./helpers.js";
 import type { HandlerContext } from "./handler-context.js";
 
-export async function handleRscRendering<TEnv>(
+export function handleRscRendering<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  isPartial: boolean,
+  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  nonce: string | undefined,
+): Promise<Response> {
+  // Instrument the whole render phase once through the unified API: it records
+  // the "render:total" perf metric AND opens the "rango.render" span from the
+  // same boundary (match -> serialize -> SSR), so the two surfaces agree.
+  // Loaders kicked off during matching nest under the span; the SSR HTML pass
+  // below opens "rango.ssr" the same way.
+  return observeStreamingPhase(PHASES.render, () =>
+    handleRscRenderingInner(
+      ctx,
+      request,
+      env,
+      url,
+      isPartial,
+      handleStore,
+      nonce,
+    ),
+  );
+}
+
+async function handleRscRenderingInner<TEnv>(
   ctx: HandlerContext<TEnv>,
   request: Request,
   env: TEnv,
@@ -158,7 +186,6 @@ export async function handleRscRendering<TEnv>(
   }
 
   const metricsStore = reqCtx._metricsStore;
-  const renderStart = performance.now();
 
   // Serialize to RSC stream
   const rscSerializeStart = performance.now();
@@ -177,8 +204,7 @@ export async function handleRscRendering<TEnv>(
   );
 
   if (isRscRequest(request, url, isPartial)) {
-    const renderDur = performance.now() - renderStart;
-    appendMetric(metricsStore, "render:total", renderStart, renderDur);
+    // render:total is recorded by the observePhase wrapper around this function.
     const rscHeaders: Record<string, string> = {
       "content-type": "text/x-component;charset=utf-8",
       vary: "accept, X-Rango-State, X-RSC-Router-Client-Path",
@@ -220,16 +246,14 @@ export async function handleRscRendering<TEnv>(
     metricsStore,
   );
 
-  const ssrRenderStart = performance.now();
-  const htmlStream = await ssrModule.renderHTML(rscStream, {
-    nonce,
-    streamMode,
-  });
-  const ssrRenderDur = performance.now() - ssrRenderStart;
-  appendMetric(metricsStore, "ssr-render-html", ssrRenderStart, ssrRenderDur);
-
-  const renderDur = performance.now() - renderStart;
-  appendMetric(metricsStore, "render:total", renderStart, renderDur);
+  // ssr-render-html metric + rango.ssr span from one boundary. render:total is
+  // recorded by the observePhase wrapper around this function.
+  const htmlStream = await observeStreamingPhase(PHASES.ssr, () =>
+    ssrModule.renderHTML(rscStream, {
+      nonce,
+      streamMode,
+    }),
+  );
 
   return createResponseWithMergedHeaders(htmlStream, {
     headers: { "content-type": "text/html;charset=utf-8" },

package/src/rsc/server-action.ts

@@ -20,6 +20,7 @@ import {
   setRequestContextParams,
 } from "../server/request-context.js";
 import { appendMetric } from "../router/metrics.js";
+import { observeStreamingPhase, PHASES } from "../router/instrument.js";
 import type { RscPayload } from "./types.js";
 import {
   hasBodyContent,
@@ -256,7 +257,32 @@ export async function executeServerAction<TEnv>(
  * provide. Redirects are the only non-partial outcome and are handled via
  * X-RSC-Redirect headers before Flight deserialization.
  */
-export async function revalidateAfterAction<TEnv>(
+export function revalidateAfterAction<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+  url: URL,
+  handleStore: ReturnType<typeof requireRequestContext>["_handleStore"],
+  continuation: ActionContinuation,
+): Promise<Response> {
+  // Instrument the action-revalidation render through the unified phase API,
+  // exactly like a normal navigation render (handleRscRendering). It records
+  // "render:total" AND opens "rango.render" from one boundary covering
+  // matchPartial -> serialize, so the revalidation loaders' rango.loader spans
+  // nest under a rango.render parent instead of dangling at the request root.
+  return observeStreamingPhase(PHASES.render, () =>
+    revalidateAfterActionInner(
+      ctx,
+      request,
+      env,
+      url,
+      handleStore,
+      continuation,
+    ),
+  );
+}
+
+async function revalidateAfterActionInner<TEnv>(
   ctx: HandlerContext<TEnv>,
   request: Request,
   env: TEnv,
@@ -335,13 +361,8 @@ export async function revalidateAfterAction<TEnv>(
   });
   const rscSerializeDur = performance.now() - renderStart;
   // This measures synchronous stream creation, not end-to-end stream consumption.
+  // render:total is recorded by the observePhase wrapper in revalidateAfterAction.
   appendMetric(metricsStore, "rsc-serialize", renderStart, rscSerializeDur);
-  appendMetric(
-    metricsStore,
-    "render:total",
-    renderStart,
-    performance.now() - renderStart,
-  );
 
   return createResponseWithMergedHeaders(rscStream, {
     status: actionStatus,

package/src/segment-system.tsx

@@ -504,7 +504,10 @@ export async function renderSegments(
 // slot name is user-controlled (`@${string}`) and may contain an uppercase "D"
 // (e.g. "@Detail"). Strip from the first `D<index>.` separator so the slot name
 // is preserved; splitting on a bare "D" mis-cut "@Detail" to "@" and silently
-// dropped the loader's data.
+// dropped the loader's data. The first-`D<index>.` strip is only correct because
+// slot names cannot contain "." -- assertValidSlotName (route-definition/
+// dsl-helpers.ts) rejects a "." at definition time, so a name like "@D3.foo"
+// (which WOULD mis-cut here) can never reach this function.
 function loaderParentId(loaderSegmentId: string): string {
   return loaderSegmentId.replace(/D\d+\..*$/, "");
 }

package/src/server/request-context.ts

@@ -41,11 +41,13 @@ import {
 } from "./handle-store.js";
 import { isHandle } from "../handle.js";
 import { withDefer } from "../defer.js";
-import { track, type MetricsStore } from "./context.js";
+import { type MetricsStore } from "./context.js";
+import { observePhase, PHASES } from "../router/instrument.js";
 import { getFetchableLoader } from "./fetchable-loader-store.js";
 import type { SegmentCacheStore } from "../cache/types.js";
 import type { Theme, ResolvedThemeConfig } from "../theme/types.js";
 import type { ExecutionContext, RequestScope } from "../types/request-scope.js";
+import type { ResolvedTracing } from "../router/tracing.js";
 import { fireAndForgetWaitUntil } from "../types/request-scope.js";
 import { THEME_COOKIE } from "../theme/constants.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
@@ -363,6 +365,19 @@ export interface RequestContext<
   /** @internal Request-scoped performance metrics store */
   _metricsStore?: MetricsStore;
 
+  /** @internal Resolved platform phase-span tracing for this request (Cloudflare or OTel) */
+  _tracing?: ResolvedTracing;
+
+  /**
+   * @internal Drain barrier for streaming phase spans. The request phase
+   * (observeRequestPhase) sets this to a promise that resolves when the final
+   * response body finishes draining; the streaming inner phases
+   * (observeStreamingPhase: middleware/render/ssr) await it so their span AND
+   * perf metric end at body-drain rather than at stream construction. Undefined
+   * when neither the perf store nor tracing is active (no instrumentation).
+   */
+  _finalDrain?: Promise<void>;
+
   /** @internal Router basename for this request (used by redirect()) */
   _basename?: string;
 
@@ -1114,10 +1129,13 @@ export function createUseFunction<TEnv>(
       },
     };
 
-    const doneLoader = track(`loader:${loader.$$id}`, 2);
-    const promise = Promise.resolve(loaderFn(loaderCtx)).finally(() => {
-      doneLoader();
-    });
+    // Meter through the same unified phase API as the loader-resolution funnel
+    // (observePhase), so a loader resolved via this base request-context ctx.use
+    // co-emits the "loader:<id>" perf metric AND the "rango.loader" span — no
+    // drift between the two ctx.use implementations.
+    const promise = observePhase(PHASES.loader(loader.$$id), () =>
+      Promise.resolve(loaderFn(loaderCtx)),
+    );
 
     loaderPromises.set(loader.$$id, promise);