@rangojs/router 0.0.0-experimental.8 → 0.0.0-experimental.80daa23e

package/dist/types/cache/cache-runtime.d.ts

@@ -0,0 +1,51 @@
+/**
+ * "use cache" Runtime
+ *
+ * Provides the runtime wrapper for functions marked with "use cache" directive.
+ * The Vite transform plugin wraps exports with registerCachedFunction().
+ *
+ * On cache miss: executes the function, serializes the result via RSC Flight
+ * protocol, captures handle data if tainted ctx is detected, and stores in
+ * the SegmentCacheStore.
+ *
+ * On cache hit: deserializes the cached result, restores handle data if present.
+ *
+ * On stale hit: returns stale data immediately, triggers background
+ * re-execution via waitUntil().
+ */
+import { isCachedFunction } from "./taint.js";
+export { isCachedFunction };
+/**
+ * Convert encodeReply result to a stable string key.
+ *
+ * encodeReply may return a string or FormData. A plain string is already
+ * deterministic for a given arg set, so return it verbatim. FormData (emitted
+ * whenever a key arg is a typed array / Blob / File / a large object React
+ * lazily chunks) carries a per-call RANDOM multipart boundary
+ * (`formdata-undici-<random>`); stringifying the whole body via
+ * `new Response(formData).text()` would therefore produce a DIFFERENT key on
+ * every call, so the cached function would always miss and the store would
+ * accumulate one duplicate entry per call (unbounded growth).
+ *
+ * Instead derive the key from the entries themselves, independent of the
+ * boundary: iterate in sorted-key order and, for each value, emit a
+ * boundary-free token — `s:<value>` for strings, `b:<size>:<type>:<name>:<hash>`
+ * for Blob/File (bytes folded via djb2 so distinct payloads of equal
+ * size/type/name still differ). Strings carry an `s:` type tag so a string whose
+ * value happens to equal a blob token (e.g. the literal `b:4::a:b:<hash>`) cannot
+ * collide with an actual Blob/File entry under the same FormData key. The
+ * user-controlled `type`/`name` are percent-encoded before joining so an embedded
+ * `:` cannot shift the field boundaries and collide two distinct files (e.g.
+ * {name:"a:b",type:""} vs {name:"b",type:":a"}). The result is stable across
+ * identical arg sets.
+ */
+export declare function replyToCacheKey(encoded: string | FormData): Promise<string>;
+/**
+ * Register a function as a cached function.
+ * Called by the Vite transform for each "use cache" function.
+ *
+ * @param fn - The original async function
+ * @param id - Stable identifier (module path + export name)
+ * @param profileName - Cache profile name (from "use cache: profileName" or "default")
+ */
+export declare function registerCachedFunction<T extends (...args: any[]) => any>(fn: T, id: string, profileName: string): T;

package/dist/types/cache/cache-scope.d.ts

