@rangojs/router 0.0.0-experimental.259 → 0.0.0-experimental.25dbaac3

package/src/router/route-snapshot.ts

@@ -0,0 +1,245 @@
+/**
+ * Route Snapshot
+ *
+ * Pure data type representing the fully-resolved state of a single route match.
+ * Consolidates the duplicated findMatch + loadManifest + collectRouteMiddleware +
+ * cacheScope derivation that previously lived separately in preview-match.ts
+ * and match-api.ts.
+ *
+ * resolveRoute() is the factory: given a pathname and dependencies, it returns
+ * a RouteSnapshot (or redirect/null). Consumers (createMatchContextForFull,
+ * createMatchContextForPartial, previewMatch) read snapshot fields instead of
+ * re-deriving them.
+ */
+
+import type { CacheScope } from "../cache/cache-scope.js";
+import { createCacheScope } from "../cache/cache-scope.js";
+import type { EntryData, MetricsStore } from "../server/context.js";
+import { loadManifest } from "./manifest.js";
+import { collectRouteMiddleware } from "./middleware.js";
+import type { CollectedMiddleware } from "./middleware-types.js";
+import { traverseBack } from "./pattern-matching.js";
+import type { RouteMatchResult } from "./pattern-matching.js";
+
+/**
+ * Immutable snapshot of a resolved route match.
+ *
+ * Contains everything derivable from (pathname, findMatch, loadManifest)
+ * without request context, navigation state, or intercept logic.
+ */
+export interface RouteSnapshot<TEnv = any> {
+  /** Raw match result from the trie/pattern matcher */
+  matched: RouteMatchResult<TEnv>;
+  /** Resolved manifest entry (with loaded handler, loader, etc.) */
+  manifestEntry: EntryData;
+  /** All entries in the route chain (from traverseBack) */
+  entries: EntryData[];
+  /** Canonical route key (e.g. "blog.detail") */
+  routeKey: string;
+  /** Last segment of a dotted route key (e.g. "detail" from "blog.detail") */
+  localRouteName: string;
+  /** Extracted route params */
+  params: Record<string, string>;
+  /** Collected route-level middleware from the entry tree */
+  routeMiddleware: CollectedMiddleware[];
+  /** Merged cache scope from the entry chain */
+  cacheScope: CacheScope | null;
+  /** Whether the matched route is a passthrough route */
+  isPassthrough: boolean;
+  /** Response type for non-RSC routes (e.g. "application/json") */
+  responseType?: string;
+}
+
+export type ResolveRouteResult<TEnv = any> =
+  | { type: "match"; snapshot: RouteSnapshot<TEnv> }
+  | { type: "redirect"; redirectTo: string }
+  | null;
+
+export interface ResolveRouteDeps<TEnv = any> {
+  findMatch: (pathname: string) => RouteMatchResult<TEnv> | null;
+  metricsStore?: MetricsStore;
+  isSSR?: boolean;
+  /**
+   * When true, skip entries array and cacheScope chain construction.
+   * Used by previewMatch which only needs matched, manifestEntry,
+   * routeMiddleware, and responseType — avoids an extra traverseBack
+   * allocation and cacheScope composition on the hot classification path.
+   */
+  lite?: boolean;
+  /**
+   * When true, skip pushing the "route-matching" metric internally.
+   * Used by createMatchContextForPartial on the fresh path (no snapshot
+   * reuse) so it can measure current + prev + intercept-source findMatch
+   * calls under one combined "route-matching" metric. On the reuse path,
+   * the partial path emits "route-matching:nav" for the prev +
+   * intercept-source lookups only (current-route resolution was done
+   * during classification without metrics).
+   */
+  skipRouteMatchMetric?: boolean;
+}
+
+/**
+ * Resolve a pathname into a RouteSnapshot.
+ *
+ * This is the single source of truth for route derivation. It performs:
+ * 1. findMatch(pathname)
+ * 2. Redirect check
+ * 3. loadManifest
+ * 4. Passthrough detection
+ * 5. collectRouteMiddleware
+ * 6. Cache scope chain
+ * 7. responseType + localRouteName extraction
+ *
+ * Metrics timing is preserved identically to the previous inline code.
+ */
+export async function resolveRoute<TEnv = any>(
+  pathname: string,
+  deps: ResolveRouteDeps<TEnv>,
+): Promise<ResolveRouteResult<TEnv>> {
+  const {
+    metricsStore,
+    isSSR = false,
+    lite = false,
+    skipRouteMatchMetric = false,
+  } = deps;
+
+  const routeMatchStart =
+    metricsStore && !skipRouteMatchMetric ? performance.now() : 0;
+  const matched = deps.findMatch(pathname);
+  if (metricsStore && !skipRouteMatchMetric) {
+    metricsStore.metrics.push({
+      label: "route-matching",
+      duration: performance.now() - routeMatchStart,
+      startTime: routeMatchStart - metricsStore.requestStart,
+    });
+  }
+
+  if (!matched) {
+    return null;
+  }
+
+  if (matched.redirectTo) {
+    return { type: "redirect", redirectTo: matched.redirectTo };
+  }
+
+  const manifestStart = metricsStore ? performance.now() : 0;
+  const manifestEntry = await loadManifest(
+    matched.entry,
+    matched.routeKey,
+    pathname,
+    metricsStore,
+    isSSR,
+  );
+  if (metricsStore) {
+    metricsStore.metrics.push({
+      label: "manifest-loading",
+      duration: performance.now() - manifestStart,
+      startTime: manifestStart - metricsStore.requestStart,
+    });
+  }
+
+  const isPassthrough =
+    manifestEntry.type === "route" && manifestEntry.isPassthrough === true;
+
+  let entries: EntryData[];
+  let cacheScope: CacheScope | null = null;
+  if (lite) {
+    entries = [];
+  } else {
+    ({ entries, cacheScope } = buildEntriesAndCacheScope(manifestEntry));
+  }
+
+  const routeMiddleware = collectRouteMiddleware(
+    lite ? traverseBack(manifestEntry) : entries,
+    matched.params,
+  );
+
+  const responseType =
+    matched.responseType ||
+    (manifestEntry.type === "route" ? manifestEntry.responseType : undefined);
+
+  const localRouteName = matched.routeKey.includes(".")
+    ? matched.routeKey.split(".").pop()!
+    : matched.routeKey;
+
+  return {
+    type: "match",
+    snapshot: {
+      matched,
+      manifestEntry,
+      entries,
+      routeKey: matched.routeKey,
+      localRouteName,
+      params: matched.params,
+      routeMiddleware,
+      cacheScope,
+      isPassthrough,
+      responseType,
+    },
+  };
+}
+
+/**
+ * Fill in the entries and cacheScope fields on a lite snapshot.
+ *
+ * When classifyRequest produces a lite snapshot (entries=[], cacheScope=null),
+ * this function computes the missing fields from manifestEntry without
+ * re-running findMatch, loadManifest, or collectRouteMiddleware.
+ *
+ * If the snapshot already has entries, returns it as-is.
+ */
+export function ensureFullRouteSnapshot<TEnv = any>(
+  snapshot: RouteSnapshot<TEnv>,
+): RouteSnapshot<TEnv> {
+  if (snapshot.entries.length > 0) {
+    return snapshot;
+  }
+
+  const { entries, cacheScope } = buildEntriesAndCacheScope(
+    snapshot.manifestEntry,
+  );
+  return { ...snapshot, entries, cacheScope };
+}
+
+/**
+ * Materialize the entry chain and derive the merged cache scope.
+ * Shared by resolveRoute (non-lite) and ensureFullRouteSnapshot.
+ */
+function buildEntriesAndCacheScope(manifestEntry: EntryData): {
+  entries: EntryData[];
+  cacheScope: CacheScope | null;
+} {
+  const entries = [...traverseBack(manifestEntry)];
+  let cacheScope: CacheScope | null = null;
+  for (const entry of entries) {
+    if (entry.cache) {
+      cacheScope = createCacheScope(entry.cache, cacheScope);
+    }
+  }
+  return { entries, cacheScope };
+}
+
+/**
+ * Test helper: create a RouteSnapshot with sensible defaults and overrides.
+ */
+export function createRouteSnapshot<TEnv = any>(
+  overrides?: Partial<RouteSnapshot<TEnv>>,
+): RouteSnapshot<TEnv> {
+  return {
+    matched: {
+      entry: {} as any,
+      routeKey: "test",
+      params: {},
+      optionalParams: new Set(),
+    } as RouteMatchResult<TEnv>,
+    manifestEntry: { type: "route", shortCode: "R0", parent: null } as any,
+    entries: [],
+    routeKey: "test",
+    localRouteName: "test",
+    params: {},
+    routeMiddleware: [],
+    cacheScope: null,
+    isPassthrough: false,
+    ...overrides,
+  };
+}

