@rangojs/router 0.0.0-experimental.0b82333f

package/src/router/metrics.ts

@@ -0,0 +1,282 @@
+/**
+ * Router Metrics Utilities
+ *
+ * Performance metrics collection and reporting for RSC Router.
+ */
+
+import type { MetricsStore, PerformanceMetric } from "../server/context";
+
+const BASE_INDENT = 2;
+const DEPTH_INDENT = 2;
+const TIMELINE_WIDTH = 40;
+
+function formatMs(value: number): string {
+  return `${value.toFixed(2)}ms`;
+}
+
+function sortMetrics(metrics: PerformanceMetric[]): PerformanceMetric[] {
+  return [...metrics].sort((a, b) => a.startTime - b.startTime);
+}
+
+interface Span {
+  startTime: number;
+  duration: number;
+}
+
+function renderTimeline(spans: Span[], total: number): string {
+  if (TIMELINE_WIDTH <= 0) {
+    return "||";
+  }
+
+  const cells = Array(TIMELINE_WIDTH).fill(".");
+
+  if (!(total > 0)) {
+    cells[0] = "#";
+    return `|${cells.join("")}|`;
+  }
+
+  for (const span of spans) {
+    const start = Math.max(0, span.startTime);
+    const end = Math.max(start, span.startTime + span.duration);
+    const startColumn = Math.min(
+      TIMELINE_WIDTH - 1,
+      Math.floor((start / total) * TIMELINE_WIDTH),
+    );
+    const endColumn = Math.max(
+      startColumn + 1,
+      Math.min(
+        TIMELINE_WIDTH,
+        Math.ceil((Math.min(total, end) / total) * TIMELINE_WIDTH),
+      ),
+    );
+
+    cells.fill("#", startColumn, endColumn);
+  }
+
+  return `|${cells.join("")}|`;
+}
+
+function createTimelineAxis(total: number): string {
+  const totalLabel = formatMs(total);
+  return `0ms${" ".repeat(
+    Math.max(1, TIMELINE_WIDTH - "0ms".length - totalLabel.length),
+  )}${totalLabel}`;
+}
+
+/**
+ * Create a metrics store for the request if debugPerformance is enabled.
+ * An optional `requestStart` timestamp can anchor the store to an earlier
+ * point (e.g. handler start) so that handler:total has startTime=0.
+ */
+export function createMetricsStore(
+  debugPerformance: boolean,
+  requestStart?: number,
+): MetricsStore | undefined {
+  if (!debugPerformance) return undefined;
+  return {
+    enabled: true,
+    requestStart: requestStart ?? performance.now(),
+    metrics: [],
+  };
+}
+
+/**
+ * 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.
+ */
+export function buildMetricsTiming(
+  method: string,
+  pathname: string,
+  metricsStore: MetricsStore | undefined,
+): string | undefined {
+  if (!metricsStore) return undefined;
+  logMetrics(method, pathname, metricsStore);
+  return generateServerTiming(metricsStore) || undefined;
+}
+
+/** Display row produced by merging :pre/:post metric pairs. */
+interface DisplayRow {
+  label: string;
+  startTime: number;
+  duration: number;
+  depth: number | undefined;
+  spans: Span[];
+}
+
+/**
+ * Build display rows from sorted metrics, merging :pre/:post pairs into
+ * a single row with disjoint timeline segments.
+ */
+function buildDisplayRows(sorted: PerformanceMetric[]): DisplayRow[] {
+  // Index :pre and :post metrics by their base label
+  const preMap = new Map<string, PerformanceMetric>();
+  const postMap = new Map<string, PerformanceMetric>();
+  const consumed = new Set<PerformanceMetric>();
+
+  for (const m of sorted) {
+    if (m.label.endsWith(":pre")) {
+      preMap.set(m.label.slice(0, -4), m);
+    } else if (m.label.endsWith(":post")) {
+      postMap.set(m.label.slice(0, -5), m);
+    }
+  }
+
+  const rows: DisplayRow[] = [];
+
+  for (const m of sorted) {
+    if (consumed.has(m)) continue;
+
+    if (m.label.endsWith(":pre")) {
+      const base = m.label.slice(0, -4);
+      const post = postMap.get(base);
+      if (post) {
+        // Merge into a single row with two disjoint spans
+        consumed.add(m);
+        consumed.add(post);
+        rows.push({
+          label: base,
+          startTime: m.startTime,
+          duration: m.duration + post.duration,
+          depth: m.depth,
+          spans: [
+            { startTime: m.startTime, duration: m.duration },
+            { startTime: post.startTime, duration: post.duration },
+          ],
+        });
+        continue;
+      }
+      // Lone :pre — display with base label
+      consumed.add(m);
+      rows.push({
+        label: base,
+        startTime: m.startTime,
+        duration: m.duration,
+        depth: m.depth,
+        spans: [{ startTime: m.startTime, duration: m.duration }],
+      });
+      continue;
+    }
+
+    if (m.label.endsWith(":post")) {
+      const base = m.label.slice(0, -5);
+      if (preMap.has(base)) {
+        // Already consumed as part of the pair above
+        continue;
+      }
+      // Lone :post — display with base label
+      consumed.add(m);
+      rows.push({
+        label: base,
+        startTime: m.startTime,
+        duration: m.duration,
+        depth: m.depth,
+        spans: [{ startTime: m.startTime, duration: m.duration }],
+      });
+      continue;
+    }
+
+    // Regular metric
+    rows.push({
+      label: m.label,
+      startTime: m.startTime,
+      duration: m.duration,
+      depth: m.depth,
+      spans: [{ startTime: m.startTime, duration: m.duration }],
+    });
+  }
+
+  return rows;
+}
+
+/**
+ * Log metrics to console in a formatted way.
+ * Uses a shared-axis timeline so overlapping work stays visible.
+ * Merges :pre/:post pairs onto one row with disjoint timeline segments.
+ */
+export function logMetrics(
+  method: string,
+  pathname: string,
+  metricsStore: MetricsStore,
+): void {
+  const total = performance.now() - metricsStore.requestStart;
+
+  const sorted = sortMetrics(metricsStore.metrics);
+  const displayRows = buildDisplayRows(sorted);
+
+  const labels = displayRows.map(
+    (r) =>
+      `${" ".repeat(BASE_INDENT + (r.depth ?? 0) * DEPTH_INDENT)}${r.label}`,
+  );
+  const startValues = displayRows.map((r) => formatMs(r.startTime));
+  const durationValues = displayRows.map((r) => formatMs(r.duration));
+  const startWidth = Math.max(
+    "start".length,
+    ...startValues.map((v) => v.length),
+  );
+  const durationWidth = Math.max(
+    "dur".length,
+    ...durationValues.map((v) => v.length),
+  );
+  const spanWidth = Math.max(
+    "span".length,
+    ...labels.map((label) => label.length),
+    22,
+  );
+  const timelinePadding = " ".repeat(
+    startWidth + 2 + durationWidth + 2 + spanWidth + 2,
+  );
+
+  console.log(`[RSC Perf] ${method} ${pathname} (${total.toFixed(2)}ms)`);
+  console.log(
+    `${"start".padStart(startWidth)}  ${"dur".padStart(durationWidth)}  ${"span".padEnd(spanWidth)}  timeline`,
+  );
+  console.log(`${timelinePadding}${createTimelineAxis(total)}`);
+
+  for (let index = 0; index < displayRows.length; index++) {
+    const row = displayRows[index];
+    const label = labels[index].padEnd(spanWidth);
+    const start = formatMs(row.startTime).padStart(startWidth);
+    const duration = formatMs(row.duration).padStart(durationWidth);
+
+    console.log(
+      `${start}  ${duration}  ${label}  ${renderTimeline(row.spans, total)}`,
+    );
+  }
+}
+
+/**
+ * Generate Server-Timing header value from metrics
+ * Format: metric-name;dur=X.XX
+ * Depth is encoded as a "d{N}-" prefix for nested metrics.
+ */
+export function generateServerTiming(metricsStore: MetricsStore): string {
+  return metricsStore.metrics
+    .map((m) => {
+      // Convert label to valid Server-Timing name (alphanumeric and hyphens)
+      const base = m.label
+        .replace(/:/g, "-")
+        .replace(/[^a-zA-Z0-9-]/g, "")
+        .toLowerCase();
+      const name = m.depth ? `d${m.depth}-${base}` : base;
+      return `${name};dur=${m.duration.toFixed(2)}`;
+    })
+    .join(", ");
+}