@@ -0,0 +1,215 @@
+/**
+ * CacheScope - Runtime cache scope for iterator-based caching
+ *
+ * Each cache() boundary in the route tree creates a new CacheScope.
+ * The scope owns: config, key management, and storage operations.
+ *
+ * Serialization is delegated to segment-codec.ts.
+ * Handle data capture/restore is delegated to handle-snapshot.ts.
+ */
+import type { PartialCacheOptions } from "../types.js";
+import type { ResolvedSegment } from "../types.js";
+import type { SegmentCacheStore } from "./types.js";
+import type { RequestContext } from "../server/request-context.js";
+export declare function resolveCacheTags(config: PartialCacheOptions | false, ctx: RequestContext | undefined): string[] | undefined;
+/**
+ * Discriminated outcome of a route cache lookup — see
+ * {@link CacheScope.lookupRouteDetailed} for what each status licenses.
+ */
+export type CacheRouteLookupOutcome = {
+    status: "hit";
+    result: {
+        segments: ResolvedSegment[];
+        shouldRevalidate: boolean;
+    };
+} | {
+    status: "miss" | "bypass" | "error";
+};
+/**
+ * CacheScope represents a cache boundary in the route tree.
+ *
+ * When withCache encounters an entry with cache config, it creates
+ * a new CacheScope. The scope owns key management, TTL resolution,
+ * and storage operations. Serialization is handled by segment-codec.ts.
+ *
+ * Store resolution priority:
+ * 1. Explicit store in cache() options
+ * 2. App-level store from handler config
+ *
+ * TTL resolution priority:
+ * 1. Explicit value in cache() options
+ * 2. Explicit store's defaults (if store specified)
+ * 3. App-level store's defaults
+ * 4. Hardcoded fallback (60 seconds)
+ */
+export declare class CacheScope {
+    private readonly defaultKeyPrefix?;
+    readonly config: PartialCacheOptions | false;
+    readonly parent: CacheScope | null;
+    /** Explicit store from cache() options, if specified */
+    private readonly explicitStore;
+    constructor(config: PartialCacheOptions | false, parent?: CacheScope | null, defaultKeyPrefix?: "doc" | undefined);
+    /**
+     * Whether caching is enabled for this scope
+     */
+    get enabled(): boolean;
+    /**
+     * Get effective TTL from config or store defaults.
+     *
+     * Unlike profile-registry.ts (which fails fast at config time), the render
+     * path must DEGRADE: a non-finite/negative ttl (NaN/Infinity from a bad
+     * defaults config) would make computeExpiration produce NaN deadlines so the
+     * entry never evicts, or a guaranteed miss for a negative value. Fall back to
+     * DEFAULT_ROUTE_TTL instead of throwing in the foreground render.
+     */
+    get ttl(): number;
+    /**
+     * Get SWR window from config or store defaults.
+     *
+     * A non-finite/negative swr is degraded to undefined (no SWR window) rather
+     * than fed into expiry math; see the ttl getter for the rationale.
+     */
+    get swr(): number | undefined;
+    /**
+     * Get the cache store - resolution priority:
+     * 1. Explicit store from cache() options
+     * 2. App-level store from request context
+     */
+    getStore(): SegmentCacheStore | null;
+    /**
+     * Resolve the cache key using the shared 3-tier priority.
+     * @internal
+     */
+    private resolveKey;
+    /**
+     * @internal Whether a cache read/write is allowed for the current request:
+     * the scope is enabled AND its `condition` (if any) returns true. "read"
+     * is consulted by the PPR navigation-replay gate BEFORE any shell-store
+     * read so a cache(false)/condition-false route reports `cache-disabled`
+     * without spending getShell I/O; "write" gates the capture's snapshot-only
+     * doc record (cache-store middleware) under the same semantics as the
+     * scope's own store write. Consumer opt-outs are absolute — the seeded
+     * fallback must never serve where the consumer refused cached serves.
+     */
+    allowsCache(op: "read" | "write"): boolean;
+    /**
+     * @internal True for scopes minted from the `_shellImplicitCache` marker
+     * (createShellImplicitDocScope) — the only construction path that passes
+     * the `doc` defaultKeyPrefix; route-derived scopes (createCacheScope) never
+     * do. withCacheLookup/withCacheStore use this to tell the implicit doc
+     * scope from a route-derived scope: the two compose on the replay serve
+     * path and only the route-derived kind gets the seeded fallback /
+     * doc-record treatment.
+     */
+    get isShellImplicitDocScope(): boolean;
+    /**
+     * Evaluate the cache `condition` predicate. Returns false (skip the cache
+     * operation) when the predicate returns false or throws; returns true when
+     * there is no condition or no request context to evaluate it against.
+     */
+    /**
+     * One WRITE decision per (scope, request), memoized on the request context.
+     * A capture render has TWO writers consulting the same predicate — the
+     * explicit tier's cacheRoute and the snapshot-only doc record gate
+     * (recordShellCaptureDocRecord) — and a true→false flap between the two
+     * evaluations recorded a REPLAYABLE canonical snapshot for a render whose
+     * real write was refused. The first evaluation pins the answer for the
+     * whole render (the capture's derived context during captures). READ
+     * decisions stay per-lookup by design: pre-deciding a flappable predicate
+     * at the replay gate was the round-2 regression.
+     */
+    private readonly writeConditionMemo;
+    private conditionAllows;
+    /**
+     * Lookup cached segments for a route (single cache entry per request).
+     * Returns { segments, shouldRevalidate } or null if cache miss.
+     *
+     * @param pathname - URL pathname for cache key generation
+     * @param params - Route params for cache key generation
+     * @param isIntercept - Whether this is an intercept navigation (uses different cache key)
+     */
+    lookupRoute(pathname: string, params: Record<string, string>, isIntercept?: boolean): Promise<{
+        segments: ResolvedSegment[];
+        shouldRevalidate: boolean;
+    } | null>;
+    /**
+     * @internal lookupRoute with a discriminated outcome. The PPR replay
+     * composition (withCacheLookup) may substitute the seeded doc record ONLY on
+     * a true `miss` — the other non-hit outcomes must not be papered over:
+     *
+     * - `bypass`: the scope refused the read — cache(false), a false
+     *   `condition()`, or no resolvable store. Consumer opt-outs are absolute;
+     *   a fallback here would serve cached segments to a request the consumer
+     *   said must render fresh.
+     * - `error`: a throwing consumer key()/store keyGenerator/store.get. The
+     *   contract on that failure is "render uncached" (see the catch below) —
+     *   falling back would serve the canonical doc record across a broken key
+     *   partition, exactly the collision resolveCacheKey's no-default-fallback
+     *   rule exists to prevent.
+     *
+     * A corrupt entry that was evicted reads as `miss`: the store was consulted
+     * and holds nothing servable, which is the post-eviction truth.
+     */
+    lookupRouteDetailed(pathname: string, params: Record<string, string>, isIntercept?: boolean): Promise<CacheRouteLookupOutcome>;
+    /**
+     * 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;
+    /**
+     * Cache all segments for a route (non-blocking via waitUntil)
+     * Single cache entry per route request.
+     * Loaders are excluded - they're always fresh unless they have their own cache() config.
+     *
+     * @param pathname - URL pathname for cache key generation
+     * @param params - Route params for cache key generation
+     * @param segments - All resolved segments to cache
+     * @param isIntercept - Whether this is an intercept navigation (uses different cache key)
+     */
+    cacheRoute(pathname: string, params: Record<string, string>, segments: ResolvedSegment[], isIntercept?: boolean): Promise<void>;
+}
+/**
+ * Create a cache scope from entry's cache config
+ */
+export declare function createCacheScope(config: {
+    options: PartialCacheOptions | false;
+} | undefined, parent?: CacheScope | null): CacheScope | null;
+type ShellImplicitCacheMarker = NonNullable<RequestContext["_shellImplicitCache"]>;
+/**
+ * Mint the implicit doc-level scope for a `_shellImplicitCache` marker: key
+ * resolution under the marker's `doc` namespace against the marker's store,
+ * with the marker's onHit wired as the hit observer. Shared by
+ * {@link resolveShellImplicitCacheScope} (routes that derived no scope) and
+ * the explicit-scope composition sites (capture doc record in the cache-store
+ * middleware, seeded replay fallback in withCacheLookup) so both ends of the
+ * shell contract resolve the SAME canonical document key.
+ */
+export declare function createShellImplicitDocScope(marker: ShellImplicitCacheMarker): CacheScope;
+/**
+ * Shell fast path: when the route tree derived NO cache scope and the current
+ * request context carries the `_shellImplicitCache` marker (a shell capture,
+ * an eligible HIT tail, or a normal partial navigation replay), substitute an
+ * implicit doc-level scope so withCacheLookup/withCacheStore treat the WHOLE
+ * matched route as a cache() boundary — the shell entry IS a cache() of the
+ * handler layer, with loaders as the live carve-outs
+ * (resolveFreshLoadersAndYield).
+ *
+ * An existing scope — including an explicit cache(false) opt-out — always
+ * wins HERE: the consumer's cache() semantics (their ttl/swr/store/condition)
+ * are never overridden, and cache(false) keeps the tail on the full handler
+ * re-run path. On the navigation-replay serve path the marker still composes
+ * with an explicit scope downstream (withCacheLookup's seeded fallback after
+ * an explicit-tier miss) — see `onExplicitHit` on `_shellImplicitCache`.
+ */
+export declare function resolveShellImplicitCacheScope(scope: CacheScope | null): CacheScope | null;
+export {};

