@rangojs/router 0.0.0-experimental.125 → 0.0.0-experimental.127

package/src/browser/validate-redirect-origin.ts

@@ -1,28 +1,56 @@
+import {
+  resolveSameOriginRedirect,
+  resolveExternalRedirect,
+} from "../redirect-origin.js";
+
 /**
  * Validate that a client-consumed redirect URL (from headers or Flight payload)
  * targets the same origin as the current page. Prevents open-redirect attacks
  * via crafted responses.
  *
+ * Thin wrapper over the shared {@link resolveSameOriginRedirect} rule (also used
+ * by the server guard in `rsc/redirect-guard.ts`) so client and server enforce
+ * the identical same-origin contract. Adds the client-side `console.error` on a
+ * block; the resolver itself stays pure.
+ *
  * @returns The canonical (normalized) URL string on success, or null if blocked.
  */
 export function validateRedirectOrigin(
   url: string,
   currentOrigin: string,
 ): string | null {
-  try {
-    const target = new URL(url, currentOrigin);
-    if (target.origin !== currentOrigin) {
-      console.error(
-        `[rango] Redirect blocked: origin mismatch (${target.origin})`,
-      );
-      return null;
-    }
-    // Origin matched above, so target.href is same-origin: return the
-    // canonical full href. This normalizes protocol-relative and other
-    // ambiguous forms.
-    return target.href;
-  } catch {
-    console.error(`[rango] Redirect blocked: invalid URL "${url}"`);
-    return null;
+  const resolved = resolveSameOriginRedirect(url, currentOrigin);
+  if (resolved === null) {
+    console.error(
+      `[rango] Redirect blocked: cross-origin or invalid target "${url}"`,
+    );
+  }
+  return resolved;
+}
+
+/**
+ * Validate an explicit off-origin redirect (`redirect(url, { external: true })`)
+ * the client is about to hard-navigate to via `window.location.assign()`.
+ *
+ * Thin wrapper over the shared {@link resolveExternalRedirect} rule (also used by
+ * the server guard in `rsc/redirect-guard.ts`) so client and server enforce the
+ * identical contract: `external` allows an off-origin target but only an
+ * http(s) scheme. This stops a forged or mistaken external payload carrying a
+ * `javascript:`/`data:` URL from turning `location.assign` into a scriptable
+ * navigation. Adds the client-side `console.error` on a block; the resolver
+ * itself stays pure.
+ *
+ * @returns The normalized URL string on success, or null if blocked.
+ */
+export function validateExternalRedirect(
+  url: string,
+  currentOrigin: string,
+): string | null {
+  const resolved = resolveExternalRedirect(url, currentOrigin);
+  if (resolved === null) {
+    console.error(
+      `[rango] External redirect blocked: non-http(s) target "${url}"`,
+    );
   }
+  return resolved;
 }

package/src/build/index.ts

@@ -22,15 +22,14 @@ export {
   type GeneratedManifest,
 } from "./generate-manifest.js";
 
-export {
-  buildRouteTrie,
-  buildPerRouterTrie,
-  type TrieNode,
-  type TrieLeaf,
-} from "./route-trie.js";
-
-export { collectFallbackClientRefs } from "./collect-fallback-refs.js";
-
+// buildRouteTrie / buildPerRouterTrie / collectFallbackClientRefs and the
+// TrieNode/TrieLeaf types are NOT exported here: they are build-pipeline
+// internals, not public API. Their only build-time consumer (the Vite
+// discovery pass) imports them directly from source via a relative path
+// (vite/discovery/discover-routers.ts), and the runtime RSC realm likewise
+// imports route-trie.js directly (rsc/manifest-init.ts). Keeping them off the
+// public ./build surface (#569 decision 6) means consumers can't mistake them
+// for intended API. generateManifest* / route-types / hashParams stay public.
 export {
   writePerModuleRouteTypes,
   extractRoutesFromSource,

package/src/build/route-trie.ts

@@ -22,9 +22,6 @@ export interface TrieLeaf {
   sp: string;
   /** Ancestry shortCodes from root to route [M0L0, M0L0L0, M0L0L0R499] */
   a: string[];
-  /** Optional param names declared on the route. Absent params are
-   * omitted from the matched params record (read as `undefined`). */
-  op?: string[];
   /** Constraint validation: paramName -> allowed values */
   cv?: Record<string, string[]>;
   /** Ordered param names for this route (positional) */
@@ -100,9 +97,49 @@ export function buildRouteTrie(
     });
   }
 
+  sortSuffixParams(root);
   return root;
 }
 