package/src/router/middleware-cookies.ts

@@ -0,0 +1,55 @@
+/**
+ * Cookie Utilities
+ *
+ * Parsing and serialization for HTTP cookies used by middleware context.
+ */
+
+import type { CookieOptions } from "./middleware-types.js";
+
+/**
+ * Parse cookies from Cookie header
+ */
+export function parseCookies(
+  cookieHeader: string | null,
+): Record<string, string> {
+  if (!cookieHeader) return {};
+
+  const cookies: Record<string, string> = {};
+  const pairs = cookieHeader.split(";");
+
+  for (const pair of pairs) {
+    const [name, ...rest] = pair.trim().split("=");
+    if (name) {
+      const raw = rest.join("=");
+      try {
+        cookies[name] = decodeURIComponent(raw);
+      } catch {
+        // Malformed percent-encoded value (e.g. %zz) - fall back to raw value
+        cookies[name] = raw;
+      }
+    }
+  }
+
+  return cookies;
+}
+
+/**
+ * Serialize a cookie for Set-Cookie header
+ */
+export function serializeCookie(
+  name: string,
+  value: string,
+  options: CookieOptions = {},
+): string {
+  let cookie = `${encodeURIComponent(name)}=${encodeURIComponent(value)}`;
+
+  if (options.domain) cookie += `; Domain=${options.domain}`;
+  if (options.path) cookie += `; Path=${options.path}`;
+  if (options.maxAge !== undefined) cookie += `; Max-Age=${options.maxAge}`;
+  if (options.expires) cookie += `; Expires=${options.expires.toUTCString()}`;
+  if (options.httpOnly) cookie += "; HttpOnly";
+  if (options.secure) cookie += "; Secure";
+  if (options.sameSite) cookie += `; SameSite=${options.sameSite}`;
+
+  return cookie;
+}

