@rangojs/router 0.5.0 → 0.5.2

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

@@ -57,10 +57,13 @@ import { reportCacheError, reportingAsync } from "../cache-error.js";
 import type { CacheErrorCategory } from "../cache-error.js";
 import { bufferToBase64, base64ToBuffer } from "./cf-base64.js";
 import {
+  KV_KEY_PRESERVED_PREFIX_BYTES,
   KV_MAX_KEY_BYTES,
   KV_MIN_EXPIRATION_TTL,
   kvKeyByteLength,
+  kvKeyDigest,
   remainingCacheControl,
+  truncateToBytes,
 } from "./cf-kv-utils.js";
 import {
   TAG_MARKER_CACHE_PREFIX,
@@ -1325,7 +1328,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
       // L2: delete from KV
       if (this.kv && this.waitUntil) {
-        const kvKey = this.toKVKey(key);
+        const kvKey = await this.toKVKey(key);
         this.waitUntil(() =>
           reportingAsync(
             () => this.kv!.delete(kvKey),
@@ -1559,7 +1562,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
       // L2: persist to KV (KV requires expirationTtl >= 60s)
       if (this.kv && this.waitUntil && totalTtl >= 60) {
-        const kvKey = this.toDocKVKey(key);
+        const kvKey = await this.toDocKVKey(key);
         // Finding #3: never persist a per-client signal in the KV envelope.
         const headersArray: [string, string][] = [];
         response.headers.forEach((v, k) => {
@@ -1848,7 +1851,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       // JSON.stringify(KVItemEnvelope); field names differ from L1 so we assemble
       // from the pre-escaped value/handles pieces rather than re-stringifying.
       if (this.kv && this.waitUntil && totalTtl >= 60) {
-        const kvKey = this.toKVKey(`fn:${key}`);
+        const kvKey = await this.toKVKey(`fn:${key}`);
         const expiresAt = staleAt + swrWindow * 1000;
         let envelopeJson = `{"v":${valueJson}`;
         if (handlesJson !== undefined) envelopeJson += `,"h":${handlesJson}`;
@@ -2073,20 +2076,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       const taggedAt =
         Array.isArray(tags) && tags.length > 0 ? entry.createdAt : undefined;
 
-      const kvKey = this.toKVKey(`shell:${key}`);
-      let writeKv = retentionTtl >= KV_MIN_EXPIRATION_TTL;
-      const kvKeyBytes = kvKeyByteLength(kvKey);
-      if (kvKeyBytes > KV_MAX_KEY_BYTES) {
-        reportCacheError(
-          new Error(
-            `shell cache key produces a ${kvKeyBytes}-byte KV key, over the ` +
-              `${KV_MAX_KEY_BYTES}-byte limit; the shell was not persisted to KV (L2).`,
-          ),
-          "cache-write",
-          "[CFCacheStore] putShell",
-        );
-        writeKv = false;
-      }
+      const kvKey = await this.toKVKey(`shell:${key}`);
+      const writeKv = retentionTtl >= KV_MIN_EXPIRATION_TTL;
 
       const write = (async (): Promise<"stored" | "invalidated" | void> => {
         if (
@@ -2219,7 +2210,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv) return null;
     try {
       const readStartedAt = INTERNAL_RANGO_DEBUG ? Date.now() : 0;
-      const kvKey = this.toKVKey(`shell:${key}`);
+      const kvKey = await this.toKVKey(`shell:${key}`);
       const { value: envelope, timedOut } =
         await this.kvGetOrEvict<CFShellEnvelope>(
           kvKey,
@@ -2330,11 +2321,27 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   /**
    * Convert string key to KV key string.
    * Uses same version prefix as Cache API for consistent invalidation.
+   *
+   * Single chokepoint for EVERY KV family (segments, items, shells, documents
+   * via toDocKVKey, tag markers via tagMarkerKey): a composed key over
+   * Cloudflare KV's 512-byte limit is normalized to a preserved readable
+   * prefix plus a SHA-256-derived 128-bit digest of the FULL key. Without
+   * this, kv.put/get reject with `414 ... exceeds key length limit of 512`
+   * and the entry silently never reaches L2 (observed in production for
+   * "use cache" items whose serialized args — e.g. a CMS query object — blow
+   * the cap; autobarn pilot). Keys are opaque storage identifiers, so
+   * normalization is semantics-preserving as long as distinct logical keys
+   * stay distinct: colliding requires an identical 400-byte prefix AND a
+   * 128-bit SHA-256 collision. Deterministic, so every family's read, write,
+   * and delete paths agree on the stored key.
    * @internal
    */
-  private toKVKey(key: string): string {
+  private async toKVKey(key: string): Promise<string> {
     const versionPath = this.version ? `v/${this.version}/` : "";
-    return `${versionPath}${key}`;
+    const composed = `${versionPath}${key}`;
+    if (kvKeyByteLength(composed) <= KV_MAX_KEY_BYTES) return composed;
+    const prefix = truncateToBytes(composed, KV_KEY_PRESERVED_PREFIX_BYTES);
+    return `${prefix}~${await kvKeyDigest(composed)}`;
   }
 
   /**
@@ -2364,7 +2371,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    * document tier is the one with a request-host context here.
    * @internal
    */
-  private toDocKVKey(key: string): string {
+  private toDocKVKey(key: string): Promise<string> {
     return this.toKVKey(`h/${this.docKVHost()}/doc:${key}`);
   }
 
@@ -2480,7 +2487,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
   // ============================================================================
 
   /** KV key for a tag's invalidation marker. */
-  private tagMarkerKey(tag: string): string {
+  private tagMarkerKey(tag: string): Promise<string> {
     return this.toKVKey(`${TAG_MARKER_PREFIX}${tag}`);
   }
 
@@ -2805,7 +2812,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // (reported cache-read), which also fails open. Either way one slow tag
     // never amplifies into a per-segment stall.
     const { value: raw, timedOut } = await this.readWithTimeout<string | null>(
-      () => this.kv!.get(this.tagMarkerKey(tag), { type: "text" }),
+      async () => this.kv!.get(await this.tagMarkerKey(tag), { type: "text" }),
       this.kvReadTimeoutMs,
       "tag marker KV read",
     );
@@ -3012,7 +3019,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
    *
    * Durable-write integrity: the in-memory write-through (memo + L1) for a tag
    * runs ONLY after that tag's KV marker write is confirmed. If any KV write
-   * fails (transient error, or an over-512-byte key), this rejects with the
+   * fails (transient error; over-limit keys are normalized by toKVKey rather
+   * than rejected), this rejects with the
    * failed tags so an awaiting updateTag() surfaces the failure instead of
    * silently reporting success while other requests/colos serve stale data. The
    * eager purge still fires for the whole batch first (it is additive).
@@ -3065,18 +3073,10 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
       }
       await Promise.all(
         tags.map(async (tag) => {
-          const markerKey = this.tagMarkerKey(tag);
-          const markerKeyBytes = kvKeyByteLength(markerKey);
-          if (markerKeyBytes > KV_MAX_KEY_BYTES) {
-            failedTags.add(tag);
-            errors.push(
-              new Error(
-                `tag "${tag}" produces a ${markerKeyBytes}-byte KV ` +
-                  `marker key, over the ${KV_MAX_KEY_BYTES}-byte limit`,
-              ),
-            );
-            return;
-          }
+          // An over-limit tag no longer rejects: tagMarkerKey normalizes
+          // through toKVKey, and the marker read path derives the key the same
+          // way, so oversized tags invalidate correctly instead of erroring.
+          const markerKey = await this.tagMarkerKey(tag);
           try {
             await this.kv!.put(markerKey, String(invalidatedAt), {
               ...(this.tagInvalidationTtl
@@ -3200,7 +3200,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv) return null;
 
     try {
-      const kvKey = this.toKVKey(key);
+      const kvKey = await this.toKVKey(key);
       const { value: envelope, timedOut } =
         await this.kvGetOrEvict<KVSegmentEnvelope>(
           kvKey,
@@ -3294,29 +3294,6 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     // KV requires expirationTtl >= 60s. Skip write for short-lived entries.
     if (!this.kv || !this.waitUntil || totalTtl < 60) return;
 
-    const kvKey = this.toKVKey(key);
-
-    // Reject an oversized data-segment KV key the same way tag-marker keys are
-    // rejected in invalidateTags(). A key over KV_MAX_KEY_BYTES makes kv.put()
-    // fail, so the segment silently never lands in L2 (KV) and every cold-colo
-    // or TTL-expired read re-renders instead of serving stale. Segment keys can
-    // grow with user-controlled inputs (e.g. a route's search params), so report
-    // a clear, actionable error and skip the doomed write rather than letting it
-    // reject deep inside waitUntil as an opaque cache-write failure.
-    const kvKeyBytes = kvKeyByteLength(kvKey);
-    if (kvKeyBytes > KV_MAX_KEY_BYTES) {
-      reportCacheError(
-        new Error(
-          `cache segment key produces a ${kvKeyBytes}-byte KV key, over the ` +
-            `${KV_MAX_KEY_BYTES}-byte limit; the segment was not persisted to KV (L2). ` +
-            `Reduce the cache-key inputs (e.g. large search params on this route).`,
-        ),
-        "cache-write",
-        "[CFCacheStore] kvSetSegment",
-      );
-      return;
-    }
-
     const expiresAt = staleAt + swrWindow * 1000;
     // Same wire shape as JSON.stringify({ d, s, e }) — dataJson is already
     // valid JSON for CachedEntryData, so embedding it avoids re-walking the tree.
@@ -3324,8 +3301,8 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
 
     this.waitUntil(() =>
       reportingAsync(
-        () =>
-          this.kv!.put(kvKey, envelopeJson, {
+        async () =>
+          this.kv!.put(await this.toKVKey(key), envelopeJson, {
             expirationTtl: totalTtl,
           }),
         "cache-write",
@@ -3386,7 +3363,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv) return null;
 
     try {
-      const kvKey = this.toKVKey(`fn:${key}`);
+      const kvKey = await this.toKVKey(`fn:${key}`);
       const { value: envelope, timedOut } =
         await this.kvGetOrEvict<KVItemEnvelope>(
           kvKey,
@@ -3508,7 +3485,7 @@ export class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
     if (!this.kv) return null;
 
     try {
-      const kvKey = this.toDocKVKey(key);
+      const kvKey = await this.toDocKVKey(key);
       // The document path is debug-silent (op is only get/getItem): a KV-read
       // timeout here is bounded for resilience parity (kvGetOrEvict applies the
       // budget) but emits no kv-timeout event, so its absence from the debug

package/src/cache/cf/cf-cache-types.ts

@@ -333,7 +333,7 @@ export interface CFCacheStoreOptions<TEnv = unknown> {
    * cannot stall the request; the read then falls through to its normal miss
    * path (L2/KV or render).
    *
-   * Defaults to {@link EDGE_LOOKUP_TIMEOUT_MS} (10). Set to 0 (or any value
+   * Defaults to {@link EDGE_LOOKUP_TIMEOUT_MS} (25). Set to 0 (or any value
    * <= 0) to disable the budget and always await `match`.
    */
   edgeLookupTimeoutMs?: number;

package/src/cache/cf/cf-kv-utils.ts

@@ -26,6 +26,44 @@ export function kvKeyByteLength(key: string): number {
   return kvKeyEncoder.encode(key).length;
 }
 
+/**
+ * Bytes of a composed key preserved verbatim when an over-limit key is
+ * normalized (toKVKey). 400 leaves room for the `~` separator and the 32-hex
+ * digest inside KV_MAX_KEY_BYTES while keeping the version prefix and most of
+ * the logical key readable (and prefix-listable) in the KV dashboard.
+ */
+export const KV_KEY_PRESERVED_PREFIX_BYTES = 400;
+
+/**
+ * Truncate to at most `maxBytes` of UTF-8. A multibyte sequence split at the
+ * boundary decodes to U+FFFD, which is stripped — the result is deterministic
+ * for a given input, which is all key normalization needs.
+ */
+export function truncateToBytes(value: string, maxBytes: number): string {
+  const bytes = kvKeyEncoder.encode(value);
+  if (bytes.length <= maxBytes) return value;
+  return new TextDecoder()
+    .decode(bytes.subarray(0, maxBytes))
+    .replace(/�+$/, "");
+}
+
+/**
+ * 128-bit hex digest (SHA-256 truncated) of a composed KV key. WebCrypto is
+ * available on workerd and Node alike; SHA-256 (not a fast non-crypto hash)
+ * because cache keys embed user-influenced serialized args — an engineered
+ * collision between two normalized keys would serve one entry's payload for
+ * the other's.
+ */
+export async function kvKeyDigest(value: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    kvKeyEncoder.encode(value),
+  );
+  return Array.from(new Uint8Array(digest, 0, 16), (b) =>
+    b.toString(16).padStart(2, "0"),
+  ).join("");
+}
+
 /**
  * Compute the Cache-Control directive for a stale-path REVALIDATING re-put from
  * the entry's stored hard-expiry deadline (CACHE_EXPIRES_AT_HEADER). Returns the

package/src/cache/segment-codec.ts

@@ -18,6 +18,12 @@ import {
 } from "@vitejs/plugin-rsc/rsc";
 import { createFromReadableStream } from "@vitejs/plugin-rsc/rsc";
 
+// Preserve embedded server references on a cache/prerender HIT so they
+// re-serialize to the client instead of resolving to a raw function React
+// refuses to pass to a Client Component. Shared across the deserialize sites so
+// the decode policy has a single owner.
+const PRESERVE_SERVER_REFS = { preserveServerReferences: true } as const;
+
 /**
  * Convert a ReadableStream to a string.
  */
@@ -81,7 +87,11 @@ export async function rscDeserialize<T>(
 
   const temporaryReferences = createTemporaryReferenceSet();
   const stream = stringToStream(encoded);
-  return createFromReadableStream<T>(stream, { temporaryReferences });
+  return createFromReadableStream<T>(
+    stream,
+    { temporaryReferences },
+    PRESERVE_SERVER_REFS,
+  );
 }
 
 /**
@@ -116,7 +126,11 @@ export async function serializeResult(value: unknown): Promise<string | null> {
 export async function deserializeResult<T>(encoded: string): Promise<T> {
   const temporaryReferences = createTemporaryReferenceSet();
   const stream = stringToStream(encoded);
-  return createFromReadableStream<T>(stream, { temporaryReferences });
+  return createFromReadableStream<T>(
+    stream,
+    { temporaryReferences },
+    PRESERVE_SERVER_REFS,
+  );
 }
 
 /**
@@ -271,9 +285,11 @@ export async function deserializeSegments(
 
       const [component, layout, loaderData, loaderDataPromise, loadingData] =
         await Promise.all([
-          createFromReadableStream(stringToStream(item.encoded), {
-            temporaryReferences,
-          }),
+          createFromReadableStream(
+            stringToStream(item.encoded),
+            { temporaryReferences },
+            PRESERVE_SERVER_REFS,
+          ),
           rscDeserialize(item.encodedLayout),
           rscDeserialize(item.encodedLoaderData),
           rscDeserialize(item.encodedLoaderDataPromise),

package/src/handles/is-thenable.ts

@@ -1,8 +1,6 @@
 /**
- * Single thenable predicate for the resolve-by-default handle machinery
- * (`handles/deferred-resolution.ts`, its sole owner) — it decides which top-level
- * handle entries are deferred (`Promise`) values to await before any consumer
- * sees them, and which pass through verbatim.
+ * Shared thenable predicate for framework orchestration. It decides which values
+ * participate in promise lifecycles and which pass through synchronously.
  *
  * Requires a CALLABLE `then` (`typeof obj.then === "function"`), not merely a
  * `"then" in obj` membership check, so a non-promise carrying a `then` field

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

@@ -33,6 +33,7 @@ import type {
   TransitionItem,
   UseItems,
 } from "../route-types.js";
+import type { StaticHandlerRef } from "../static-handler.js";
 
 // Re-export route item types for backward compatibility
 export type {
@@ -140,8 +141,8 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
    *   },
    * })
    * ```
-   * @param slots - Object with slot names (prefixed with @) mapped to handlers
-   *                or `{ handler, use? }` slot descriptors.
+   * @param slots - Object with slot names (prefixed with @) mapped to handlers,
+   *                Static() definitions, or `{ handler, use? }` descriptors.
    * @param use - Optional callback for loaders, loading, revalidate, etc.
    *              Items here apply to every slot in the call (broadcast).
    *              For per-slot single-assignment items, use the slot descriptor's
@@ -157,8 +158,9 @@ export type RouteHelpers<T extends RouteDefinition, TEnv> = {
       `@${string}`,
       | Handler<any, any, TEnv>
       | ReactNode
+      | StaticHandlerRef
       | {
-          handler: Handler<any, any, TEnv> | ReactNode;
+          handler: Handler<any, any, TEnv> | ReactNode | StaticHandlerRef;
           use?: () => UseItems<ParallelUseItem>;
         }
     >,

package/src/router/match-middleware/cache-lookup.ts

@@ -450,21 +450,30 @@ export function withCacheLookup<TEnv>(
       resolveLoadersOnly,
     } = getRouterContext<TEnv>();
 
-    if (
-      !ctx.isAction &&
-      prerenderStoreShortCircuits(ctx.matched.pr, ctx.request)
-    ) {
-      await ensurePrerenderDeps();
-      if (prerenderStoreInstance) {
-        const served = yield* tryPrerenderLookup(
-          ctx,
-          state,
-          pipelineStart,
-          pipelineReqCtx,
-          resolveLoadersOnly,
-          resolveLoadersOnlyWithRevalidation,
-        );
-        if (served) return;
+    if (prerenderStoreShortCircuits(ctx.matched.pr, ctx.request)) {
+      // Actions normally re-render fresh and skip the prerender store. But a pure
+      // Prerender route's handler is evicted at build, so there is no fresh
+      // handler to run on an action re-render -- without the fallback the
+      // re-render falls through to the evicted handler and throws "No prerender
+      // data found". Serve the prerendered entry instead (the action ran already;
+      // its result is applied client-side via useActionState). Passthrough routes
+      // keep a liveHandler, so they still re-render fresh on actions.
+      const isPassthroughPrerenderRoute = ctx.entries.some(
+        (entry) => entry.type === "route" && entry.isPassthrough === true,
+      );
+      if (!ctx.isAction || !isPassthroughPrerenderRoute) {
+        await ensurePrerenderDeps();
+        if (prerenderStoreInstance) {
+          const served = yield* tryPrerenderLookup(
+            ctx,
+            state,
+            pipelineStart,
+            pipelineReqCtx,
+            resolveLoadersOnly,
+            resolveLoadersOnlyWithRevalidation,
+          );
+          if (served) return;
+        }
       }
     }
 

package/src/rsc/handler.ts

@@ -110,6 +110,7 @@ import {
   type RequestPlan,
   type ExecutableRequestPlan,
 } from "../router/request-classification.js";
+import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 
 /**
  * Create an RSC request handler.
@@ -247,7 +248,8 @@ export function createRSCHandler<
     actionId?: string,
   ): Promise<Response> {
     const timeoutError = new RouterTimeoutError(phase, durationMs);
-    const cursor = _getRequestContext<TEnv>()?._renderForeground;
+    const requestContext = _getRequestContext<TEnv>();
+    const cursor = requestContext?._renderForeground;
     const render: RenderTimeoutContext | undefined =
       phase === "render-start" && cursor
         ? {
@@ -261,11 +263,29 @@ export function createRSCHandler<
             }),
           }
         : undefined;
+    const trace =
+      phase === "render-start" ? requestContext?._activeRoutine : undefined;
+    const activeEntries = trace?.active() ?? [];
+    const activeStep = activeEntries.at(-1);
+    const activeAt = performance.now();
+    const routineSnapshot =
+      trace && activeStep
+        ? {
+            name: trace.name,
+            path: activeEntries.map((entry) => entry.name),
+            durationMs: activeAt - activeStep.startedAt,
+          }
+        : undefined;
+
+    if (INTERNAL_RANGO_DEBUG && trace && activeStep) {
+      console.log(
+        `[routine] TIMEOUT ${request.method} ${url.pathname} (${trace.name})\n${trace.formatActive(activeEntries, activeAt)}`,
+      );
+    }
 
-    // Each surface gets its OWN shallow copy of the snapshot. onError, telemetry,
-    // and onTimeout are independent consumers; a consumer that mutates its
-    // `render` (e.g. an onError redacting metadata) must not corrupt what the
-    // other two observe.
+    // Each surface gets its OWN shallow render snapshot. A consumer that mutates
+    // its copy must not corrupt what the other two observe. The internal-debug
+    // routine snapshot is bounded metadata sent only to onError.
     callOnError(timeoutError, phase === "action" ? "action" : "handler", {
       request,
       url,
@@ -278,6 +298,7 @@ export function createRSCHandler<
         phase,
         durationMs,
         ...(render && { render: { ...render } }),
+        ...(routineSnapshot && { routine: routineSnapshot }),
       },
     });
 

package/src/rsc/helpers.ts

@@ -7,6 +7,7 @@
 import {
   _getRequestContext,
   getLocationState,
+  setRequestContextParams,
 } from "../server/request-context.js";
 import type { RequestContext } from "../server/request-context.js";
 import { resolveLocationStateEntries } from "../browser/react/location-state-shared.js";
@@ -23,6 +24,7 @@ import {
 import type { MiddlewareEntry, MiddlewareFn } from "../router/middleware.js";
 import { formatCacheSignalHeader } from "../router/telemetry.js";
 import type { RscPayload } from "./types.js";
+import type { HandlerContext } from "./handler-context.js";
 
 /**
  * DEVELOPMENT/TEST ONLY. When the debug cache signal gate is on,
@@ -381,3 +383,14 @@ export function finalizeResponse(response: Response): Response {
   if (!ctx) return response;
   return drainOnResponseCallbacks(ctx, response);
 }
+
+/** Match and stamp params/routeName on the request context as one operation. */
+export async function matchAndRecordParams<TEnv>(
+  ctx: HandlerContext<TEnv>,
+  request: Request,
+  env: TEnv,
+): Promise<Awaited<ReturnType<HandlerContext<TEnv>["router"]["match"]>>> {
+  const match = await ctx.router.match(request, { env });
+  setRequestContextParams(match.params, match.routeName);
+  return match;
+}