Reworking Headers impl #5396

jasnell · 2025-10-23T01:33:47Z

Needs careful review. It does improve performance but the impl is a bit more complex. Fiddled around with a number of other perf tweaks but nothing that really moved the needle enough to justify the increased complexity. Not entirely sold on this impl so be brutal in reviews.

codspeed-hq · 2025-10-23T03:52:34Z

CodSpeed Performance Report

Merging #5396 will improve performances by 45.68%

_{Comparing jasnell/http-headers-take-2 (30f6df6) with main (153c3ef)}

Summary

⚡ 2 improvements
✅ 32 untouched
⏩ 9 skipped¹

Benchmarks breakdown

	Benchmark	`BASE`	`HEAD`	Change
⚡	`constructor[ApiHeaders]`	90.9 ms	62.4 ms	+45.68%
⚡	`set_append[ApiHeaders]`	15.9 ms	11.9 ms	+33.69%

9 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

jasnell · 2025-10-23T15:10:12Z

Internal tests are failing because the refactor changes the ordering of the headers in places... will need to see if we can preserve the order but first want to see if this has a positive impact on performance overall... waiting for benchmark results to be updated.

jasnell · 2025-10-23T16:42:12Z

Marking as ready for review but there are still some internal test updates I'll need to do on the internal repo.

npaun · 2025-10-23T17:24:05Z

