fix(http)!: resolve handler name before merging defaults

Author: pi0

AGENTS.md

@@ -20,7 +20,7 @@ Never touch contents inside `<!-- automd -->` in README.md. They are auto genera
 ### Core caching (`cache.ts`)
 
 - `defineCachedFunction(fn, opts)` — wraps any function with caching (SWR, TTL, integrity checks, deduplication of in-flight requests)
-- Cache key `name` resolves as `opts.name || fn.name || \`anon_<hash(fn)>\``. Resolved once and written back into `opts`so the internal read/write path and the`resolveKeys`/`invalidate`/`expire` helpers all agree. Named/`fn.name`functions get a stable, human-readable name; anonymous functions fall back to a source hash so distinct inline fns don't collide (they would otherwise share one key and thrash). Caveat: a source hash can't tell apart same-source fns that differ only by closed-over variables — pass an explicit`name`(or`getKey`) for those. When reconstructing keys via the standalone `resolveCacheKeys`/`invalidateCache`/`expireCache`helpers (which can't see`fn`), always pass the same `name` you cached with
+- Cache key `name` resolves as `opts.name || fn.name || \`anon_<hash(fn)>\``— in`_resolveName`, an internal exported from `cache.ts`and **shared with`http.ts`** (which passes the wrapped `EventHandler`as`fn`) so the two paths cannot drift; both call it on the caller's options *before* the `defaultCacheOptions()`merge, which is the whole point (see the`http.ts`bullet). Resolved once and written back into`opts`so the internal read/write path and the`resolveKeys`/`invalidate`/`expire` helpers all agree. Named/`fn.name`functions get a stable, human-readable name; anonymous functions fall back to a source hash so distinct inline fns don't collide (they would otherwise share one key and thrash). Caveat: a source hash can't tell apart same-source fns that differ only by closed-over variables — pass an explicit`name`(or`getKey`) for those. When reconstructing keys via the standalone `resolveCacheKeys`/`invalidateCache`/`expireCache`helpers (which can't see`fn`), always pass the same `name` you cached with
 - `getMaxAge(entry)` option — dynamic per-entry TTL: runs after the resolver, returns a number (seconds, shorthand for `maxAge`) or `{ maxAge?, staleMaxAge? }` that override the static options for that entry. Resolved values are persisted on the entry (`CacheEntry.maxAge` / `CacheEntry.staleMaxAge`) and drive both the read freshness check and the storage TTL. Absent field / `undefined` → falls back to static options. Flows through to `defineCachedHandler`, where it runs before the internal `serialize` hook so `entry.value` is the live `Response` (inspect its headers/status; don't consume its body — `serialize` reads it exactly once)
 - `serialize(entry, { args })` option — write-side counterpart of `transform`: runs once right after the resolver (and after `getMaxAge`, so that hook still sees the raw value) and returns the value to persist. `transform` deserializes it back on read. Use for resolver outputs a storage backend can't persist as-is (raw `ReadableStream`, class instances). It runs **exactly once per resolution** — shared across concurrent, deduplicated calls (every caller observes the serialized value), so consuming a one-shot source like a stream is safe. A throwing `serialize` fails the call and evicts, like a rejected resolver. Both `getMaxAge` and `serialize` are folded into the shared in-flight (`pending`) promise so they never run more than once
 - The in-flight dedup registry (`pending`) is a **`Map`, never a plain object**: keys are caller-controlled (the documented `getKey: (id) => id`), and a plain object inherits from `Object.prototype`, so `pending["constructor"]` / `"toString"` / `"valueOf"` / `"hasOwnProperty"` / `"__proto__"` / `"isPrototypeOf"` / `"propertyIsEnumerable"` / `"toLocaleString"` read truthy with nothing in flight. Such a call was treated as a deduplicated follower, `await`ed the inherited member (not a thenable, so it resolved to itself), never called the resolver, and cached `undefined` — silently for `defineCachedFunction`, and as a hard, permanent `TypeError` for `defineCachedHandler` (whose `transform` then dereferences `undefined.headers`). Default keys can't hit it (the auto handler key always contains a `.`; `cache.ts`'s default is `hash(args)` or `""`), so it takes a custom `getKey`. Unrelated to prototype _pollution_ — there is none; this was unsafe prototype-chain _reading_
@@ -36,6 +36,7 @@ Never touch contents inside `<!-- automd -->` in README.md. They are auto genera
 ### HTTP handler caching (`http.ts`)
 
 - `defineCachedHandler<E extends HTTPEvent>(handler, opts)` — wraps an `EventHandler` with response caching (generic over event type)