+/**
+ * Sort every node's suffix-param map (`node.xp`) by descending suffix length so
+ * the matcher tries the most specific suffix first. Overlapping suffixes like
+ * `.min.js` and `.js` must resolve by specificity, not route declaration order:
+ * a request for `/app.min.js` should match `:file.min.js`, not `:file.js`.
+ *
+ * This started as a bug — `walkTrie` iterates `node.xp` in object order and
+ * returns the first suffix the segment ends with, so the winner depended on
+ * which route was declared first. Sorting at build time fixes it allocation-free
+ * on the match hot path: the serialized production trie preserves this key order
+ * through JSON.parse, so dev (per-request rebuild) and production match
+ * identically. Array.prototype.sort is stable (ES2019+), so equal-length
+ * suffixes keep their declaration order — the router's existing tiebreak.
+ */
+function sortSuffixParams(node: TrieNode): void {
+  if (node.xp) {
+    const sorted: Record<string, { n: string; c: TrieNode }> = {};
+    for (const suffix of Object.keys(node.xp).sort(
+      (a, b) => b.length - a.length,
+    )) {
+      sorted[suffix] = node.xp[suffix];
+    }
+    node.xp = sorted;
+  }
+  if (node.s) {
+    for (const child of Object.values(node.s)) {
+      sortSuffixParams(child);
+    }
+  }
+  if (node.p) {
+    sortSuffixParams(node.p.c);
+  }
+  if (node.xp) {
+    for (const child of Object.values(node.xp)) {
+      sortSuffixParams(child.c);
+    }
+  }
+}
+
 /**
  * Build a per-router trie from a generated manifest. This is the single
  * construction path shared by build/discovery (discover-routers.ts, serialized
@@ -158,18 +195,14 @@ function insertRoute(
   node: TrieNode,
   segments: ParsedSegment[],
   index: number,
-  leaf: Omit<TrieLeaf, "op" | "cv" | "pa">,
+  leaf: Omit<TrieLeaf, "cv" | "pa">,
 ): void {
-  // op (full optional list) and cv (full constraint map) are route-level and
-  // identical on every terminal, so compute them once on the shared base.
-  const optionalParams: string[] = [];
+  // cv (full constraint map) is route-level and identical on every terminal,
+  // so compute it once on the shared base.
   const constraints: Record<string, string[]> = {};
 
   for (const seg of segments) {
     if (seg.type === "param") {
-      if (seg.optional) {
-        optionalParams.push(seg.value);
-      }
       if (seg.constraint) {
         constraints[seg.value] = seg.constraint;
       }
@@ -178,7 +211,6 @@ function insertRoute(
 
   const leafBase: Omit<TrieLeaf, "pa"> = {
     ...leaf,
-    ...(optionalParams.length > 0 ? { op: optionalParams } : {}),
     ...(Object.keys(constraints).length > 0 ? { cv: constraints } : {}),
   };
 

package/src/build/route-types/codegen.ts

@@ -88,14 +88,25 @@ export function generateRouteTypesSource(
     })
     .join("\n");
 
+  // The global augmentation extends an alias of `typeof NamedRoutes` rather than
+  // `Readonly<typeof NamedRoutes>`. `as const` already makes the members readonly,
+  // so the two are behaviour-identical, but `Readonly<>` is a homomorphic mapped
+  // type the compiler instantiates once per route at the augmentation site
+  // (~4 instantiations/route). An interface `extends` clause cannot name a bare
+  // `typeof` query, so the alias is what lets us drop the wrapper. Measured: ~35%
+  // fewer type instantiations on a 14k-route app; negligible (but free) on small.
   return `// Auto-generated by @rangojs/router - do not edit
 export const NamedRoutes = {
 ${objectBody}
 } as const;
 
+// Aliased so the augmentation below does not pay a homomorphic mapped-type
+// instantiation per route; \`as const\` already makes the members readonly.
+type NamedRoutesShape = typeof NamedRoutes;
+
 declare global {
   namespace Rango {
-    interface GeneratedRouteMap extends Readonly<typeof NamedRoutes> {}
+    interface GeneratedRouteMap extends NamedRoutesShape {}
   }
 }
 `;

package/src/cache/cache-runtime.ts

@@ -21,6 +21,7 @@ import {
   createClientTemporaryReferenceSet,
 } from "@vitejs/plugin-rsc/rsc";
 import { getRequestContext } from "../server/request-context.js";
+import { isUnderTestRunner } from "../runtime-env.js";
 import {
   isTainted,
   CACHED_FN_SYMBOL,
@@ -59,6 +60,10 @@ async function replyToCacheKey(encoded: string | FormData): Promise<string> {
   return text;
 }
 
+// Cached-fn ids already warned about running uncached under a test runner, so
+// the test-ergonomics warning fires once per fn rather than once per call.
+const warnedUncachedUnderTest = new Set<string>();
+
 // ============================================================================
 // Core: registerCachedFunction
 // ============================================================================
@@ -91,6 +96,22 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
     // and nothing is lost on a (non-existent) hit. Same applies to the
     // non-serializable-args bypass below.
     if (!store?.getItem) {
+      // Test-ergonomics guard: under a test runner, a "use cache" function that
+      // executes with no item-capable store seeded is exercising the UNCACHED
+      // path — a green test that proves nothing about caching. Warn once per fn
+      // id so the author knows to seed a cacheStore. Advisory (never throws), so
+      // a test that DELIBERATELY runs uncached is unaffected. Gated on the test
+      // runner (process.env.VITEST, not folded) so production never evaluates it.
+      if (isUnderTestRunner() && !warnedUncachedUnderTest.has(id)) {
+        warnedUncachedUnderTest.add(id);
+        console.warn(
+          `[rango] "use cache" function "${id}" executed but no cacheStore was ` +
+            `seeded; the cached path is NOT under test (it ran uncached). Pass ` +
+            `{ cacheStore, cacheProfiles } to runLoader/runMiddleware/renderHandler/` +
+            `runInRequestContext (or configure createRouter({ cache }) for dispatch) ` +
+            `to exercise it.`,
+        );
+      }
       const scoped = runWithCacheTagScope(() => fn.apply(this, args));
       const result = await scoped.result;
       // Still record the runtime tags into the request set so a cacheTag() in an

package/src/cache/cache-scope.ts

@@ -299,6 +299,26 @@ export class CacheScope {
     }
   }
 
+  /**
+   * Record this scope's segment-DSL cache({ tags }) into the request tag union
+   * synchronously, under the same gate cacheRoute() uses for a write.
+   *
+   * cacheRoute() already records these tags, but it is invoked inside
+   * requestCtx.waitUntil() by the cache-store middleware (and the proactive path
+   * re-resolves the whole tree before calling it), so its recording is deferred
+   * and RACES the document cache's post-body-drain snapshot of _requestTags. On a
+   * first-write (segment-cache miss) the document tag union could miss these
+   * tags, and updateTag()/revalidateTag() would then fail to invalidate the
+   * cached document until a later write reseeded it. Calling this synchronously
+   * in the request pipeline (before the snapshot) closes that window. Idempotent
+   * (the tag union is a Set), so the duplicate record in cacheRoute is harmless.
+   */
+  recordTags(requestCtx: RequestContext | undefined): void {
+    if (!this.enabled) return;
+    if (!this.conditionAllows("write")) return;
+    recordRequestTags(resolveCacheTags(this.config, requestCtx), requestCtx);
+  }
+
   /**
    * Cache all segments for a route (non-blocking via waitUntil)
    * Single cache entry per route request.

package/src/cache/document-cache.ts

@@ -55,6 +55,16 @@ interface CacheDirectives {
 function parseCacheControl(header: string | null): CacheDirectives | null {
   if (!header) return null;
 
+  // RFC 7234: in a SHARED cache, `private` and `no-store` forbid storage and
+  // MUST win over `s-maxage` even though `private, s-maxage` is contradictory.
+  // The document cache is a shared edge store, so refuse both regardless of any
+  // s-maxage / stale-while-revalidate also present. Match standalone directive
+  // tokens (start/end, whitespace, comma, semicolon, or `=` bounded), not a
+  // substring, so a value containing "private" cannot false-veto.
+  if (/(^|[\s,;])(private|no-store)(?=$|[\s,;=])/i.test(header)) {
+    return null;
+  }
+
   const directives: CacheDirectives = {};
 
   // Parse s-maxage

package/src/cache/profile-registry.ts

@@ -1,9 +1,11 @@
 /**
- * Cache Profile Registry
+ * Cache profile resolution.
  *
- * Named cache profiles for "use cache" directive.
- * Profiles define TTL, SWR, and optional default tags.
- * Set by createRouter() at startup, read by registerCachedFunction() at runtime.
+ * Named cache profiles for the "use cache" directive define TTL, SWR, and
+ * optional default tags. createRouter() resolves the user's profiles once via
+ * resolveCacheProfiles() and threads the resulting map onto each request
+ * context; the "use cache: <profile>" runtime path reads it from there
+ * (request-scoped) — there is no global registry.
  */
 
 export interface CacheProfile {
@@ -17,10 +19,6 @@ export interface CacheProfile {
 
 const DEFAULT_PROFILE: CacheProfile = { ttl: 900, swr: 1800 };
 
-let _profiles: Record<string, CacheProfile> = {
-  default: DEFAULT_PROFILE,
-};
-
 const PROFILE_NAME_RE = /^[a-zA-Z0-9_-]+$/;
 
 /**
@@ -49,29 +47,3 @@ export function resolveCacheProfiles(
   }
   return merged;
 }
-
-/**
- * Set all cache profiles in the global registry.
- * Called by createRouter() at startup for DSL-time resolution
- * (cache("profileName") reads from this during route definition).
- *
- * WARNING: This is global mutable state. It exists only for DSL-time
- * reads. Runtime resolution (registerCachedFunction) uses request-scoped
- * profiles and does NOT read from this registry.
- */
-export function setCacheProfiles(profiles: Record<string, CacheProfile>): void {
-  _profiles = resolveCacheProfiles(profiles);
-}
-
-/**
- * Read a profile out of the global registry by name.
- *
- * There is currently no production reader: the "use cache: <profile>" runtime
- * path resolves from the request-scoped _cacheProfiles map (see
- * cache-runtime.ts), and the route DSL has no cache("profileName") form (see
- * dsl-helpers.ts). This accessor exists so tests can assert what
- * setCacheProfiles() wrote into the global registry.
- */
-export function getCacheProfile(name: string): CacheProfile | undefined {
-  return _profiles[name];
-}

package/src/client.rsc.tsx

@@ -63,5 +63,8 @@ export { useHref } from "./browser/react/use-href.js";
 export { useReverse } from "./browser/react/use-reverse.js";
 
 export { useHandle } from "./browser/react/use-handle.js";
+// Type a deferred-aware consumer narrows: an accumulated entry may be a Promise
+// (a `ctx.use(Handle).defer()` slot) until it resolves.
+export type { DeferredHandleEntry } from "./defer.js";
 
 export { useLocationState } from "./browser/react/location-state.js";

package/src/client.tsx

@@ -344,6 +344,8 @@ export type {
   RouterInstance,
   RouterNavigateOptions,
   ReadonlyURLSearchParams,
+  ActionState,
+  ActionLifecycleState,
 } from "./browser/types.js";
 
 export {
@@ -382,6 +384,9 @@ export {
 
 export { type Handle } from "./handle.js";
 export { useHandle } from "./browser/react/use-handle.js";
+// Type a deferred-aware consumer narrows: an accumulated entry may be a Promise
+// (a `ctx.use(Handle).defer()` slot) until it resolves.
+export type { DeferredHandleEntry } from "./defer.js";
 
 export { Meta } from "./handles/meta.js";
 export { MetaTags } from "./handles/MetaTags.js";

package/src/cloudflare/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Cloudflare preset integration surface for @rangojs/router.
+ *
+ * Imported via `@rangojs/router/cloudflare`. Cloudflare-only helpers live here
+ * so Node/other-platform consumers never pull them in.
+ */
+
+export {
+  createCloudflareTracing,
+  type CloudflareTracingOptions,
+} from "./tracing.js";

package/src/cloudflare/tracing.ts

@@ -0,0 +1,109 @@
+/**
+ * Cloudflare custom-spans integration.
+ *
+ * Bridges the router's performance phases (request, middleware, action,
+ * loaders, render, ssr) onto Cloudflare Workers custom spans so they show up in the
+ * trace waterfall and OpenTelemetry exports next to the platform's automatic
+ * spans (KV reads, D1 queries, fetch calls), with correct parent-child nesting.
+ *
+ * Usage (Cloudflare preset only):
+ *
+ *   import { createRouter } from "@rangojs/router";
+ *   import { createCloudflareTracing } from "@rangojs/router/cloudflare";
+ *
+ *   export const router = createRouter({
+ *     tracing: createCloudflareTracing(),
+ *   });
+ *
+ * The runner reads `executionContext.tracing` (the same object as
+ * `import { tracing } from "cloudflare:workers"`) at call time. It is therefore
+ * dependency-free: no `cloudflare:workers` import and no hard dependency on
+ * `@cloudflare/workers-types`, matching the convention in cache/cf. When the
+ * worker is not running on a tracing-enabled Cloudflare runtime — Node, dev
+ * without a tracing destination, an older runtime — `executionContext.tracing`
+ * is undefined and every span call falls through to the work directly, so the
+ * request behaves exactly as if tracing were off. Whether spans are actually
+ * recorded is governed by the `observability`/tracing block in wrangler config.
+ *
+ * Span duration note: a phase span ends when its callback's returned value (or
+ * promise) settles, which for the streaming phases (request/render/ssr) is when
+ * the Response or HTML/RSC stream is *constructed*, not when the body finishes
+ * draining. Loader/Suspense work that settles while the body streams therefore
+ * extends past the parent span's end, and platform spans emitted during that
+ * drain (deferred SSR, waitUntil-scheduled cache writes) are siblings of the
+ * automatic request span rather than children of rango.*. Phase spans bound
+ * setup-to-stream-handoff; they are not a full request-duration measure.
+ */
+
+import { _getRequestContext } from "../server/request-context.js";
+import {
+  type RouterTracingConfig,
+  type SpanRunner,
+  type TracePhaseToggles,
+  NOOP_TRACE_SPAN,
+} from "../router/tracing.js";
+
+/**
+ * Minimal local view of Cloudflare's `Span`. Declared here (not imported from
+ * `@cloudflare/workers-types`) to avoid a hard type dependency.
+ */
+interface CloudflareSpan {
+  readonly isTraced: boolean;
+  setAttribute(key: string, value?: boolean | number | string): void;
+}
+
+/** Minimal local view of Cloudflare's `Tracing` (only enterSpan is used). */
+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;
+}
+
+/**
+ * Resolve the per-request Cloudflare tracer from the active execution context.
+ * Returns undefined off-Cloudflare or when tracing is not enabled for the
+ * worker, in which case the caller runs the work without a span.
+ */
+function getRequestTracer(): CloudflareTracing | undefined {
+  const executionContext = _getRequestContext()?.executionContext as
+    | { tracing?: CloudflareTracing }
+    | undefined;
+  const tracing = executionContext?.tracing;
+  return tracing && typeof tracing.enterSpan === "function"
+    ? tracing
+    : undefined;
+}
+
+const cloudflareSpanRunner: SpanRunner = (name, fn) => {
+  const tracer = getRequestTracer();
+  if (!tracer) return fn(NOOP_TRACE_SPAN);
+  // enterSpan runs the callback now and ends the span when its return value
+  // (or returned promise) settles; spans nest by JS async context. fn's param
+  // is the narrower TraceSpan, so the wider CloudflareSpan satisfies it directly.
+  return tracer.enterSpan(name, fn);
+};
+
+/**
+ * Create the tracing config for a Cloudflare router. Pass the result to
+ * `createRouter({ tracing })`. Spans are emitted for the request, middleware,
+ * action, loaders, render, and ssr phases; pass `spans` to turn individual
+ * phases off.
+ *
+ * @see createOTelTracing (`@rangojs/router`) for the same slot on any platform
+ *   with an OpenTelemetry SDK.
+ */
+export function createCloudflareTracing(
+  options: CloudflareTracingOptions = {},
+): RouterTracingConfig {
+  return {
+    runner: cloudflareSpanRunner,
+    enabled: options.enabled ?? true,
+    spans: options.spans,
+  };
+}

package/src/context-var.ts

@@ -70,6 +70,18 @@ export function isContextVar(value: unknown): value is ContextVar<unknown> {
   );
 }
 
+/**
+ * Does a variables object hold any entries? Counts both string keys and the
+ * symbol-keyed entries (context vars are stored under symbols), so an object
+ * carrying only symbol-keyed vars is still reported as non-empty.
+ */
+export function hasContextVars(variables: object): boolean {
+  return (
+    Object.keys(variables).length > 0 ||
+    Object.getOwnPropertySymbols(variables).length > 0
+  );
+}
+
 /**
  * Symbol used as a Set stored on the variables object to track
  * which keys hold non-cacheable values (from write-level { cache: false }).