@rangojs/router 0.0.0-experimental.23 → 0.0.0-experimental.25

package/dist/vite/index.js

@@ -1745,7 +1745,7 @@ import { resolve } from "node:path";
 // package.json
 var package_default = {
   name: "@rangojs/router",
-  version: "0.0.0-experimental.23",
+  version: "0.0.0-experimental.25",
   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.23",
+  "version": "0.0.0-experimental.25",
   "description": "Django-inspired RSC router with composable URL patterns",
   "keywords": [
     "react",

package/src/router/match-result.ts

@@ -108,7 +108,7 @@
  */
 import type { MatchResult, ResolvedSegment } from "../types.js";
 import type { MatchContext, MatchPipelineState } from "./match-context.js";
-import { generateServerTiming, logMetrics } from "./metrics.js";
+import { generateServerTiming } from "./metrics.js";
 import { debugLog } from "./logging.js";
 
 /**
@@ -189,7 +189,6 @@ export function buildMatchResult<TEnv>(
   // Output metrics if enabled
   let serverTiming: string | undefined;
   if (ctx.metricsStore) {
-    logMetrics(ctx.request.method, ctx.pathname, ctx.metricsStore);
     serverTiming = generateServerTiming(ctx.metricsStore);
   }
 

package/src/router/metrics.ts

@@ -69,6 +69,42 @@ export function createMetricsStore(
   };
 }
 
+/**
+ * Append a metric to the request store using an absolute start timestamp.
+ */
+export function appendMetric(
+  metricsStore: MetricsStore | undefined,
+  label: string,
+  start: number,
+  duration: number,
+  depth?: number,
+): void {
+  if (!metricsStore) return;
+  metricsStore.metrics.push({
+    label,
+    duration,
+    startTime: start - metricsStore.requestStart,
+    depth,
+  });
+}
+
+/**
+ * Log the current request metrics and return the corresponding Server-Timing value.
+ * Falls back to an existing header value when no metrics store is active.
+ */
+export function buildMetricsTiming(
+  method: string,
+  pathname: string,
+  metricsStore: MetricsStore | undefined,
+  fallback?: string,
+): string | undefined {
+  if (!metricsStore) {
+    return fallback;
+  }
+  logMetrics(method, pathname, metricsStore);
+  return generateServerTiming(metricsStore) || undefined;
+}
+
 /**
  * Log metrics to console in a formatted way.
  * Uses a shared-axis timeline so overlapping work stays visible.

package/src/router/middleware.ts

@@ -20,6 +20,7 @@ import type {
 } from "./middleware-types.js";
 import { _getRequestContext } from "../server/request-context.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
+import { appendMetric, createMetricsStore } from "./metrics.js";
 
 // Re-export types and cookie utilities for backward compatibility
 export type {
@@ -49,6 +50,29 @@ function warnCtxSetBeforeRedirect(handler: Function): void {
   );
 }
 
+const MIDDLEWARE_METRIC_DEPTH = 1;
+
+function getMiddlewareMetricBase<TEnv>(
+  entry: MiddlewareEntry<TEnv>,
+  ordinal: number,
+): string {
+  const handlerName = entry.handler.name?.trim();
+  const scope = entry.pattern ?? "*";
+
+  if (handlerName) {
+    return `${handlerName}@${scope}`;
+  }
+
+  return `${scope}#${ordinal + 1}`;
+}
+
+function getMiddlewareMetricLabel<TEnv>(
+  entry: MiddlewareEntry<TEnv>,
+  ordinal: number,
+): string {
+  return `middleware:${getMiddlewareMetricBase(entry, ordinal)}`;
+}
+
 /** Reset W5 deduplication state (for tests only). */
 export function _resetW5Warnings(): void {
   warnedRedirectMiddleware = new WeakSet();
@@ -232,6 +256,7 @@ export function createMiddlewareContext<TEnv>(
       const reqCtx = _getRequestContext();
       if (reqCtx) {
         reqCtx._debugPerformance = true;
+        reqCtx._metricsStore ??= createMetricsStore(true);
       }
     },
   };
@@ -346,6 +371,7 @@ export async function executeMiddleware<TEnv>(
       return responseHolder.response;
     }
 
+    const middlewareOrdinal = index;
     const { entry, params } = middlewares[index++];
     const ctx = createMiddlewareContext(
       request,
@@ -355,6 +381,20 @@ export async function executeMiddleware<TEnv>(
       responseHolder,
       reverse,
     );
+    const metricStart = performance.now();
+    let middlewareFinished = false;
+    const finishMiddleware = () => {
+      if (!middlewareFinished) {
+        middlewareFinished = true;
+        appendMetric(
+          _getRequestContext()?._metricsStore,
+          getMiddlewareMetricLabel(entry, middlewareOrdinal),
+          metricStart,
+          performance.now() - metricStart,
+          MIDDLEWARE_METRIC_DEPTH,
+        );
+      }
+    };
 
     // Track if next() was called and capture its Promise.
     // Guard against double-calling: a second call would re-enter the
@@ -366,6 +406,7 @@ export async function executeMiddleware<TEnv>(
           `[@rangojs/router] Middleware called next() more than once.`,
         );
       }
+      finishMiddleware();
       nextPromise = next();
       return nextPromise;
     };
@@ -380,7 +421,14 @@ export async function executeMiddleware<TEnv>(
       }) as typeof ctx.set;
     }
 