package/src/router/router-context.ts

@@ -18,6 +18,7 @@ import type {
   ShouldRevalidateFn,
 } from "../types.js";
 import type { RouteMatchResult } from "./pattern-matching.js";
+import type { TelemetrySink } from "./telemetry.js";
 
 /**
  * Revalidation context passed to segment resolution
@@ -79,6 +80,7 @@ export interface RouterContext<TEnv = any> {
     routeMap?: Record<string, string>,
     routeName?: string,
     responseType?: string,
+    isPassthroughRoute?: boolean,
   ) => HandlerContext<any, TEnv>;
 
   // Loader setup
@@ -136,6 +138,7 @@ export interface RouterContext<TEnv = any> {
     interceptResult: InterceptResult | null,
     localRouteName: string,
     pathname: string,
+    stale?: boolean,
   ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
 
   // Generator-based segment resolution (for pipeline)
@@ -181,6 +184,15 @@ export interface RouterContext<TEnv = any> {
     context: HandlerContext<any, TEnv>;
     actionContext?: any;
     stale?: boolean;
+    traceSource?:
+      | "segment-resolution"
+      | "cache-hit"
+      | "loader"
+      | "parallel"
+      | "orphan-layout"
+      | "route-handler"
+      | "layout-handler"
+      | "intercept-loader";
   }) => Promise<boolean>;
 
   // Request context
@@ -198,6 +210,7 @@ export interface RouterContext<TEnv = any> {
     params: Record<string, string>,
     handlerContext: HandlerContext<any, TEnv>,
     loaderPromises: Map<string, Promise<any>>,
+    options?: { skipLoaders?: boolean },
   ) => Promise<ResolvedSegment[]>;
 
   // Generator-based simple resolution
@@ -234,6 +247,7 @@ export interface RouterContext<TEnv = any> {
     nextUrl: URL,
     routeKey: string,
     actionContext?: any,
+    stale?: boolean,
   ) => Promise<{ segments: ResolvedSegment[]; matchedIds: string[] }>;
 
   // Entry revalidation map
@@ -241,6 +255,12 @@ export interface RouterContext<TEnv = any> {
     entries: EntryData[],
   ) => Map<string, { revalidate: ShouldRevalidateFn[] }>;
 
+  // Telemetry sink (optional, no-op when undefined)
+  telemetry?: TelemetrySink;
+
+  // Request ID for telemetry span correlation (set per-request in match handlers)
+  requestId?: string;
+
   // Intercept loaders only (for cache hit + intercept scenarios)
   resolveInterceptLoadersOnly?: (
     intercept: InterceptEntry,

package/src/router/router-interfaces.ts

@@ -2,6 +2,7 @@ import type { ComponentType, ReactNode } from "react";
 import type { SerializedManifest } from "../debug.js";
 import type { ReverseFunction } from "../reverse.js";
 import type { UrlPatterns } from "../urls.js";
+import type { UrlBuilder } from "../urls/pattern-types.js";
 import type { EntryData } from "../server/context";
 import type { ErrorInfo, MatchResult } from "../types";
 import type { NonceProvider } from "../rsc/types.js";
@@ -14,6 +15,7 @@ import type { MiddlewareEntry, MiddlewareFn } from "./middleware.js";
 import { RSC_ROUTER_BRAND } from "./router-registry.js";
 import type { RSCRouterOptions, RootLayoutProps } from "./router-options.js";
 import type { DefaultVars } from "../types/global-namespace.js";
+import type { ResolvedTimeouts, OnTimeoutCallback } from "./timeout.js";
 
 /**
  * Options passed to router.fetch(), router.match(), and other request entrypoints.
@@ -47,19 +49,19 @@ type MergeRoutesWithResponses<
 };
 
 /**
- * RSC Router interface
- * TRoutes accumulates all registered route types through the builder chain
+ * Public RSC Router interface — the user-facing API surface.
+ *
+ * Users interact with this type when building and using routers.
+ * Internal framework code uses RSCRouterInternal (via toInternal()) to access
+ * matching, build-time, and configuration members that are not part of the
+ * public contract.
+ *
+ * TRoutes accumulates all registered route types through the builder chain.
  */
 export interface RSCRouter<
   TEnv = any,
   TRoutes extends Record<string, unknown> = Record<string, string>,
 > {
-  /**
-   * Brand marker for build-time discovery.
-   * The Vite plugin uses this to identify router instances in module exports.
-   */
-  readonly __brand: typeof RSC_ROUTER_BRAND;
-
   /**
    * Unique identifier for this router instance.
    * Used to namespace static output and isolate route maps between routers.
@@ -67,12 +69,24 @@ export interface RSCRouter<
   readonly id: string;
 
   /**
-   * Register routes using URL patterns from urls()
+   * URL prefix applied to all routes. Undefined when no basename is configured.
+   */
+  readonly basename: string | undefined;
+
+  /**
+   * Register routes using URL patterns from urls() or a builder function
    *
    * @example
    * ```typescript
-   * createRouter({})
-   *   .routes(urlpatterns)
+   * // With urls()
+   * createRouter({}).routes(urlpatterns)
+   *
+   * // With builder function (urls() is implicit)
+   * createRouter({}).routes(({ path, layout }) => [
+   *   layout(RootLayout, () => [
+   *     path("/", HomePage),
+   *   ]),
+   * ])
    * ```
    */
   routes<T extends UrlPatterns<TEnv, any>>(
@@ -84,6 +98,7 @@ export interface RSCRouter<
         ? MergeRoutesWithResponses<NonNullable<T["_routes"]>, T["_responses"]>
         : Record<string, string>)
   >;
+  routes(builder: UrlBuilder<TEnv>): RSCRouter<TEnv, TRoutes>;
 
   /**
    * Add global middleware that runs on all routes
@@ -134,6 +149,94 @@ export interface RSCRouter<
    */
   readonly routeMap: TRoutes;
 
+  /**
+   * Handle an RSC request.
+   *
+   * Uses the router's configuration (nonce, version, cache) automatically.
+   * The handler is lazily created on first call.
+   *
+   * @example Cloudflare Workers
+   * ```tsx
+   * import { router } from "./router";
+   *
+   * export default { fetch: router.fetch };
+   * ```
+   *
+   * @example Direct export
+   * ```tsx
+   * const router = createRouter({
+   *   document: Document,
+   *   urls: urlpatterns,
+   *   nonce: () => true,
+   * });
+   *
+   * export const fetch = router.fetch;
+   * ```
+   */
+  fetch(request: Request, input?: RouterRequestInput<TEnv>): Promise<Response>;
+}
+
+/**
+ * Internal RSC Router interface — the full framework-facing API.
+ *
+ * This type includes all members used by the Vite plugin, RSC handler,
+ * pre-rendering pipeline, and other framework internals. It is NOT exported
+ * from the public package API.
+ *
+ * Use toInternal(router) to assert a public RSCRouter into this type
+ * at the boundary where framework code receives a user-provided router.
+ */
+export interface RSCRouterInternal<
+  TEnv = any,
+  TRoutes extends Record<string, unknown> = Record<string, string>,
+> {
+  /**
+   * Brand marker for build-time discovery.
+   * The Vite plugin uses this to identify router instances in module exports.
+   */
+  readonly __brand: typeof RSC_ROUTER_BRAND;
+
+  /**
+   * Unique identifier for this router instance.
+   * Used to namespace static output and isolate route maps between routers.
+   */
+  readonly id: string;
+
+  /** URL prefix applied to all routes. */
+  readonly basename: string | undefined;
+
+  /**
+   * Register routes using URL patterns from urls() or a builder function
+   */
+  routes<T extends UrlPatterns<TEnv, any>>(
+    patterns: T,
+  ): RSCRouter<
+    TEnv,
+    TRoutes &
+      (NonNullable<T["_routes"]> extends Record<string, unknown>
+        ? MergeRoutesWithResponses<NonNullable<T["_routes"]>, T["_responses"]>
+        : Record<string, string>)
+  >;
+  routes(builder: UrlBuilder<TEnv>): RSCRouter<TEnv, TRoutes>;
+
+  /**
+   * Add global middleware that runs on all routes
+   */
+  use(
+    patternOrMiddleware: string | MiddlewareFn<TEnv>,
+    middleware?: MiddlewareFn<TEnv>,
+  ): RSCRouter<TEnv, TRoutes>;
+
+  /**
+   * Type-safe URL builder for registered routes
+   */
+  reverse: ReverseFunction<TRoutes>;
+
+  /**
+   * Accumulated route map for typeof extraction
+   */
+  readonly routeMap: TRoutes;
+
   /**
    * Root layout component that wraps the entire application
    * Access this to pass to renderSegments
@@ -147,12 +250,12 @@ export interface RSCRouter<
   readonly onError?: RSCRouterOptions<TEnv>["onError"];
 
   /**
-   * Cache configuration (for internal use by RSC handler)
+   * Cache configuration
    */
   readonly cache?: RSCRouterOptions<TEnv>["cache"];
 
   /**
-   * Not found component to render when no route matches (for internal use by RSC handler)
+   * Not found component to render when no route matches
    */
   readonly notFound?: RSCRouterOptions<TEnv>["notFound"];
 
@@ -162,6 +265,28 @@ export interface RSCRouter<
    */
   readonly themeConfig: import("../theme/types.js").ResolvedThemeConfig | null;
 
+  /**
+   * Cache profiles for "use cache" per-request resolution.
+   * Always includes at least the "default" profile.
+   */
+  readonly cacheProfiles: Record<
+    string,
+    import("../cache/profile-registry.js").CacheProfile
+  >;
+
+  /**
+   * Cache-Control header value for prefetch responses.
+   * False means no caching of prefetch responses.
+   * Derived from prefetchCacheTTL.
+   */
+  readonly prefetchCacheControl: string | false;
+
+  /**
+   * TTL in milliseconds for the client-side in-memory prefetch cache.
+   * 0 means caching is disabled.
+   */
+  readonly prefetchCacheTTL: number;
+
   /**
    * Whether connection warmup is enabled.
    * When true, the client sends HEAD /?_rsc_warmup after idle periods
@@ -169,43 +294,71 @@ export interface RSCRouter<
    */
   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.
-   * @internal
    */
   readonly allowDebugManifest: boolean;
 
   /**
-   * App-level middleware entries (for internal use by RSC handler)
+   * Resolved timeout configuration (merged from shorthand + structured).
+   */
+  readonly timeouts: ResolvedTimeouts;
+
+  /**
+   * Custom timeout response handler.
+   */
+  readonly onTimeout?: OnTimeoutCallback<TEnv>;
+
+  /**
+   * App-level middleware entries
    * These wrap the entire request/response cycle
    */
   readonly middleware: MiddlewareEntry<TEnv>[];
 
   /**
-   * Nonce provider for CSP (for internal use by createHandler)
+   * Nonce provider for CSP
    */
   readonly nonce?: NonceProvider<TEnv>;
 
   /**
-   * RSC version string (for internal use by createHandler)
+   * RSC version string
    */
   readonly version?: string;
 
   /**
    * URL patterns reference for build-time manifest generation
-   * @internal
    */
   readonly urlpatterns?: UrlPatterns<TEnv, any>;
 
+  /**
+   * SSR configuration. resolveStreaming determines stream vs allReady
+   * per HTML request (undefined = always stream).
+   */
+  readonly ssr?: import("./router-options.js").SSROptions<TEnv>;
+
+  /**
+   * Cross-origin request protection configuration.
+   * Default: true (enabled).
+   */
+  readonly originCheck: import("../rsc/origin-guard.js").OriginCheckConfig<TEnv>;
+
   /**
    * Source file path where createRouter() was called.
    * Set via Error.stack parsing at construction time.
    * Used by the Vite plugin to write per-router named-routes.gen.ts files.
-   * @internal
    */
   readonly __sourceFile?: string;
 
+  /** @internal basename for runtime manifest generation */
+  readonly __basename?: string;
+
   match(
     request: Request,
     input?: RouterRequestInput<TEnv>,
@@ -215,12 +368,14 @@ export interface RSCRouter<
    * Build-time pre-render match. Resolves segments with a BuildContext
    * (no request/env/headers/cookies), skipping middleware and loaders.
    * Used by the Vite plugin to collect pre-render data at build time.
-   * @internal
    */
   matchForPrerender(
     pathname: string,
     params: Record<string, string>,
     buildVars?: Record<string, any>,
+    isPassthroughRoute?: boolean,
+    buildEnv?: any,
+    devMode?: boolean,
   ): Promise<{
     segments: SerializedSegmentData[];
     handles: Record<string, SegmentHandleData>;
@@ -228,17 +383,19 @@ export interface RSCRouter<
     params: Record<string, string>;
     interceptSegments?: SerializedSegmentData[];
     interceptHandles?: Record<string, SegmentHandleData>;
+    passthrough?: true;
   } | null>;
 
   /**
    * Render a single Static handler at build time.
    * Returns the RSC-serialized component string and handle data, or null on failure.
-   * @internal
    */
   renderStaticSegment(
     handler: Function,
     handlerId: string,
     routeName?: string,
+    buildEnv?: any,
+    devMode?: boolean,
   ): Promise<{ encoded: string; handles: Record<string, unknown[]> } | null>;
 
   /**
@@ -293,7 +450,13 @@ export interface RSCRouter<
   ): Promise<MatchResult | null>;
 
   /**
-   * @internal
+   * Low-level route matching function.
+   * Used by classifyRequest() for request classification without
+   * entering the full match pipeline.
+   */
+  findMatch(pathname: string, metricsStore?: any): any;
+
+  /**
    * Debug utility to serialize the manifest for inspection
    * Returns a JSON-friendly representation of all routes and layouts
    */
@@ -301,27 +464,21 @@ export interface RSCRouter<
 
   /**
    * Handle an RSC request.
-   *
-   * Uses the router's configuration (nonce, version, cache) automatically.
-   * The handler is lazily created on first call.
-   *
-   * @example Cloudflare Workers
-   * ```tsx
-   * import { router } from "./router";
-   *
-   * export default { fetch: router.fetch };
-   * ```
-   *
-   * @example Direct export
-   * ```tsx
-   * const router = createRouter({
-   *   document: Document,
-   *   urls: urlpatterns,
-   *   nonce: () => true,
-   * });
-   *
-   * export const fetch = router.fetch;
-   * ```
    */
   fetch(request: Request, input?: RouterRequestInput<TEnv>): Promise<Response>;
 }
+
+/**
+ * Assert a public RSCRouter into the internal type.
+ *
+ * Use this at the boundary where framework code receives a user-provided
+ * router and needs access to internal members (match, config, build-time).
+ * The cast is safe because createRouter() always produces an object that
+ * satisfies RSCRouterInternal; the public type is just a narrower view.
+ */
+export function toInternal<
+  TEnv = any,
+  TRoutes extends Record<string, unknown> = Record<string, string>,
+>(router: RSCRouter<TEnv, TRoutes>): RSCRouterInternal<TEnv, TRoutes> {
+  return router as RSCRouterInternal<TEnv, TRoutes>;
+}