@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/src/build/route-types/scan-filter.ts

@@ -54,7 +54,7 @@ export function findTsFiles(dir: string, filter?: ScanFilter): string[] {
     entries = readdirSync(dir, { withFileTypes: true });
   } catch (err) {
     console.warn(
-      `[rsc-router] Failed to scan directory ${dir}: ${(err as Error).message}`,
+      `[rango] Failed to scan directory ${dir}: ${(err as Error).message}`,
     );
     return results;
   }

package/src/build/route-types/source-scan.ts

@@ -0,0 +1,216 @@
+// Allocation-light, linear-time source scanning for the build-time scanners.
+//
+// The router-file scanner, the HMR relevance check, and the unsupported-shape
+// warning all need to know whether a token like `createRouter(` / `createLoader(`
+// appears in REAL code versus inside a comment or string literal. Rather than
+// build a full comment/string-stripped copy of the source (which on a large
+// file allocates an O(n) string plus, naively, a per-char array), these helpers
+// run the regex over the whole source ONCE (the engine sweeps left-to-right,
+// O(n)) and classify each match's offset with a forward, O(1)-memory cursor that
+// advances monotonically across the source.
+//
+// Time: O(n) — one native regex sweep plus one forward classification pass.
+// Memory: O(1) for the boolean check; O(#matches) for the index list. No
+// stripped copy and no per-char array are ever materialized.
+//
+// Pragmatic scanner, not a full tokenizer: regex literals ARE coarsely skipped
+// (see below) and template interpolations are treated as opaque string content.
+// One intentional consequence: a token whose match would only complete by
+// treating an interleaved comment as whitespace (e.g. `createRouter /* x */ (`)
+// is not detected — real calls never interleave a comment between the callee
+// and its arguments.
+//
+// Regex literals are skipped because a literal containing a quote or comment
+// char (e.g. `const re = /it's a "x"/g;`) would otherwise open a phantom string
+// at the inner quote and swallow the following REAL code — dropping a router
+// file from discovery. We only treat a `/` as a regex start when it is in
+// "regex position" (the previous significant code char is not value-producing),
+// so genuine division (`a / b`) is left untouched.
+
+// JS line terminators end a `//` comment: LF, CR, LS (U+2028), PS (U+2029).
+function isLineTerminator(ch: string): boolean {
+  const c = ch.charCodeAt(0);
+  // LF, CR, LS (U+2028), PS (U+2029)
+  return c === 10 || c === 13 || c === 0x2028 || c === 0x2029;
+}
+
+// Identifier-position keywords after which a `/` begins a regex literal, not
+// division: the keyword cannot be the left operand of a division, so `return
+// /re/`, `typeof /re/`, `case /re/`, etc. are regexes. After any OTHER identifier
+// or number (a value), `/` is division.
+const REGEX_PRECEDING_KEYWORDS = new Set([
+  "return",
+  "typeof",
+  "instanceof",
+  "in",
+  "of",
+  "new",
+  "delete",
+  "void",
+  "do",
+  "else",
+  "yield",
+  "await",
+  "case",
+  "throw",
+]);
+
+// A `/` at `slashPos` is a regex-literal start (not division) when the previous
+// significant code char cannot end an expression. A closing `)`/`]`/`}` and an
+// identifier/digit/`$`/`_` are value-producing (division); everything else
+// (operators, `(`, `,`, `=`, `:`, `{`, `;`, `<`, `>`, ...) and the start-of-file
+// put `/` in regex position. The one subtlety: an identifier that is actually a
+// regex-preceding KEYWORD (`return /re/`) ends in a word char, so the
+// previous-char-only test misread it as division and then let the regex body's
+// inner quotes open a phantom string — dropping a later real `createRouter()`.
+// So when the previous char is a word char we walk back over any whitespace and
+// the identifier and treat `/` as a regex iff that identifier is such a keyword.
+// `}` stays value-producing to avoid swallowing an object/block followed by
+// division; the cost is only that a regex right after a block isn't skipped.
+function isRegexPositionAt(
+  code: string,
+  slashPos: number,
+  prevChar: string | undefined,
+): boolean {
+  if (prevChar === undefined) return true; // start of file
+  if (prevChar === ")" || prevChar === "]" || prevChar === "}") return false;
+  if (!/[\w$]/.test(prevChar)) return true; // operator / `(` / `,` / `=` / ...
+  // Previous char ends an identifier or number: regex only after a keyword that
+  // expects an expression. Walk back over whitespace + the identifier run.
+  let k = slashPos - 1;
+  while (k >= 0 && /\s/.test(code[k])) k--;
+  const wordEnd = k + 1;
+  while (k >= 0 && /[\w$]/.test(code[k])) k--;
+  return REGEX_PRECEDING_KEYWORDS.has(code.slice(k + 1, wordEnd));
+}
+
+/**
+ * Build a classifier that answers "is offset `q` in code (not a comment or
+ * string)?" for STRICTLY INCREASING `q`. The internal cursor only moves forward,
+ * so a full left-to-right sequence of queries costs O(n) total with O(1) memory.
+ */
+function makeCodeClassifier(code: string): (q: number) => boolean {
+  const n = code.length;
+  let i = 0; // forward cursor: everything before `i` is already classified
+  let skipStart = -1; // last detected comment/string region (cache)
+  let skipEnd = -1;
+  // Last significant code char, used to disambiguate `/` (regex vs division).
+  // Comments are transparent (don't update it); strings/regex are value-producing.
+  let lastSig: string | undefined;
+
+  return (q: number): boolean => {
+    if (q >= skipStart && q < skipEnd) return false; // q in the cached region
+    while (i < n && i <= q) {
+      const c = code[i];
+      const d = i + 1 < n ? code[i + 1] : "";
+      let end = -1;
+      let transparent = false; // comment: skipped but does not set lastSig
+      if (c === "/" && d === "/") {
+        let j = i + 2;
+        while (j < n && !isLineTerminator(code[j])) j++;
+        end = j;
+        transparent = true;
+      } else if (c === "/" && d === "*") {
+        let j = i + 2;
+        while (j < n && !(code[j] === "*" && code[j + 1] === "/")) j++;
+        end = Math.min(n, j + 2);
+        transparent = true;
+      } else if (c === '"' || c === "'" || c === "`") {
+        let j = i + 1;
+        while (j < n) {
+          if (code[j] === "\\") {
+            j += 2;
+            continue;
+          }
+          if (code[j] === c) {
+            j++;
+            break;
+          }
+          j++;
+        }
+        end = j;
+      } else if (
+        c === "/" &&
+        d !== "/" &&
+        d !== "*" &&
+        isRegexPositionAt(code, i, lastSig)
+      ) {
+        // Coarse regex-literal skip. A regex literal cannot span a raw newline;
+        // `/` inside a `[...]` character class is literal (not a terminator).
+        // Bail (treat the `/` as a normal char) if no closing `/` on the line
+        // so a stray division-looking `/` never swallows the rest of the line.
+        let j = i + 1;
+        let inClass = false;
+        let closed = false;
+        while (j < n && !isLineTerminator(code[j])) {
+          const r = code[j];
+          if (r === "\\") {
+            j += 2;
+            continue;
+          }
+          if (r === "[") inClass = true;
+          else if (r === "]") inClass = false;
+          else if (r === "/" && !inClass) {
+            j++;
+            closed = true;
+            break;
+          }
+          j++;
+        }
+        if (closed) {
+          while (j < n && /[a-z]/.test(code[j])) j++; // flags
+          end = j;
+        }
+      }
+      if (end >= 0) {
+        // Comment/string/regex region [i, end). `q >= i` here (loop condition).
+        if (q < end) {
+          skipStart = i;
+          skipEnd = end;
+          return false;
+        }
+        i = end;
+        // Strings and regex literals are value-producing; comments are not.
+        if (!transparent) lastSig = "x";
+      } else {
+        if (!/\s/.test(c)) lastSig = c;
+        i++;
+      }
+    }
+    return true; // reached q in code mode
+  };
+}
+
+/**
+ * Index of the first match of `pattern` that occurs in code (not in a comment
+ * or string), or -1. `pattern` MUST be a global (`/g`) regex. Single native
+ * regex sweep with early-exit; O(1) extra memory.
+ */
+export function firstCodeMatchIndex(code: string, pattern: RegExp): number {
+  const inCode = makeCodeClassifier(code);
+  pattern.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = pattern.exec(code)) !== null) {
+    if (inCode(m.index)) return m.index;
+    if (pattern.lastIndex <= m.index) pattern.lastIndex = m.index + 1;
+  }
+  return -1;
+}
+
+/**
+ * Byte offsets of every match of `pattern` that occurs in code (not in a
+ * comment or string). `pattern` MUST be a global (`/g`) regex. Each offset is
+ * the match start — the same byte offset a raw `pattern.exec` reports. O(n)
+ * time, O(#matches) memory.
+ */
+export function codeMatchIndices(code: string, pattern: RegExp): number[] {
+  const inCode = makeCodeClassifier(code);
+  const indices: number[] = [];
+  pattern.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = pattern.exec(code)) !== null) {
+    if (inCode(m.index)) indices.push(m.index);
+    if (pattern.lastIndex <= m.index) pattern.lastIndex = m.index + 1;
+  }
+  return indices;
+}

