Skip to content

perf(ext/fetch): cache Headers iteration for all guard types - #32728

Closed
bartlomieju wants to merge 2 commits into
mainfrom
perf/headers-iteration-cache
Closed

bartlomieju wants to merge 2 commits into
mainfrom
perf/headers-iteration-cache

Conversation

@bartlomieju

@bartlomieju bartlomieju commented Mar 14, 2026 •

Copy link
Copy Markdown
Member

Summary

  • Cache the _iterableHeaders computed entries for all guard types, not just "immutable"
  • Invalidate cache on mutation (append, set, delete)

Root cause

The _iterableHeaders getter rebuilds the sorted entries array on every access for non-immutable Headers (guard !== "immutable"), which is the common case for user-created Headers objects. Each rebuild lowercases all header names, builds a dedup map, creates entry arrays, and sorts — all discarded on the next iteration.

Benchmark: release build vs system Deno 2.7.5 (8 headers × 1KB values)

System Deno 2.7.5 This PR Speedup
Headers for...of 14.8 µs 296 ns 50x faster
vs Map gap 88x slower 3x slower

The remaining ~3x gap vs Map is inherent overhead from the WebIDL iterator protocol.

Closes #20980

Test plan

  • Verified with benchmark from the issue
  • cargo test -p specs_tests -- fetch (13 tests passed)
  • cargo test -p specs_tests -- headers (1 test passed)
  • Manual correctness tests for cache invalidation on append/set/delete, set-cookie non-combining, keys/values/forEach

🤖 Generated with Claude Code

The `_iterableHeaders` getter was rebuilding the sorted entries array on
every access for non-immutable Headers (guard !== "immutable"), which is
the common case for user-created Headers objects. This caused ~60x
slower iteration compared to a Map.

Cache the computed entries for all guard types and invalidate on
mutation (append, set, delete). This reduces the gap from ~60x to ~3x.

Closes #20980

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@devsnek

devsnek commented Mar 14, 2026

Copy link
Copy Markdown
Contributor

is this safe from reentrancy?

@lucacasonato lucacasonato left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are there no places we mutate the header list internally?

@bartlomieju

Copy link
Copy Markdown
Member Author

@lucacasonato Good catch — there are two places that mutate the header list internally without going through append/set/delete:

  1. 23_response.js — initializeAResponse pushes Content-Type directly onto the raw list via ArrayPrototypePush(list, ...) when the body has a content type.
  2. 23_request.js — Request constructor splices the header list to clear it via ArrayPrototypeSplice(headerList, 0, headerList.length).

In practice these are safe today because they happen during construction before the Headers object is exposed to user code (cache is undefined), but it's fragile. I've pushed a fix that adds an exported invalidateHeaderListCache(headers) helper and calls it at both sites.

@bartlomieju

Copy link
Copy Markdown
Member Author

@devsnek Yes, it's safe from reentrancy. The _iterableHeaders getter only performs internal string/array operations using cached primordials (ArrayPrototypePush, ArrayPrototypeSort, byteLowerCase, string concatenation) — no user callbacks, no getters on the data, no Proxy-observable operations. The _headerList entries are plain [string, string] arrays created internally, so there's no way for user code to intercept property access on them.

The cache is written only after the entries array is fully computed. The mutation methods (append/set/delete) invalidate the cache before returning, and their user-observable parts (webidl ByteString conversion) happen before any mutation. So there's no window where user code could re-enter and observe a stale cache.

The iterator (mixinPairIterable) snapshots the entries array by calling the getter once, then walks it by index — so even if a mutation happens mid-iteration, the iterator holds a reference to the old (now-detached) entries array and continues safely.

@fibibot fibibot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Substance is right (cache _iterableHeaders for all guard types and invalidate on mutation), and the three sites added in this PR (appendHeader, Request._init splice, initializeAResponse Content-Type push) close the cases @lucacasonato flagged. But there are at least three more direct request.headerList mutation sites in ext/fetch/26_fetch.js that bypass Headers-level mutation methods — pre-PR these were safe because non-immutable guards never cached, post-PR they leave a stale cache.

