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

package/src/testing/dispatch.ts

@@ -55,6 +55,14 @@
  *   metadata.category, while the request still degrades-to-miss exactly as before.
  *   (A thrown response-route HANDLER error is the one onError path NOT covered —
  *   see "DOES NOT support" below.)
+ * - createRouter({ telemetry }) match-transaction lifecycle: request.start opens
+ *   the transaction before the global middleware chain, request.end closes it
+ *   after finalizeResponse (segmentCount 0 / cacheHit false — dispatch renders no
+ *   RSC segments and holds no match-cache state), and a thrown non-Response error
+ *   emits request.error with phase "routing". All three carry the same requestId
+ *   (getRequestId). Emission is gated entirely on a configured sink; with none,
+ *   dispatch does zero new work and stays byte-identical for existing callers.
+ *   Lets a consumer unit-test their sink wiring in-process instead of only at e2e.
  *
  * What dispatch DOES NOT support (and why):
  * - RSC component routes — rendering requires the Flight serializer + React
@@ -76,6 +84,13 @@
  *   merged cookies/headers all match production; only the Flight-embedded
  *   location-state entries are absent. Cover location-state restoration across a
  *   partial redirect with an e2e test.
+ * - Telemetry cache.decision / loader.* / handler.error events: these fire from
+ *   the real match()/matchPartial() + RSC render + loader pipeline (match-
+ *   handlers.ts, loader-resolution.ts, segment-resolution), none of which
+ *   dispatch runs. Synthesizing them here would be faking (the events would not
+ *   reflect a real cache lookup or loader run), so dispatch emits only the
+ *   request.start/end/error lifecycle above; cover cache/loader telemetry with an
+ *   e2e test driving a real RSC request.
  *
  * dispatch reuses router.previewMatch(), which itself runs content negotiation
  * and resolves route middleware from the matched entry tree, so dispatch's
@@ -127,6 +142,8 @@ import { isWebSocketUpgradeResponse } from "../response-utils.js";
 import { invokeOnError } from "../router/error-handling.js";
 import type { OnErrorCallback } from "../types/error-types.js";
 import type { Rango } from "../router/router-interfaces.js";