package/src/router/middleware-types.ts

@@ -0,0 +1,222 @@
+/**
+ * Middleware Types
+ *
+ * Type definitions and interfaces for the middleware system.
+ * Separated from execution logic for cleaner imports.
+ */
+
+import type { ContextVar } from "../context-var.js";
+import type {
+  DefaultReverseRouteMap,
+  DefaultRouteName,
+  DefaultVars,
+} from "../types/global-namespace.js";
+import type { ScopedReverseFunction } from "../reverse.js";
+import type { Theme } from "../theme/types.js";
+import type { LocationStateEntry } from "../browser/react/location-state-shared.js";
+
+/**
+ * Get variable function type
+ */
+type GetVariableFn = {
+  <T>(contextVar: ContextVar<T>): T | undefined;
+  <K extends keyof DefaultVars>(key: K): DefaultVars[K];
+};
+
+/**
+ * Set variable function type
+ */
+type SetVariableFn = {
+  <T>(contextVar: ContextVar<T>, value: T): void;
+  <K extends keyof DefaultVars>(key: K, value: DefaultVars[K]): void;
+};
+
+/**
+ * Cookie options for setting cookies
+ */
+export interface CookieOptions {
+  domain?: string;
+  path?: string;
+  maxAge?: number;
+  expires?: Date;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: "strict" | "lax" | "none";
+}
+
+/**
+ * Context passed to middleware
+ *
+ * @template TEnv - Environment type (bindings, variables) - defaults to any for internal flexibility
+ * @template TParams - URL params type (typed for route middleware, Record<string, string> for global middleware)
+ */
+export interface MiddlewareContext<
+  TEnv = any,
+  TParams = Record<string, string>,
+> {
+  /** Original 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 */
+  searchParams: URLSearchParams;
+
+  /** Platform bindings (Cloudflare, etc.) */
+  env: TEnv;
+
+  /** URL params extracted from route/middleware pattern */
+  params: TParams;
+
+  /**
+   * Response headers.
+   * Before `next()`, returns headers from the shared response stub.
+   * After `next()`, returns headers from the downstream response.
+   */
+  readonly headers: Headers;
+
+  /** Get a context variable (shared with route handlers) */
+  get: GetVariableFn;
+
+  /** Set a context variable (shared with route handlers) */
+  set: SetVariableFn;
+
+  /**
+   * Middleware-injected variables.
+   * Same shared dictionary as `ctx.get()`/`ctx.set()`.
+   */
+  var: DefaultVars;
+
+  /**
+   * Set a response header - can be called before or after `next()`.
+   *
+   * When called before `next()`, headers are queued and merged into the final response.
+   * When called after `next()`, headers are set directly on the response.
+   */
+  header(name: string, value: string): void;
+
+  /**
+   * The matched route name, if available and the route has an explicit name.
+   * Undefined for global middleware (runs before route matching) or unnamed routes.
+   */
+  routeName?: DefaultRouteName;
+
+  /**
+   * Enable performance metrics for this request.
+   * When called, granular timing breakdown is logged to console and
+   * included in the Server-Timing response header, regardless of the
+   * router-level `debugPerformance` option.
+   *
+   * Call **before** `await next()` so the metrics store exists when
+   * downstream phases (route matching, rendering, SSR) record their
+   * spans. Calling after `next()` returns still emits `handler:total`
+   * but misses all upstream metrics.
+   */
+  debugPerformance(): void;
+
+  /**
+   * Current theme (from cookie or default).
+   * Only available when theme is enabled in router config.
+   */
+  theme?: Theme;
+
+  /**
+   * Set the theme (only available when theme is enabled in router config).
+   * Sets a cookie with the new theme value.
+   */
+  setTheme?: (theme: Theme) => void;
+
+  /**
+   * Attach location state entries to this response.
+   * State is delivered to the client via history.pushState and accessible
+   * through the useLocationState() hook.
+   */
+  setLocationState(entries: LocationStateEntry | LocationStateEntry[]): void;
+
+  /**
+   * Generate URLs from route names.
+   * - `name` — global route, from the named-routes definition
+   */
+  reverse: ScopedReverseFunction<
+    Record<string, string>,
+    DefaultReverseRouteMap
+  >;
+}
+
+/**
+ * Middleware function signature
+ *
+ * @template TEnv - Environment type - defaults to any for internal flexibility
+ * @template TParams - URL params type (typed for route middleware)
+ *
+ * When using middleware with global augmentation (RSCRouter.Env), explicitly
+ * annotate your middleware functions, or the types will be inferred from context:
+ *
+ * @example
+ * ```typescript
+ * // With explicit annotation (recommended for reusable middleware)
+ * const authMiddleware: MiddlewareFn<AppEnv> = async (ctx, next) => {...}
+ *
+ * // Types inferred from router.use() call
+ * router.use((ctx, next) => {...}) // ctx is typed from router's TEnv
+ * ```
+ */
+export type MiddlewareFn<TEnv = any, TParams = Record<string, string>> = (
+  ctx: MiddlewareContext<TEnv, TParams>,
+  next: () => Promise<Response>,
+) => Response | void | Promise<Response | void>;
+
+/**
+ * Stored middleware entry with pattern matching info
+ * @internal - uses any for internal flexibility
+ */
+export interface MiddlewareEntry<TEnv = any> {
+  /** Original pattern string */
+  pattern: string | null;
+
+  /** Compiled regex for matching */
+  regex: RegExp | null;
+
+  /** Param names extracted from pattern */
+  paramNames: string[];
+
+  /** The middleware function */
+  handler: MiddlewareFn<TEnv>;
+
+  /** Mount prefix this middleware is scoped to (null = global) */
+  mountPrefix: string | null;
+}
+
+/**
+ * Mutable response holder - tracks the current response through the middleware chain.
+ */
+export interface ResponseHolder {
+  response: Response | null;
+}
+
+/**
+ * Entry type for middleware collection
+ * Matches the shape of EntryData used in router.ts
+ */
+export interface MiddlewareCollectableEntry {
+  middleware?: MiddlewareFn<any, any>[];
+  layout?: MiddlewareCollectableEntry[];
+}
+
+/**
+ * Collected route middleware with params
+ */
+export interface CollectedMiddleware {
+  handler: MiddlewareFn<any, any>;
+  params: Record<string, string>;
+}