Concrete failure mode

const req = new Request("http://example.com", { headers: { Foo: "bar" } });
[...req.headers];                       // populates _iterableHeadersCache (guard="request")
await fetch(req);                       // mainFetch pushes Accept/Accept-Language onto request.headerList
[...req.headers];                       // STALE: returns the pre-fetch entries, no Accept

Pre-PR, the second iteration rebuilt entries from _headerList, picking up the new Accept/Accept-Language. Post-PR the cache lookup at 20_headers.js:236 short-circuits with stale data.

User visibility: edge case (post-fetch header inspection on the same Request object) but a behavioral regression vs current main.

Sites the PR misses

All mutate the raw request.headerList/inner.headerList array bypassing the Headers instance:

ext/fetch/26_fetch.js:316    ArrayPrototypeSplice(request.headerList, i, 1);    // redirect: drop body headers
ext/fetch/26_fetch.js:337    ArrayPrototypeSplice(request.headerList, i, 1);    // redirect: drop sensitive headers
ext/fetch/26_fetch.js:415    ArrayPrototypePush(request.headerList, ["Accept", "*/*"]);
ext/fetch/26_fetch.js:419    ArrayPrototypePush(request.headerList, ["Accept-Language", "*"]);

request.headerList here is the InnerRequest's raw array; the user-facing Headers wrapper is created via headersFromHeaderList(request.headerList, "request") at 23_request.js:31 (and shares the array by reference). The wrapper's _iterableHeadersCache doesn't see these direct array mutations.

23_response.js:281 (ArrayPrototypePush(inner.headerList, ["Location", ...])) is safe because the Headers wrapper is created via headersFromHeaderList(inner.headerList, "immutable") after the push — cache is populated post-mutation.

Fix direction

Two options:

  1. Invalidate at each direct mutation. In 26_fetch.js, after each splice/push on request.headerList, call invalidateHeaderListCache(requestObject.headers). The requestObject is in scope at :415,419 (it's the outer-scope variable), but the redirect handler at :316,337 runs in mainFetch/httpRedirectFetch where requestObject may not be reachable — would need a back-reference from InnerRequest to its wrapping Headers, or pass the wrapper through.

  2. Restrict the cache to guards where direct-mutation cannot happen. Cache for "none", "immutable", "request-no-cors" (no internal mutations on these). Skip caching for "request" and "response". This narrows the perf win but eliminates the staleness window — the perf-sensitive case in the PR's motivation (Headers constructed in user code) is "none" guard, so the user-code benefit is preserved.

Option 2 is simpler and matches the original "immutable"-only design intent. Option 1 is more thorough but needs the invalidation plumbing across the fetch redirect path.

Other notes

  • mergeable_state: dirty — needs a rebase.
  • @bartlomieju's response to @devsnek ("safe from reentrancy" — only primordials, no user callbacks) is correct; that line of concern is closed.
  • No test additions in this PR. A regression test for the Accept-injection staleness would be straightforward — [...req.headers] before and after fetch on a server that stalls long enough to inspect.

@bartlomieju

Copy link
Copy Markdown
Member Author

Closing as part of an open-PR backlog cleanup. The underlying idea is sound, but the branch needs a rebase and the flagged issues addressed. Closing is not a rejection — reopen or re-push if/when this gets prioritized. Thanks!

@bartlomieju bartlomieju closed this Aug 4, 2026
tomas-zijdemans added a commit to tomas-zijdemans/deno-tz that referenced this pull request Aug 8, 2026
… pushes

Covers the staleness scenario from the denoland#32728 review:
populate the iteration entries cache on a Request, fetch it (fetch
pushes Accept and Accept-Language directly onto the inner request's raw
header list), iterate again. The inner request is a clone, so the
original must iterate unchanged while the pushes reach the wire.

Co-authored-by: Cursor <cursoragent@cursor.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Poor Headers performance

4 participants