+import { getRequestId, resolveSink, safeEmit } from "../router/telemetry.js";
+import type { TelemetrySink } from "../router/telemetry.js";
 
 /**
  * The internal subset of the router surface dispatch depends on. The public
@@ -140,6 +157,13 @@ interface DispatchableRouter<TEnv> {
   routeMap: Record<string, unknown>;
   middleware: MiddlewareEntry<TEnv>[];
   onError?: OnErrorCallback<TEnv>;
+  /**
+   * Optional telemetry sink from createRouter({ telemetry }) (RangoInternal
+   * field). dispatch emits the match-transaction lifecycle events onto it so a
+   * consumer can unit-test their sink wiring in-process; undefined keeps dispatch
+   * byte-identical for every existing caller.
+   */
+  telemetry?: TelemetrySink;
   findMatch(pathname: string): Promise<{
     redirectTo?: string;
     routeKey?: string;
@@ -444,6 +468,19 @@ export async function dispatch<TEnv = any>(
   const isPartial = url.searchParams.has("_rsc_partial");
   const isAction = url.searchParams.has("_rsc_action");
 
+  // Telemetry: mirror the router's match-transaction lifecycle onto the
+  // configured sink so a consumer can unit-test createRouter({ telemetry })
+  // wiring in-process (the dogfood gap the RSC-free dispatch left — see
+  // tests/cloudflare-basic/test/cache-status.test.ts). Every emit is gated on
+  // `sink` truthiness: with no sink configured dispatch does zero new work and
+  // stays byte-identical for existing callers. Only request.start/end/error are
+  // reachable here — cache.decision and loader.* originate in the real match()/
+  // matchPartial() + RSC render pipeline dispatch deliberately does not run
+  // (module header), so fabricating them would violate the no-fake rule.
+  const sink = router.telemetry;
+  const telemetryRequestId = sink ? getRequestId(req) : undefined;
+  const telemetryStart = sink ? performance.now() : 0;
+
   return runWithRequestContext(requestContext, async () => {
     // Set params before middleware/handler run, so global middleware sees
     // ctx.params (production sets them during matching, before middleware).
@@ -658,44 +695,119 @@ export async function dispatch<TEnv = any>(
       return callResponseRoute();
     };
 
-    // Global (pattern-matched) middleware wraps coreHandler, exactly as
-    // production wraps coreHandler with executeMiddleware (handler.ts).
-    const globalMatches = matchMiddleware(url.pathname, router.middleware);
-    const mwResponse =
-      globalMatches.length === 0
-        ? await coreHandler()
-        : await executeMiddleware<TEnv>(
-            globalMatches,
-            req,
-            env,
-            variables,
-            coreHandler,
-            reverse,
-          );
-
-    // Match production's global-chain exit (handler.ts): on a partial/action
-    // request a middleware 3xx redirect is converted to a Flight-safe response
-    // so fetch() does not auto-follow it; every path then drains onResponse
-    // callbacks via finalizeResponse. dispatch is RSC-free, so the
-    // createRedirectFlightResponse stand-in falls back to the no-state
-    // 204 + X-RSC-Redirect (see the location-state divergence in the header).
-    let finalResponse: Response;
-    if (isPartial || isAction) {
-      const intercepted = interceptRedirectForPartial(
-        mwResponse,
-        (redirectUrl) => createSimpleRedirectResponse(redirectUrl),
-      );
-      finalResponse = finalizeResponse(intercepted ?? mwResponse);
-    } else {
-      finalResponse = finalizeResponse(mwResponse);
+    // request.start opens the match transaction, mirroring match-handlers.ts.
+    // transaction is always "match" (dispatch has no matchPartial split);
+    // isPartial carries the ?_rsc_partial signal the same way production does.
+    if (sink) {
+      safeEmit(resolveSink(sink), {
+        type: "request.start",
+        timestamp: telemetryStart,
+        requestId: telemetryRequestId,
+        method: req.method,
+        pathname: url.pathname,
+        transaction: "match",
+        isPartial,
+      });
     }
 
-    // Mirror production's single open-redirect chokepoint (handler.ts): every
-    // browser-followed (3xx + Location) redirect is same-origin guarded before
-    // it leaves -- a cross-origin Location is rewritten to the basename root
-    // unless redirect(url, { external: true }) opted out. Soft partial/action
-    // redirects are 204 + X-RSC-Redirect and pass through untouched (the client
-    // validates them), so this is a no-op for them.
-    return guardOutgoingRedirect(finalResponse, url.origin, router.basename);
+    try {
+      // Global (pattern-matched) middleware wraps coreHandler, exactly as
+      // production wraps coreHandler with executeMiddleware (handler.ts).
+      const globalMatches = matchMiddleware(url.pathname, router.middleware);
+      const mwResponse =
+        globalMatches.length === 0
+          ? await coreHandler()
+          : await executeMiddleware<TEnv>(
+              globalMatches,
+              req,
+              env,
+              variables,
+              coreHandler,
+              reverse,
+            );
+
+      // Match production's global-chain exit (handler.ts): on a partial/action
+      // request a middleware 3xx redirect is converted to a Flight-safe response
+      // so fetch() does not auto-follow it; every path then drains onResponse
+      // callbacks via finalizeResponse. dispatch is RSC-free, so the
+      // createRedirectFlightResponse stand-in falls back to the no-state
+      // 204 + X-RSC-Redirect (see the location-state divergence in the header).
+      let finalResponse: Response;
+      if (isPartial || isAction) {
+        const intercepted = interceptRedirectForPartial(
+          mwResponse,
+          (redirectUrl) => createSimpleRedirectResponse(redirectUrl),
+        );
+        finalResponse = finalizeResponse(intercepted ?? mwResponse);
+      } else {
+        finalResponse = finalizeResponse(mwResponse);
+      }
+
+      // request.end closes the transaction. dispatch produces no RSC segments and
+      // holds no match-cache state, so segmentCount/cacheHit are 0/false — the
+      // same shape production emits for its own redirect (segment-less) result.
+      if (sink) {
+        safeEmit(resolveSink(sink), {
+          type: "request.end",
+          timestamp: performance.now(),
+          requestId: telemetryRequestId,
+          method: req.method,
+          pathname: url.pathname,
+          transaction: "match",
+          durationMs: performance.now() - telemetryStart,
+          segmentCount: 0,
+          cacheHit: false,
+          // dispatch's final response IS built before request.end (unlike
+          // match()/matchPartial(), whose Response is built after), so stamp its
+          // status — the same field a thrown-Response short-circuit carries.
+          status: finalResponse.status,
+        });
+      }
+
+      // Mirror production's single open-redirect chokepoint (handler.ts): every
+      // browser-followed (3xx + Location) redirect is same-origin guarded before
+      // it leaves -- a cross-origin Location is rewritten to the basename root
+      // unless redirect(url, { external: true }) opted out. Soft partial/action
+      // redirects are 204 + X-RSC-Redirect and pass through untouched (the client
+      // validates them), so this is a no-op for them.
+      return guardOutgoingRedirect(finalResponse, url.origin, router.basename);
+    } catch (error) {
+      if (sink) {
+        if (error instanceof Response) {
+          // executeMiddleware absorbs a middleware-thrown Response and returns it
+          // (middleware.ts:566), so a thrown Response never actually reaches this
+          // level in dispatch. Defensive: if one ever does it is a completed
+          // request from the consumer's seat (a short-circuit redirect), so mirror
+          // plan 002 / match-handlers.ts and emit request.end, not request.error.
+          safeEmit(resolveSink(sink), {
+            type: "request.end",
+            timestamp: performance.now(),
+            requestId: telemetryRequestId,
+            method: req.method,
+            pathname: url.pathname,
+            transaction: "match",
+            durationMs: performance.now() - telemetryStart,
+            segmentCount: 0,
+            cacheHit: false,
+            // Carry the short-circuit Response's status (parity with
+            // match-handlers.ts's thrown-Response request.end).
+            status: error.status,
+          });
+        } else {
+          safeEmit(resolveSink(sink), {
+            type: "request.error",
+            timestamp: performance.now(),
+            requestId: telemetryRequestId,
+            method: req.method,
+            pathname: url.pathname,
+            transaction: "match",
+            error: error instanceof Error ? error : new Error(String(error)),
+            phase: "routing",
+            durationMs: performance.now() - telemetryStart,
+          });
+        }
+      }
+      throw error;
+    }
   });
 }

package/src/urls/path-helper-types.ts

@@ -268,9 +268,16 @@ export type PathHelpers<TEnv> = {
    * `{ handler, use? }` whose `use` is scoped to that slot only. Per-slot
    * merge order is `handler.use` → shared `use` → slot-local `use`, with
    * narrowest scope winning for last-write-wins items like `loading()`.
+   *
+   * Not generic over the slots record: an inferred type parameter makes the
+   * object literal an inference site, which suppresses contextual typing of
+   * arrow slot handlers (`(ctx) => ...` was implicit any). Bare handlers infer
+   * now; a descriptor's `handler:` arrow still needs an explicit ctx annotation
+   * because StaticHandlerDefinition's own `.handler` joins the contextual union
+   * (two callables — see parallel-slot-handler-types.test.ts).
    */
-  parallel: <
-    TSlots extends Record<
+  parallel: (
+    slots: Record<
       `@${string}`,
       | Handler<any, any, TEnv>
       | ReactNode
@@ -283,8 +290,6 @@ export type PathHelpers<TEnv> = {
           use?: () => ParallelUseItem[];
         }
     >,
-  >(
-    slots: TSlots,
     use?: () => ParallelUseItem[],
   ) => ParallelItem;
 

package/src/vercel/tracing.ts

@@ -44,15 +44,15 @@ import {
 } from "../router/telemetry-otel.js";
 import type {
   RouterTracingConfig,
-  TracePhaseToggles,
+  TracingToggleOptions,
 } from "../router/tracing.js";
 
-/** Options for createVercelTracing. */
-export interface VercelTracingOptions {
-  /** Master switch. Defaults to true. */
-  enabled?: boolean;
-  /** Per-phase span toggles. Omitted phases default to enabled. */
-  spans?: TracePhaseToggles;
+/**
+ * Options for createVercelTracing. Extends the shared
+ * {@link TracingToggleOptions} (`enabled` + per-phase `spans`) with the
+ * Vercel-specific tracer selectors.
+ */
+export interface VercelTracingOptions extends TracingToggleOptions {
   /**
    * OTel instrumentation-scope name passed to `trace.getTracer()`. Defaults to
    * `"rango"`. Ignored when `tracer` is provided.

package/src/vite/inject-client-debug.ts

@@ -1,3 +1,5 @@
+import type { Connect } from "vite";
+
 /**
  * Bake the resolved INTERNAL_RANGO_DEBUG value into the router's `internal-debug`
  * module so the flag reaches the CLIENT debug logs by just setting the env var.
@@ -10,27 +12,77 @@
  * runs on the module regardless of how (or whether) the define is delivered, in
  * both dev and build and for every environment, so the discovery plugin uses this
  * to replace the module with the resolved literal.
- *
+ */
+
+/**
+ * Scope to the router's own internal-debug module: the published package
+ * (`/@rangojs/router/`, incl. pnpm's nested layout) or the monorepo workspace
+ * (`/packages/rangojs-router/`). The package-anchored path avoids matching a
+ * consumer file that merely sits under a directory named `rangojs-router`.
+ * Accepts module ids and dev-server URLs (`/@fs/...internal-debug.ts?v=abc`).
+ */
+export function isRouterInternalDebugId(id: string): boolean {
+  if (!id.includes("internal-debug")) return false;
+  const norm = id.replace(/\\/g, "/");
+  return (
+    /\/internal-debug\.[cm]?[jt]sx?(\?|$)/.test(norm) &&
+    (norm.includes("/@rangojs/router/") ||
+      norm.includes("/packages/rangojs-router/"))
+  );
+}
+
+/**
+ * Transform: replace the module with the resolved literal.
  * Returns null for any module that is not the router's internal-debug module.
  */
 export function injectClientDebugFlag(
   id: string,
 ): { code: string; map: null } | null {
   // Cheap early-out: this hook runs on every module in every environment.
-  if (!id.includes("internal-debug")) return null;
-  const norm = id.replace(/\\/g, "/");
-  // Scope to the router's own internal-debug module: the published package
-  // (`/@rangojs/router/`, incl. pnpm's nested layout) or the monorepo workspace
-  // (`/packages/rangojs-router/`). The package-anchored path avoids matching a
-  // consumer file that merely sits under a directory named `rangojs-router`.
-  const isInternalDebug =
-    /\/internal-debug\.[cm]?[jt]sx?(\?|$)/.test(norm) &&
-    (norm.includes("/@rangojs/router/") ||
-      norm.includes("/packages/rangojs-router/"));
-  if (!isInternalDebug) return null;
+  if (!isRouterInternalDebugId(id)) return null;
   // Emit the whole module: internal-debug.ts has a single export, kept in sync.
   return {
     code: `export const INTERNAL_RANGO_DEBUG = ${!!process.env.INTERNAL_RANGO_DEBUG};\n`,
     map: null,
   };
 }
+
+/**
+ * Dev middleware companion: serve the internal-debug module `no-cache` so the
+ * browser revalidates it (etag) instead of trusting an immutable cache entry.
+ *
+ * Why: the transform bakes the flag into module CONTENT, but a published
+ * consumer resolves the module into node_modules, where dev serves it as
+ * `internal-debug.ts?v=<hash>` with `Cache-Control: max-age=31536000,immutable`.
+ * That `?v=` hash does not vary with env vars (verified on Vite 8: getConfigHash
+ * hashes NODE_ENV, resolve, plugin names, optimizeDeps -- not arbitrary env
+ * state), so toggling the flag changed the content under an unchanged immutable
+ * URL: a browser that ever loaded the app with the flag off kept the
+ * baked-`false` module across dev-server restarts, and INTERNAL_RANGO_DEBUG
+ * never reached the FE logs while the server logs worked. The monorepo was
+ * immune -- workspace source is outside node_modules and served no-cache --
+ * which is why this bit only npm consumers.
+ *
+ * internal-debug.ts is the ONLY flag-varying module in the graph (its importers
+ * are byte-identical across flag states), so forcing revalidation for this one
+ * tiny module is sufficient and costs one conditional request per session. The
+ * middleware is unconditional (not gated on the flag) so an already-poisoned
+ * cache heals in both directions. Alternatives that do not work: a plugin
+ * `resolveId` appending a flag query never fires in Vite 8 dev for
+ * fs-resolvable relative imports, and the pre-#621 `define` no longer rotates
+ * the optimizer hash (define contents are not part of getConfigHash).
+ */
+export function internalDebugNoCacheMiddleware(): Connect.NextHandleFunction {
+  return function rangoInternalDebugNoCache(req, res, next) {
+    if (req.url && isRouterInternalDebugId(req.url)) {
+      const setHeader = res.setHeader.bind(res);
+      res.setHeader = (name, value) => {
+        return setHeader(
+          name,
+          name.toLowerCase() === "cache-control" ? "no-cache" : value,
+        );
+      };
+    }
+    next();
+  };
+}

package/src/vite/router-discovery.ts

@@ -19,7 +19,10 @@ import {
   createScanFilter,
 } from "../build/generate-route-types.js";
 import { firstCodeMatchIndex } from "../build/route-types/source-scan.js";
-import { injectClientDebugFlag } from "./inject-client-debug.js";
+import {
+  injectClientDebugFlag,
+  internalDebugNoCacheMiddleware,
+} from "./inject-client-debug.js";
 import { createVersionPlugin } from "./plugins/version-plugin.js";
 import { createVirtualStubPlugin } from "./plugins/virtual-stub-plugin.js";
 import {
@@ -392,6 +395,11 @@ export function createRouterDiscoveryPlugin(
       if ((globalThis as any).__rscRouterDiscoveryActive) return;
       s.devServer = server;
 
+      // Serve the internal-debug module no-cache: consumers resolve it into
+      // node_modules, where dev's immutable `?v=` caching pinned browsers to a
+      // stale baked INTERNAL_RANGO_DEBUG. See internalDebugNoCacheMiddleware.
+      server.middlewares.use(internalDebugNoCacheMiddleware());
+
       // Discovery promise that the handler can await if requests arrive
       // before discovery completes
       let resolveDiscovery: () => void;