Skip to content

perf(ext/fetch): cache Headers iteration entries - #33681

Closed
crowlbot wants to merge 1 commit into
denoland:mainfrom
crowlbot:perf/cache-headers-iteration
Closed

crowlbot wants to merge 1 commit into
denoland:mainfrom
crowlbot:perf/cache-headers-iteration

Conversation

@crowlbot

Copy link
Copy Markdown
Contributor

Summary

Iterating a Headers instance — for (const [k, v] of headers),
headers.entries(), [...headers], etc. — invokes the
[_iterableHeaders] getter via mixinPairIterable's iterator
next() on every step. The getter rebuilt the lowercase / sorted
entries array from scratch each call, allocating a fresh
seenHeaders dict, an entries array, and one [name, value]
tuple per unique name, and running a sort.

For a 7-header Headers iterated once with for...of, that's 8
rebuilds (one per next()) — 8 dict allocations + 8 entries arrays

  • 56 tuple arrays + 8 sorts — pure waste, because the underlying
    list never changes across the iteration.

The existing cache (_iterableHeadersCache) was only consulted when
_guard === "immutable", so non-immutable Headers — which is what
Response.headers, Request.headers, and new Headers(...) all
default to — never benefited.

This PR:

  • Caches the result for any guard.
  • Tracks _iterableHeadersCacheLength alongside the cache so that
    direct mutations to the underlying list (e.g. initializeAResponse
    pushing a Content-Type header into _headerList) are detected by
    length-mismatch and force a rebuild on the next access.
  • Explicitly clears the cache in appendHeader / set / delete
    so that value-only replacements (which don't change length) are
    also covered.

Numbers

cargo bench -p deno_fetch --bench headers (release, mean of 3
baseline / 5 after — variance verified across both):

bench before after Δ
bench_iter_headers_7 (reused, hits cache after first iter) 8,436 µs/iter 810 µs/iter −90.4%
bench_iter_headers_7_after_set (mutate, then iterate; cache invalidated) 9,342 µs/iter 3,156 µs/iter −66.2%
bench_iter_headers_7_fresh (construct + iterate, discard) 11,975 µs/iter 5,769 µs/iter −51.8%

Even the "fresh" case (construct, iterate once, throw away) speeds
up by ~2× because the iterator's per-step target[dataSymbol]
access now hits the cache after the first next() within a single
for...of.

Memory

Allocations per typical iteration of a 7-header instance drop from
~80 (8 seenHeaders dicts + 8 entries arrays + 8×7 tuples + 8
sort scratch) to ~10 (one rebuild + one cache slot read per
next()). Scales linearly with header count.

Test plan

  • cargo bench -p deno_fetch --bench headers x5 before / after
  • CI: existing fetch / headers unit + spec tests (cover append,
    set, delete, has, get, getSetCookie, iteration order,
    duplicate-name combine, set-cookie split, immutable behaviour)
  • CI: WPT fetch/api/headers suite

ext/fetch had no bench harness before this PR — ext/fetch/benches/headers.rs is new (plus the matching [[bench]] entry and deno_bench_util / deno_web / deno_webidl dev-deps in ext/fetch/Cargo.toml). Happy to split the harness scaffolding into a separate prep PR if a maintainer prefers.

Iterating a `Headers` instance — `for (const [k, v] of headers)`,
`headers.entries()`, `[...headers]`, etc. — invokes the
`[_iterableHeaders]` getter via `mixinPairIterable`'s iterator
`next()` *on every step*. The getter rebuilt the lowercase / sorted
entries array from scratch each call, allocating a fresh `seenHeaders`
dict, an `entries` array, and one `[name, value]` tuple per unique
name, and running a sort.

For a 7-header Headers iterated once with `for...of`, that's 8
rebuilds (one per `next()`), so 8 dict allocations + 8 entries
arrays + 56 tuples + 8 sorts — pure waste, since the underlying
list never changed across the iteration.

The existing cache (`_iterableHeadersCache`) was only consulted when
`_guard === "immutable"`, so non-immutable Headers (the default
guard for `Response.headers`, `Request.headers`, `new Headers(...)`)
never benefited.

This commit:

  - Caches the result for any guard.
  - Tracks `_iterableHeadersCacheLength` alongside the cache so that
    direct mutations to the underlying list (e.g.
    `initializeAResponse` pushing a Content-Type header) are detected
    by length-mismatch and force a rebuild on the next access.
  - Explicitly clears the cache in `appendHeader` / `set` / `delete`
    so that value-only replacements (which don't change length) are
    also covered.

Numbers (cargo bench -p deno_fetch --bench headers, release, mean of
3 baseline / 5 after):

  bench_iter_headers_7            8,436 → 810  µs/iter   −90.4%
  bench_iter_headers_7_after_set  9,342 → 3,156 µs/iter  −66.2%
  bench_iter_headers_7_fresh     11,975 → 5,769 µs/iter  −51.8%

Even the "fresh" case (construct + iterate, throw away) speeds up
because the iterator's per-step `target[dataSymbol]` access now hits
the cache after the first `next()`.

Memory: per typical iteration, allocations drop from N+1 (one per
`next()`) to 1 — a ~7× allocation reduction for a 7-header iteration,
scaling linearly with header count.

Adds `ext/fetch/benches/headers.rs` (and the matching `[[bench]]`
entry plus `deno_bench_util` / `deno_web` / `deno_webidl` dev-deps in
`ext/fetch/Cargo.toml`); `ext/fetch` had no bench harness before.
@bartlomieju

Copy link
Copy Markdown
Member

IS this the same as #32728?

@crowlbot

Copy link
Copy Markdown
Contributor Author

Yes, you're right — the core change here (cache [_iterableHeaders] for all guards, invalidate on mutation) is the same as #32728. I didn't see that PR before opening this; sorry for the duplicate review work.

Differences worth noting in case any of them are useful for the older PR:

  • External-mutation handling. initializeAResponse (23_response.js) and the Request splice/refill block (23_request.js) push directly to _headerList without going through appendHeader / set / delete. perf(ext/fetch): cache Headers iteration for all guard types #32728 exports invalidateHeaderListCache(headers) and calls it explicitly at those two sites. This PR instead tracks _iterableHeadersCacheLength and rebuilds when the lengths diverge — same end result, no cross-file edits, but the explicit-invalidation form is cleaner if you don't mind touching the two callers (and is what I'd land if I were doing it again).
  • Bench harness. ext/fetch has no bench harness on main, so there were no numbers in perf(ext/fetch): cache Headers iteration for all guard types #32728's diff. This PR adds ext/fetch/benches/headers.rs (and the matching [[bench]] + dev-deps in Cargo.toml) so the gain is measurable from cargo bench -p deno_fetch --bench headers. Since this same harness scaffolding lands in the other ext/fetch PRs I have open right now, I'm happy to extract it into a separate prep PR if that's easier.

Happy to close this in favour of #32728 — would you like me to do that, or push the harness across as a follow-up if #32728 lands?

@crowlbot

Copy link
Copy Markdown
Contributor Author

Yes — you're right, this is the same core optimization as #32728. Apologies, I should have checked for prior art before opening.

A couple of differences if useful for the comparison:

Happy to close in favor of #32728. If the bench harness is useful, I can split it into a separate prep PR (just the scaffolding, no JS change) so future ext/fetch perf work has it. Let me know which you prefer.

@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. The win is real because mixinPairIterable.next() reads target[dataSymbol] on every iteration step (webidl/00_webidl.js:1170), so a 7-header for...of was calling the entries-rebuild getter 8 times — verified.

Walked the invalidation strategy:

  • Cache hit gate: cached !== undefined && _iterableHeadersCacheLength === list.length. Two independent guards.
  • Method mutations: appendHeader (line 156), Headers.set (line 452), Headers.delete (line 353) all explicitly clear [_iterableHeadersCache] = undefined. ✓
  • Direct _headerList mutations:
    • 23_response.js:223–232 initializeAResponse push of Content-Type: caught by length-divergence (_iterableHeadersCacheLength = N, list.length = N+1). ✓
    • 23_request.js:412–419 splice/refill: the splice empties the list, then fillHeaders calls appendHeader which clears the cache symbol on first push — and the length is also divergent in the meantime, so even a stale read between the two would rebuild. ✓
  • Mid-iteration mutations (for (const [k,v] of h) { h.delete("x") }): both old and new code give the same behavior — the mutation invalidates the cache, the next next() rebuilds, and the iterator's index keeps incrementing across the new array. Identical pre-existing semantics, no regression.

Same fragility concern as #33683

The invalidation strategy catches:

  1. Mutations through append/set/delete (cache symbol cleared explicitly).
  2. Mutations that change _headerList.length (length divergence).

It does not catch in-place same-length mutations like list[i] = ["new-name", val] or list[i][0] = "new-name". None exist in the codebase today, and headersFromHeaderList always replaces the list as a whole on a fresh Headers (cache starts undefined). Same suggestions I made on #33683 apply here too:

  • Add a // IMPORTANT: if you mutate the returned list in place at the same length, also clear headers[_iterableHeadersCache]. comment on headerListFromHeaders.

  • Or expose a small invalidateHeaderCaches(headers) helper that future callers can use defensively. Coordinated with #33683's _lowerNames cache, both could share the same invalidation function:

    function invalidateHeaderCaches(headers) {
      headers[_iterableHeadersCache] = undefined;
      headers[_lowerNames] = null; // if #33683 lands
    }
    

The _iterableHeadersCacheLength field nicely doubles as a defense — but it's silent. A debug-mode assert that cached.length === list.length && every-name-matches on cache hit would catch desyncs loudly without runtime cost in release.

Coordination with #33683

#33683 (lowercased-names cache) and this PR share two concerns:

  1. Both add identical [dev-dependencies] scaffolding (deno_bench_util / deno_web / deno_webidl) and the matching [[bench]] entry to ext/fetch/Cargo.toml. Whichever lands first wins; the other will need to rebase on a bench harness that already exists. Worth extracting that scaffolding into a separate prep PR — it would unblock both perf PRs cleanly.
  2. Both add cache invalidation to appendHeader / set / delete. If both land, those methods will end up with two separate headers[_someCache] = undefined lines back-to-back. Easy to miss one in a future edit. A single invalidateHeaderCaches(headers) helper covers both.

Suggest landing this and #33683 sequentially with the second one rebased to use a shared helper.

Smaller nits

  • _iterableHeadersCacheLength is declared inline (set on first cache write, undefined initially). Same pattern as _iterableHeadersCache. Consistent. ✓
  • bench_iter_headers_7 description says "subsequent calls hit the cache" — strictly the bench harness measures one full for...of loop per iteration, and the cache hits within a single loop after the first next(). The "subsequent calls" framing in the bench comment is slightly off; the cache hits between iter-steps within one for-of, which is the real win. Cosmetic.

CI

Only license/cla and lint title have run — the full fetch/headers + WPT shards haven't started. Holding COMMENT per the CI-must-complete rule. Substance is clean; happy to flip to APPROVE once CI lands and either the cache-invalidation comment is added or the shared-helper consolidation with #33683 is decided.

@crowlbot

Copy link
Copy Markdown
Contributor Author

Closing as duplicate of #32728 — confirmed by @bartlomieju and walking the diffs the core change (cache [_iterableHeaders] for all guard types, invalidate on mutation) is the same. Deferring to that PR.

@crowlbot crowlbot closed this May 12, 2026
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.

3 participants