@rangojs/router 0.0.0-experimental.d7eeaa75 → 0.0.0-experimental.d98a8e9d

package/src/server/request-context.ts

@@ -37,6 +37,8 @@ import { track, type MetricsStore } from "./context.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 { fireAndForgetWaitUntil } from "../types/request-scope.js";
 import { THEME_COOKIE } from "../theme/constants.js";
 import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
 import { NOCACHE_SYMBOL, assertNotInsideCacheExec } from "../cache/taint.js";
@@ -58,22 +60,7 @@ import { isAutoGeneratedRouteName } from "../route-name.js";
 export interface RequestContext<
   TEnv = DefaultEnv,
   TParams = Record<string, string>,
-> {
-  /** Platform bindings (Cloudflare env, etc.) */
-  env: TEnv;
-  /** Original HTTP request */
-  request: Request;
-  /** Parsed URL (with internal `_rsc*` params stripped) */
-  url: URL;
-  /**
-   * The original request URL with all parameters intact, including
-   * internal `_rsc*` transport params.
-   */
-  originalUrl: URL;
-  /** URL pathname */
-  pathname: string;
-  /** URL search params (with internal `_rsc*` params stripped, same as `url.searchParams`) */
-  searchParams: URLSearchParams;
+> extends RequestScope<TEnv> {
   /** @internal Shared variable backing store for ctx.get()/ctx.set(). */
   _variables: Record<string, any>;
   /** Get a variable set by middleware */
@@ -159,20 +146,6 @@ export interface RequestContext<
     import("../cache/profile-registry.js").CacheProfile
   >;
 
-  /**
-   * Schedule work to run after the response is sent.
-   * On Cloudflare Workers, uses ctx.waitUntil().
-   * On Node.js, runs as fire-and-forget.
-   *
-   * @example
-   * ```typescript
-   * ctx.waitUntil(async () => {
-   *   await cacheStore.set(key, data, ttl);
-   * });
-   * ```
-   */
-  waitUntil(fn: () => Promise<void>): void;
-
   /**
    * Register a callback to run when the response is created.
    * Callbacks are sync and receive the response. They can:
@@ -300,7 +273,9 @@ export interface RequestContext<
 
   /**
    * @internal Set to true when the matched entry tree contains any `loading()`
-   * entries (streaming). Used by rendered() to fail fast.
+   * entries (streaming). On a streaming tree rendered() waits for the streaming
+   * handlers to settle (via handleStore.settled) before resolving, and the
+   * deadlock guard state is kept live until that wait completes.
    */
   _treeHasStreaming?: boolean;
 
@@ -324,6 +299,18 @@ export interface RequestContext<
    */
   _renderBarrierHandleSnapshot?: HandleData;
 
+  /**
+   * @internal The deadlock guard window is closed (no further handler-awaits-
+   * loader cycle is possible). For non-streaming trees this is set when the
+   * barrier resolves. For streaming trees the window stays open until
+   * handleStore.settled — rendered() keeps waiting past the barrier and a
+   * loading() handler can still resume and await a still-waiting loader — so it
+   * is set only after settled. The guard (loader-resolution `setupLoaderAccess`)
+   * reads this instead of `_renderBarrierSegmentOrder` so it does not go blind
+   * during the streaming settle wait.
+   */
+  _renderBarrierGuardClosed?: boolean;
+
   /** @internal Per-request error dedup set for onError reporting */
   _reportedErrors: WeakSet<object>;
 
@@ -349,6 +336,15 @@ export interface RequestContext<
    * to avoid a second resolveRoute call. Cleared on HMR invalidation.
    */
   _classifiedRoute?: import("../router/route-snapshot.js").RouteSnapshot;
+
+  /**
+   * @internal Coarse route-level cache signal for the X-Rango-Cache debug
+   * header. Populated by match/matchPartial only when the debug cache signal
+   * gate is enabled (debugCacheSignal option or RANGO_TEST_SIGNALS=1). Read by
+   * the response-finalization path (createResponseWithMergedHeaders). Undefined
+   * when the gate is off, so no header is emitted.
+   */
+  _cacheSignal?: import("../router/telemetry.js").CacheSegmentSignal[];
 }
 
 /**
@@ -382,6 +378,7 @@ export type PublicRequestContext<
   | "_renderBarrierWaiters"
   | "_handlerLoaderDeps"
   | "_renderBarrierHandleSnapshot"
+  | "_renderBarrierGuardClosed"
   | "_reportBackgroundError"
   | "_debugPerformance"
   | "_metricsStore"
@@ -389,6 +386,7 @@ export type PublicRequestContext<
   | "_setStatus"
   | "_variables"
   | "_classifiedRoute"
+  | "_cacheSignal"
   | "res"
 >;
 
@@ -498,13 +496,7 @@ export function requireRequestContext<
   return getRequestContext<TEnv>();
 }
 
-/**
- * Cloudflare Workers ExecutionContext (subset we need)
- */
-export interface ExecutionContext {
-  waitUntil(promise: Promise<any>): void;
-  passThroughOnException(): void;
-}
+export type { ExecutionContext };
 
 /**
  * Options for creating a request context
@@ -768,16 +760,14 @@ export function createRequestContext<TEnv>(
 
     waitUntil(fn: () => Promise<void>): void {
       if (executionContext?.waitUntil) {
-        // Cloudflare Workers: use native waitUntil
         executionContext.waitUntil(fn());
       } else {
-        // Node.js / dev: fire-and-forget with error logging
-        fn().catch((err) =>
-          console.error("[waitUntil] Background task failed:", err),
-        );
+        fireAndForgetWaitUntil(fn);
       }
     },
 
+    executionContext,
+
     _onResponseCallbacks: [],
 
     onResponse(callback: (response: Response) => Response): void {
@@ -832,14 +822,37 @@ export function createRequestContext<TEnv>(
       .filter((s) => s.type !== "loader")
       .map((s) => s.id);
     ctx._renderBarrierSegmentOrder = segOrder;
-    // Build and cache handle snapshot so loader ctx.use(handle) calls
-    // don't rebuild it on every invocation.
-    ctx._renderBarrierHandleSnapshot = buildHandleSnapshot(
-      handleStore,
-      segOrder,
-    );
-    ctx._renderBarrierWaiters = undefined;
-    ctx._handlerLoaderDeps = undefined;
+
+    // Closing the guard window means no handler can still form a deadlock cycle
+    // with a rendered() loader: drop the dependency-tracking state and mark it
+    // closed. WHEN this runs is the only streaming/non-streaming difference.
+    const closeGuard = () => {
+      ctx._renderBarrierWaiters = undefined;
+      ctx._handlerLoaderDeps = undefined;
+      ctx._renderBarrierGuardClosed = true;
+    };
+
+    if (ctx._treeHasStreaming) {
+      // Streaming: rendered() keeps waiting on handleStore.settled past this
+      // point, and loading() handlers are still in flight. The eager snapshot
+      // here would be incomplete, so leave it unset — rendered() builds and
+      // caches the complete one after settled. Keep the guard window OPEN so a
+      // handler that resumes and awaits a still-waiting rendered() loader is
+      // still caught; close it once settled (every tracked handler has finished
+      // then, so none can await a loader anymore). settled resolves after
+      // rendered() seals; if no loader used rendered(), nothing seals and the
+      // (empty) guard state is simply GC'd at request end.
+      handleStore.settled.then(closeGuard);
+    } else {
+      // Non-streaming: all handlers have settled by now. Build and cache the
+      // snapshot so loader ctx.use(handle) calls don't rebuild it, and close the
+      // guard window immediately.
+      ctx._renderBarrierHandleSnapshot = buildHandleSnapshot(
+        handleStore,
+        segOrder,
+      );
+      closeGuard();
+    }
     if (resolveBarrier) resolveBarrier();
   };
   Object.defineProperty(ctx, "_renderBarrier", {
@@ -1043,7 +1056,10 @@ export function createUseFunction<TEnv>(
       search: (ctx as any).search ?? {},
       pathname: ctx.pathname,
       url: ctx.url,
+      originalUrl: ctx.originalUrl,
       env: ctx.env as any,
+      waitUntil: ctx.waitUntil.bind(ctx),
+      executionContext: ctx.executionContext,
       get: ctx.get as any,
       use: (<TDep, TDepParams = any>(
         dep: LoaderDefinition<TDep, TDepParams>,

package/src/ssr/index.tsx

@@ -162,9 +162,13 @@ function createSsrEventController(opts: {
 }): EventController {
   const location = new URL(opts.pathname, "http://localhost");
   let params = opts.params ?? {};
+  const rawMatched = opts.matched ?? [];
   const handleState = {
     data: opts.handleData ?? {},
-    segmentOrder: filterSegmentOrder(opts.matched ?? []),
+    segmentOrder: filterSegmentOrder(rawMatched),
+    routeSegmentIds: rawMatched.filter(
+      (id) => !id.includes(".@") && !/D\d+\./.test(id),
+    ),
   };
   const state: DerivedNavigationState = {
     state: "idle",

package/src/static-handler.ts

@@ -35,6 +35,7 @@ import type { Handler } from "./types.js";
 import type { StaticBuildContext } from "./prerender.js";
 import type { UseItems, HandlerUseItem } from "./route-types.js";
 import { isCachedFunction } from "./cache/taint.js";
+import { isUnderTestRunner } from "./runtime-env.js";
 
 // -- Types ------------------------------------------------------------------
 
@@ -63,6 +64,11 @@ export interface StaticHandlerDefinition<
 
 // -- Function ---------------------------------------------------------------
 
+// Process-stable fallback id counter (mirrors createHandle / createLoader /
+// Prerender). Only assigned in a bare unit test where the Vite plugin did not
+// inject an id; never fires in a real build (the plugin always injects).
+let runtimeStaticIdCounter = 0;
+
 export function Static<TParams extends Record<string, any> = {}>(
   handler: (ctx: StaticBuildContext) => ReactNode | Promise<ReactNode>,
   options?: StaticHandlerOptions,
@@ -94,12 +100,28 @@ export function Static<TParams extends Record<string, any>>(
     id = maybeId ?? "";
   }
 
-  if (!id) {
+  // Throw unless under a test runner. The plugin always injects $$id for a
+  // supported `export const` Static on every build, so a missing id means either
+  // no plugin (a bare test — fall back below) or an UNSUPPORTED shape the plugin
+  // silently skipped (dev OR a real build — fail loud; a synthetic id would
+  // degrade to a silent static/prerender miss). The message is already small (no
+  // stack-parsing diagnostic), so it ships as-is. isUnderTestRunner() is
+  // runtime-safe — never a bare `process.env` access.
+  if (!id && !isUnderTestRunner()) {
     throw new Error(
-      "[rsc-router] Static: missing $$id. " +
-        "Ensure the exposeInternalIds Vite plugin is configured.",
+      "[rango] Static: missing $$id. Use `export const X = Static(...)` and " +
+        "ensure the exposeInternalIds Vite plugin is configured.",
     );
   }
+  // Under vitest with no plugin id: assign a process-stable runtime id so a
+  // whole-app router with Static() routes constructs in a bare test. Never
+  // reached in a real build (the throw above fires there); staticHandlerId is
+  // read only during RSC serving (never in dispatch / assertGeneratedRoutesMatch),
+  // and the build static manifest keys on the plugin id. Mirrors createHandle /
+  // createLoader / Prerender.
+  if (!id) {
+    id = `__rango_runtime_static_${runtimeStaticIdCounter++}`;
+  }
 
   return {
     __brand: "staticHandler" as const,

package/src/testing/cache-status.ts

@@ -0,0 +1,166 @@
+/**
+ * Cache-status testing primitives for @rangojs/router consumers.
+ *
+ * Two complementary paths, both DEVELOPMENT/TEST ONLY:
+ *
+ * 1. Header path — `parseCacheHeader` / `assertCacheStatus` read the
+ *    `X-Rango-Cache` response header. The header is emitted only when the
+ *    router's debug cache signal gate is on (the `debugCacheSignal` option or
+ *    `RANGO_TEST_SIGNALS=1`). With the gate off there is no header and these
+ *    helpers throw a clear "header missing" error.
+ *
+ * 2. Telemetry path — `createCacheSink` returns a `{ sink, events }` pair the
+ *    consumer wires via `createRouter({ telemetry: sink })`. This has ZERO
+ *    production surface: no header, just structured `cache.decision` events
+ *    (which carry the same coarse `segments` cache signal).
+ *
+ * v1 cache status is COARSE (route-level): the router reports a single entry
+ * keyed by the route key (the route NAME), not per individual segment.
+ *
+ * Import path: from a Vitest unit/integration test use `@rangojs/router/testing`;
+ * from a Playwright e2e use `@rangojs/router/testing/e2e` (the barrel pulls a
+ * build-only virtual that does not resolve in a plain Playwright runner).
+ */
+
+import type {
+  CacheDecisionEvent,
+  CacheSegmentStatus,
+  TelemetryEvent,
+  TelemetrySink,
+} from "../router/telemetry.js";
+
+const CACHE_HEADER = "X-Rango-Cache";
+
+/** Expected cache status passed to assertCacheStatus. */
+export type ExpectedCacheStatus = CacheSegmentStatus;
+
+/** A target carrying response headers (a Response or a `{ headers }` object). */
+export type CacheStatusTarget = Response | { headers: Headers };
+
+/**
+ * Parse an `X-Rango-Cache` header value into a `{ routeKey: status }` map.
+ *
+ * Header format: `<routeKey>=<status>, <routeKey2>=<status2>`. The key is the
+ * route NAME (ctx.routeKey, e.g. `product.detail`), NOT the URL pattern —
+ * see assertCacheStatus. Whitespace around entries and the `=` is tolerated.
+ * Entries without a status are ignored.
+ *
+ * @example
+ * parseCacheHeader("product.detail=hit, shop.layout=stale")
+ * // => { "product.detail": "hit", "shop.layout": "stale" }
+ */
+export function parseCacheHeader(
+  headerValue: string | null | undefined,
+): Record<string, string> {
+  const result: Record<string, string> = {};
+  if (!headerValue) return result;
+  for (const rawEntry of headerValue.split(",")) {
+    const entry = rawEntry.trim();
+    if (entry.length === 0) continue;
+    const eq = entry.indexOf("=");
+    if (eq === -1) continue;
+    const id = entry.slice(0, eq).trim();
+    const status = entry.slice(eq + 1).trim();
+    if (id.length === 0 || status.length === 0) continue;
+    result[id] = status;
+  }
+  return result;
+}
+
+function getHeaders(target: CacheStatusTarget): Headers {
+  return target.headers;
+}
+
+/**
+ * Assert that the `X-Rango-Cache` header reports `expected` status for the
+ * given route. Throws a descriptive error when the header is missing (gate
+ * off), the route is absent, or the status differs.
+ *
+ * `routeKey` is the route NAME (e.g. `product.detail`), the same id the header
+ * carries — NOT the URL pattern (`/products/:id`). The signal is built from
+ * ctx.routeKey (telemetry.ts), so a pattern-shaped key never matches.
+ *
+ * The header is produced by the RSC render pipeline, so get the Response from
+ * the router's real fetch path (`router.fetch(...)`), with the debug cache
+ * signal gate enabled (`debugCacheSignal: true` or `RANGO_TEST_SIGNALS=1`).
+ * NOTE: `dispatch()` is the non-RSC primitive and never emits this header.
+ *
+ * @example
+ * // debugCacheSignal must be enabled on the router under test.
+ * const res = await router.fetch(new Request("https://app/products/42"));
+ * assertCacheStatus(res, "product.detail", "hit");
+ */
+export function assertCacheStatus(
+  target: CacheStatusTarget,
+  segment: string,
+  expected: ExpectedCacheStatus,
+): void {
+  const headerValue = getHeaders(target).get(CACHE_HEADER);
+  if (headerValue === null) {
+    throw new Error(
+      `assertCacheStatus: response has no ${CACHE_HEADER} header. ` +
+        `Enable the debug cache signal via createRouter({ debugCacheSignal: true }) ` +
+        `or RANGO_TEST_SIGNALS=1.`,
+    );
+  }
+  const map = parseCacheHeader(headerValue);
+  const actual = map[segment];
+  if (actual === undefined) {
+    const known = Object.keys(map);
+    throw new Error(
+      `assertCacheStatus: segment "${segment}" not found in ${CACHE_HEADER} ` +
+        `("${headerValue}"). Known segments: ${
+          known.length > 0 ? known.join(", ") : "(none)"
+        }.`,
+    );
+  }
+  if (actual !== expected) {
+    throw new Error(
+      `assertCacheStatus: segment "${segment}" expected "${expected}" but got "${actual}".`,
+    );
+  }
+}
+
+/**
+ * A telemetry sink paired with the array it records events into.
+ */
+export interface CacheSink {
+  /** Wire into `createRouter({ telemetry: sink })`. */
+  sink: TelemetrySink;
+  /** All telemetry events captured so far, in emit order. */
+  events: TelemetryEvent[];
+}
+
+/**
+ * Create a capturing telemetry sink for asserting on `cache.decision` events.
+ *
+ * This is the ZERO-production-surface path: no response header is emitted, the
+ * consumer just inspects the captured events.
+ *
+ * @example
+ * const { sink, events } = createCacheSink();
+ * const router = createRouter({ telemetry: sink, ... });
+ * // ...send a request through the router's RSC fetch path...
+ * const decisions = filterCacheDecisions(events);
+ * expect(decisions[0].segments?.[0].cacheStatus).toBe("hit");
+ */
+export function createCacheSink(): CacheSink {
+  const events: TelemetryEvent[] = [];
+  const sink: TelemetrySink = {
+    emit(event: TelemetryEvent): void {
+      events.push(event);
+    },
+  };
+  return { sink, events };
+}
+
+/**
+ * Filter captured telemetry events down to `cache.decision` events.
+ */
+export function filterCacheDecisions(
+  events: readonly TelemetryEvent[],
+): CacheDecisionEvent[] {
+  return events.filter(
+    (e): e is CacheDecisionEvent => e.type === "cache.decision",
+  );
+}

package/src/testing/collect-handle.ts

@@ -0,0 +1,63 @@
+/**
+ * collectHandle — unit-test a handle's `collect`/accumulator function directly.
+ *
+ * A handle's collect function (the `createHandle(collect)` argument that maps the
+ * per-segment pushed values into the accumulated result) is otherwise not
+ * directly reachable: createHandle keeps it in a private registry keyed by the
+ * handle's `$$id` and returns only `{ __brand, $$id }`. This primitive runs that
+ * REAL registered collect on per-segment values you provide and returns the
+ * accumulated result — so the mapper/accumulator is unit-testable without a full
+ * route match.
+ *
+ * It relies on createHandle registering the collect even in a bare test (it
+ * assigns a runtime fallback id when the Vite plugin did not inject one). If a
+ * handle's module was never imported (so createHandle never ran), the collect is
+ * unregistered and this falls back to a flat array with a warning.
+ */
+
+import { getCollectFn, type Handle } from "../handle.js";
+
+/**
+ * Run a handle's collect function on per-segment pushed values.
+ *
+ * @param handle - The handle whose collect to run.
+ * @param segments - Per-segment pushed values: each entry is the array of values
+ *   one route segment pushed for this handle, in parent -> child order. Empty
+ *   per-segment arrays are dropped before the collect runs, matching production
+ *   collectHandleData (a segment that pushed nothing is not passed through).
+ * @returns The accumulated value the handle's collect produces.
+ *
+ * @example
+ * ```ts
+ * // Default flatten
+ * collectHandle(Breadcrumbs, [[{ label: "Home", href: "/" }], [{ label: "P", href: "/p" }]]);
+ * // -> [{ label: "Home", href: "/" }, { label: "P", href: "/p" }]
+ *
+ * // Custom "last wins"
+ * const PageTitle = createHandle<string, string>((s) => s.flat().at(-1) ?? "");
+ * collectHandle(PageTitle, [["Home"], ["Product"]]); // -> "Product"
+ * ```
+ */
+export function collectHandle<TData, TAccumulated>(
+  handle: Handle<TData, TAccumulated>,
+  segments: ReadonlyArray<ReadonlyArray<TData>>,
+): TAccumulated {
+  const collectFn = getCollectFn(handle.$$id) as
+    | ((segments: TData[][]) => TAccumulated)
+    | undefined;
+
+  if (!collectFn) {
+    console.warn(
+      `[rango] collectHandle: handle "${handle.$$id}" has no registered collect ` +
+        `function. Import the handle's module so createHandle() runs. Falling ` +
+        `back to a flat array.`,
+    );
+    return segments.flat() as unknown as TAccumulated;
+  }
+
+  // Match production collectHandleData (handle.ts): segments that pushed
+  // nothing (empty arrays) are dropped before the collect runs, so a collect
+  // that inspects segment count or indices sees the same input as at runtime.
+  const nonEmpty = segments.filter((seg) => seg.length > 0) as TData[][];
+  return collectFn(nonEmpty);
+}