src/wpt/fetch/api-test.ts

  'headers/headers-errors.any.js': {
    comment: 'Our validation of header names is too lax',
    expectedFailures: [
-      'Create headers giving bad header name as init argument',


So we did end up getting a couple of WPT improvements out of it, nice.

Yep, but we'll need to make sure this doesn't count as a breaking change that'll need a compat flag.

danlapid · 2025-10-23T17:31:50Z

Whenever this is done I want as many reviewers as we can get on this, incl Harris, Kenton, Mike, Yagiz, etc.

src/workerd/api/headers.c++

src/workerd/api/global-scope.c++

src/workerd/api/headers.h

src/workerd/tests/bench-response.c++

src/workerd/api/headers.c++

jasnell · 2025-10-24T23:42:42Z

Note for reviewers: while it likely is possible to get more performance gain with additional tweaks on this, the emphasis for review should be on correctness and ensuring that the revised implementation does not introduce new bugs, etc. We can tweak additional performance knobs separately in follow up PRs.

src/workerd/tests/bench-response.c++

kentonv

Only skimmed briefly but I think there's an opportunity for big gains here by taking advantage of the tables that are already available in HttpOverCapnpFactory.

src/workerd/api/headers.h

src/workerd/api/headers.c++

jasnell · 2025-10-28T18:30:55Z

Further improved the revised implementation and added an additional benchmark.

The additional benchmark shows a ~31% performance improvement in a set/append case.
The common headers are now indexed and hashed at compile time to shave off additional work
jsg::ByteString is removed since it was largely a useless shell anyway. It's warning functionality was wasted on header names since we strictly validate those anyway, and has been replaced to only warn on header values. Given that use of jsg::ByteString was incurring an additional redundant scan on all header names and values this yielded a fairly good performance improvement.
Additional improvements are likely possible but this is already quite significant as it is.

danlapid · 2025-10-28T23:30:21Z

Whenever this is done I want as many reviewers as we can get on this, incl Harris, Kenton, Mike, Yagiz, etc.

Bumping this
@harrishancock @kentonv @mikea @anonrig we need as many eyes as we can get on this, we can't get this change wrong again, important to optimise headers but we need to make sure we are right with our change

In preparation to re-apply Headers performance improvements

Modify the kj::HttpHeaders instead and then construct the api::Headers from that.

While the common header names and indices are defined in the capnp header, they are unlikely to change often (if at all). To avoid the overhead of building the hash map at runtime and performing the hash lookups, we can hardcode the common header names in an array and use direct indexing to retrieve them. Should at least save a handful of CPU cycles.

The type is largely obsolete and was being used only to warn about invalid header names/values in Headers. However, it incurred an additional overhead when being created. This was especially non-sensical for header names since we already validate those to be proper HTTP token strings. Removing the type simplifies code and helps boost overall performance.

jasnell requested review from a team as code owners October 23, 2025 01:33

jasnell marked this pull request as draft October 23, 2025 01:53

jasnell force-pushed the jasnell/http-headers-take-2 branch 2 times, most recently from 7f431f6 to b94d316 Compare October 23, 2025 02:30

jasnell force-pushed the jasnell/http-headers-take-2 branch 4 times, most recently from 8191e31 to 7f84859 Compare October 23, 2025 15:09

jasnell force-pushed the jasnell/http-headers-take-2 branch 2 times, most recently from 21b09a3 to b59e107 Compare October 23, 2025 16:13

jasnell marked this pull request as ready for review October 23, 2025 16:41

jasnell force-pushed the jasnell/http-headers-take-2 branch from 7ac27f1 to 7c52fb0 Compare October 23, 2025 17:02

npaun reviewed Oct 23, 2025

View reviewed changes

jasnell force-pushed the jasnell/http-headers-take-2 branch from 0a4c8f0 to 7c52fb0 Compare October 23, 2025 19:53

jasnell requested review from harrishancock and kentonv October 23, 2025 20:58

jasnell commented Oct 23, 2025

View reviewed changes

src/workerd/api/headers.c++ Show resolved Hide resolved

jasnell requested a review from mikea October 23, 2025 23:15

anonrig reviewed Oct 24, 2025

View reviewed changes

jasnell force-pushed the jasnell/http-headers-take-2 branch 2 times, most recently from 2e794b4 to fb81688 Compare October 24, 2025 23:40

anonrig reviewed Oct 25, 2025

View reviewed changes

src/workerd/tests/bench-response.c++ Show resolved Hide resolved

kentonv reviewed Oct 27, 2025

View reviewed changes

jasnell force-pushed the jasnell/http-headers-take-2 branch from 38a2fab to 37b85f0 Compare October 28, 2025 00:47

jasnell force-pushed the jasnell/http-headers-take-2 branch from 37b85f0 to cd7bdc8 Compare October 28, 2025 18:26

jasnell force-pushed the jasnell/http-headers-take-2 branch from cd7bdc8 to 95b9cbc Compare October 28, 2025 20:36

jasnell mentioned this pull request Oct 29, 2025

Some of the benchmark updates from the headers change #5429

Merged

jasnell added 9 commits October 29, 2025 03:45

Move Headers definition/impl to headers.h/c++

04a44a6

In preparation to re-apply Headers performance improvements

Avoid mutating the api::Headers immediately after creation

a18df61

Modify the kj::HttpHeaders instead and then construct the api::Headers from that.

Refactor header storage

47f6173

Refine the header validation performance further

bb34758

Expand bench-api-headers benchmarks

8da3079

Update various uses of api::Headers

2b37ff6

Further performance refinements in headers

30f6df6

jasnell force-pushed the jasnell/http-headers-take-2 branch from 95b9cbc to 30f6df6 Compare October 29, 2025 10:47

anonrig approved these changes Oct 30, 2025

View reviewed changes

Reworking Headers impl #5396

Are you sure you want to change the base?

Reworking Headers impl #5396

Uh oh!

Conversation

jasnell commented Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codspeed-hq bot commented Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CodSpeed Performance Report

Merging #5396 will improve performances by 45.68%

Summary

Benchmarks breakdown

Footnotes

Uh oh!

jasnell commented Oct 23, 2025

Uh oh!

jasnell commented Oct 23, 2025

Uh oh!

npaun Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

jasnell Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

danlapid commented Oct 23, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jasnell commented Oct 24, 2025

Uh oh!

Uh oh!

kentonv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jasnell commented Oct 28, 2025

Uh oh!

danlapid commented Oct 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jasnell commented Oct 23, 2025 •

edited

Loading

codspeed-hq bot commented Oct 23, 2025 •

edited

Loading