package/src/build/runtime-discovery.ts

@@ -1,9 +1,11 @@
-import { dirname, join, basename, resolve } from "node:path";
+import { resolve } from "node:path";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import {
   generateRouteTypesSource,
-  buildCombinedRouteMapForRouterFile,
+  genFileTsPath,
+  resolveSearchSchemas,
 } from "./generate-route-types.ts";
+import { mergeFullManifests } from "./merge-full-manifests.js";
 import { isAutoGeneratedRouteName } from "../route-name.js";
 
 export interface RuntimeDiscoveryOptions {
@@ -125,21 +127,34 @@ export async function discoverAndWriteRouteTypes(
 
     // Import build utilities for manifest generation
     const buildMod = await rscEnv.runner.import("@rangojs/router/build");
-    const generateManifest = buildMod.generateManifest;
+    const generateManifestFull = buildMod.generateManifestFull;
 
-    if (!generateManifest) {
-      throw new Error("generateManifest not found in @rangojs/router/build");
+    if (!generateManifestFull) {
+      throw new Error(
+        "generateManifestFull not found in @rangojs/router/build",
+      );
     }
 
     const outputFiles: string[] = [];
     let totalRouteCount = 0;
-    let routerMountIndex = 0;
+    let globalMountIndex = 0;
+    let routerCount = 0;
 
     for (const [id, router] of registry) {
-      if (!router.urlpatterns) continue;
-
-      const manifest = generateManifest(router.urlpatterns, routerMountIndex);
-      routerMountIndex++;
+      const mounts =
+        router.__urlpatternMounts ??
+        (router.urlpatterns ? [{ patterns: router.urlpatterns }] : []);
+      if (mounts.length === 0) continue;
+
+      const mountManifests = [];
+      for (const mount of mounts) {
+        mountManifests.push(
+          await generateManifestFull(mount.patterns, globalMountIndex),
+        );
+        globalMountIndex++;
+      }
+      const manifest = mergeFullManifests(mountManifests);
+      routerCount++;
 
       // Filter out auto-generated route names that the runtime creates for
       // unnamed routes (path() with no name option). These get names like
@@ -175,25 +190,13 @@ export async function discoverAndWriteRouteTypes(
         );
       }
 
-      // Search schema fallback: runtime manifest may omit search schema metadata
-      // in some module-runner flows. Fall back to static source parsing.
-      if (!routeSearchSchemas || Object.keys(routeSearchSchemas).length === 0) {
-        const staticParsed = buildCombinedRouteMapForRouterFile(sourceFile);
-        if (Object.keys(staticParsed.searchSchemas).length > 0) {
-          const filtered: Record<string, Record<string, string>> = {};
-          for (const name of Object.keys(routeManifest)) {
-            const schema = staticParsed.searchSchemas[name];
-            if (schema) filtered[name] = schema;
-          }
-          if (Object.keys(filtered).length > 0) {
-            routeSearchSchemas = filtered;
-          }
-        }
-      }
+      routeSearchSchemas = resolveSearchSchemas(
+        Object.keys(routeManifest),
+        routeSearchSchemas,
+        sourceFile,
+      );
 
-      const routerDir = dirname(sourceFile);
-      const routerBasename = basename(sourceFile).replace(/\.(tsx?|jsx?)$/, "");
-      const outPath = join(routerDir, `${routerBasename}.named-routes.gen.ts`);
+      const outPath = genFileTsPath(sourceFile);
 
       const source = generateRouteTypesSource(
         routeManifest,
@@ -219,7 +222,7 @@ export async function discoverAndWriteRouteTypes(
     }
 
     return {
-      routerCount: routerMountIndex,
+      routerCount,
       routeCount: totalRouteCount,
       outputFiles,
     };

package/src/cache/cache-error.ts

@@ -0,0 +1,104 @@
+/**
+ * Cache error reporting.
+ *
+ * Caches are best-effort: a read failure degrades to a miss (render fresh) and a
+ * write failure degrades to a no-op - they MUST NOT throw up and fail the
+ * request. But the failure must still be LOUD: it is logged to the console (so
+ * it is visible even in a background waitUntil task or when no hook is wired)
+ * AND routed through the router's onError callback (via the request context's
+ * deduped _reportBackgroundError) so consumers can observe cache degradation in
+ * their own telemetry.
+ *
+ * The one deliberate exception is the invalidation WRITE verb (updateTag ->
+ * store.invalidateTags): a failed durable marker write is rejected so an awaited
+ * updateTag() surfaces it (read-your-own-writes honesty). That is not a data
+ * read/write and does not go through this helper's swallow-and-degrade path.
+ */
+
+import { _getRequestContext } from "../server/request-context.js";
+
+/**
+ * Minimal shape of a request context for error reporting. Passed explicitly by
+ * background tasks (waitUntil) where the ALS context is already gone, so the
+ * error can still reach the router's onError. Structural to avoid importing the
+ * full RequestContext type (request-context.ts imports CacheErrorCategory from
+ * here - a mutual type-only reference).
+ */
+export interface CacheErrorReporter {
+  _reportBackgroundError?: (
+    error: unknown,
+    category: CacheErrorCategory,
+  ) => void;
+}
+
+export type CacheErrorCategory =
+  /** A read failed (transient infra: KV/Cache API error). Degrade to a miss. */
+  | "cache-read"
+  /** A write failed. Degrade to a no-op (entry simply not cached). */
+  | "cache-write"
+  /** A delete/eviction failed. Best-effort. */
+  | "cache-delete"
+  /**
+   * A STORED entry could not be parsed/deserialized (partial KV read, truncated
+   * Cache API body, malformed envelope/RSC payload). The entry is faulty and is
+   * evicted so subsequent reads do not keep failing on it. Distinct from
+   * cache-read so consumers can tell corruption from a transient outage.
+   */
+  | "cache-corrupt"
+  /** A tag-invalidation side effect failed (e.g. the eager CDN purge hook). */
+  | "cache-invalidate"
+  /**
+   * A background stale-while-revalidate refresh failed (the `"use cache"`
+   * read-through path). The stale value was already served; the refresh that
+   * would have replaced it errored.
+   */
+  | "stale-revalidation";
+
+/**
+ * Report a non-fatal cache error loudly without failing the request: always logs
+ * (label + error) and, when a request context is available, routes the error
+ * through the router's onError callback. Never throws.
+ *
+ * `ctx` is for callers running in a detached background task (waitUntil), where
+ * the ALS request context is already gone (so `_getRequestContext()` is null):
+ * they capture the context up front and pass it here so onError still fires.
+ * Foreground callers omit it and fall back to the ALS context.
+ */
+export function reportCacheError(
+  error: unknown,
+  category: CacheErrorCategory,
+  label: string,
+  ctx?: CacheErrorReporter,
+): void {
+  console.error(`${label}:`, error);
+  try {
+    const target = ctx ?? _getRequestContext();
+    target?._reportBackgroundError?.(error, category);
+  } catch {
+    // Reporting must never itself break the cache path.
+  }
+}
+
+/**
+ * Run a best-effort async cache task (typically scheduled via waitUntil), catching
+ * any rejection and routing it through reportCacheError so background cache work
+ * (non-blocking L1 writes, KV persistence, L1 promotion) reports failures via
+ * onError instead of throwing or silently swallowing. Never rejects.
+ *
+ * Pass `ctx` when the task runs detached (the ALS context is gone) and the
+ * failure should still reach onError; omit it to fall back to the ALS context.
+ *
+ * @example this.waitUntil(() => reportingAsync(() => cache.put(req, res), "cache-write", "[CFCacheStore] L1 write"))
+ */
+export async function reportingAsync(
+  task: () => Promise<unknown>,
+  category: CacheErrorCategory,
+  label: string,
+  ctx?: CacheErrorReporter,
+): Promise<void> {
+  try {
+    await task();
+  } catch (error) {
+    reportCacheError(error, category, label, ctx);
+  }
+}

package/src/cache/cache-exec-scope.ts

@@ -0,0 +1,47 @@
+/**
+ * Execution-chain scope for "use cache" function bodies.
+ *
+ * The ambient guards (cookies(), headers(), ctx.set() reached via
+ * getRequestContext()) must fire for code running INSIDE a cached body and
+ * stay silent for everything else on the request. A property stamped on the
+ * shared RequestContext cannot express that: while a slow "use cache" body is
+ * in flight, every parallel read on the same request sees the stamp. Scar: a
+ * 2s cached product fetch running beside a sibling loader made the loader's
+ * cookies() read throw `cannot be called inside a "use cache" function` —
+ * same shared-object hazard as issue #684 plan 010, which fixed only the
+ * background-revalidation path. AsyncLocalStorage follows the cached body's
+ * own async chain, so parallel work is invisible to the guard while genuine
+ * in-body reads still throw.
+ *
+ * Deliberately NOT entered on the store-less bypass paths in cache-runtime.ts:
+ * there the body executes for real on every call, side effects take effect,
+ * and request-scoped reads are safe (see the bypass comments there).
+ *
+ * Kept separate from taint.ts so `node:async_hooks` stays out of that module —
+ * taint.ts is reachable from browser-bundled DSL helpers. The probe
+ * registration below wires assertNotInsideCacheExec to this scope without
+ * taint.ts importing it.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { _setCacheExecScopeProbe } from "./taint.js";
+
+const cacheExecStorage = new AsyncLocalStorage<true>();
+
+/**
+ * Run fn with the "use cache" execution scope active. Continuations spawned
+ * from fn's synchronous kickoff inherit the scope; parallel chains do not.
+ */
+export function runWithCacheExecScope<T>(fn: () => T): T {
+  return cacheExecStorage.run(true, fn);
+}
+
+/** True when the calling async chain is inside a "use cache" body. */
+export function isInsideCacheExecScope(): boolean {
+  return cacheExecStorage.getStore() === true;
+}
+
+// Wire the ambient ctx-method guards (assertNotInsideCacheExec in taint.ts)
+// to this scope. Module-init registration cannot be missed: exec scopes only
+// exist once cache-runtime.ts (which imports this module) is loaded.
+_setCacheExecScopeProbe(isInsideCacheExecScope);

package/src/cache/cache-key-utils.ts

@@ -6,24 +6,55 @@
  * document-cache, and loader-cache.
  */
 
+import { encodeKV } from "../encode-kv.js";
+import type { SearchParamsFilter } from "./search-params-filter.js";
+
+/**
+ * Reserved URL query params that the router owns and must never key the cache
+ * on. `_rsc*` is the router's internal navigation/action/loader prefix (matched
+ * by prefix). `__no_cache` is the single `__`-prefixed param the router reads
+ * (handler.ts / testing dispatch.ts use it to bypass the store); it and the
+ * other router-internal `__`-prefixed request params are matched by an EXACT
+ * allowlist, not a blanket `__` prefix. A blanket `__` filter would silently
+ * collapse consumer params like `__variant=a` vs `__variant=b` onto one cache
+ * slot; an allowlist keeps the router's own params out of the key while leaving
+ * consumer `__` params intact.
+ */
+const RESERVED_SEARCH_PARAMS = new Set([
+  "__no_cache",
+  "__rsc",
+  "__html",
+  "__prerender_collect",
+]);
+
+function isReservedSearchParam(key: string): boolean {
+  return key.startsWith("_rsc") || RESERVED_SEARCH_PARAMS.has(key);
+}
+
 /**
  * Build a sorted, deterministic query string from URLSearchParams,
- * excluding internal _rsc* and __* params.
+ * excluding the router's reserved params (see isReservedSearchParam).
  *
- * Returns empty string when no user-facing params exist.
+ * `filter` is the compiled `cache.searchParams` config (search-params-filter.ts),
+ * applied AFTER the reserved-param exclusion and BEFORE the sort, so reserved
+ * params can never be re-included (`include: ["__no_cache"]` is a no-op) and
+ * surviving params stay order-insensitive. `undefined` means no filtering --
+ * that path must stay byte-identical to the pre-filter format (cacheKeyBase
+ * output is byte-stable by contract).
+ *
+ * Returns empty string when no user-facing params survive.
  */
-export function sortedSearchString(searchParams: URLSearchParams): string {
+export function sortedSearchString(
+  searchParams: URLSearchParams,
+  filter?: SearchParamsFilter,
+): string {
   const pairs: [string, string][] = [];
   for (const [k, v] of searchParams) {
-    if (!k.startsWith("_rsc") && !k.startsWith("__")) {
+    if (!isReservedSearchParam(k) && (filter === undefined || filter(k))) {
       pairs.push([k, v]);
     }
   }
-  if (pairs.length === 0) return "";
-  pairs.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-  return pairs
-    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
-    .join("&");
+  return encodeKV(pairs, { sort: true });
 }
 
 /**
@@ -35,10 +66,37 @@ export function sortedRouteParams(
   params: Record<string, string> | undefined,
 ): string {
   if (!params) return "";
-  const entries = Object.entries(params);
-  if (entries.length === 0) return "";
-  return entries
-    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
-    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
-    .join("&");
+  return encodeKV(Object.entries(params), { sort: true });
+}
+
+/**
+ * Host-namespaced cache key base: `${host}${pathname}[:params][?search]`.
+ *
+ * The ONE composition of the host-namespacing rule, shared by the segment tier
+ * (cache-scope.ts) and the document tier (document-cache.ts) so the rule cannot
+ * drift between them. Host prefixing matters because VercelCacheStore /
+ * MemorySegmentCacheStore key by the raw string (only CFCacheStore adds host
+ * internally) -- on a single function serving multiple domains an
+ * un-namespaced key bleeds tenant A's cached response to tenant B.
+ *
+ * Output is BYTE-STABLE by contract: changing the composition silently
+ * invalidates every persisted cache entry on upgrade. Callers append their own
+ * tier-specific suffixes (`:rsc`/`:html`, segment hash) after this base.
+ */
+export function cacheKeyBase(
+  host: string,
+  pathname: string,
+  searchParams?: URLSearchParams,
+  params?: Record<string, string>,
+  filter?: SearchParamsFilter,
+): string {
+  const paramStr = sortedRouteParams(params);
+  const searchStr = searchParams
+    ? sortedSearchString(searchParams, filter)
+    : "";
+
+  let key = `${host}${pathname}`;
+  if (paramStr) key += `:${paramStr}`;
+  if (searchStr) key += `?${searchStr}`;
+  return key;
 }