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

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

package/src/cloudflare/tracing.ts

@@ -26,16 +26,13 @@
  * recorded is governed by the `observability`/tracing block in wrangler config.
  *
  * 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.
+ * (or promise) settles. For the streaming phases (request/render/ssr) that is at
+ * stream CONSTRUCTION, not body-drain. Instrumentation is best-effort and never
+ * wraps or buffers the response body, so it cannot regress streaming or latency.
+ * A loader/Suspense child that resolves mid-stream therefore keeps a rango.loader
+ * span that can extend past its render parent — overlapping spans are valid. Uses
+ * only the typed enterSpan API; spans bound work up to stream-handoff, matching
+ * the co-emitted perf metric.
  */
 
 import { _getRequestContext } from "../server/request-context.js";

package/src/router/instrument.ts

@@ -42,9 +42,7 @@ import {
   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
@@ -208,11 +206,15 @@ function recordPhaseMetric(
  * 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).
+ * This is the ONLY phase primitive: every phase (request/middleware/action/
+ * loader/handler/render/ssr) is construction-bound — the span and metric settle
+ * when fn's own work completes (for the streaming phases, when the RSC/HTML
+ * stream is constructed, NOT when the body drains). Instrumentation is strictly
+ * best-effort: it never wraps or buffers the response and adds no work on the
+ * streaming path, so it cannot regress response latency or streaming. A loader
+ * that resolves while the body streams therefore keeps a rango.loader span that
+ * may extend past its render parent — overlapping spans are valid; the loader
+ * really did take that long.
  *
  * Reads the metrics store + tracing off the RequestContext ALS, which is active
  * for the WHOLE request — contrast observeEvent, which reads the RouterContext
@@ -231,12 +233,25 @@ export function observePhase<T>(
 
   // Attributes only land on a real span, so skip the wrapper when only the perf
   // surface is active (traceSpan would apply them to NOOP_TRACE_SPAN for nothing).
+  // `lazyAttributes` resolve AFTER fn runs (e.g. rango.route, known post-match).
   const attributes = spec.attributes;
+  const lazy = spec.lazyAttributes;
   const wrapped: (span: TraceSpan) => T =
-    attributes && tracing
+    (attributes || lazy) && tracing
       ? (span) => {
-          applyAttributes(span, attributes);
-          return fn(span);
+          if (attributes) applyAttributes(span, attributes);
+          const out = fn(span);
+          if (!lazy) return out;
+          if (out instanceof Promise) {
+            return out.then((value) => {
+              const late = lazy();
+              if (late) applyAttributes(span, late);
+              return value;
+            }) as T;
+          }
+          const late = lazy();
+          if (late) applyAttributes(span, late);
+          return out;
         }
       : fn;
 
@@ -254,195 +269,6 @@ export function observePhase<T>(
   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
-    }
-    // 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
-  };
-
-  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,
-  );
-}
-
 /**
  * Emit one discrete telemetry event (the event-shaped counterpart to
  * observePhase). Resolves the sink from the active router context and stamps the

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 { observeStreamingPhase, PHASES } from "./instrument.js";
+import { observePhase, 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 observeStreamingPhase(PHASES.middleware(metricLabel), () =>
+      result = await observePhase(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 observeStreamingPhase(PHASES.middleware(label), () =>
+      result = await observePhase(PHASES.middleware(label), () =>
         middleware(ctx, guardedNext),
       );
     } catch (error) {

package/src/router/tracing.ts

@@ -31,18 +31,15 @@
  * 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
- * 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.
+ * 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.

package/src/rsc/handler.ts

@@ -82,12 +82,7 @@ import {
   appendMetric,
   buildMetricsTiming,
 } from "../router/metrics.js";
-import {
-  observePhase,
-  observeRequestPhase,
-  observeEvent,
-  PHASES,
-} from "../router/instrument.js";
+import { observePhase, observeEvent, PHASES } from "../router/instrument.js";
 import {
   startSSRSetup,
   getSSRSetup,
@@ -501,14 +496,12 @@ 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. 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.
+    // it. Construction-bound: the span ends when the Response is built, never
+    // wrapping the streamed body. metric:false — handler:total is metered
+    // directly below (a grand total incl. the pre-context bootstrap timings).
+    // When tracing is off this is a direct pass-through.
     return runWithRequestContext(requestContext, () =>
-      observeRequestPhase(PHASES.request, async (span) => {
+      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

package/src/rsc/rsc-rendering.ts

@@ -11,7 +11,7 @@ import {
   setRequestContextParams,
 } from "../server/request-context.js";
 import { appendMetric } from "../router/metrics.js";
-import { observeStreamingPhase, PHASES } from "../router/instrument.js";
+import { observePhase, 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 observeStreamingPhase(PHASES.render, () =>
+  return observePhase(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 observeStreamingPhase(PHASES.ssr, () =>
+  const htmlStream = await observePhase(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 { observeStreamingPhase, PHASES } from "../router/instrument.js";
+import { observePhase, 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 observeStreamingPhase(PHASES.render, () =>
+  return observePhase(PHASES.render, () =>
     revalidateAfterActionInner(
       ctx,
       request,

package/src/server/request-context.ts

@@ -368,16 +368,6 @@ 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;