+- Cache key `name`: resolved with `cache.ts`'s shared `_resolveName(opts.name, handler)` **before** the `defaultCacheOptions()` merge, exactly like `defineCachedFunction`. Merging first (the old order) left `opts.name` permanently `"_"` by the time `cachedFunction` re-derived it, so issue #53's fix never reached the HTTP layer and **every** handler keyed as `name: "_"`. Two handlers sharing one `storage` (the configuration `types.ts` recommends) that can see the same path then collided: identical source ⇒ identical integrity ⇒ one served the other's cached response (cross-handler leak); differing source ⇒ every read failed the other's integrity check ⇒ permanent thrash at 0% hit rate. **Breaking key change**, not a behavior change: every existing handler entry goes cold once (the key gains a real name segment). The `HEAD:` method component still sits directly after the name segment, so key shape is otherwise unchanged. Same **documented caveat** as `defineCachedFunction`, and it bites harder here because the shared-`storage` setup turns it into a leak: `hash(handler)` sees only source, so handlers from one factory (`(tenant) => defineCachedHandler(() => render(tenant), { storage })`) share a name _and_ an integrity — pass an explicit `name` per instance. A per-instance discriminator (counter/WeakMap/randomness) is inadmissible: keys must be deterministic across process restarts for persistent/shared backends, which is exactly why a source hash is the right fallback
 - Split along the `serialize` seam (built on `cache.ts`'s `cachedFunction<Response>`): the **resolver** narrows the request and returns the handler's live `Response`; the internal **`serialize`** hook consumes the body (`res.arrayBuffer()`), synthesizes `etag`/`last-modified`/`cache-control`/`Vary`, strips every `Set-Cookie`, and builds the stored `ResponseCacheEntry`; **`transform`** reconstructs the servable shape and injects the cache-status header on read. `serialize`/`validate`/`transform` are `Omit`ted from the user-facing `CachedEventHandlerOptions` so internal use doesn't collide
 - Binary responses: `serialize` reads the body as bytes and decides by **byte validity, not content-type** — a valid-UTF-8 body (fatal `TextDecoder` with `ignoreBOM`, lossless roundtrip) is stored verbatim as a string (unchanged text behavior, stable text etags); anything else (images, protobuf/MVT tiles, arbitrary binary) is base64-encoded and flagged `base64: true` on the `ResponseCacheEntry`. Base64 (not a raw `Uint8Array`) so binary bodies survive JSON-serializing storage backends. On read, a `base64` entry is decoded back to a `Uint8Array` before `createResponse`, so the exact bytes replay untouched. `createResponse` therefore receives `string | Uint8Array | null` (widened from `string | null`)
 - Cache key = **resource identity + method component**. `_resolveKey` derives the method-free resource part (auto: URL path + `varies` header values + allowlisted cookies; or the caller's `getKey`), then `_methodKey` prefixes it: **GET is the implicit default and carries no component**, every other cacheable method contributes `<METHOD>:` — today exactly `HEAD:` (`_cacheableMethods`, the enumerable counterpart of `_shouldBypassCache`; making another method cacheable is a one-line addition there, not a key redesign). Closes the h3#1524 audit finding #3 poisoning: GET and HEAD used to share one entry, and a spec-compliant host `toResponse` (h3's, and every real framework's) nulls the body of a HEAD response — exactly the `Response` `serialize` stores — so one anonymous `HEAD /page` seeded the shared entry with a zero-byte body, a synthesized `public, max-age=N` and a weak etag over that empty body, and every GET for the rest of the TTL got a blank 200 that CDNs/browsers cached and successfully revalidated. Applied around **both** key branches (a custom `getKey` expresses content identity; preventing the method collision is ocache's job either way). Deliberate scoping: GET keys are byte-identical to pre-fix ones so existing entries stay warm, and the cost is one origin dispatch per method per resource per TTL. Non-cacheable methods never reach `getKey`

docs/1.guide/4.storage.md

@@ -81,6 +81,9 @@ const getPosts = defineCachedFunction(fetchPosts, { maxAge: 60, storage });
 
 They still key entries by `base`/`group`/`name`, so sharing a backend does not mean sharing entries — it means sharing one connection, one eviction budget, and one place to purge.
 
+> [!IMPORTANT]
+> The `name` is what separates them, and it defaults to the function's or [handler's](/guide/handler#cache-key-name) own name, falling back to a hash of its source. Instances built by a factory or a loop have identical source, so they resolve to the **same** name — on a shared storage they then share entries. Give those an explicit `name`.
+
 ## Late Binding
 
 Handlers are usually defined at module load, while the real backend only exists once the server has started. Pass a **factory** instead of an instance: it is called on the first actual cache read or write — never at definition time — and at most once per cached function or handler.

docs/1.guide/5.handler.md

@@ -34,7 +34,7 @@ The first request runs your handler and stores the response; subsequent requests
 
 ## What it does
 
-- **Cache keys** — auto-generated from the request URL path (plus any query params and headers you opt into varying, see below) and the request method.
+- **Cache keys** — auto-generated from the handler's [name](#cache-key-name), the request URL path (plus any query params and headers you opt into varying, see below) and the request method.
 - **Conditional requests** — answers `304 Not Modified` when the client sends a matching `if-none-match` / `if-modified-since`.
 - **Response headers** — synthesizes `etag`, `last-modified`, and `cache-control` when the handler didn't set them.
 - **`Vary`** — advertises which request headers the response varies on (from `varies`, plus `Cookie` when `allowCookies` is set).
@@ -69,6 +69,41 @@ const handler = defineCachedHandler(myHandler, {
 });
 ```
 
+## Cache key name
+
+Every key carries a `name` component, resolved exactly like a [cached function's](/guide/functions#cache-keys): `opts.name || handler.name || anon_<hash(handler)>`. It is what keeps two handlers that share one `storage` and can see the same path from colliding.
+
+```ts
+const storage = createMemoryStorage();
+
+// Named handlers → "/cache:handlers:dashboard:..." and "/cache:handlers:profile:..."
+const dashboard = defineCachedHandler(
+  async function dashboard(event) {
+    return renderDashboard(event);
+  },
+  { maxAge: 60, storage },
+);
+const profile = defineCachedHandler(
+  async function profile(event) {
+    return renderProfile(event);
+  },
+  { maxAge: 60, storage },
+);
+```
+
+> [!IMPORTANT]
+> The fallback hashes the handler **source**, so handlers produced by the same factory — identical source, different closed-over variables — share a name. Sharing a `storage` then means sharing entries: one tenant's cached response is served to another. Pass an explicit `name` (or `getKey`) whenever you build handlers in a loop or a factory.
+>
+> ```ts
+> // ✗ both handlers key identically
+> const make = (tenant) => defineCachedHandler(() => render(tenant), { maxAge: 60, storage });
+> // ✓ named per instance
+> const make = (tenant) =>
+>   defineCachedHandler(() => render(tenant), { maxAge: 60, name: `page-${tenant}`, storage });
+> ```
+
+The name is derived from the handler, so a source hash is stable across restarts — which is what makes keys usable with a persistent backend.
+
 ## Varying by request headers
 
 By default the cache key depends only on the URL path — every client shares one cached entry. List header names in `varies` to cache a separate variant per header value:

src/cache.ts

@@ -36,18 +36,8 @@ export function defineCachedFunction<T, ArgsT extends unknown[] = any[]>(
   fn: (...args: ArgsT) => T | Promise<T>,
   opts: CacheOptions<T, ArgsT> = {},
 ): CachedFunction<T, ArgsT> {
-  // Resolve `name` from the caller's opts BEFORE merging defaults: defaultCacheOptions()
-  // sets a truthy `name: "_"`, so if defaults were merged first `opts.name` would always
-  // be `"_"` and the `fn.name` fallback would be unreachable (silent cache-key collision
-  // across every unnamed cached function — https://github.com/unjs/ocache/issues/53).
-  //
-  // For anonymous functions (no `opts.name`, no `fn.name`) fall back to a hash of the
-  // function source instead of a shared literal: two distinct inline arrows would
-  // otherwise resolve to the same key and thrash each other (each read fails the
-  // integrity check and re-resolves). This can't disambiguate same-source functions
-  // that only differ by closed-over variables — pass an explicit `name`/`getKey` for
-  // those (the integrity hash collides there too, so it's unfixable from the source alone).
-  const name = opts.name || fn.name || `anon_${hash(fn).slice(0, 16)}`;
+  // Resolve `name` from the caller's opts BEFORE merging defaults — see `_resolveName`.
+  const name = _resolveName(opts.name, fn);
   // Keep a handle on the caller's own options object *before* the defaults merge clones
   // it: that object is the memo slot for the resolved storage, so a caller who hands the
   // same object to `invalidateCache`/`expireCache` reaches this instance's store (see
@@ -520,6 +510,34 @@ export async function expireCache<ArgsT extends unknown[] = any[]>(
 
 // --- Internal helpers ---
 
+// Cache-key `name` resolution, shared by `defineCachedFunction` and `defineCachedHandler`
+// (which passes the wrapped `EventHandler` as `fn`) so the two paths cannot drift.
+// Deliberately commented with `//`, not JSDoc, so docs4ts keeps it out of the API docs.
+//
+// MUST be called on the *caller's* options, BEFORE `defaultCacheOptions()` is merged in:
+// those defaults set a truthy `name: "_"`, so merging first makes `opts.name` always `"_"`
+// and the `fn.name` fallback dead code — a silent cache-key collision across every unnamed
+// cached function/handler (https://github.com/unjs/ocache/issues/53). `defineCachedHandler`
+// merged its defaults first and so shipped exactly that bug for handlers: every handler
+// keyed as `_`, and two handlers sharing one `storage` (the configuration the `storage`
+// docs recommend) either thrashed each other's entries or — when their sources match, so
+// the integrity hash matches too — served each other's cached responses.
+//
+// For anonymous functions (no `opts.name`, no `fn.name`) fall back to a hash of the
+// function source instead of a shared literal: two distinct inline arrows would
+// otherwise resolve to the same key and thrash each other (each read fails the
+// integrity check and re-resolves). A source hash is the right fallback precisely because
+// it is *stable* — keys must survive a process restart for persistent/shared backends, so
+// nothing per-instance (counter, WeakMap, randomness) is admissible here. The cost is that
+// it can't disambiguate same-source functions that only differ by closed-over variables
+// (the classic factory: `const make = (t) => defineCachedHandler(() => render(t))`) — pass
+// an explicit `name`/`getKey` for those. The integrity hash collides there too, so it is
+// unfixable from the source alone, and with a shared `storage` it is a cross-instance leak
+// rather than mere thrash.
+export function _resolveName(name: string | undefined, fn: (...args: any[]) => any): string {
+  return name || fn.name || `anon_${hash(fn).slice(0, 16)}`;
+}
+
 // Storage for the standalone purge helpers, which — unlike `resolveCacheKeys` (pure key
 // derivation, no storage) — are useless without the backend the entries were written to.
 // Since storage became per-instance there is no ambient store to fall back on, so an unset

src/http.ts

@@ -1,5 +1,11 @@
 import { hash } from "ohash";
-import { cachedFunction, expireCache, invalidateCache, resolveCacheKeys } from "./cache.ts";
+import {
+  _resolveName,
+  cachedFunction,
+  expireCache,
+  invalidateCache,
+  resolveCacheKeys,
+} from "./cache.ts";
 import { _resolveStorage } from "./storage.ts";
 
 import type {
@@ -41,7 +47,18 @@ export function defineCachedHandler<E extends HTTPEvent = HTTPEvent>(
   handler: EventHandler<E>,
   opts: CachedEventHandlerOptions<E> = {},
 ): CachedEventHandler<E> {
-  opts = { ...defaultCacheOptions(), ...opts };
+  // Resolve `name` from the caller's opts BEFORE merging the defaults below, which set a
+  // truthy `name: "_"`. Merging first (the previous behavior) made `opts.name` always `"_"`
+  // by the time `cachedFunction` re-derived it, so the `fn.name`/source-hash fallback was
+  // unreachable and *every* handler keyed as `_` — issue #53's fix never reached the HTTP
+  // layer. Two handlers sharing one `storage` on the same path then collided: identical
+  // sources hash to the same integrity too, so one served the other's cached response;
+  // differing sources failed each other's integrity check on every read (0% hit rate).
+  // Same rule as `defineCachedFunction`, via the same helper so the two cannot drift — see
+  // `_resolveName` in `cache.ts`, including the documented caveat that same-source handlers
+  // from one factory still share a name (pass an explicit `name`).
+  const name = _resolveName(opts.name, handler);
+  opts = { ...defaultCacheOptions(), ...opts, name };
 
   // Allowlist of cookie names that may participate in caching — the *request* side only.
   // `undefined` means "no cookies allowed": the Cookie request header is stripped before

src/types.ts

@@ -89,7 +89,16 @@ export interface CacheEntry<T = any> {
  * Options for configuring cached functions created by `defineCachedFunction`.
  */
 export interface CacheOptions<T = any, ArgsT extends unknown[] = any[]> {
-  /** Name used as part of the cache key. Defaults to the function name or `"_"`. */
+  /**
+   * Name used as part of the cache key.
+   *
+   * Defaults to the cached function's (or handler's) own `name`, falling back to a hash of
+   * its source for anonymous ones. A source hash cannot distinguish same-source functions
+   * that differ only by a closed-over variable (the classic factory:
+   * `const make = (tenant) => defineCachedHandler(() => render(tenant), { storage })`) —
+   * those share a key, and with a shared `storage` they share entries outright. Pass an
+   * explicit `name` whenever instances are built in a factory or a loop.
+   */
   name?: string;
   /** Custom cache key generator. Receives the same arguments as the cached function. */
   getKey?: (...args: ArgsT) => string | Promise<string>;