@rangojs/router 0.0.0-experimental.19 → 0.0.0-experimental.1b930379

package/src/router/segment-resolution/fresh.ts

@@ -24,6 +24,7 @@ import {
 } from "./helpers.js";
 import { getRouterContext } from "../router-context.js";
 import { resolveSink, safeEmit } from "../telemetry.js";
+import { track } from "../../server/context.js";
 
 // ---------------------------------------------------------------------------
 // Streamed handler telemetry
@@ -178,7 +179,9 @@ export async function resolveSegment<TEnv>(
     (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
       entry.shortCode;
 
+    const doneLayoutHandler = track(`handler:${entry.id}`, 2);
     const component = await resolveLayoutComponent(entry, context);
+    doneLayoutHandler();
 
     segments.push({
       id: entry.shortCode,
@@ -241,9 +244,11 @@ export async function resolveSegment<TEnv>(
       entry.shortCode,
     );
     if (component === undefined) {
+      const doneRouteHandler = track(`handler:${entry.id}`, 2);
       if (entry.loading) {
         const result = handleHandlerResult(entry.handler(context));
         if (result instanceof Promise) {
+          result.finally(doneRouteHandler).catch(() => {});
           const tracked = deps.trackHandler(result, {
             segmentId: entry.shortCode,
             segmentType: entry.type,
@@ -258,10 +263,12 @@ export async function resolveSegment<TEnv>(
           );
           component = tracked;
         } else {
+          doneRouteHandler();
           component = result;
         }
       } else {
         component = handleHandlerResult(await entry.handler(context));
+        doneRouteHandler();
       }
     }
 
@@ -343,7 +350,9 @@ export async function resolveOrphanLayout<TEnv>(
 
   // Handler-first: orphan layout handler executes before its parallels
   // so that ctx.set() values are visible to parallel children.
+  const doneOrphanHandler = track(`handler:${orphan.id}`, 2);
   const component = await resolveLayoutComponent(orphan, context);
+  doneOrphanHandler();
 
   segments.push({
     id: orphan.shortCode,
@@ -410,12 +419,17 @@ export async function resolveParallelEntry<TEnv>(
     );
 
     if (component === undefined) {
+      const doneParallelHandler = track(
+        `handler:${parallelEntry.id}.${slot}`,
+        2,
+      );
       const hasLoadingFallback =
         parallelEntry.loading !== undefined && parallelEntry.loading !== false;
       if (hasLoadingFallback) {
         const result =
           typeof handler === "function" ? handler(context) : handler;
         if (result instanceof Promise) {
+          result.finally(doneParallelHandler).catch(() => {});
           const tracked = deps.trackHandler(result, {
             segmentId: `${parentShortCode}.${slot}`,
             segmentType: "parallel",
@@ -430,11 +444,13 @@ export async function resolveParallelEntry<TEnv>(
           );
           component = tracked as ReactNode;
         } else {
+          doneParallelHandler();
           component = result as ReactNode;
         }
       } else {
         component =
           typeof handler === "function" ? await handler(context) : handler;
+        doneParallelHandler();
       }
     }
 
@@ -499,6 +515,7 @@ export async function resolveAllSegments<TEnv>(
   } catch {}
 
   for (const entry of entries) {
+    const doneEntry = track(`segment:${entry.id}`, 1);
     const resolvedSegments = await resolveWithErrorBoundary(
       entry,
       params,
@@ -518,6 +535,7 @@ export async function resolveAllSegments<TEnv>(
       { request: safeRequest, url: context.url, routeKey, telemetry },
       context.pathname,
     );
+    doneEntry();
     // Deduplicate by segment ID. include() scopes can produce entries that
     // resolve the same shared layout/loader segment. Duplicates in the segment
     // array propagate to the client's matched[] and change the React tree depth.

package/src/router/segment-resolution/helpers.ts

@@ -174,7 +174,7 @@ export function catchSegmentError<TEnv>(
   const setResponseStatus = (status: number) => {
     const reqCtx = getRequestContext();
     if (reqCtx) {
-      reqCtx.setStatus(status);
+      reqCtx._setStatus(status);
     }
   };
 

package/src/router/segment-resolution/revalidation.ts

@@ -37,6 +37,7 @@ import {
 } from "./helpers.js";
 import { getRouterContext } from "../router-context.js";
 import { resolveSink, safeEmit } from "../telemetry.js";
+import { track } from "../../server/context.js";
 
 // ---------------------------------------------------------------------------
 // Telemetry helpers
@@ -621,20 +622,29 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
       return shouldRevalidate;
     },
     async () => {
+      const doneHandler = track(`handler:${entry.id}`, 2);
       (context as InternalHandlerContext<any, TEnv>)._currentSegmentId =
         entry.shortCode;
       if (entry.type === "layout" || entry.type === "cache") {
-        return resolveLayoutComponent(entry, context);
+        const layoutComponent = await resolveLayoutComponent(entry, context);
+        doneHandler();
+        return layoutComponent;
       }
       const staticComponent = await tryStaticHandler(entry, entry.shortCode);
-      if (staticComponent !== undefined) return staticComponent;
+      if (staticComponent !== undefined) {
+        doneHandler();
+        return staticComponent;
+      }
       const routeEntry = entry as Extract<EntryData, { type: "route" }>;
       if (!routeEntry.loading) {
-        return handleHandlerResult(await routeEntry.handler(context));
+        const result = handleHandlerResult(await routeEntry.handler(context));
+        doneHandler();
+        return result;
       }
       if (!actionContext) {
         const result = handleHandlerResult(routeEntry.handler(context));
         if (result instanceof Promise) {
+          result.finally(doneHandler).catch(() => {});
           const tracked = deps.trackHandler(result, {
             segmentId: entry.shortCode,
             segmentType: entry.type,
@@ -649,15 +659,18 @@ export async function resolveEntryHandlerWithRevalidation<TEnv>(
           );
           return { content: tracked };
         }
+        doneHandler();
         return { content: result };
       }
       debugLog("segment.action", "resolving action route with awaited value", {
         entryId: entry.id,
       });
+      const actionResult = handleHandlerResult(
+        await routeEntry.handler(context),
+      );
+      doneHandler();
       return {
-        content: Promise.resolve(
-          handleHandlerResult(await routeEntry.handler(context)),
-        ),
+        content: Promise.resolve(actionResult),
       };
     },
     () => null,
@@ -1178,6 +1191,7 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
     }
 
     const nonParallelEntry = entry as Exclude<EntryData, { type: "parallel" }>;
+    const doneEntry = track(`segment:${entry.id}`, 1);
     const resolved = await resolveWithErrorBoundary(
       nonParallelEntry,
       params,
@@ -1199,11 +1213,10 @@ export async function resolveAllSegmentsWithRevalidation<TEnv>(
         ),
       (seg) => ({ segments: [seg], matchedIds: [seg.id] }),
       deps,
-      telemetry
-        ? { request, url: context.url, routeKey, isPartial: true, telemetry }
-        : undefined,
+      { request, url: context.url, routeKey, isPartial: true, telemetry },
       pathname,
     );
+    doneEntry();
 
     // Deduplicate segments and matchedIds by ID, matching resolveAllSegments.
     // include() scopes can produce entries that resolve the same shared

package/src/router/trie-matching.ts

@@ -114,7 +114,25 @@ function walkTrie(
     if (result) return result;
   }
 
-  // Priority 2: Param match
+  // Priority 2: Suffix-param match (e.g., :productId.html)
+  if (node.xp) {
+    for (const suffix in node.xp) {
+      if (segment.endsWith(suffix) && segment.length > suffix.length) {
+        const paramValue = segment.slice(0, -suffix.length);
+        paramValues.push(paramValue);
+        const result = walkTrie(
+          node.xp[suffix].c,
+          segments,
+          index + 1,
+          paramValues,
+        );
+        paramValues.pop();
+        if (result) return result;
+      }
+    }
+  }
+
+  // Priority 3: Param match
   if (node.p) {
     paramValues.push(segment);
     const result = walkTrie(node.p.c, segments, index + 1, paramValues);
@@ -122,7 +140,7 @@ function walkTrie(
     if (result) return result;
   }
 
-  // Priority 3: Wildcard match (consumes rest)
+  // Priority 4: Wildcard match (consumes rest)
   if (node.w) {
     const rest = joinRemainingSegments(segments, index);
     return {

package/src/router.ts

@@ -147,7 +147,7 @@ export function createRouter<TEnv = any>(
     $$sourceFile: injectedSourceFile,
     nonce,
     version,
-    prefetchCacheControl: prefetchCacheControlOption,
+    prefetchCacheTTL: prefetchCacheTTLOption,
     warmup: warmupOption,
     allowDebugManifest: allowDebugManifestOption = false,
     telemetry: telemetrySink,
@@ -200,11 +200,17 @@ export function createRouter<TEnv = any>(
   const routerId =
     userProvidedId ?? injectedId ?? `router_${nextRouterAutoId()}`;
 
-  // Resolve prefetch cache control (default: 'private, max-age=300')
-  const prefetchCacheControl =
-    prefetchCacheControlOption !== undefined
-      ? prefetchCacheControlOption
-      : "private, max-age=300";
+  // Resolve prefetch cache TTL (default: 300 seconds / 5 minutes)
+  // Clamp to a non-negative integer for valid Cache-Control max-age.
+  const rawTTL =
+    prefetchCacheTTLOption !== undefined ? prefetchCacheTTLOption : 300;
+  const prefetchCacheTTLSeconds =
+    rawTTL === false ? 0 : Math.max(0, Math.floor(rawTTL));
+  const prefetchCacheTTL = prefetchCacheTTLSeconds * 1000;
+  const prefetchCacheControl: string | false =
+    prefetchCacheTTLSeconds === 0
+      ? false
+      : `private, max-age=${prefetchCacheTTLSeconds}`;
 
   // Resolve warmup enabled flag (default: true)
   const warmupEnabled = warmupOption !== false;
@@ -357,8 +363,18 @@ export function createRouter<TEnv = any>(
     return precomputedByPrefix;
   }
 
-  // Wrapper to pass debugPerformance to external createMetricsStore
-  const getMetricsStore = () => createMetricsStore(debugPerformance);
+  // Wrapper to pass debugPerformance to external createMetricsStore.
+  // Also checks per-request flag set by ctx.debugPerformance() in middleware.
+  const getMetricsStore = () => {
+    const reqCtx = _getRequestContext();
+    const enabled = debugPerformance || !!reqCtx?._debugPerformance;
+    if (!enabled) return undefined;
+    if (!reqCtx) {
+      return createMetricsStore(true);
+    }
+    reqCtx._metricsStore ??= createMetricsStore(true);
+    return reqCtx._metricsStore;
+  };
 
   // Wrapper to pass defaults to error/notFound boundary finders
   const findNearestErrorBoundary = (entry: EntryData | null) =>
@@ -869,12 +885,16 @@ export function createRouter<TEnv = any>(
     // Expose resolved cache profiles for per-request resolution
     cacheProfiles: resolvedCacheProfiles,
 
-    // Expose prefetch cache control for RSC handler
+    // Expose prefetch cache settings
     prefetchCacheControl,
+    prefetchCacheTTL,
 
     // Expose warmup enabled flag for handler and client
     warmupEnabled,
 
+    // Expose router-wide performance debugging for request-level metrics setup
+    debugPerformance,
+
     // Expose debug manifest flag for handler
     allowDebugManifest: allowDebugManifestOption,
 

package/src/rsc/handler.ts

@@ -18,7 +18,12 @@ import {
 } from "../server/request-context.js";
 import * as rscDeps from "@vitejs/plugin-rsc/rsc";
 
-import type { RscPayload, CreateRSCHandlerOptions } from "./types.js";
+import type {
+  RscPayload,
+  CreateRSCHandlerOptions,
+  LoadSSRModule,
+  SSRModule,
+} from "./types.js";
 import {
   createResponseWithMergedHeaders,
   finalizeResponse,
@@ -66,6 +71,17 @@ import {
   createDefaultTimeoutResponse,
   type TimeoutPhase,
 } from "../router/timeout.js";
+import {
+  createMetricsStore,
+  appendMetric,
+  buildMetricsTiming,
+} from "../router/metrics.js";
+import {
+  startSSRSetup,
+  getSSRSetup,
+  mayNeedSSR,
+  SSR_SETUP_VAR,
+} from "./ssr-setup.js";
 
 /**
  * Create an RSC request handler.
@@ -117,10 +133,22 @@ export function createRSCHandler<
     decodeFormState,
   } = deps;
 
-  // Use provided loadSSRModule or default to vite RSC module loader
-  const loadSSRModule =
+  // Use provided loadSSRModule or default to vite RSC module loader.
+  // In production the SSR module is stable across requests, so memoize
+  // the dynamic import to avoid repeated module resolution overhead.
+  // In dev mode Vite may hot-reload the module, so skip memoization.
+  const rawLoadSSRModule: LoadSSRModule =
     options.loadSSRModule ??
     (() => import.meta.viteRsc.loadModule("ssr", "index"));
+  let _ssrModulePromise: Promise<SSRModule> | undefined;
+  const loadSSRModule: LoadSSRModule =
+    process.env.NODE_ENV === "production"
+      ? () =>
+          (_ssrModulePromise ??= rawLoadSSRModule().catch((err) => {
+            _ssrModulePromise = undefined;
+            throw err;
+          }))
+      : rawLoadSSRModule;
 
   /**
    * Per-request error reporter that deduplicates via the ALS request context.
@@ -268,6 +296,11 @@ export function createRSCHandler<
     input: RouterRequestInput<TEnv> = {},
   ): Promise<Response> {
     const handlerStart = performance.now();
+    // Create the metrics store at handler start so handler:total has startTime=0
+    // and all metrics are relative to the request entry point.
+    const earlyMetricsStore = router.debugPerformance
+      ? createMetricsStore(true, handlerStart)
+      : undefined;
 
     const { env = {} as TEnv, vars: initialVars, ctx: executionCtx } = input;
 
@@ -381,6 +414,10 @@ export function createRSCHandler<
       executionContext: executionCtx,
       themeConfig: router.themeConfig,
     });
+    if (earlyMetricsStore) {
+      requestContext._debugPerformance = true;
+      requestContext._metricsStore = earlyMetricsStore;
+    }
     // Wire background error reporting so "use cache" and other subsystems
     // can surface non-fatal errors through the router's onError callback.
     requestContext._reportBackgroundError = (
@@ -422,6 +459,7 @@ export function createRSCHandler<
       };
 
       // Execute middleware chain if any, otherwise call core handler directly
+      let response: Response;
       if (matchedMiddleware.length > 0) {
         const mwResponse = await executeMiddleware(
           matchedMiddleware,
@@ -440,13 +478,52 @@ export function createRSCHandler<
             mwResponse,
             createRedirectFlightResponse,
           );
-          if (intercepted) return intercepted;
+          response = intercepted ?? finalizeResponse(mwResponse);
+        } else {
+          response = finalizeResponse(mwResponse);
         }
+      } else {
+        response = await coreHandler();
+      }
 
-        return finalizeResponse(mwResponse);
+      // Finalize metrics after all middleware (including post-next work)
+      // has completed so :post spans are captured in the timeline.
+      // Handler timing parts are always emitted (even without debug metrics)
+      // so non-debug requests still get bootstrap Server-Timing entries.
+      const handlerTimingArr: string[] = variables.__handlerTiming || [];
+      // Preserve any existing Server-Timing set by response routes or middleware
+      const existingTiming = response.headers.get("Server-Timing");
+      const timingParts = existingTiming
+        ? [existingTiming, ...handlerTimingArr]
+        : [...handlerTimingArr];
+
+      const metricsStore = requestContext._metricsStore;
+      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.
+        const totalStart = earlyMetricsStore
+          ? handlerStart
+          : metricsStore.requestStart;
+        appendMetric(
+          metricsStore,
+          "handler:total",
+          totalStart,
+          performance.now() - totalStart,
+        );
+        const metricsTiming = buildMetricsTiming(
+          request.method,
+          url.pathname,
+          metricsStore,
+        );
+        if (metricsTiming) timingParts.push(metricsTiming);
       }
 
-      return coreHandler();
+      const fullTiming = timingParts.join(", ");
+      if (fullTiming) response.headers.set("Server-Timing", fullTiming);
+
+      return response;
     });
   };
 
@@ -490,6 +567,21 @@ export function createRSCHandler<
       return responseOutcome.result;
     }
 
+    // Kick off SSR module loading + stream mode resolution in parallel with
+    // segment resolution. Placed after the response-route short-circuit so
+    // response/mime routes never pay for SSR work.
+    if (mayNeedSSR(request, url)) {
+      variables[SSR_SETUP_VAR] = startSSRSetup(
+        handlerCtx,
+        request,
+        env,
+        url,
+        router.debugPerformance
+          ? () => requireRequestContext()._metricsStore
+          : undefined,
+      );
+    }
+
     const routeReverse = createReverseFunction(getRequiredRouteMap());
 
     const isAction =
@@ -964,11 +1056,14 @@ export function createRSCHandler<
           });
         }
 
-        // Delegate to SSR for HTML response
-        const [ssrModule, streamMode] = await Promise.all([
-          loadSSRModule(),
-          handlerCtx.resolveStreamMode(request, env, url),
-        ]);
+        // Delegate to SSR for HTML response (reuse early setup if available)
+        const [ssrModule, streamMode] = await getSSRSetup(
+          handlerCtx,
+          request,
+          env,
+          url,
+          requireRequestContext()._metricsStore,
+        );
         const htmlStream = await ssrModule.renderHTML(rscStream, {
           nonce,
           streamMode,

package/src/rsc/index.ts

@@ -29,28 +29,8 @@ export type {
   NonceProvider,
 } from "./types.js";
 
-// Re-export HandleStore types for consumers who need custom handling
-export {
-  createHandleStore,
-  type HandleStore,
-  type HandleData,
-} from "../server/handle-store.js";
-
 // Re-export request context utilities for server-side access to env/request/params
 export {
   getRequestContext,
   requireRequestContext,
-  setRequestContextParams,
 } from "../server/request-context.js";
-
-// Re-export cache store types and implementations
-export type {
-  SegmentCacheStore,
-  CachedEntryData,
-  CachedEntryResult,
-  SegmentCacheProvider,
-  SegmentHandleData,
-} from "../cache/types.js";
-
-export { MemorySegmentCacheStore } from "../cache/memory-segment-store.js";
-export { CFCacheStore, type CFCacheStoreOptions } from "../cache/cf/index.js";

package/src/rsc/progressive-enhancement.ts

@@ -10,6 +10,7 @@ import {
   requireRequestContext,
   setRequestContextParams,
 } from "../server/request-context.js";
+import { getSSRSetup } from "./ssr-setup.js";
 import type { MiddlewareFn } from "../router/middleware.js";
 import { executeMiddleware } from "../router/middleware.js";
 import type { RscPayload, ReactFormState } from "./types.js";
@@ -257,10 +258,16 @@ export async function handleProgressiveEnhancement<TEnv>(
     };
 
     const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
-    const [ssrModule, streamMode] = await Promise.all([
-      ctx.loadSSRModule(),
-      ctx.resolveStreamMode(request, env, url),
-    ]);
+    // metricsStore=undefined is safe: the handler already stashed the early
+    // SSR setup promise on request variables, so getSSRSetup returns it
+    // without falling back to a fresh startSSRSetup.
+    const [ssrModule, streamMode] = await getSSRSetup(
+      ctx,
+      request,
+      env,
+      url,
+      undefined,
+    );
     const htmlStream = await ssrModule.renderHTML(rscStream, {
       formState: reactFormState,
       nonce,
@@ -350,10 +357,16 @@ async function renderPeErrorBoundary<TEnv>(
   };
 
   const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
-  const [ssrModule, streamMode] = await Promise.all([
-    ctx.loadSSRModule(),
-    ctx.resolveStreamMode(request, env, url),
-  ]);
+  // metricsStore=undefined is safe: the handler already stashed the early
+  // SSR setup promise on request variables, so getSSRSetup returns it
+  // without falling back to a fresh startSSRSetup.
+  const [ssrModule, streamMode] = await getSSRSetup(
+    ctx,
+    request,
+    env,
+    url,
+    undefined,
+  );
   const htmlStream = await ssrModule.renderHTML(rscStream, {
     nonce,
     streamMode,