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

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.127",
+  version: "0.0.0-experimental.128",
   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.127",
+  "version": "0.0.0-experimental.128",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/skills/observability/SKILL.md

@@ -95,6 +95,31 @@ const router = createRouter({
 });
 ```
 
+On **Cloudflare Workers**, use `createCloudflareTracing` for the `tracing` slot
+instead — it emits the same phases as native Cloudflare custom spans (in the
+Workers trace waterfall, next to the automatic KV/D1/fetch spans), with no
+`@opentelemetry/api` dependency:
+
+```typescript
+import { createRouter } from "@rangojs/router";
+import { createCloudflareTracing } from "@rangojs/router/cloudflare";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  tracing: createCloudflareTracing(), // all phases on by default
+  // tracing: createCloudflareTracing({ spans: { ssr: false } }), // toggle phases
+});
+```
+
+Both factories return a `RouterTracingConfig` for the same `tracing` slot;
+`telemetry` stays independent (events only, no phase spans). Phase spans:
+`rango.request`, `rango.middleware`, `rango.action`, `rango.loader`,
+`rango.render`, `rango.ssr` — the same phases the `debugPerformance` timeline
+shows, co-emitted from one site. Off-platform (no Cloudflare tracing destination
+/ no OTel SDK) every span call is a transparent pass-through, so the request
+behaves as if tracing were off.
+
 Custom sinks implement `emit(event)`:
 
 ```typescript