-    const result = await entry.handler(ctx, wrappedNext);
+    let result: Response | void;
+    try {
+      result = await entry.handler(ctx, wrappedNext);
+    } catch (error) {
+      finishMiddleware();
+      throw error;
+    }
+    finishMiddleware();
 
     // Explicit return takes precedence (middleware short-circuit).
     // Merge stub headers (from ctx.header before this point) and

package/src/router/router-interfaces.ts

@@ -269,6 +269,12 @@ export interface RSCRouterInternal<
    */
   readonly warmupEnabled: boolean;
 
+  /**
+   * Whether router-wide performance debugging is enabled.
+   * Used by the request handler to create metrics before middleware runs.
+   */
+  readonly debugPerformance?: boolean;
+
   /**
    * Whether ?__debug_manifest is allowed in production.
    * Always enabled in development.

package/src/router.ts

@@ -359,10 +359,16 @@ export function createRouter<TEnv = any>(
 
   // Wrapper to pass debugPerformance to external createMetricsStore.
   // Also checks per-request flag set by ctx.debugPerformance() in middleware.
-  const getMetricsStore = () =>
-    createMetricsStore(
-      debugPerformance || !!_getRequestContext()?._debugPerformance,
-    );
+  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) =>
@@ -879,6 +885,9 @@ export function createRouter<TEnv = any>(
     // 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

@@ -66,6 +66,7 @@ import {
   createDefaultTimeoutResponse,
   type TimeoutPhase,
 } from "../router/timeout.js";
+import { createMetricsStore } from "../router/metrics.js";
 
 /**
  * Create an RSC request handler.
@@ -381,6 +382,10 @@ export function createRSCHandler<
       executionContext: executionCtx,
       themeConfig: router.themeConfig,
     });
+    if (router.debugPerformance) {
+      requestContext._debugPerformance = true;
+      requestContext._metricsStore ??= createMetricsStore(true);
+    }
     // Wire background error reporting so "use cache" and other subsystems
     // can surface non-fatal errors through the router's onError callback.
     requestContext._reportBackgroundError = (

package/src/rsc/rsc-rendering.ts

@@ -12,6 +12,7 @@ import {
   getLocationState,
 } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
+import { appendMetric, buildMetricsTiming } from "../router/metrics.js";
 import type { RscPayload } from "./types.js";
 import {
   createResponseWithMergedHeaders,
@@ -166,10 +167,20 @@ export async function handleRscRendering<TEnv>(
     }
   }
 
+  const metricsStore = reqCtx._metricsStore;
+  const renderStart = performance.now();
+
   // Serialize to RSC stream
   const rscSerializeStart = performance.now();
   const rscStream = ctx.renderToReadableStream<RscPayload>(payload);
   const rscSerializeDur = performance.now() - rscSerializeStart;
+  // This measures synchronous stream creation, not end-to-end stream consumption.
+  appendMetric(
+    metricsStore,
+    "rsc-serialize",
+    rscSerializeStart,
+    rscSerializeDur,
+  );
 
   // Determine if this is an RSC request or HTML request.
   // Partial requests (_rsc_partial) are always RSC -- they come from client-side
@@ -183,12 +194,19 @@ export async function handleRscRendering<TEnv>(
 
   // Build complete Server-Timing: handler phases + match/manifest + RSC serialize
   const timingParts: string[] = [...handlerTimingArr];
-  if (serverTiming) {
-    timingParts.push(serverTiming);
-  }
-  timingParts.push(`rsc-serialize;dur=${rscSerializeDur.toFixed(2)}`);
 
   if (isRscRequest) {
+    const renderDur = performance.now() - renderStart;
+    appendMetric(metricsStore, "render:total", renderStart, renderDur);
+    const metricsTiming = buildMetricsTiming(
+      request.method,
+      url.pathname,
+      metricsStore,
+      serverTiming,
+    );
+    if (metricsTiming) {
+      timingParts.push(metricsTiming);
+    }
     const fullTiming = timingParts.join(", ");
     const rscHeaders: Record<string, string> = {
       "content-type": "text/x-component;charset=utf-8",
@@ -220,7 +238,7 @@ export async function handleRscRendering<TEnv>(
     ctx.resolveStreamMode(request, env, url),
   ]);
   const ssrSetupDur = performance.now() - ssrSetupStart;
-  timingParts.push(`ssr-setup;dur=${ssrSetupDur.toFixed(2)}`);
+  appendMetric(metricsStore, "ssr-setup", ssrSetupStart, ssrSetupDur);
 
   const ssrRenderStart = performance.now();
   const htmlStream = await ssrModule.renderHTML(rscStream, {
@@ -228,7 +246,7 @@ export async function handleRscRendering<TEnv>(
     streamMode,
   });
   const ssrRenderDur = performance.now() - ssrRenderStart;
-  timingParts.push(`ssr-render-html;dur=${ssrRenderDur.toFixed(2)}`);
+  appendMetric(metricsStore, "ssr-render-html", ssrRenderStart, ssrRenderDur);
 
   // Add total handler duration
   if (handlerStart) {
@@ -236,6 +254,18 @@ export async function handleRscRendering<TEnv>(
     timingParts.push(`handler-total;dur=${totalHandler.toFixed(2)}`);
   }
 
+  const renderDur = performance.now() - renderStart;
+  appendMetric(metricsStore, "render:total", renderStart, renderDur);
+  const metricsTiming = buildMetricsTiming(
+    request.method,
+    url.pathname,
+    metricsStore,
+    serverTiming,
+  );
+  if (metricsTiming) {
+    timingParts.push(metricsTiming);
+  }
+
   const fullTiming = timingParts.join(", ");
   const htmlHeaders: Record<string, string> = {
     "content-type": "text/html;charset=utf-8",

package/src/rsc/server-action.ts

@@ -21,6 +21,7 @@ import {
   getLocationState,
 } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
+import { appendMetric, buildMetricsTiming } from "../router/metrics.js";
 import type { RscPayload } from "./types.js";
 import {
   hasBodyContent,
@@ -274,6 +275,8 @@ export async function revalidateAfterAction<TEnv>(
 ): Promise<Response> {
   const { returnValue, actionStatus, temporaryReferences, actionContext } =
     continuation;
+  const reqCtx = requireRequestContext();
+  const metricsStore = reqCtx._metricsStore;
 
   const matchResult = await ctx.router.matchPartial(
     request,
@@ -326,15 +329,31 @@ export async function revalidateAfterAction<TEnv>(
 
   attachLocationState(payload);
 
+  const renderStart = performance.now();
   const rscStream = ctx.renderToReadableStream<RscPayload>(payload, {
     temporaryReferences,
   });
+  const rscSerializeDur = performance.now() - renderStart;
+  // This measures synchronous stream creation, not end-to-end stream consumption.
+  appendMetric(metricsStore, "rsc-serialize", renderStart, rscSerializeDur);
+  appendMetric(
+    metricsStore,
+    "render:total",
+    renderStart,
+    performance.now() - renderStart,
+  );
 
   const actionHeaders: Record<string, string> = {
     "content-type": "text/x-component;charset=utf-8",
   };
-  if (serverTiming) {
-    actionHeaders["Server-Timing"] = serverTiming;
+  const metricsTiming = buildMetricsTiming(
+    request.method,
+    url.pathname,
+    metricsStore,
+    serverTiming,
+  );
+  if (metricsTiming) {
+    actionHeaders["Server-Timing"] = metricsTiming;
   }
 
   return createResponseWithMergedHeaders(rscStream, {

package/src/server/request-context.ts

@@ -23,7 +23,7 @@ import type { Handle } from "../handle.js";
 import { type ContextVar, contextGet, contextSet } from "../context-var.js";
 import { createHandleStore, type HandleStore } from "./handle-store.js";
 import { isHandle } from "../handle.js";
-import { track } from "./context.js";
+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";
@@ -269,6 +269,9 @@ export interface RequestContext<
 
   /** @internal Per-request debug performance override (set via ctx.debugPerformance()) */
   _debugPerformance?: boolean;
+
+  /** @internal Request-scoped performance metrics store */
+  _metricsStore?: MetricsStore;
 }
 
 /**
@@ -297,6 +300,7 @@ export type PublicRequestContext<
   | "_reportedErrors"
   | "_reportBackgroundError"
   | "_debugPerformance"
+  | "_metricsStore"
 >;
 
 // AsyncLocalStorage instance for request context
@@ -681,6 +685,7 @@ export function createRequestContext<TEnv>(
     _locationState: undefined,
 
     _reportedErrors: new WeakSet<object>(),
+    _metricsStore: undefined,
 
     reverse: createReverseFunction(getGlobalRouteMap(), undefined, {}),
   };