package/dist/types/cache/cache-tag.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Cache Tag API
+ *
+ * Provides cacheTag() for tagging cached entries at runtime inside "use cache"
+ * functions. Tags are scoped via AsyncLocalStorage; calling cacheTag() outside
+ * a "use cache" execution throws.
+ *
+ * The runtime (cache-runtime.ts) wraps "use cache" execution in
+ * runWithCacheTagScope(), collects the runtime tags, and merges them with the
+ * profile/DSL tags before storing.
+ */
+import { type RequestContext } from "../server/request-context.js";
+export declare function normalizeTag(tag: string): string | null;
+export declare function normalizeTags(tags: Iterable<string>): string[];
+/**
+ * Tag content for later invalidation via updateTag() / revalidateTag().
+ *
+ * cacheTag() serves two forms depending on what is active when it runs:
+ *
+ * 1. Inside a "use cache" function — the DEFAULT. The tags go to the current
+ *    cache entry; `revalidateTag(tag)` drops that entry. Tags are additive
+ *    (multiple calls accumulate), and normalizeTag() is the single chokepoint so
+ *    a padded write matches an unpadded invalidate.
+ *
+ * 2. Render-callable (#648) — no "use cache" scope active, but a request context
+ *    is present. The tags record onto the request's DOCUMENT artifact
+ *    (ctx._requestTags) instead of throwing. The collection layers already exist:
+ *    PPR shell capture unions _requestTags into the shell entry, the document
+ *    cache tags the full-page entry with it, and prerender build contexts seed
+ *    their own set — so a server component that renders into a shell makes
+ *    `revalidateTag("campaign:spring")` evict that shell with ZERO cache()/"use
+ *    cache" in its tree. This is PPR's DERIVATIVE invalidation: PPR is
+ *    execution-PRESERVING (everything still runs underneath; only document bytes
+ *    are shortcut), so its tags ride this existing instrument rather than a
+ *    first-class ppr key/tag API. The shell-expiry invariant holds by
+ *    construction — baked ⇒ evicts (bake-lane loaders execute during capture and
+ *    record here), hole ⇒ fresh (masked loaders behind a renderable loading()
+ *    never execute during capture, so nothing under a hole can tag the shell).
+ *
+ * Inside a cache() DSL segment the render-callable form records at the DOCUMENT
+ * level, not the segment (only the "use cache" runtime enters the tag scope) — a
+ * documented semantic, not a filtered one. An empty/whitespace-only tag is
+ * dropped in both forms (the render-callable form silently, via normalizeTags in
+ * recordRequestTags; the scope form with a dev warning).
+ *
+ * With neither a scope nor a request context, cacheTag() throws.
+ *
+ * @example
+ * ```typescript
+ * // Form 1 — inside "use cache":
+ * async function getProduct(ctx) {
+ *   "use cache";
+ *   cacheTag(`product:${ctx.params.id}`, "products");
+ *   return db.getProduct(ctx.params.id);
+ * }
+ *
+ * // Form 2 — render-callable, tags the shell/document from a server component:
+ * function CampaignBanner() {
+ *   cacheTag("campaign:spring");
+ *   return <aside>Spring sale</aside>;
+ * }
+ * ```
+ */
+export declare function cacheTag(...tags: string[]): void;
+export declare function recordRequestTags(tags: Iterable<string> | undefined, ctx?: RequestContext | undefined): void;
+/**
+ * Run a function within a cache tag scope. Any cacheTag() calls inside `fn`
+ * accumulate into the returned Set.
+ *
+ * The returned Set is the LIVE reference - the caller must await `result`
+ * before reading `tags`, because an async cached function may call cacheTag()
+ * after an await boundary.
+ *
+ * @internal Used by cache-runtime.ts to wrap "use cache" execution.
+ */
+export declare function runWithCacheTagScope<T>(fn: () => T): {
+    result: T;
+    tags: Set<string>;
+};

