@rangojs/router 0.0.0-experimental.142 → 0.0.0-experimental.144

package/src/router/segment-resolution/loader-snapshot.ts

@@ -10,15 +10,20 @@
  *
  *   - elide:   deep-walk the settled container; a SETTLED nested promise baked
  *              its value (physics: it won the quiet window), so it is pinned as
- *              that value; a PENDING nested promise is a hole, replaced by
- *              {@link LOADER_HOLE_MARKER}. The result is promise-free and
+ *              that value wrapped in a SETTLED marker — the wrapper remembers
+ *              "this was a promise" so the overlay can rehydrate the shape; a
+ *              PENDING nested promise is a hole, replaced by
+ *              {@link LOADER_HOLE_KEY}. The result is promise-free and
  *              Flight-serializable.
  *   - overlay: on a HIT the loader runs fresh (only the loader body can mint
  *              the live nested promises), then the recorded container is laid
  *              over it: recorded paths win (they are what the prelude froze),
- *              marker paths take the fresh run's value (the live hole), and
- *              fresh-only paths pass through (they cannot contradict prelude
- *              bytes that never rendered them).
+ *              hole-marker paths take the fresh run's value (the live hole),
+ *              SETTLED-marker paths become Promise.resolve(pinned) — consumers
+ *              wrote use(data.x) against a promise-shaped container, and
+ *              handing them the raw value throws React #438 on every HIT (the
+ *              storefront PDP regression) — and fresh-only paths pass through
+ *              (they cannot contradict prelude bytes that never rendered them).
  */
 
 import { isThenable } from "../../handles/is-thenable.js";
@@ -42,6 +47,37 @@ export function isLoaderHoleMarker(value: unknown): value is LoaderHoleMarker {
   );
 }
 
+/**
+ * Marker wrapping the inlined value of a NESTED promise that settled during
+ * capture. The value baked (physics), but the container key was a promise —
+ * the overlay must hand consumers a Promise.resolve(value), not the raw value,
+ * or an unconditional use(data.x) throws React #438 on every HIT. The ROOT
+ * container is never wrapped: loader-cache overlays against the awaited fresh
+ * container value.
+ */
+export const LOADER_SETTLED_KEY = "$rangoLoaderSettled" as const;
+
+export interface LoaderSettledMarker {
+  [LOADER_SETTLED_KEY]: 1;
+  value: unknown;
+  /**
+   * Present when the pinned subtree contains hole markers. Computed once at
+   * capture (elide already visits every node) so the per-HIT overlay never
+   * rescans the pinned structure to pick its rehydration path.
+   */
+  holes?: 1;
+}
+
+export function isLoaderSettledMarker(
+  value: unknown,
+): value is LoaderSettledMarker {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Record<string, unknown>)[LOADER_SETTLED_KEY] === 1
+  );
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   if (typeof value !== "object" || value === null) return false;
   const proto = Object.getPrototypeOf(value);
@@ -77,17 +113,22 @@ async function probeSettled(
 }
 
 export type ElideResult =
