@rangojs/router 0.4.0 → 0.4.2

package/dist/types.backup/cache/cf/cf-cache-store.d.ts

@@ -1,481 +0,0 @@
-declare global {
-    interface CacheStorage {
-        readonly default: Cache;
-    }
-}
-/**
- * Cloudflare Edge Cache Store
- *
- * Production cache store using Cloudflare's Cache API (L1) with optional
- * KV persistence (L2).
- *
- * L1 (Cache API): Per-colo, fast, ephemeral. Handles SWR atomically.
- * L2 (KV): Global, persistent, ~50ms reads. Auto-warms cold colos.
- *
- * Read flow:  L1 hit → serve | L1 miss → L2 hit → serve + promote to L1 | both miss → render
- * Write flow: L1 write + L2 write (both via waitUntil)
- *
- * Features:
- * - Extended TTL for SWR window (max-age = ttl + swr)
- * - Staleness via x-edge-cache-stale-at header
- * - Atomic REVALIDATING status for thundering herd prevention (L1 only)
- * - Non-blocking writes via waitUntil
- * - KV L2 for cross-colo cache persistence
- */
-import type { SegmentCacheStore, CachedEntryData, CacheDefaults, CacheGetResult, CacheItemResult, CacheItemOptions, ShellCacheEntry } from "../types.js";
-import { type RequestContext } from "../../server/request-context.js";
-import { CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, CACHE_TAGS_HEADER, CACHE_TAGGED_AT_HEADER, TAG_MARKER_PREFIX, CACHE_REVALIDATING_AT_HEADER, MAX_REVALIDATION_INTERVAL, EDGE_LOOKUP_TIMEOUT_MS, EDGE_READ_TIMEOUT_MS, KV_READ_TIMEOUT_MS } from "./cf-cache-constants.js";
-export { CACHE_STALE_AT_HEADER, CACHE_STATUS_HEADER, CACHE_TAGS_HEADER, CACHE_TAGGED_AT_HEADER, TAG_MARKER_PREFIX, CACHE_REVALIDATING_AT_HEADER, MAX_REVALIDATION_INTERVAL, EDGE_LOOKUP_TIMEOUT_MS, EDGE_READ_TIMEOUT_MS, KV_READ_TIMEOUT_MS, };
-import type { KVNamespace, CFCacheReadDebugEvent, CFCacheDebug, CFCacheStoreOptions } from "./cf-cache-types.js";
-export type { KVNamespace, CFCacheReadDebugEvent, CFCacheDebug, CFCacheStoreOptions, };
-export declare class CFCacheStore<TEnv = unknown> implements SegmentCacheStore<TEnv> {
-    readonly defaults?: CacheDefaults;
-    readonly keyGenerator?: (ctx: RequestContext<TEnv>, defaultKey: string) => string | Promise<string>;
-    private readonly namespace?;
-    private readonly explicitBaseUrl?;
-    private readonly waitUntil?;
-    private readonly version?;
-    private readonly edgeLookupTimeoutMs;
-    private readonly edgeReadTimeoutMs;
-    private readonly kvReadTimeoutMs;
-    private readonly debug?;
-    private readonly kv?;
-    private readonly onRevalidateTag?;
-    private readonly tagInvalidationTtl?;
-    private readonly tagCacheTtl;
-    constructor(options: CFCacheStoreOptions<TEnv>);
-    /**
-     * Warn about a namespace-scoped misconfiguration once per namespace per
-     * isolate. `seen` is the module-level Set for that message family -- Sets
-     * are module-level (not instance fields) so re-constructed stores in the
-     * same isolate don't re-warn.
-     * @internal
-     */
-    private warnOncePerNamespace;
-    /**
-     * Validate a consumer-supplied tagInvalidationTtl against CF KV's expirationTtl
-     * floor. A finite value below KV_MIN_EXPIRATION_TTL is raised to it (with a
-     * one-time warning) so invalidation keeps working instead of every marker
-     * write throwing; a non-finite or non-positive value returns undefined (the
-     * no-expiry default). The warning still notes the sizing rule: the TTL must
-     * exceed the largest entry TTL+SWR or invalidated entries can resurrect.
-     * @internal
-     */
-    private sanitizeTagInvalidationTtl;
-    /**
-     * Emit a debug event if `debug` is enabled. Swallows sink errors so a faulty
-     * debug callback can never break a cache read.
-     * @internal
-     */
-    private emitDebug;
-    /**
-     * Resolve the cache-key base URL for the current cache operation.
-     * Prefers an explicit `baseUrl` option; otherwise derives it from the live
-     * request. Called per operation (from keyToRequest), which runs inside the
-     * request-context ALS, so deriveBaseUrl sees the request and can use the
-     * production host instead of the internal fallback.
-     * @internal
-     */
-    private resolveBaseUrl;
-    /**
-     * Derive base URL from request hostname via requestContext.
-     * Uses internal fallback for dev/preview environments and untrusted hostnames.
-     * Must run inside the request context (invoked lazily via resolveBaseUrl).
-     * @internal
-     */
-    private deriveBaseUrl;
-    /**
-     * Get the cache instance - uses caches.default unless namespace is specified.
-     * @internal
-     */
-    private getCache;
-    /**
-     * Race an async cache read against a latency budget. Shared by all three read
-     * tiers (L1 match, L1 body, L2/KV) so the timeout policy lives in one place:
-     * on timeout it returns `{ value: undefined, timedOut: true }` and logs
-     * `${label} exceeded ${budgetMs}ms; treating as miss`; the abandoned read is
-     * left to settle in the background (late rejection swallowed) rather than
-     * aborted, since the underlying CF primitives expose no cancellation. A budget
-     * <= 0 disables the bound and awaits the read directly. `read` is a thunk so
-     * the disabled path and the raced path start the read identically.
-     * @internal
-     */
-    private readWithTimeout;
-    /**
-     * Read from the L1 edge cache under the edgeLookupTimeoutMs budget. A `match`
-     * slower than the budget is abandoned and reported as a miss
-     * (`{ response: undefined, timedOut: true }`) so a degraded colo cannot stall
-     * the request; callers fall through to their normal miss path (L2/KV or
-     * render). The `timedOut` flag lets callers distinguish an abandoned slow
-     * match from a genuine miss for debug reporting; `error` is set when the
-     * `match` itself rejected (a transient L1 infra error) so the caller can
-     * report it as cache-read while still degrading to L2/KV -- distinct from a
-     * genuine miss (no entry), which sets neither flag.
-     * @internal
-     */
-    private matchWithTimeout;
-    /**
-     * Read and JSON-parse a matched L1 Response's body under the edgeReadTimeoutMs
-     * budget. CF resolves `match()` with a lazily-streamed body, so the latency
-     * tail surfaces here -- after matchWithTimeout has already passed -- not in the
-     * match itself. On timeout `undefined` is returned so the caller falls through
-     * to L2/KV or render.
-     * @internal
-     */
-    private readJsonWithTimeout;
-    /**
-     * Self-heal a corrupt L1 entry, then return the fall-through result. Reports
-     * the corruption as cache-corrupt (so an onError consumer sees it distinctly
-     * from a transient outage), runs the caller's L2/KV fall-through, and evicts
-     * the faulty per-colo entry ONLY when that fall-through found no good copy.
-     *
-     * The conditional evict is the load-bearing detail: when KV DOES serve a copy,
-     * kvGet* has already scheduled a same-key promote (`cache.put`); an eager
-     * `cache.delete` here would race that put with no CF Cache API ordering
-     * guarantee and could clobber the freshly-restored entry. So in that case we
-     * lean on #558's heal-by-overwrite (the non-suppressed fall-through promotes /
-     * a fresh render re-`set`s over the bad entry) and skip the delete. Only when
-     * this request's fall-through found no copy (=== null) is the eager evict
-     * scheduled -- useful then, since nothing else will overwrite the poison entry.
-     * A null fall-through can also be a KV-read TIMEOUT rather than a genuine miss:
-     * a concurrent request that read KV successfully may be promoting the same key,
-     * and this evict could race it. That is benign -- the worst case is one wasted
-     * colo-local promote, never a wrong served value, and the next read self-heals
-     * -- so we accept it rather than suppressing the evict on a timeout (which
-     * would strand the poison entry when KV really is empty). The evict is
-     * non-blocking (waitUntil) so it never adds latency to the degraded read.
-     * @internal
-     */
-    private healCorruptL1;
-    /**
-     * Re-put a stale L1 entry marked REVALIDATING, so concurrent requests serve it
-     * without each triggering a revalidation. Shared by get()/getItem().
-     *
-     * The write is NON-BLOCKING (waitUntil) and best-effort by design:
-     * - It runs in waitUntil, so it never adds the put latency to the served stale
-     *   read and a put failure can never turn that good read into a miss. The put
-     *   is still initiated synchronously (this.waitUntil invokes its callback
-     *   immediately), so concurrent readers see the marker land at the same time an
-     *   awaited write would -- awaiting only blocks the current request.
-     * - The background revalidation's fresh set() is gated behind a full re-render,
-     *   so it lands well after this put; a stale-clobbers-fresh race would require
-     *   this single put to be slower than that entire render+set, and self-heals
-     *   within MAX_REVALIDATION_INTERVAL.
-     *
-     * Cache-Control is recomputed to the REMAINING ttl from the stored hard-expiry
-     * deadline (see remainingCacheControl), not copied from the original
-     * full-window header -- copying it would restart CF retention on every re-arm
-     * and pin a perpetually-failing entry past hard-expiry. A legacy/tampered entry
-     * without a valid deadline floors to max-age=1 and self-heals via KV.
-     * @internal
-     */
-    private markRevalidating;
-    /**
-     * Document-tier counterpart of markRevalidating for getResponse's herd guard.
-     * The segment/item tiers JSON-parse the body, so they re-put with a string
-     * body; document bodies are streamed verbatim, so we re-put with a CLONED
-     * response body (`response.clone()`) supplied by the caller -- the original
-     * body still streams to the client while the marker carries the clone. Same
-     * REVALIDATING status header, same revalidating-at stamp, same
-     * remainingCacheControl re-put math as markRevalidating, so the document tier
-     * suppresses concurrent revalidation for the identical MAX_REVALIDATION_INTERVAL
-     * window the segment tier does. Best-effort and non-blocking: a failed marker
-     * write must not affect the served stale read.
-     * @internal
-     */
-    private markResponseRevalidating;
-    /**
-     * Guard the segment tier against a `keyGenerator` that returns a key colliding
-     * with a reserved tag-marker namespace: `__tag__/` (the KV marker key) or
-     * `__tagmarker__/` (the L1 Cache API marker request). The item/doc tiers are
-     * internally prefixed (`fn:`/`doc:`) so only the bare segment key can collide;
-     * a collision would let a segment write clobber - or a segment read/delete
-     * evict - a live tag marker, silently breaking invalidation. Report loudly
-     * (so a misconfigured keyGenerator surfaces immediately) and treat the segment
-     * operation as a miss/no-op rather than corrupting the marker namespace.
-     * @internal
-     */
-    private isReservedSegmentKey;
-    /**
-     * Get cached entry data by key.
-     *
-     * Handles SWR atomically:
-     * - If stale and not already revalidating, marks as REVALIDATING and returns shouldRevalidate: true
-     * - If already REVALIDATING (and recent), returns shouldRevalidate: false
-     * - If fresh, returns shouldRevalidate: false
-     *
-     * On L1 miss, falls back to KV (L2) if configured.
-     * KV hits are promoted to L1 in the background.
-     */
-    get(key: string): Promise<CacheGetResult | null>;
-    /**
-     * Store entry data with TTL and optional SWR window.
-     * Uses waitUntil for non-blocking write when available.
-     * When KV is configured, also persists to L2.
-     */
-    set(key: string, data: CachedEntryData, ttl: number, swr?: number): Promise<void>;
-    /**
-     * Delete a cached entry from L1 and L2.
-     */
-    delete(key: string): Promise<boolean>;
-    /**
-     * Get a cached Response by key (for document-level caching).
-     * Returns the response and whether it should be revalidated (SWR).
-     * Falls back to KV (L2) on L1 miss.
-     */
-    getResponse(key: string): Promise<{
-        response: Response;
-        shouldRevalidate: boolean;
-    } | null>;
-    /**
-     * Strip internal edge headers and restore the author's Cache-Control before a
-     * cached document Response is served to a client. L1 entries carry the
-     * internal staleness/status headers and a rewritten Cache-Control; none of
-     * those should reach the browser or an upstream CDN.
-     */
-    private toClientResponse;
-    /**
-     * Store a Response with TTL and optional SWR window (for document-level caching).
-     * When KV is configured, also persists to L2.
-     */
-    putResponse(key: string, response: Response, ttl: number, swr?: number, tags?: string[]): Promise<void>;
-    /**
-     * Get a cached function result by key.
-     * Follows the same SWR pattern as get() for segment caching.
-     * Falls back to KV (L2) on L1 miss.
-     */
-    getItem(key: string): Promise<CacheItemResult | null>;
-    /**
-     * Store a function result with TTL and optional SWR window.
-     * When KV is configured, also persists to L2.
-     */
-    setItem(key: string, value: string, options?: CacheItemOptions): Promise<void>;
-    /**
-     * Warn once per isolate that the shell family is inert: getShell/putShell
-     * are ONLY called for routes that declared the `ppr` path option, so firing
-     * here (not in the constructor) scopes the warning to apps that actually
-     * use PPR — a KV-less CFCacheStore is a perfectly fine config otherwise.
-     * Without it, the correctness-first fail-open (issue #651) is invisible:
-     * every ppr route is a permanent MISS with zero diagnostics.
-     * @internal
-     */
-    private warnShellFamilyInertOnce;
-    /**
-     * Get a cached PPR shell entry by key from KV (no L1). Applies the KV read
-     * budget, corrupt-entry eviction, hard-expiry, and tag invalidation exactly
-     * like kvGetItem, minus the L1 promote. SWR is a plain staleness flag — KV has
-     * no REVALIDATING herd guard, so the shell-cache middleware's module-level
-     * in-flight set is the recapture stampede guard.
-     */
-    getShell(key: string): Promise<{
-        entry: ShellCacheEntry;
-        shouldRevalidate?: boolean;
-    } | null>;
-    /**
-     * Store a PPR shell entry in KV with TTL and optional SWR window. Non-blocking
-     * (waitUntil) like the other KV writes. The tags/taggedAt ride in the envelope
-     * so isGloballyInvalidated() can invalidate the shell via the shared KV markers.
-     */
-    putShell(key: string, entry: ShellCacheEntry, ttlSeconds?: number, swrSeconds?: number, tags?: string[]): Promise<void>;
-    /**
-     * Convert string key to Request object for CF Cache API.
-     * Includes version in URL if specified (for cache invalidation on code changes).
-     * @internal
-     */
-    private keyToRequest;
-    /**
-     * Convert string key to KV key string.
-     * Uses same version prefix as Cache API for consistent invalidation.
-     * @internal
-     */
-    private toKVKey;
-    /**
-     * Host token for the current request, used to namespace the document KV key.
-     * Derived from the same resolveBaseUrl() that namespaces the L1 (Cache API)
-     * tier, so a doc entry's KV twin lands under the identical host bucket.
-     * Falls back to "_" if the base URL cannot be parsed (it always carries a
-     * trailing-slash origin, so parsing succeeds in practice).
-     * @internal
-     */
-    private docKVHost;
-    /**
-     * Convert a document key to its host-namespaced KV key. The L1 tier already
-     * namespaces document entries by host via keyToRequest/resolveBaseUrl, but the
-     * KV fallback keyed only on `doc:{key}`, so two hosts serving the same path
-     * could collide on the KV tier (one host serving another's cached document).
-     * Prefixing the host closes that cross-host collision. Deterministic per
-     * (host, key). Segment/fn/tag-marker KV keys keep toKVKey unchanged: tag
-     * markers are intentionally global (invalidation must cross hosts), and the
-     * document tier is the one with a request-host context here.
-     * @internal
-     */
-    private toDocKVKey;
-    /**
-     * Best-effort delete of a single KV key, reporting (not swallowing) a delete
-     * failure as cache-delete. Used by the corrupt-entry self-heal paths.
-     * @internal
-     */
-    private evictKvKey;
-    /**
-     * Schedule a corrupt-entry KV eviction as a NON-BLOCKING background task
-     * (waitUntil) instead of awaiting it on the request path. The corrupt read has
-     * already resolved to a miss; awaiting an unbounded kv.delete here would re-add
-     * exactly the multi-second stall the read budgets exist to prevent when the KV
-     * namespace is degraded. evictKvKey never rejects (it reports its own failure),
-     * so the fire-and-forget fallback is safe when no waitUntil is available.
-     * @internal
-     */
-    private scheduleKvEvict;
-    /**
-     * KV-get a JSON envelope, EVICTING the key only when it is genuinely corrupt.
-     *
-     * Reads as { type: "text" }, NOT { type: "json" }, on purpose: the "json" form
-     * fuses the network read and the JSON parse, so a transient KV outage (5xx/429/
-     * network blip) is indistinguishable from a malformed body and would delete a
-     * still-good cross-colo entry - a self-inflicted miss storm. Reading text lets a
-     * transient read error propagate to the caller's outer catch (reported
-     * cache-read, the entry left intact); only a JSON.parse failure on a body that
-     * WAS successfully read - or an envelope that parses but fails `validate`
-     * (fields missing from a truncated write) - is true corruption that evicts +
-     * reports cache-corrupt. A MISSING key (kv.get -> null) is a normal miss.
-     * @internal
-     */
-    private kvGetOrEvict;
-    /** KV key for a tag's invalidation marker. */
-    private tagMarkerKey;
-    /**
-     * Header entries carrying an entry's tags (JSON-encoded, comma-safe) and the
-     * timestamp they were attached. Returns an empty object when there are no
-     * tags so untagged entries stay header-free and skip the invalidation check.
-     */
-    private tagHeaderEntries;
-    /**
-     * Merge the internal tag headers onto an existing Headers instance. The
-     * from-scratch paths spread tagHeaderEntries() into an object-literal init;
-     * the document put/promote paths build a Headers first, so they .set() each
-     * entry instead.
-     */
-    private setTagHeaders;
-    /** Read an entry's tags/taggedAt back from its headers. */
-    private readTagInfo;
-    /**
-     * Whether an entry tagged at `taggedAt` with `tags` has been invalidated since.
-     * Reads the per-tag invalidation markers from KV and returns true if any tag's
-     * latest invalidation is at or after taggedAt (>= so a same-millisecond
-     * invalidate wins, favouring freshness over staleness). Fails open: KV errors
-     * never turn a hit into a wrongful miss-storm beyond this single read.
-     */
-    private isGloballyInvalidated;
-    /** Synthetic Cache API request for a tag's L1-cached invalidation marker. */
-    private tagMarkerRequest;
-    /**
-     * Read a tag's latest invalidation timestamp (or null if never invalidated)
-     * through the cascade: per-request memo -> per-colo L1 cache (only when
-     * tagCacheTtl > 0) -> KV (the global truth). The memo is always consulted
-     * first so it stays authoritative within a request (read-your-own-writes),
-     * and every KV/L1 result is written back into the memo. A Cache API miss
-     * always falls through to KV; absence is represented by a cached sentinel,
-     * never by a miss.
-     *
-     * Concurrent reads of the same tag within a request share one in-flight read
-     * (the resolved-value memo only collapses sequential reads; parallel segment
-     * loading would otherwise issue one KV read per concurrent reader).
-     * @internal
-     */
-    private readTagMarker;
-    /**
-     * Uncached body of readTagMarker: L1 (per-colo Cache API, opt-in via
-     * tagCacheTtl) -> KV. Writes the resolved value back into the memo.
-     * @internal
-     */
-    private fetchTagMarker;
-    /**
-     * Cloudflare Cache-Tags written on a tag's L1 marker entry, namespaced per
-     * store so purges never collide with other Cache-Tags in the zone. Three
-     * tiers, broad to specific:
-     *   rg:{ns}            - everything this store cached (deploy/nuclear reset)
-     *   rg:{ns}:lk         - all tag-lookup markers
-     *   rg:{ns}:lk:{tag}   - this tag's lookup (the normal updateTag purge target)
-     * The tag value is encodeURIComponent'd so commas/spaces can't corrupt the
-     * comma-delimited Cache-Tag header.
-     * @internal
-     */
-    private lookupCacheTags;
-    /** The specific Cache-Tag a consumer purges to evict tag `tag`'s lookup. */
-    private lookupPurgeTag;
-    /**
-     * Write a tag marker value into the per-colo L1 Cache API with tagCacheTtl.
-     * `null` is stored as the TAG_MARKER_ABSENT sentinel so "no marker yet" is
-     * cacheable (most tags are never invalidated - that is where the read savings
-     * come from). The entry also carries a namespaced Cache-Tag so an external
-     * purge-by-tag (via onRevalidateTag) can evict it across colos promptly,
-     * rather than waiting out tagCacheTtl. Best-effort.
-     * @internal
-     */
-    private putTagMarkerL1;
-    /**
-     * Invalidate every entry tagged with any of `tags`. Receives the whole batch
-     * from one updateTag()/revalidateTag() call so the eager-purge hook fires
-     * ONCE (one CDN purge request, not one per tag). For each tag: records the KV
-     * marker (the durable cross-colo truth that reads compare taggedAt against),
-     * writes the fresh marker straight into this colo's L1 (write-through, NOT
-     * delete - a delete would let the next read re-read a not-yet-converged KV
-     * value and re-arm the stale window), and memoizes it for same-request
-     * read-your-own-writes. Finally fires onRevalidateTag with the namespaced
-     * lookup Cache-Tags so a consumer purge evicts the cached lookups in other
-     * colos promptly (otherwise they converge within tagCacheTtl).
-     *
-     * 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
-     * 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).
-     */
-    /**
-     * Build-shell read-through gate (SegmentCacheStore.isTagsInvalidatedSince):
-     * a baked shell entry is immutable in the build manifest, so eviction is
-     * answered by the SAME KV tag markers updateTag() writes, compared against
-     * the entry's build-time createdAt. Thin public wrapper over the private
-     * envelope check (identical semantics: marker >= since, fail open).
-     */
-    isTagsInvalidatedSince(tags: string[], sinceMs: number): Promise<boolean>;
-    invalidateTags(tags: string[]): Promise<void>;
-    /**
-     * KV fallback for segment cache reads.
-     * Returns null if KV is not configured, entry is missing, or expired.
-     * Promotes hits to L1 via waitUntil.
-     * @internal
-     */
-    private kvGetSegment;
-    /**
-     * Write segment data to KV.
-     * @internal
-     */
-    private kvSetSegment;
-    /**
-     * Promote segment data from KV to L1 Cache API.
-     * @internal
-     */
-    private promoteSegmentToL1;
-    /**
-     * KV fallback for function cache reads.
-     * @internal
-     */
-    private kvGetItem;
-    /**
-     * Promote function cache data from KV to L1.
-     * @internal
-     */
-    private promoteItemToL1;
-    /**
-     * KV fallback for document cache reads.
-     * @internal
-     */
-    private kvGetResponse;
-    /**
-     * Promote document cache data from KV to L1.
-     * @internal
-     */
-    private promoteResponseToL1;
-}