@@ -112,7 +137,8 @@ const router = createRouter({
 ```
 
 Events include `request.start/end/error`, `loader.start/end/error`,
-`handler.error`, `cache.decision`, and `revalidation.decision`.
+`handler.error`, `cache.decision`, `revalidation.decision`, `request.timeout`,
+and `request.origin-rejected`.
 
 ## Debugging revalidation and stale data
 

package/skills/router-setup/SKILL.md

@@ -488,6 +488,18 @@ const router = createRouter({
 });
 ```
 
+```typescript
+// On Cloudflare Workers, swap the tracing factory for native custom spans
+// (no @opentelemetry/api dependency); the telemetry slot is unchanged.
+import { createCloudflareTracing } from "@rangojs/router/cloudflare";
+
+const router = createRouter({
+  document: Document,
+  urls: urlpatterns,
+  tracing: createCloudflareTracing(), // { spans: { ssr: false } } to toggle phases
+});
+```
+
 ```typescript
 // Custom sink
 const router = createRouter({

package/src/cloudflare/tracing.ts

@@ -25,14 +25,17 @@
  * request behaves exactly as if tracing were off. Whether spans are actually
  * recorded is governed by the `observability`/tracing block in wrangler config.
  *
- * Span duration note: a phase span ends when its callback's returned value (or
- * promise) settles, which for the streaming phases (request/render/ssr) is when
- * the Response or HTML/RSC stream is *constructed*, not when the body finishes
- * draining. Loader/Suspense work that settles while the body streams therefore
- * extends past the parent span's end, and platform spans emitted during that
- * drain (deferred SSR, waitUntil-scheduled cache writes) are siblings of the
- * automatic request span rather than children of rango.*. Phase spans bound
- * setup-to-stream-handoff; they are not a full request-duration measure.
+ * Span duration note: enterSpan ends a span when its callback's returned value
+ * (or promise) settles. The streaming phases (request/render/ssr/middleware) are
+ * wrapped (in instrument.ts) so their callback awaits the response body's drain
+ * before settling — the constructed Response is handed to the client immediately,
+ * but the callback (hence the SPAN) stays open until the body finishes draining.
+ * So these spans cover the full streamed request and loader/Suspense children
+ * that resolve mid-stream nest under a still-open parent. This uses only the
+ * typed enterSpan API; no startActiveSpan/end. The perf METRICS (render:total,
+ * the middleware own-time, handler:total) stay construction-bound — they ship in
+ * the Server-Timing header, flushed before drain — so a span reads at least as
+ * long as its same-named metric, the difference being post-construction streaming.
  */
 
 import { _getRequestContext } from "../server/request-context.js";

package/src/router/instrument.ts

@@ -35,13 +35,16 @@ import { isAutoGeneratedRouteName } from "../route-name.js";
 import { getRouterContext } from "./router-context.js";
 import { resolveSink, safeEmit, type TelemetryEvent } from "./telemetry.js";
 import { appendMetric } from "./metrics.js";
+import { type MetricsStore } from "../server/context.js";
 import {
   NOOP_TRACE_SPAN,
   traceSpan,
   runThenSettle,
   type TracePhase,
   type TraceSpan,
+  type ResolvedTracing,
 } from "./tracing.js";
+import { isWebSocketUpgradeResponse } from "../response-utils.js";
 
 /**
  * Perf-metric boundary for a phase, or `false` for span-only. `false` means the
@@ -138,6 +141,29 @@ export const PHASES = {
   } as PhaseSpec,
 } as const;
 
+/** Apply a phase spec's static attributes to a span (the no-op span ignores them). */
+function applyAttributes(
+  span: TraceSpan,
+  attributes: Record<string, string | number | boolean>,
+): void {
+  for (const key in attributes) span.setAttribute(key, attributes[key]);
+}
+
+/**
+ * Record a phase's perf metric for the interval [start, now]. The label may be
+ * lazy (resolved here, e.g. render:total needs the route name that match sets
+ * partway through the wrapped work).
+ */
+function recordPhaseMetric(
+  store: MetricsStore,
+  metric: Exclude<PhaseMetric, false>,
+  start: number,
+): void {
+  const label =
+    typeof metric.label === "function" ? metric.label() : metric.label;
+  appendMetric(store, label, start, performance.now() - start, metric.depth);
+}
+
 /**
  * Instrument one unit of work: open its span AND (unless `metric: false`) record
  * its perf metric, from a single wrap site. fn is invoked exactly once with the
@@ -145,6 +171,12 @@ export const PHASES = {
  * unchanged and thrown errors / rejected promises propagate unchanged. When fn
  * returns a promise both the metric duration and the span end when it settles.
  *
+ * This is the boundary for NON-streaming phases (action, loader): both the span
+ * and the metric settle when their own work completes. Streaming phases (request,
+ * middleware, render, ssr) use observeRequestPhase / observeStreamingPhase, where
+ * the SPAN is held open until body-drain (valid tree) while the perf metric is
+ * still recorded at construction (Server-Timing parity).
+ *
  * Reads the metrics store + tracing off the RequestContext ALS, which is active
  * for the WHOLE request — contrast observeEvent, which reads the RouterContext
  * ALS (entered later, during match).
@@ -166,7 +198,7 @@ export function observePhase<T>(
   const wrapped: (span: TraceSpan) => T =
     attributes && tracing
       ? (span) => {
-          for (const key in attributes) span.setAttribute(key, attributes[key]);
+          applyAttributes(span, attributes);
           return fn(span);
         }
       : fn;
@@ -182,13 +214,191 @@ export function observePhase<T>(
   // failed loader/render still shows its timing in the perf report (parity with
   // the old track().finally() path it replaced).
   const start = performance.now();
-  return runThenSettle(runSpan, () => {
-    // The label may be lazy (resolved at record time, e.g. render:total needs the
-    // route name that match sets partway through the wrapped work).
-    const label =
-      typeof metric.label === "function" ? metric.label() : metric.label;
-    appendMetric(store, label, start, performance.now() - start, metric.depth);
+  return runThenSettle(runSpan, () => recordPhaseMetric(store, metric, start));
+}
+
+/**
+ * Re-stream `response`'s body through a pass-through that fires `onDrain` exactly
+ * once when the body finishes — on natural end, a stream error, or a client
+ * cancel (so a span can never leak on an aborted response). A bodyless response
+ * fires immediately. Only used while instrumentation is active, so the per-chunk
+ * relay cost never touches an untraced request.
+ */
+function instrumentResponseDrain(
+  response: Response,
+  onDrain: () => void,
+): Response {
+  // WS-upgrade responses (status 101 / workerd `webSocket` property) must never
+  // be reconstructed: `new Response(body, { status: 101 })` throws and a copy
+  // drops the non-standard webSocket handoff (the invariant every other Response
+  // reconstruction site honors). A bodyless response has nothing to drain.
+  const source = response.body;
+  if (!source || isWebSocketUpgradeResponse(response)) {
+    onDrain();
+    return response;
+  }
+  let fired = false;
+  const fire = (): void => {
+    if (fired) return;
+    fired = true;
+    onDrain();
+  };
+  const reader = source.getReader();
+  const wrapped = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const { done, value } = await reader.read();
+        if (done) {
+          controller.close();
+          fire();
+          return;
+        }
+        controller.enqueue(value);
+      } catch (error) {
+        controller.error(error);
+        fire();
+      }
+    },
+    cancel(reason) {
+      fire();
+      return reader.cancel(reason);
+    },
+  });
+  return new Response(wrapped, response);
+}
+
+/**
+ * Shared engine for the streaming phases (request, middleware, render, ssr). It
+ * opens the span, runs fn, records the phase's perf metric at CONSTRUCTION (so it
+ * still reaches the Server-Timing header / [RSC Perf] table, both built before
+ * the body drains), hands the constructed value to the caller via a side channel
+ * (streaming preserved), then holds the span open until `drain` resolves. The
+ * SPAN therefore ends at body-drain — keeping the trace tree valid (a loader
+ * child that resolves mid-stream ends before its parent) — while the perf metric
+ * stays the construction work-time. `onDeliver` lets the request phase instrument
+ * the final body before handing it back; `onError` lets it release the barrier on
+ * failure. Fire-and-forget: the value reaches the caller via the returned
+ * promise, so the span promise's rejection is swallowed (already surfaced there).
+ */
+function runDrainBoundPhase<R>(
+  spec: PhaseSpec,
+  fn: (span: TraceSpan) => R | Promise<R>,
+  tracing: ResolvedTracing | undefined,
+  store: MetricsStore | undefined,
+  drain: Promise<void>,
+  onDeliver: (value: R) => R,
+  onError?: () => void,
+): Promise<R> {
+  let deliver!: (value: R) => void;
+  let reject!: (error: unknown) => void;
+  const delivered = new Promise<R>((res, rej) => {
+    deliver = res;
+    reject = rej;
   });
+
+  const start = performance.now();
+  const attributes = spec.attributes;
+  const metric = spec.metric;
+  const record = (): void => {
+    if (store && metric !== false) recordPhaseMetric(store, metric, start);
+  };
+  const spanCallback = async (span: TraceSpan): Promise<void> => {
+    if (attributes && tracing) applyAttributes(span, attributes);
+    let value: R;
+    try {
+      value = await fn(span);
+    } catch (error) {
+      record(); // a failed phase still shows its (construction) timing
+      onError?.();
+      reject(error);
+      throw error; // settle the span with the error, at construction
+    }
+    record(); // construction-bound metric, before the response/header is built
+    deliver(onDeliver(value));
+    await drain; // hold the span open until the response body drains
+  };
+
+  traceSpan(tracing, spec.tracePhase, spec.spanName, spanCallback).catch(
+    () => {},
+  );
+  return delivered;
+}
+
+/**
+ * The request phase (rango.request, metric:false). Owns the drain barrier: it
+ * runs fn to construct the final Response, instruments that Response's body so
+ * the barrier resolves at drain, hands the Response to the caller immediately
+ * (streaming preserved), and holds the span open until the body drains. Every
+ * streaming inner phase awaits the same barrier (via observeStreamingPhase), so
+ * the request/middleware/render/ssr chain ends at body-drain together and the
+ * trace tree is valid (no child span outlives its parent). The perf metrics
+ * (render:total, …) are recorded at construction so they still reach the
+ * Server-Timing header; only the SPANS are drain-bound. ctx.waitUntil holds the
+ * worker alive until drain so the span end runs. Pass-through when no surface is
+ * active.
+ */
+export function observeRequestPhase(
+  spec: PhaseSpec,
+  fn: (span: TraceSpan) => Promise<Response>,
+): Promise<Response> {
+  const reqCtx = _getRequestContext();
+  const store = reqCtx?._metricsStore;
+  const tracing = reqCtx?._tracing;
+
+  if ((!store && !tracing) || !reqCtx) return fn(NOOP_TRACE_SPAN);
+
+  let resolveDrain!: () => void;
+  const finalDrain = new Promise<void>((resolve) => {
+    resolveDrain = resolve;
+  });
+  reqCtx._finalDrain = finalDrain;
+
+  // Keep the worker alive until the body drains, so the drain-bound span end
+  // (and the inner phases' settle) runs before the runtime can reclaim it.
+  const ec = reqCtx.executionContext;
+  if (typeof ec?.waitUntil === "function") ec.waitUntil(finalDrain);
+
+  return runDrainBoundPhase<Response>(
+    spec,
+    fn,
+    tracing,
+    store,
+    finalDrain,
+    (response) => instrumentResponseDrain(response, resolveDrain),
+    resolveDrain, // release the barrier if fn fails before constructing a body
+  );
+}
+
+/**
+ * A streaming inner phase (rango.middleware / render / ssr). Its SPAN settles
+ * when the request's final response body drains (the barrier owned by
+ * observeRequestPhase), not when fn returns the constructed stream — so
+ * loader/Suspense children that resolve mid-stream nest under a still-open
+ * parent. fn's result is delivered at construction (streaming preserved) and the
+ * perf metric is recorded at construction (Server-Timing parity). Falls back to
+ * observePhase (construction-bound span) when there is no barrier — a
+ * non-streaming request, or instrumentation off.
+ */
+export function observeStreamingPhase<R>(
+  spec: PhaseSpec,
+  fn: (span: TraceSpan) => R | Promise<R>,
+): Promise<R> {
+  const reqCtx = _getRequestContext();
+  const store = reqCtx?._metricsStore;
+  const tracing = reqCtx?._tracing;
+  const finalDrain = reqCtx?._finalDrain;
+
+  if ((!store && !tracing) || !finalDrain) {
+    return Promise.resolve(observePhase(spec, fn));
+  }
+  return runDrainBoundPhase<R>(
+    spec,
+    fn,
+    tracing,
+    store,
+    finalDrain,
+    (value) => value,
+  );
 }
 
 /**

package/src/router/middleware.ts

@@ -19,7 +19,7 @@ import {
 } from "../redirect-origin.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 import { appendMetric, createMetricsStore } from "./metrics.js";
-import { observePhase, PHASES } from "./instrument.js";
+import { observeStreamingPhase, PHASES } from "./instrument.js";
 import { stripInternalParams } from "./handler-context.js";
 import { isWebSocketUpgradeResponse } from "../response-utils.js";
 
@@ -487,7 +487,7 @@ export async function executeMiddleware<TEnv>(
     // when neither surface is active.
     let result: Response | void;
     try {
-      result = await observePhase(PHASES.middleware(metricLabel), () =>
+      result = await observeStreamingPhase(PHASES.middleware(metricLabel), () =>
         entry.handler(ctx, wrappedNext),
       );
     } catch (error) {
@@ -664,7 +664,7 @@ export async function executeInterceptMiddleware<TEnv>(
 
     let result: Response | void;
     try {
-      result = await observePhase(PHASES.middleware(label), () =>
+      result = await observeStreamingPhase(PHASES.middleware(label), () =>
         middleware(ctx, guardedNext),
       );
     } catch (error) {

package/src/router/tracing.ts

@@ -29,13 +29,18 @@
  * 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.
+ * Streaming-phase span lifetime: a span ends when its callback's value (or
+ * promise) settles. The streaming phases (request, middleware, render, ssr) are
+ * wrapped by observeRequestPhase / observeStreamingPhase (instrument.ts), whose
+ * callback hands the constructed Response/stream to the caller immediately
+ * (streaming preserved) but then awaits a request-scoped drain barrier, so the
+ * SPAN ends when the response BODY finishes draining, not at stream construction.
+ * That keeps span durations covering the real streamed work and the trace tree
+ * valid: a loader/Suspense child that resolves while the body streams ends before
+ * its now-drain-bound parent. The co-emitted perf METRIC (render:total, …) is
+ * still recorded at construction — it ships in the Server-Timing header, flushed
+ * before the body drains — so a streaming span legitimately reads longer than its
+ * same-named metric by the time the body spent streaming after construction.
  *
  * Both shipped runners (Cloudflare, OTel) keep the core agnostic: the
  * platform-specific bridge lives at the edge behind the SpanRunner contract.

package/src/rsc/handler.ts

@@ -82,7 +82,12 @@ import {
   appendMetric,
   buildMetricsTiming,
 } from "../router/metrics.js";
-import { observePhase, observeEvent, PHASES } from "../router/instrument.js";
+import {
+  observePhase,
+  observeRequestPhase,
+  observeEvent,
+  PHASES,
+} from "../router/instrument.js";
 import {
   startSSRSetup,
   getSSRSetup,
@@ -496,11 +501,14 @@ export function createRSCHandler<
     // 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.
+    // 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, () =>
-      observePhase(PHASES.request, async (span) => {
+      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

package/src/rsc/rsc-rendering.ts

@@ -11,7 +11,7 @@ import {
   setRequestContextParams,
 } from "../server/request-context.js";
 import { appendMetric } from "../router/metrics.js";
-import { observePhase, PHASES } from "../router/instrument.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";
@@ -36,7 +36,7 @@ export function handleRscRendering<TEnv>(
   // 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 observePhase(PHASES.render, () =>
+  return observeStreamingPhase(PHASES.render, () =>
     handleRscRenderingInner(
       ctx,
       request,
@@ -248,7 +248,7 @@ async function handleRscRenderingInner<TEnv>(
 
   // ssr-render-html metric + rango.ssr span from one boundary. render:total is
   // recorded by the observePhase wrapper around this function.
-  const htmlStream = await observePhase(PHASES.ssr, () =>
+  const htmlStream = await observeStreamingPhase(PHASES.ssr, () =>
     ssrModule.renderHTML(rscStream, {
       nonce,
       streamMode,

package/src/rsc/server-action.ts

@@ -20,7 +20,7 @@ import {
   setRequestContextParams,
 } from "../server/request-context.js";
 import { appendMetric } from "../router/metrics.js";
-import { observePhase, PHASES } from "../router/instrument.js";
+import { observeStreamingPhase, PHASES } from "../router/instrument.js";
 import type { RscPayload } from "./types.js";
 import {
   hasBodyContent,
@@ -270,7 +270,7 @@ export function revalidateAfterAction<TEnv>(
   // "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 observePhase(PHASES.render, () =>
+  return observeStreamingPhase(PHASES.render, () =>
     revalidateAfterActionInner(
       ctx,
       request,

package/src/server/request-context.ts

@@ -368,6 +368,16 @@ export interface RequestContext<
   /** @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;