-  | { state: "ok"; value: unknown }
+  | { state: "ok"; value: unknown; hasHole: boolean }
   | { state: "rejected" };
 
 /**
  * Deep-elide a settled bake-lane container for recording. Settled nested
- * promises are inlined (they baked); pending ones become hole markers; a
- * REJECTED nested promise poisons the record (error UI must never bake into a
- * shared shell) — the caller refuses the capture. Only plain objects/arrays are
+ * promises pin their value behind a settled marker (they baked, but consumers
+ * hold a promise-shaped key); pending ones become hole markers; a REJECTED
+ * nested promise poisons the record (error UI must never bake into a shared
+ * shell) — the caller refuses the capture. Only plain objects/arrays are
  * traversed; anything else (Date, Map, class instance) is a pinned leaf.
  * Cycles are cut as pinned references (best effort — Flight rejects true
  * cycles later regardless).
+ *
+ * The ROOT container promise-chain unwraps with NO marker: loader-cache
+ * overlays against the AWAITED fresh container, so the recorded root must be
+ * the unwrapped structure. Everything below it goes through elideNested.
  */
 export async function elideLoaderContainer(
   value: unknown,
@@ -96,37 +137,61 @@ export async function elideLoaderContainer(
   if (isThenable(value)) {
     const probed = await probeSettled(value);
     if (probed.state === "pending") {
-      return { state: "ok", value: { [LOADER_HOLE_KEY]: 1 } };
+      return { state: "ok", value: { [LOADER_HOLE_KEY]: 1 }, hasHole: true };
     }
     if (probed.state === "rejected") return { state: "rejected" };
     return elideLoaderContainer(probed.value, seen);
   }
+  return elideNested(value, seen);
+}
+
+async function elideNested(
+  value: unknown,
+  seen: Set<object>,
+): Promise<ElideResult> {
+  if (isThenable(value)) {
+    const probed = await probeSettled(value);
+    if (probed.state === "pending") {
+      return { state: "ok", value: { [LOADER_HOLE_KEY]: 1 }, hasHole: true };
+    }
+    if (probed.state === "rejected") return { state: "rejected" };
+    const inner = await elideNested(probed.value, seen);
+    if (inner.state === "rejected") return inner;
+    const marker: LoaderSettledMarker = inner.hasHole
+      ? { [LOADER_SETTLED_KEY]: 1, value: inner.value, holes: 1 }
+      : { [LOADER_SETTLED_KEY]: 1, value: inner.value };
+    return { state: "ok", value: marker, hasHole: inner.hasHole };
+  }
 
   if (Array.isArray(value)) {
-    if (seen.has(value)) return { state: "ok", value };
+    if (seen.has(value)) return { state: "ok", value, hasHole: false };
     seen.add(value);
     const out: unknown[] = new Array(value.length);
+    let hasHole = false;
     for (let i = 0; i < value.length; i++) {
-      const r = await elideLoaderContainer(value[i], seen);
+      const r = await elideNested(value[i], seen);
       if (r.state === "rejected") return r;
       out[i] = r.value;
+      hasHole ||= r.hasHole;
     }
-    return { state: "ok", value: out };
+    return { state: "ok", value: out, hasHole };
   }
 
   if (isPlainObject(value)) {
-    if (seen.has(value)) return { state: "ok", value };
+    if (seen.has(value)) return { state: "ok", value, hasHole: false };
     seen.add(value);
     const out: Record<string, unknown> = {};
+    let hasHole = false;
     for (const key of Object.keys(value)) {
-      const r = await elideLoaderContainer(value[key], seen);
+      const r = await elideNested(value[key], seen);
       if (r.state === "rejected") return r;
       out[key] = r.value;
+      hasHole ||= r.hasHole;
     }
-    return { state: "ok", value: out };
+    return { state: "ok", value: out, hasHole };
   }
 
-  return { state: "ok", value };
+  return { state: "ok", value, hasHole: false };
 }
 
 /**
@@ -142,6 +207,22 @@ export function overlayLoaderContainer(
 ): unknown {
   if (isLoaderHoleMarker(recorded)) return fresh;
 
+  if (isLoaderSettledMarker(recorded)) {
+    const pinned = recorded.value;
+    // Deep holes inside a settled container (capture-computed `holes` bit)
+    // need the fresh promise's resolved value to fill them; a fully-pinned
+    // container resolves immediately (the prelude already shows it — never
+    // gate it on fresh latency). A rejecting fresh run degrades holes to
+    // undefined instead of poisoning the pin.
+    if (recorded.holes === 1) {
+      return Promise.resolve(fresh).then(
+        (freshValue) => overlayLoaderContainer(freshValue, pinned),
+        () => overlayLoaderContainer(undefined, pinned),
+      );
+    }
+    return Promise.resolve(overlayLoaderContainer(undefined, pinned));
+  }
+
   if (Array.isArray(recorded)) {
     const freshArr = Array.isArray(fresh) ? fresh : [];
     return recorded.map((item, i) => overlayLoaderContainer(freshArr[i], item));

package/src/router/telemetry-otel.ts

@@ -41,7 +41,7 @@ import { runThenSettle } from "./tracing.js";
 import type {
   RouterTracingConfig,
   SpanRunner,
-  TracePhaseToggles,
+  TracingToggleOptions,
 } from "./tracing.js";
 
 // ---------------------------------------------------------------------------
@@ -92,13 +92,11 @@ const STATUS_ERROR = 2;
 // Tracing adapter: phase spans via startActiveSpan (the `tracing` slot)
 // ---------------------------------------------------------------------------
 
-/** Options for createOTelTracing. */
-export interface OTelTracingOptions {
-  /** Master switch. Defaults to true. */
-  enabled?: boolean;
-  /** Per-phase span toggles. Omitted phases default to enabled. */
-  spans?: TracePhaseToggles;
-}
+/**
+ * Options for createOTelTracing. Alias of the shared {@link TracingToggleOptions}
+ * (`enabled` master switch + per-phase `spans` toggles); the name is public API.
+ */
+export type OTelTracingOptions = TracingToggleOptions;
 
 /**
  * Create the tracing config that maps the router's phases onto OTel spans via

package/src/router/telemetry.ts

@@ -38,6 +38,14 @@ export interface RequestEndEvent extends BaseEvent {
   durationMs: number;
   segmentCount: number;
   cacheHit: boolean;
+  /**
+   * HTTP status when a Response ended the transaction — a thrown-Response
+   * short-circuit (redirect / auth gate carries the Response's status, e.g. 302),
+   * or dispatch()'s final response status. Absent for a normal render completion:
+   * the Response is built after match(), so match()/matchPartial() have no status
+   * to stamp there. Lets a sink split 3xx short-circuits from 2xx completions.
+   */
+  status?: number;
 }
 
 export interface RequestErrorEvent extends BaseEvent {
@@ -320,7 +328,7 @@ export function createConsoleSink(): TelemetrySink {
           break;
         case "request.end":
           console.log(
-            `[telemetry] ${event.type} ${event.method} ${event.pathname} ${event.durationMs.toFixed(1)}ms segments=${event.segmentCount} cache=${event.cacheHit}`,
+            `[telemetry] ${event.type} ${event.method} ${event.pathname} ${event.durationMs.toFixed(1)}ms segments=${event.segmentCount} cache=${event.cacheHit}${event.status !== undefined ? ` status=${event.status}` : ""}`,
           );
           break;
         case "request.error":

package/src/router/tracing.ts

@@ -81,17 +81,26 @@ export interface TracePhaseToggles {
   ssr?: boolean;
 }
 
+/**
+ * The option pair shared by every tracing factory (enabled master switch +
+ * per-phase span toggles). Extended by OTelTracingOptions,
+ * CloudflareTracingOptions, VercelTracingOptions, and RouterTracingConfig so
+ * a phase added to TracePhaseToggles propagates everywhere from one place.
+ */
+export interface TracingToggleOptions {
+  /** Master switch. Defaults to true. */
+  enabled?: boolean;
+  /** Per-phase span toggles. Omitted phases default to enabled. */
+  spans?: TracePhaseToggles;
+}
+
 /**
  * Value passed to `createRouter({ tracing })`. Produced by a platform factory
  * such as `createCloudflareTracing()`.
  */
-export interface RouterTracingConfig {
+export interface RouterTracingConfig extends TracingToggleOptions {
   /** Platform span runner. */
   runner: SpanRunner;
-  /** Master switch. Defaults to true when a config object is provided. */
-  enabled?: boolean;
-  /** Per-phase span toggles. */
-  spans?: TracePhaseToggles;
 }
 
 /**

package/src/router.ts

@@ -420,14 +420,17 @@ export function createRouter<TEnv = any>(
 
   // Wrapper to pass debugPerformance to external createMetricsStore.
   // Also checks per-request flag set by ctx.debugPerformance() in middleware.
+  // With no active request context there is nowhere to hang the store, so return
+  // undefined: an orphan store would collect metrics no reader can reach (nothing
+  // holds it, and appendMetric(undefined, ...) is already a no-op).
   const getMetricsStore = () => {
     const reqCtx = _getRequestContext();
     const enabled = debugPerformance || !!reqCtx?._debugPerformance;
-    if (!enabled) return undefined;
-    if (!reqCtx) {
-      return createMetricsStore(true);
-    }
-    reqCtx._metricsStore ??= createMetricsStore(true);
+    if (!enabled || !reqCtx) return undefined;
+    // Anchor a mid-request store to the true request entry (reqCtx._handlerStart),
+    // not this call's performance.now(); undefined falls back to now() inside
+    // createMetricsStore (metrics.ts).
+    reqCtx._metricsStore ??= createMetricsStore(true, reqCtx._handlerStart);
     return reqCtx._metricsStore;
   };
 
@@ -438,11 +441,6 @@ export function createRouter<TEnv = any>(
   const findNearestNotFoundBoundary = (entry: EntryData | null) =>
     findNotFoundBoundary(entry, defaultNotFoundBoundary);
 
-  // Helper to get handleStore from request context
-  const getHandleStore = (): HandleStore | undefined => {
-    return _getRequestContext()?._handleStore;
-  };
-
   // Track a pending handler promise (non-blocking).
   // Attaches a side-effect .catch() to report streaming handler errors to onError
   // without altering the rejection chain (React's streaming error boundary still handles it).
@@ -453,13 +451,14 @@ export function createRouter<TEnv = any>(
       segmentType?: string;
     },
   ): Promise<T> => {
-    const store = getHandleStore();
+    // One ALS read serves both the store lookup and the onError closure.
+    const reqCtx = _getRequestContext();
+    const store = reqCtx?._handleStore;
     const tracked = store ? store.track(promise) : promise;
 
     // Report streaming handler errors to onError as a side-effect.
     // The rejection still propagates to the RSC stream for client error boundaries.
     // Captures request context eagerly (closure) so the catch handler has full context.
-    const reqCtx = _getRequestContext();
     if (reqCtx && onError) {
       tracked.catch((error) => {
         callOnError(error, "handler", {
@@ -501,8 +500,12 @@ export function createRouter<TEnv = any>(
         ? getRequestId(errorContext.request)
         : undefined
       : undefined;
+    // Derived once here for both the loader.start and loader.end emits (the
+    // loader.error emit uses ctx.loaderName from wrapLoaderWithErrorHandling).
+    const loaderName = telemetrySink
+      ? segmentId.split(".").pop() || "unknown"
+      : "";
     if (telemetrySink) {
-      const loaderName = segmentId.split(".").pop() || "unknown";
       safeEmit(telemetry, {
         type: "loader.start",
         timestamp: loaderStart,
@@ -556,7 +559,6 @@ export function createRouter<TEnv = any>(
 
     // Emit loader.end after the promise settles (fire-and-forget)
     if (telemetrySink) {
-      const loaderName = segmentId.split(".").pop() || "unknown";
       result.then((r) => {
         safeEmit(telemetry, {
           type: "loader.end",
@@ -1008,6 +1010,12 @@ export function createRouter<TEnv = any>(
     // Expose resolved span tracing for the handler (Cloudflare custom spans)
     tracing: resolvedTracing,
 
+    // Expose the raw telemetry sink so handler-level emitters (timeout, origin
+    // rejection, late-handle handler.error) can emit outside the match ALS.
+    // Raw (not the resolveSink no-op wrapper) so router.telemetry stays
+    // undefined when unconfigured and call sites gate on truthiness.
+    telemetry: telemetrySink,
+
     // Expose debug manifest flag for handler
     allowDebugManifest: allowDebugManifestOption,
 

package/src/rsc/handler.ts

@@ -85,7 +85,8 @@ import {
   appendMetric,
   buildMetricsTiming,
 } from "../router/metrics.js";
-import { observePhase, observeEvent, PHASES } from "../router/instrument.js";
+import { observePhase, PHASES } from "../router/instrument.js";
+import { safeEmit, resolveSink, getRequestId } from "../router/telemetry.js";
 import {
   startSSRSetup,
   getSSRSetup,
@@ -246,16 +247,19 @@ export function createRSCHandler<
       metadata: { timeout: true, phase, durationMs },
     });
 
-    observeEvent({
-      type: "request.timeout",
-      timestamp: performance.now(),
-      phase,
-      pathname: url.pathname,
-      routeKey,
-      actionId,
-      durationMs,
-      customHandler: !!router.onTimeout,
-    });
+    if (router.telemetry) {
+      safeEmit(resolveSink(router.telemetry), {
+        type: "request.timeout",
+        timestamp: performance.now(),
+        requestId: getRequestId(request),
+        phase,
+        pathname: url.pathname,
+        routeKey,
+        actionId,
+        durationMs,
+        customHandler: !!router.onTimeout,
+      });
+    }
 
     if (router.onTimeout) {
       try {
@@ -462,6 +466,11 @@ export function createRSCHandler<
       stateCookieName: router.resolvedStateCookieName,
       version,
     });
+    // Thread the true request entry timestamp onto the context so a metrics
+    // store created MID-request (ctx.debugPerformance() / getMetricsStore) anchors
+    // to the real start, not the opt-in moment — phases that began earlier then
+    // report non-negative offsets. Set unconditionally: debug may be enabled later.
+    requestContext._handlerStart = handlerStart;
     if (earlyMetricsStore) {
       requestContext._debugPerformance = true;
       requestContext._metricsStore = earlyMetricsStore;
@@ -569,8 +578,10 @@ export function createRSCHandler<
         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.
+          // created the store mid-request its requestStart is now the threaded
+          // _handlerStart (== handlerStart), so both branches yield the true
+          // request entry; reading the store's own anchor keeps this correct even
+          // if a store ever lands without the threading (falls back to its start).
           const totalStart = earlyMetricsStore
             ? handlerStart
             : metricsStore.requestStart;
@@ -590,7 +601,13 @@ export function createRSCHandler<
 
         const fullTiming = timingParts.join(", ");
         if (fullTiming && !isWebSocketUpgradeResponse(response)) {
-          response.headers.set("Server-Timing", fullTiming);
+          try {
+            response.headers.set("Server-Timing", fullTiming);
+          } catch {
+            // Immutable headers (e.g. a passed-through platform Response) — drop
+            // the timing header, never the response. Instrumentation must not
+            // 500 a request.
+          }
         }
 
         // Single open-redirect chokepoint: every response (PE, full-page,
@@ -737,15 +754,18 @@ export function createRSCHandler<
           },
         });
 
-        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"),
-        });
+        if (router.telemetry) {
+          safeEmit(resolveSink(router.telemetry), {
+            type: "request.origin-rejected",
+            timestamp: performance.now(),
+            requestId: getRequestId(request),
+            method: request.method,
+            pathname: url.pathname,
+            phase: originPhase,
+            origin: request.headers.get("origin"),
+            host: request.headers.get("host"),
+          });
+        }
 
         return originResult;
       }
@@ -787,15 +807,18 @@ export function createRSCHandler<
         params: reqCtx.params as Record<string, string>,
         handledByBoundary: true,
       });
-      observeEvent({
-        type: "handler.error",
-        timestamp: performance.now(),
-        error,
-        handledByBoundary: true,
-        pathname: url.pathname,
-        routeKey: reqCtx._routeName,
-        params: reqCtx.params as Record<string, string>,
-      });
+      if (router.telemetry) {
+        safeEmit(resolveSink(router.telemetry), {
+          type: "handler.error",
+          timestamp: performance.now(),
+          requestId: getRequestId(request),
+          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.

package/src/rsc/redirect-guard.ts

@@ -38,6 +38,7 @@ import {
   resolveSameOriginRedirect,
   resolveExternalRedirect,
   isExternalRedirect,
+  safeSameOriginLanding,
   EXTERNAL_REDIRECT_MARKER,
 } from "../redirect-origin.js";
 import { carryOverRedirectHeaders } from "./helpers.js";
@@ -79,7 +80,7 @@ export function guardOutgoingRedirect(
 
   // Cross-origin (or unsafe-scheme external): neutralize to a safe same-origin
   // landing.
-  const safeTarget = basename && basename !== "/" ? basename : "/";
+  const safeTarget = safeSameOriginLanding(basename);
   if (process.env.NODE_ENV !== "production") {
     console.error(
       `[rango] Blocked cross-origin redirect to "${location}"; sent to ` +

package/src/rsc/rsc-rendering.ts

@@ -44,6 +44,10 @@ import {
   warnPprNonceActiveOnce,
 } from "./shell-serve.js";
 import { contextGet } from "../context-var.js";
+import {
+  resolveSameOriginRedirect,
+  safeSameOriginLanding,
+} from "../redirect-origin.js";
 import { nonce as nonceToken } from "./nonce.js";
 import { reportCacheError } from "../cache/cache-error.js";
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
@@ -413,6 +417,29 @@ async function handleRscRenderingInner<TEnv>(
   return response;
 }
 
+/**
+ * Neutralize the shell-HIT degradation redirect target.
+ *
+ * The inline `location.replace` emitted by serveShellHit when a shell HIT lands
+ * on a URL whose route became redirecting mid-TTL is a document-native redirect
+ * exit that BYPASSES the 3xx chokepoint (guardOutgoingRedirect acts only on 3xx
+ * + Location responses, never a committed 200 body). So it reuses the ONE
+ * same-origin resolver directly: a cross-origin/unparseable/unsafe target
+ * neutralizes to the same safe same-origin landing as redirect-guard.ts
+ * (basename root, or "/" when unset) rather than navigating the user off-host.
+ * A safe same-origin/relative target passes through as its normalized href.
+ */
+export function resolveShellHitRedirectTarget(
+  rawTarget: string,
+  requestOrigin: string,
+  basename: string | undefined,
+): string {
+  return (
+    resolveSameOriginRedirect(rawTarget, requestOrigin) ??
+    safeSameOriginLanding(basename)
+  );
+}
+
 /**
  * Serve a validated shell HIT: commit the composed response NOW — the stored
  * prelude bytes are the first thing on the wire — and run the live tail
@@ -535,10 +562,16 @@ function serveShellHit(
           // a shell (capture bails on redirects), so a HIT on a redirecting URL
           // requires the route to have BECOME redirecting within the shell TTL.
           // The 200 + prelude are already committed; degrade to a client-side
-          // replace so the user still lands on the target.
+          // replace so the user still lands on the target. The target is
+          // neutralized first (see resolveShellHitRedirectTarget).
+          const safeTarget = resolveShellHitRedirectTarget(
+            tail.redirect,
+            url.origin,
+            ctx.router.basename,
+          );
           controller.enqueue(
             new TextEncoder().encode(
-              `<script>location.replace(${JSON.stringify(tail.redirect)})</script>`,
+              `<script>location.replace(${JSON.stringify(safeTarget)})</script>`,
             ),
           );
         }