@rangojs/router 0.0.0-experimental.142 → 0.0.0-experimental.144

package/src/cache/document-cache.ts

@@ -19,7 +19,7 @@ import {
   type RequestContext,
 } from "../server/request-context.js";
 import { mayNeedSSR } from "../rsc/ssr-setup.js";
-import { sortedSearchString } from "./cache-key-utils.js";
+import { cacheKeyBase } from "./cache-key-utils.js";
 import { runBackground } from "./background-task.js";
 import { reportCacheError } from "./cache-error.js";
 
@@ -188,7 +188,13 @@ export interface DocumentCacheOptions<TEnv = any> {
   skipPaths?: string[];
 
   /**
-   * Custom cache key generator
+   * Custom cache key generator.
+   *
+   * Replaces the default `host + pathname + search` key entirely. On a
+   * multi-domain deployment served by one function you MUST include `url.host`
+   * (or an equivalent tenant discriminator) yourself — the default key is
+   * host-namespaced, but a custom generator's output is used verbatim, so
+   * omitting host bleeds one hostname's cached response to another.
    */
   keyGenerator?: (url: URL) => string;
 
@@ -311,17 +317,17 @@ export function createDocumentCacheMiddleware<TEnv = any>(
         isPartial && clientSegments ? `:${hashSegmentIds(clientSegments)}` : "";
       const typeSuffix = isRscRequest ? ":rsc" : ":html";
 
-      let searchSuffix = "";
-      if (!keyGenerator) {
-        const sorted = sortedSearchString(url.searchParams);
-        if (sorted) {
-          searchSuffix = `?${sorted}`;
-        }
-      }
-
+      // Default key rides the shared host-namespaced base (cacheKeyBase) so the
+      // segment tier (cache-scope.ts) and this document tier cannot drift on the
+      // host-namespacing rule -- see the contract on cacheKeyBase.
+      // The keyGenerator branch is left untouched: a consumer-supplied generator
+      // owns its own namespacing (auto-prefixing host would silently change their
+      // existing keys and double any host they already include).
       const cacheKey = keyGenerator
         ? keyGenerator(url) + segmentHash + typeSuffix
-        : `${url.pathname}${searchSuffix}${segmentHash}${typeSuffix}`;
+        : cacheKeyBase(url.host, url.pathname, url.searchParams) +
+          segmentHash +
+          typeSuffix;
       // 1. Check cache
       const cached = await store.getResponse(cacheKey);
 

package/src/cache/vercel/vercel-cache-store.ts

@@ -51,6 +51,15 @@ import {
 } from "../cache-policy.js";
 import { reportCacheError, reportingAsync } from "../cache-error.js";
 import type { CacheErrorCategory } from "../cache-error.js";
+// Reuse the CF store's binary-safe base64 helpers. bufferToBase64 caps each
+// String.fromCharCode batch at 8192 and uses .apply (never a spread), so a large
+// Response/PPR-shell body cannot blow the JS argument-count ceiling (~65k) and
+// throw RangeError inside putResponse/putShell - which the outer try/catch would
+// swallow as a cache-write degrade, silently never caching the entry. Output is
+// byte-identical to a per-byte encoder (chunk size does not affect base64), so
+// this is a robustness fix, not a format change. Do NOT reintroduce a local
+// spread-based encoder or raise the chunk here; cf-base64.ts is import-pure.
+import { bufferToBase64, base64ToBuffer } from "../cf/cf-base64.js";
 
 /**
  * Minimal structural shape of the Vercel Runtime Cache returned by `getCache()`
@@ -277,25 +286,6 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }
 
-/** Encode binary body bytes to base64 in chunks (avoids call-stack blowups). */
-function bufferToBase64(buffer: ArrayBuffer): string {
-  const bytes = new Uint8Array(buffer);
-  let binary = "";
-  const CHUNK = 0x8000;
-  for (let i = 0; i < bytes.length; i += CHUNK) {
-    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
-  }
-  return btoa(binary);
-}
-
-/** Decode a base64 body back into bytes. */
-function base64ToBuffer(b64: string): ArrayBuffer {
-  const binary = atob(b64);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
-  return bytes.buffer;
-}
-
 /**
  * Vercel Runtime Cache-backed segment cache store.
  *

package/src/cloudflare/tracing.ts

@@ -39,7 +39,7 @@ import { _getRequestContext } from "../server/request-context.js";
 import {
   type RouterTracingConfig,
   type SpanRunner,
-  type TracePhaseToggles,
+  type TracingToggleOptions,
   NOOP_TRACE_SPAN,
 } from "../router/tracing.js";
 
@@ -57,13 +57,12 @@ interface CloudflareTracing {
   enterSpan<T>(name: string, callback: (span: CloudflareSpan) => T): T;
 }
 
-/** Options for createCloudflareTracing. */
-export interface CloudflareTracingOptions {
-  /** Master switch. Defaults to true. */
-  enabled?: boolean;
-  /** Per-phase span toggles. Omitted phases default to enabled. */
-  spans?: TracePhaseToggles;
-}
+/**
+ * Options for createCloudflareTracing. Alias of the shared
+ * {@link TracingToggleOptions} (`enabled` master switch + per-phase `spans`
+ * toggles); the name is public API.
+ */
+export type CloudflareTracingOptions = TracingToggleOptions;
 
 /**
  * Resolve the per-request Cloudflare tracer from the active execution context.

package/src/index.rsc.ts

@@ -308,6 +308,7 @@ export type {
   RouterTracingConfig,
   TracePhase,
   TracePhaseToggles,
+  TracingToggleOptions,
 } from "./router/tracing.js";
 
 // Timeout types and error class

package/src/index.ts

@@ -343,14 +343,17 @@ export {
 // Path and response types are ambient on the `Rango` namespace (`Rango.Path`,
 // `Rango.PathResponse`, declared in href-client.ts) — no import needed.
 
-// Telemetry types only — the createConsoleSink/createOTelSink values are
-// server-only and live in index.rsc.ts (the `react-server` condition of the
-// bare `@rangojs/router` import). Re-exporting them as values from this
-// (default/client) entry would pull telemetry.ts and telemetry-otel.ts into
-// the client module graph; both tree-shake to zero bytes but still appear in
-// bundle analysis output and slow build-time module resolution. Consumers
-// who need the values in non-RSC contexts can import from
-// `@rangojs/router/server`.
+// Telemetry types only — the createConsoleSink / createOTelSink /
+// createOTelTracing VALUES are server-only and live in index.rsc.ts (the
+// `react-server` condition of the bare `@rangojs/router` import). Re-exporting
+// them as values from this (default/client) entry would pull telemetry.ts and
+// telemetry-otel.ts into the client module graph; both tree-shake to zero bytes
+// but still appear in bundle analysis output and slow build-time module
+// resolution. The factory values are NOT re-exported from `@rangojs/router/server`
+// either — that subpath is internal, not user-facing (see server.ts header).
+// Non-RSC server code imports these TYPES from the root and obtains the factory
+// VALUES from its own router definition module, which resolves to index.rsc.ts
+// under the `react-server` condition.
 export type {
   OTelTracer,
   OTelActiveSpanTracer,
@@ -386,6 +389,7 @@ export type {
   RouterTracingConfig,
   TracePhase,
   TracePhaseToggles,
+  TracingToggleOptions,
 } from "./router/tracing.js";
 
 // Timeout types and error class

package/src/redirect-origin.ts

@@ -60,6 +60,20 @@ export function resolveExternalRedirect(
   }
 }
 
+/**
+ * The safe same-origin landing for a blocked redirect.
+ *
+ * Every guard that neutralizes a cross-origin/unsafe redirect target sends the
+ * browser here instead: the app's basename root, or `"/"` when unset. Kept
+ * beside the resolvers so the "where does a blocked redirect go" answer lives
+ * in ONE place -- the server 3xx guard (`rsc/redirect-guard.ts`) and the
+ * shell-HIT degradation path (`rsc/rsc-rendering.ts`) must agree, or a blocked
+ * redirect lands differently depending on which exit it took.
+ */
+export function safeSameOriginLanding(basename: string | undefined): string {
+  return basename && basename !== "/" ? basename : "/";
+}
+
 /**
  * Out-of-band brand for `redirect(url, { external: true })`.
  *

package/src/route-definition/helpers-types.ts

@@ -149,8 +149,11 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *              so they take precedence on `loading()` and other last-write-wins
    *              fields.
    */
-  parallel: <
-    TSlots extends Record<
+  // Not generic over the slots record: an inferred type parameter makes the
+  // object literal an inference site, which suppresses contextual typing of
+  // arrow slot handlers (`(ctx) => ...` was implicit any).
+  parallel: (
+    slots: Record<
       `@${string}`,
       | Handler<any, any, TEnv>
       | ReactNode
@@ -159,8 +162,6 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
           use?: () => UseItems<ParallelUseItem>;
         }
     >,
-  >(
-    slots: TSlots,
     use?: () => UseItems<ParallelUseItem>,
   ) => ParallelItem;
   /**

package/src/route-map-builder.ts

@@ -20,11 +20,25 @@ let cachedPrecomputedEntries: Array<{
 /**
  * Register routes into the global route map.
  * Routes are merged with any existing registered routes.
- * Called by createRouter() during module evaluation.
+ * Called by createRouter() during module evaluation, and by lazy-include
+ * expansion (src/router/lazy-includes.ts) with each expansion's route delta.
+ *
+ * Merges IN PLACE — O(|map|), not O(total routes). The previous
+ * `globalRouteMap = { ...globalRouteMap, ...map }` copy made every
+ * lazy-include first hit O(total routes) on the request path: with a 26k-route
+ * manifest the spread measured 8.9ms/call (M4, node), paid once per level of a
+ * nested async-include chain (3 calls on a 3-level chain — the 464ms edge
+ * cold-hit in issue #666).
+ *
+ * In-place mutation is safe because every getGlobalRouteMap() consumer reads
+ * it fresh per call (server/request-context.ts, rsc/loader-fetch.ts,
+ * router/intercept-resolution.ts, testing/generated-routes.ts,
+ * rsc/manifest-init.ts) — none memoizes the returned reference. If you add a
+ * consumer that caches the map object, it will now observe later
+ * registrations; snapshot it yourself if you need frozen contents.
  */
 export function registerRouteMap(map: Record<string, string>): void {
-  // Always merge with existing map (don't replace)
-  globalRouteMap = { ...globalRouteMap, ...map };
+  Object.assign(globalRouteMap, map);
 }
 
 /**
@@ -139,6 +153,7 @@ export function clearAllRouterData(): void {
   perRouterManifestMap.clear();
   perRouterTrieMap.clear();
   perRouterPrecomputedEntriesMap.clear();
+  authoritativeTrieRouters.clear();
 }
 
 export function setRouterManifest(
@@ -162,6 +177,23 @@ export function setRouterTrie(
   perRouterTrieMap.set(routerId, trie);
 }
 
+// Routers whose trie came from the COMPLETE build manifest (deserialized via
+// ensureRouterManifest). For these, a trie miss is a real 404 and findMatch
+// skips the regex fallback scan — the only remaining route-count-proportional
+// match path (#664). Dev rebuilds (manifest-init.ts, router-discovery HMR
+// pushes) deliberately never mark authoritative: the dev-only trie-gap warning
+// in find-match.ts depends on the fallback running on misses, and dev route
+// churn (HMR, dev-time routes) makes a stale-trie 404 unacceptable there.
+const authoritativeTrieRouters: Set<string> = new Set();
+
+export function markRouterTrieAuthoritative(routerId: string): void {
+  authoritativeTrieRouters.add(routerId);
+}
+
+export function isRouterTrieAuthoritative(routerId: string): boolean {
+  return authoritativeTrieRouters.has(routerId);
+}
+
 export function getRouterTrie(
   routerId: string,
 ): import("./build/route-trie.js").TrieNode | undefined {
@@ -204,7 +236,12 @@ export async function ensureRouterManifest(routerId: string): Promise<void> {
   if (loader) {
     const mod = await loader();
     if (mod.manifest) perRouterManifestMap.set(routerId, mod.manifest);
-    if (mod.trie) perRouterTrieMap.set(routerId, mod.trie);
+    if (mod.trie) {
+      perRouterTrieMap.set(routerId, mod.trie);
+      // A trie serialized into the build manifest comes from complete
+      // discovery — misses are authoritative 404s (see find-match.ts).
+      markRouterTrieAuthoritative(routerId);
+    }
     if (mod.precomputedEntries)
       perRouterPrecomputedEntriesMap.set(routerId, mod.precomputedEntries);
     routerManifestLoaders.delete(routerId);

package/src/router/find-match.ts

@@ -1,5 +1,8 @@
 import { tryTrieMatch } from "./trie-matching.js";
-import { getRouterTrie } from "../route-map-builder.js";
+import {
+  getRouterTrie,
+  isRouterTrieAuthoritative,
+} from "../route-map-builder.js";
 import {
   findMatch as findRouteMatch,
   isLazyEvaluationNeeded,
@@ -166,6 +169,17 @@ export function createFindMatch<TEnv = any>(
           };
           return cloneMatchResult(lastFindMatchResult);
         }
+      } else if (isRouterTrieAuthoritative(deps.routerId)) {
+        // Authoritative miss (#664): this trie was deserialized from the
+        // COMPLETE build manifest, so trailing-slash redirects are already
+        // trie-native hits and a miss means no route exists. Skip the regex
+        // fallback — the only route-count-proportional match path — and do
+        // not evaluate lazy includes for unmatched (bot-probe) traffic.
+        // Trie hits that need lazy splicing keep the fallback loop below
+        // (trieMatched === true never reaches this branch).
+        lastFindMatchPathname = pathname;
+        lastFindMatchResult = null;
+        return null;
       }
     }
 

package/src/router/instrument.ts

@@ -318,10 +318,10 @@ export function observeHandler<C, R>(
  * sink is configured.
  *
  * This is the canonical emitter for SYNCHRONOUS facts that fire inside the
- * request's ALS scope (handler errors, timeouts, origin rejections, revalidation
- * decisions). A few emitters deliberately stay on the lower-level
- * resolveSink + safeEmit because observeEvent's lazy, per-call
- * getRouterContext() read does not fit them — keep this the complete list:
+ * request's ALS scope (revalidation decisions, cache-lookup decisions). A few
+ * emitters deliberately stay on the lower-level resolveSink + safeEmit because
+ * observeEvent's lazy, per-call getRouterContext() read does not fit them — keep
+ * this the complete list:
  *   - router.ts wrapLoaderPromise (loader.start/end/error) and
  *     segment-resolution/streamed-handler-telemetry.ts (streamed handler.error)
  *     capture the sink + request id EAGERLY and emit from a fire-and-forget
@@ -330,6 +330,11 @@ export function observeHandler<C, R>(
  *     loop (request.start/end/error, cache.decision, ...).
  *   - segment-resolution/helpers.ts emits via a caller-provided report.telemetry
  *     sink rather than the ALS router context.
+ *   - rsc/handler.ts handleTimeoutResponse (request.timeout), the origin guard
+ *     (request.origin-rejected), and handleStore.onError (late-handle
+ *     handler.error) emit via router.telemetry directly — they run outside the
+ *     RouterContext ALS (only match()/matchPartial() enter it), so a
+ *     getRouterContext() read there throws and the event would vanish.
  */
 export function observeEvent(event: TelemetryEvent): void {
   // getRouterContext() either throws (real impl, outside a router context — e.g.

package/src/router/lazy-includes.ts

@@ -91,7 +91,11 @@ export function evaluateLazyEntry<TEnv = any>(
         for (const [name, pattern] of Object.entries(routes)) {
           deps.mergedRouteMap[name] = pattern;
         }
-        registerRouteMap(deps.mergedRouteMap);
+        // Register only this entry's routes (the delta): the full
+        // mergedRouteMap is seeded from the generated manifest at
+        // createRouter() time and already registered there — re-passing it
+        // made this request-path call O(total routes) (issue #666).
+        registerRouteMap(routes);
         return;
       }
     }
@@ -245,7 +249,9 @@ function runExpansion<TEnv = any>(
     deps.routesEntries.splice(insertIndex, 0, nestedEntry);
   }
 
-  registerRouteMap(deps.mergedRouteMap);
+  // Delta only — see the matching comment on the precomputed branch above and
+  // the WHY block on registerRouteMap (issue #666).
+  registerRouteMap(routesObject);
 
   // Expansion fully succeeded (handler ran, routes + nested includes spliced) —
   // mark done now so a mid-expansion throw above leaves lazyEvaluated=false and

package/src/router/loader-resolution.ts

@@ -420,10 +420,22 @@ function createLoaderExecutor<TEnv>(
     // throw. rendered() gating uses the captured isDslLoader (above), so this
     // does not grant rendered() to handler-invoked loaders. Uses a body-only
     // scope, so isInsideLoaderScope() / barrier / deadlock gating is unchanged.
+    //
+    // `handlerInvoked` (!isDslLoader) rides on the scope for the CONSUMPTION-
+    // LANE RULE: a handler-consumed loader's value is a BAKED copy in every
+    // shared artifact (cache(), "use cache", the PPR shell), so its identity
+    // reads are exempt from the shell-capture guard — same allowance the
+    // cache-purity guards give it. DSL segment loaders keep their lane
+    // machinery (live = masked at capture, bake = guarded). A DSL loader's
+    // nested deps inherit isDslLoader=false only when the CHAIN started in a
+    // handler; a chain started by the segment funnel stays DSL (the loader
+    // scope ALS survives the body's awaits).
     const promise = observePhase(PHASES.loader(loader.$$id), () =>
       Promise.resolve(
-        runInsideLoaderBodyScope(() =>
-          loaderFn(loaderCtx as LoaderContext<any, TEnv>),
+        runInsideLoaderBodyScope(
+          () => loaderFn(loaderCtx as LoaderContext<any, TEnv>),
+          loader.$$id,
+          !isDslLoader,
         ),
       ).finally(() => {
         pendingLoaders.delete(loader.$$id);