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

package/dist/vite/index.js

@@ -2133,7 +2133,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.128",
+  version: "0.0.0-experimental.129",
   description: "Django-inspired RSC router with composable URL patterns",
   keywords: [
     "react",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rangojs/router",
-  "version": "0.0.0-experimental.128",
+  "version": "0.0.0-experimental.129",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/src/cloudflare/tracing.ts

@@ -2,9 +2,9 @@
  * Cloudflare custom-spans integration.
  *
  * Bridges the router's performance phases (request, middleware, action,
- * loaders, render, ssr) onto Cloudflare Workers custom spans so they show up in the
- * trace waterfall and OpenTelemetry exports next to the platform's automatic
- * spans (KV reads, D1 queries, fetch calls), with correct parent-child nesting.
+ * loaders, handler, render, ssr) onto Cloudflare Workers custom spans so they show
+ * up in the trace waterfall and OpenTelemetry exports next to the platform's
+ * automatic spans (KV reads, D1 queries, fetch calls), with correct nesting.
  *
  * Usage (Cloudflare preset only):
  *
@@ -95,8 +95,8 @@ const cloudflareSpanRunner: SpanRunner = (name, fn) => {
 /**
  * Create the tracing config for a Cloudflare router. Pass the result to
  * `createRouter({ tracing })`. Spans are emitted for the request, middleware,
- * action, loaders, render, and ssr phases; pass `spans` to turn individual
- * phases off.
+ * action, loaders, handler, render, and ssr phases; pass `spans` to turn
+ * individual phases off.
  *
  * @see createOTelTracing (`@rangojs/router`) for the same slot on any platform
  *   with an OpenTelemetry SDK.

package/src/router/instrument.ts

@@ -66,6 +66,25 @@ export interface PhaseSpec {
   spanName: string;
   /** Span attributes set automatically when the span opens. */
   attributes?: Record<string, string | number | boolean>;
+  /**
+   * Span attributes resolved AFTER the wrapped work runs (so they can read state
+   * that only exists once the work is underway, e.g. the matched route name).
+   * Applied for streaming phases once fn has constructed its value. Return
+   * undefined to add nothing.
+   */
+  lazyAttributes?: () => Record<string, string | number | boolean> | undefined;
+}
+
+/**
+ * The matched route name for the current request, or undefined when there is no
+ * named route (unmatched / auto-generated). Shared by the render phase's metric
+ * label and its rango.route span attribute so the two can't disagree.
+ */
+function currentRouteName(): string | undefined {
+  const routeName = _getRequestContext()?._routeName;
+  return routeName && !isAutoGeneratedRouteName(routeName)
+    ? routeName
+    : undefined;
 }
 
 /**
@@ -115,6 +134,18 @@ export const PHASES = {
     attributes: { "rango.loader_id": id },
   }),
 
+  /** One segment route/layout handler execution (the component/handler that
+   * produces a segment). Span only — the perf metric (handler:<id>) is owned by
+   * the legacy track() at the same call site, so observePhase here adds the
+   * rango.handler span without double-recording. `id` is the segment id, carried
+   * as the rango.segment_id attribute to match the handler:<id> perf row. */
+  handler: (id: string): PhaseSpec => ({
+    metric: false,
+    tracePhase: "handler",
+    spanName: "rango.handler",
+    attributes: { "rango.segment_id": id },
+  }),
+
   /** Whole render phase: match + serialize + SSR. The metric label is resolved
    * lazily at record time (after match has set the route name) so the perf
    * timeline shows WHICH route rendered: `render:total:<routeName>`, falling back
@@ -122,14 +153,20 @@ export const PHASES = {
   render: {
     metric: {
       label: () => {
-        const routeName = _getRequestContext()?._routeName;
-        return routeName && !isAutoGeneratedRouteName(routeName)
-          ? `render:total:${routeName}`
-          : "render:total";
+        const routeName = currentRouteName();
+        return routeName ? `render:total:${routeName}` : "render:total";
       },
     },
     tracePhase: "render",
     spanName: "rango.render",
+    // Tag the render span with the matched route so the Cloudflare/OTel waterfall
+    // shows WHICH route rendered (rango.render + rango.route=index), resolved
+    // after match has run. Kept an attribute (not baked into the span name) so the
+    // span name stays low-cardinality and aggregatable across routes.
+    lazyAttributes: () => {
+      const routeName = currentRouteName();
+      return routeName ? { "rango.route": routeName } : undefined;
+    },
   } as PhaseSpec,
 
   /** SSR HTML render from the RSC stream. Colon-delimited like the other ssr:*
@@ -313,6 +350,11 @@ function runDrainBoundPhase<R>(
       reject(error);
       throw error; // settle the span with the error, at construction
     }
+    // Late attributes (e.g. rango.route) — resolved now that the work has run,
+    // so they can read state like the matched route name that match sets midway.
+    const lazy =
+      tracing && spec.lazyAttributes ? spec.lazyAttributes() : undefined;
+    if (lazy) applyAttributes(span, lazy);
     record(); // construction-bound metric, before the response/header is built
     deliver(onDeliver(value));
     await drain; // hold the span open until the response body drains

package/src/router/segment-resolution/fresh.ts

@@ -30,6 +30,7 @@ import {
 import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
 import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
+import { observePhase, PHASES } from "../instrument.js";
 import {
   track,
   RangoContext,
@@ -258,7 +259,9 @@ export async function resolveSegment<TEnv>(
         !context.build && entry.liveHandler ? entry.liveHandler : entry.handler;
       const doneRouteHandler = track(`handler:${entry.id}`, 2);
       if (entry.loading) {
-        const result = handleHandlerResult(handler(context));
+        const result = handleHandlerResult(
+          observePhase(PHASES.handler(entry.id), () => handler(context)),
+        );
         if (result instanceof Promise) {
           warnOnStreamedResponse(result, entry.id);
           result.finally(doneRouteHandler).catch(() => {});
@@ -280,7 +283,9 @@ export async function resolveSegment<TEnv>(
           component = result;
         }
       } else {
-        component = handleHandlerResult(await handler(context));
+        component = handleHandlerResult(
+          await observePhase(PHASES.handler(entry.id), () => handler(context)),
+        );
         doneRouteHandler();
       }
     }
@@ -505,7 +510,11 @@ export async function resolveParallelEntry<TEnv>(
         parallelEntry.loading !== undefined && parallelEntry.loading !== false;
       if (hasLoadingFallback) {
         const result =
-          typeof handler === "function" ? handler(context) : handler;
+          typeof handler === "function"
+            ? observePhase(PHASES.handler(`${parallelEntry.id}.${slot}`), () =>
+                handler(context),
+              )
+            : handler;
         if (result instanceof Promise) {
           result.finally(doneParallelHandler).catch(() => {});
           const tracked = deps.trackHandler(result, {
@@ -527,7 +536,12 @@ export async function resolveParallelEntry<TEnv>(
         }
       } else {
         component =
-          typeof handler === "function" ? await handler(context) : handler;
+          typeof handler === "function"
+            ? await observePhase(
+                PHASES.handler(`${parallelEntry.id}.${slot}`),
+                () => handler(context),
+              )
+            : handler;
         doneParallelHandler();
       }
     }

package/src/router/segment-resolution/helpers.ts

@@ -23,6 +23,7 @@ import type { ResolvedSegment, ErrorInfo, HandlerContext } from "../../types";
 import type { SegmentResolutionDeps } from "../types.js";
 import { debugLog } from "../logging.js";
 import { tryStaticLookup } from "./static-store.js";
+import { observePhase, PHASES } from "../instrument.js";
 import type { TelemetrySink } from "../telemetry.js";
 import { resolveSink, safeEmit, getRequestId } from "../telemetry.js";
 
@@ -130,11 +131,15 @@ export async function resolveLayoutComponent<TEnv>(
   entry: EntryData,
   context: HandlerContext<any, TEnv>,
 ): Promise<ReactNode> {
-  const component = await tryStaticHandler(entry, entry.shortCode);
-  if (component !== undefined) return component;
-  return typeof entry.handler === "function"
-    ? handleHandlerResult(await entry.handler(context))
-    : (entry.handler as ReactNode);
+  // rango.handler span for this layout/cache handler (the perf metric is owned
+  // by the track("handler:<id>") at the call site; this adds the span only).
+  return observePhase(PHASES.handler(entry.id), async () => {
+    const component = await tryStaticHandler(entry, entry.shortCode);
+    if (component !== undefined) return component;
+    return typeof entry.handler === "function"
+      ? handleHandlerResult(await entry.handler(context))
+      : (entry.handler as ReactNode);
+  });
 }
 
 // ---------------------------------------------------------------------------

package/src/router/segment-resolution/revalidation.ts

@@ -43,7 +43,7 @@ import {
 } from "./helpers.js";
 import { applyViewTransitionDefault } from "./view-transition-default.js";
 import { getRouterContext } from "../router-context.js";
-import { observeEvent } from "../instrument.js";
+import { observeEvent, observePhase, PHASES } from "../instrument.js";
 import { observeStreamedHandler } from "./streamed-handler-telemetry.js";
 import {
   track,
@@ -793,12 +793,16 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
           ? routeEntry.liveHandler
           : routeEntry.handler;
       if (!routeEntry.loading) {
-        const result = handleHandlerResult(await handler(context));
+        const result = handleHandlerResult(
+          await observePhase(PHASES.handler(entry.id), () => handler(context)),
+        );
         doneHandler();
         return result;
       }
       if (!actionContext) {
-        const result = handleHandlerResult(handler(context));
+        const result = handleHandlerResult(
+          observePhase(PHASES.handler(entry.id), () => handler(context)),
+        );
         if (result instanceof Promise) {
           warnOnStreamedResponse(result, routeEntry.id);
           result.finally(doneHandler).catch(() => {});
@@ -822,7 +826,9 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
       debugLog("segment.action", "resolving action route with awaited value", {
         entryId: entry.id,
       });
-      const actionResult = handleHandlerResult(await handler(context));
+      const actionResult = handleHandlerResult(
+        await observePhase(PHASES.handler(entry.id), () => handler(context)),
+      );
       doneHandler();
       return {
         content: Promise.resolve(actionResult),

package/src/router/tracing.ts

@@ -26,7 +26,9 @@
  * 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
+ * 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).
  *
  * Streaming-phase span lifetime: a span ends when its callback's value (or
@@ -67,6 +69,7 @@ export type TracePhase =
   | "middleware"
   | "action"
   | "loader"
+  | "handler"
   | "render"
   | "ssr";
 
@@ -76,6 +79,7 @@ export interface TracePhaseToggles {
   middleware?: boolean;
   action?: boolean;
   loader?: boolean;
+  handler?: boolean;
   render?: boolean;
   ssr?: boolean;
 }
@@ -112,6 +116,7 @@ const ALL_PHASES_ON: Record<TracePhase, boolean> = {
   middleware: true,
   action: true,
   loader: true,
+  handler: true,
   render: true,
   ssr: true,
 };
@@ -139,6 +144,7 @@ export function resolveTracing(
           middleware: spans.middleware ?? true,
           action: spans.action ?? true,
           loader: spans.loader ?? true,
+          handler: spans.handler ?? true,
           render: spans.render ?? true,
           ssr: spans.ssr ?? true,
         }