package/dist/types/cache/cf/cf-base64.d.ts

@@ -0,0 +1,4 @@
+/** Encode ArrayBuffer to base64 string. */
+export declare function bufferToBase64(buffer: ArrayBuffer): string;
+/** Decode base64 string to ArrayBuffer. */
+export declare function base64ToBuffer(base64: string): ArrayBuffer;

package/dist/types/cache/cf/cf-cache-constants.d.ts

@@ -0,0 +1,112 @@
+/** Header storing timestamp when entry becomes stale */
+export declare const CACHE_STALE_AT_HEADER = "x-edge-cache-stale-at";
+/** Header storing cache status: HIT | REVALIDATING */
+export declare const CACHE_STATUS_HEADER = "x-edge-cache-status";
+/**
+ * Header storing this entry's cache tags as a JSON array. JSON-encoded (not the
+ * comma-delimited CF `Cache-Tag` format) so tags containing commas round-trip
+ * safely; the read paths parse this to run the tag-invalidation check.
+ */
+export declare const CACHE_TAGS_HEADER = "x-edge-cache-tags";
+/** Header storing the ms-epoch timestamp when this entry's tags were attached. */
+export declare const CACHE_TAGGED_AT_HEADER = "x-edge-cache-tagged-at";
+/**
+ * KV key prefix for tag-invalidation markers. A marker stores the ms-epoch
+ * timestamp of the most recent invalidation of a tag; reads treat any entry
+ * whose taggedAt is older than its tags' latest marker as invalidated. Markers
+ * live in the SAME KV namespace as the cached entries - there is no separate
+ * tag-invalidation store.
+ */
+export declare const TAG_MARKER_PREFIX = "__tag__/";
+/**
+ * Header storing the epoch-ms timestamp when an entry was marked REVALIDATING.
+ * The SWR thundering-herd guard reads this to decide whether the in-flight
+ * revalidation is still recent. It replaces a prior reliance on the HTTP `Age`
+ * header: CF's Cache API does not populate `Age` reliably per-colo (and our own
+ * unit MockCache never set it), so an absent `Age` defaulted to 0 and made every
+ * REVALIDATING entry look "just revalidated" forever -- a dropped/never-finished
+ * background revalidation could then pin an entry stale until hard expiry. An
+ * explicit timestamp we write ourselves (same pattern as CACHE_STALE_AT_HEADER)
+ * is reliable and lets the MAX_REVALIDATION_INTERVAL re-arm actually fire.
+ */
+export declare const CACHE_REVALIDATING_AT_HEADER = "x-edge-cache-revalidating-at";
+/**
+ * Header storing the absolute epoch-ms hard-expiry deadline (staleAt +
+ * swrWindow*1000) of an L1 entry. The stale-path REVALIDATING re-put reads this
+ * to recompute a SHRINKING Cache-Control max-age instead of copying set()'s
+ * original full-window max-age. Without it, every MAX_REVALIDATION_INTERVAL
+ * re-arm re-puts the full window and restarts CF's retention clock, pinning a
+ * perpetually-stale entry (one whose background revalidation keeps failing) past
+ * its intended hard-expiry indefinitely. Mirrors the KVSegmentEnvelope `e`
+ * field and the remaining-ttl math in promoteSegmentToL1/promoteItemToL1.
+ * @internal
+ */
+export declare const CACHE_EXPIRES_AT_HEADER = "x-edge-cache-expires-at";
+/**
+ * Header stashing the route author's original Cache-Control on L1 document
+ * entries. putResponse/promoteResponseToL1 overwrite Cache-Control with a long
+ * `max-age` so the CF Cache API retains the entry across the whole SWR window;
+ * getResponse restores this original value before serving so the client and any
+ * upstream CDN see the author's intended directive, not the internal edge TTL.
+ */
+export declare const CACHE_ORIG_CC_HEADER = "x-edge-cache-orig-cc";
+/**
+ * Maximum age in seconds for REVALIDATING status before allowing new revalidation.
+ * After this period, a stale entry in REVALIDATING status will trigger revalidation again.
+ * @internal
+ */
+export declare const MAX_REVALIDATION_INTERVAL = 30;
+/**
+ * Maximum time (ms) to wait for an L1 edge cache (CF Cache API) read before
+ * giving up and treating it as a miss. The Cache API is normally sub-millisecond
+ * per-colo, so a slow `match` signals a degraded colo; we don't want it adding
+ * latency to the request. On timeout the lookup is abandoned, a warning is
+ * logged, and the read falls through to its normal miss path (L2/KV or render).
+ *
+ * This is the default; override per store via
+ * `CFCacheStoreOptions.edgeLookupTimeoutMs` (<= 0 disables the budget).
+ *
+ * 25ms, raised from 10: production Workers logs (autobarn pilot) showed the
+ * 10ms budget firing frequently on cold colos where the first Cache API touch
+ * is slow but healthy — each false positive downgrades a warm L1 HIT to an
+ * L2/render round trip that costs far more than the 15ms of extra patience.
+ * A genuinely degraded colo still gets cut off; tune per store for
+ * shell-critical routes.
+ */
+export declare const EDGE_LOOKUP_TIMEOUT_MS = 25;
+/**
+ * Maximum time (ms) to wait for the BODY of a matched L1 entry to be read
+ * (response.json()) before treating the read as a miss.
+ *
+ * This is separate from {@link EDGE_LOOKUP_TIMEOUT_MS} on purpose. CF's Cache
+ * API resolves `match()` with a lazily-streamed body, so a fast `match` can be
+ * followed by a multi-second stall while the body bytes are fetched -- the
+ * latency tail lives here, after the match budget has already passed. The
+ * default bounds that tail aggressively: a healthy per-colo body read (fetch +
+ * JSON parse) settles in low single-digit milliseconds, so 20ms clears a
+ * healthy read while still failing fast to L2/KV (or render) on a degraded colo
+ * instead of pinning the request behind a seconds-long read. Raise it per store
+ * if large Flight payloads legitimately need longer.
+ *
+ * Override per store via `CFCacheStoreOptions.edgeReadTimeoutMs` (<= 0 disables).
+ */
+export declare const EDGE_READ_TIMEOUT_MS = 20;
+/**
+ * Maximum time (ms) to wait for an L2 (KV) read (`kv.get(key, {type:"json"})`)
+ * before treating it as a miss. Unlike the L1 budgets, KV is a GLOBAL store: the
+ * file header documents ~50ms healthy reads, and a degraded namespace can tail
+ * to seconds. KV is the LAST cache tier before a full render, so an unbounded
+ * read here pins the whole request behind a degraded global lookup.
+ *
+ * The default (170ms) sits a few multiples above the documented ~50ms healthy
+ * read, leaving headroom for legitimate latency tails (larger payloads,
+ * far-from-colo regions) so a healthy-but-slow read does not false-miss into a
+ * render, while still abandoning a genuinely degraded namespace well before its
+ * multi-second tail can pin the request. A deployment with a tighter SLA can
+ * lower it, and one whose healthy p99 runs higher should raise it: measure the
+ * KV read p99 (Workers Analytics) and add margin. It is a degradation
+ * guard-rail, not a tuning lever for "slow KV is normal here".
+ *
+ * Override per store via `CFCacheStoreOptions.kvReadTimeoutMs` (<= 0 disables).
+ */
+export declare const KV_READ_TIMEOUT_MS = 170;