Skip to content

http: cache header validation in setHeader() - #67232

Open
araujogui wants to merge 3 commits into
nodejs:mainfrom
araujogui:http-cache-header-validation
Open

araujogui wants to merge 3 commits into
nodejs:mainfrom
araujogui:http-cache-header-validation

Conversation

@araujogui

Copy link
Copy Markdown
Member

setHeader() and appendHeader() validate, lowercase, and scan the value of every header on every call, even though applications send the same names and mostly the same values on every response.

This caches each valid header name with its lowercased form and the last valid string value set for it, so repeated names skip the token check and toLowerCase(), and repeated values skip the character scan. Arrays are always re-validated since they are mutable. The cache is capped at 256 names, and values longer than 256 characters are not cached.

Adds benchmark/http/set-header-rest.js and a regression test.

Copilot AI balanced review requested due to automatic review settings November 3, 2026 23:00
@nodejs-github-bot

Copy link
Copy Markdown
Collaborator

Review requested:

  • @nodejs/http
  • @nodejs/net
  • @nodejs/performance

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@nodejs-github-bot nodejs-github-bot added http Issues and PRs related to the http subsystem. needs-ci PRs that need a full CI run. labels Nov 3, 2026
@codecov

codecov Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.73%. Comparing base (5884b8e) to head (a0bc32d).
⚠️ Report is 19 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main   #67232      +/-   ##
==========================================
+ Coverage   90.71%   90.73%   +0.01%     
==========================================
  Files         801      801              
  Lines      280906   280964      +58     
  Branches    54249    54269      +20     
==========================================
+ Hits       254832   254940     +108     
+ Misses      16246    16200      -46     
+ Partials     9828     9824       -4     
Files with missing lines Coverage Δ
lib/internal/http/outgoing.js 98.26% <100.00%> (+0.26%) ⬆️

... and 34 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@araujogui
araujogui force-pushed the http-cache-header-validation branch from 7e0458a to 4b4d19e Compare November 4, 2026 19:12
@araujogui araujogui added the review wanted PRs that need review. label Nov 6, 2026
marcastben-hash

This comment was marked as low quality.

@Ethan-Arrowood Ethan-Arrowood 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.

Mainly want to see what the benchmarks actually look like for this change. Need to fix that error stack frames thing too. Otherwise, I'm definitely in support of a change like this to make the main headers validation path faster.

Comment thread benchmark/http/set-header-rest.js Resolved
Comment thread lib/internal/http/outgoing.js Resolved
Comment thread lib/internal/http/outgoing.js Resolved
@araujogui

araujogui commented Nov 18, 2026 •

Copy link
Copy Markdown
Member Author

https://ci.nodejs.org/view/Node.js%20benchmark/job/benchmark-node-micro-benchmarks/1907/

benchmark/http/set-header-rest.js
++ ./node-master benchmark/compare.js --set CPUSET=0-11 --analyze --old ./node-master --new ./node-pr --filter set-header-rest -- http
                                                                                                confidence   improvement   accuracy (*)    (**)   (***)
http/set-header-rest.js duration=5 names='fixed' values='static' headers=2 benchmarker='wrk'    ***             +3.57 %   ±0.82%  ±1.10%  ±1.43%
http/set-header-rest.js duration=5 names='many' values='static' headers=2 benchmarker='wrk'                     -0.28 %   ±1.03%  ±1.37%  ±1.79%
http/set-header-rest.js duration=5 names='fixed' values='dynamic' headers=2 benchmarker='wrk'   ***             +1.87 %   ±1.03%  ±1.38%  ±1.79%
http/set-header-rest.js duration=5 names='many' values='dynamic' headers=2 benchmarker='wrk'    ***             -2.59 %   ±0.69%  ±0.92%  ±1.19%
http/set-header-rest.js duration=5 names='fixed' values='static' headers=12 benchmarker='wrk'   ***            +16.89 %   ±0.78%  ±1.03%  ±1.35%
http/set-header-rest.js duration=5 names='many' values='static' headers=12 benchmarker='wrk'    ***             -5.05 %   ±0.82%  ±1.09%  ±1.42%
http/set-header-rest.js duration=5 names='fixed' values='dynamic' headers=12 benchmarker='wrk'  ***             +7.53 %   ±1.02%  ±1.36%  ±1.77%
http/set-header-rest.js duration=5 names='many' values='dynamic' headers=12 benchmarker='wrk'   ***             -5.84 %   ±0.80%  ±1.07%  ±1.40%

                                                                                                   -17.7%             0%             +17.7%
http/set-header-rest.js duration=5 names='fixed' values='static' headers=2 benchmarker='wrk'                        |███░                 +3.57% ***
http/set-header-rest.js duration=5 names='many' values='static' headers=2 benchmarker='wrk'                        ░|                     -0.28% 
http/set-header-rest.js duration=5 names='fixed' values='dynamic' headers=2 benchmarker='wrk'                       |█░                   +1.87% ***
http/set-header-rest.js duration=5 names='many' values='dynamic' headers=2 benchmarker='wrk'                    ░███|                     -2.59% ***
http/set-header-rest.js duration=5 names='fixed' values='static' headers=12 benchmarker='wrk'                       |██████████████████░  +16.89% ***
http/set-header-rest.js duration=5 names='many' values='static' headers=12 benchmarker='wrk'                 ░██████|                     -5.05% ***
http/set-header-rest.js duration=5 names='fixed' values='dynamic' headers=12 benchmarker='wrk'                      |████████░            +7.53% ***
http/set-header-rest.js duration=5 names='many' values='dynamic' headers=12 benchmarker='wrk'               ░███████|                     -5.84% ***

Rates were scaled by 1000x into HdrHistogram (3 significant figures).
Use --scale to adjust precision if needed.

Be aware that when doing many comparisons the risk of a false-positive
result increases. In this case, there are 8 comparisons, you can thus
expect the following amount of false-positive results:
  0.40 false positives, when considering a   5% risk acceptance (*, **, ***),
  0.08 false positives, when considering a   1% risk acceptance (**, ***),
  0.01 false positives, when considering a 0.1% risk acceptance (***)

The stars above are per-benchmark and uncorrected. Adjusting for the size of
this comparison set (Holm-Bonferroni), 7 comparisons remain significant at 5%.
--max-regression uses the corrected values.

@araujogui
araujogui force-pushed the http-cache-header-validation branch from 4b4d19e to 8c04114 Compare November 18, 2026 01:17
@Ethan-Arrowood

Copy link
Copy Markdown
Contributor

Looks like my own #67528 caused a merge conflict here. Sorry about that. Can you rebase and rerun the benchmarks? What I'm seeing so far looks good though so I'm optimistic we can land this asap!

Cache each valid header name with its lowercased form and the last
valid string value set for it, so repeated names and values skip
validation and toLowerCase() in setHeader() and appendHeader().
Arrays are always re-validated. The cache is bounded.

Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>
Assisted-by: Claude
Use a two-generation LRU instead of stopping at 256 names. Wrap
validation in hideStackFrames() and add a benchmark case with many
unique names.

Assisted-by: Claude
Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>
Cache only one in eight new names, so most misses skip the allocation
and insertion.

Assisted-by: Claude
Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>
@araujogui

Copy link
Copy Markdown
Member Author

https://ci.nodejs.org/view/Node.js%20benchmark/job/benchmark-node-micro-benchmarks/1908/

benchmark/http/set-header-rest.js
++ ./node-master benchmark/compare.js --set CPUSET=0-11 --analyze --old ./node-master --new ./node-pr --filter set-header-rest -- http
                                                                                                confidence   improvement   accuracy (*)    (**)   (***)
http/set-header-rest.js duration=5 names='fixed' values='static' headers=2 benchmarker='wrk'    ***             +4.38 %   ±0.67%  ±0.89%  ±1.16%
http/set-header-rest.js duration=5 names='many' values='static' headers=2 benchmarker='wrk'       *             -0.84 %   ±0.71%  ±0.95%  ±1.23%
http/set-header-rest.js duration=5 names='fixed' values='dynamic' headers=2 benchmarker='wrk'   ***             +1.78 %   ±0.94%  ±1.24%  ±1.62%
http/set-header-rest.js duration=5 names='many' values='dynamic' headers=2 benchmarker='wrk'    ***             -1.95 %   ±0.89%  ±1.18%  ±1.54%
http/set-header-rest.js duration=5 names='fixed' values='static' headers=12 benchmarker='wrk'   ***            +16.28 %   ±0.65%  ±0.87%  ±1.14%
http/set-header-rest.js duration=5 names='many' values='static' headers=12 benchmarker='wrk'    ***             -4.54 %   ±0.72%  ±0.96%  ±1.25%
http/set-header-rest.js duration=5 names='fixed' values='dynamic' headers=12 benchmarker='wrk'  ***             +6.23 %   ±0.72%  ±0.96%  ±1.25%
http/set-header-rest.js duration=5 names='many' values='dynamic' headers=12 benchmarker='wrk'   ***             -6.43 %   ±0.83%  ±1.11%  ±1.44%

                                                                                                   -16.9%             0%             +16.9%
http/set-header-rest.js duration=5 names='fixed' values='static' headers=2 benchmarker='wrk'                        |████░                +4.38% ***
http/set-header-rest.js duration=5 names='many' values='static' headers=2 benchmarker='wrk'                       ░█|                     -0.84% *
http/set-header-rest.js duration=5 names='fixed' values='dynamic' headers=2 benchmarker='wrk'                       |█░                   +1.78% ***
http/set-header-rest.js duration=5 names='many' values='dynamic' headers=2 benchmarker='wrk'                     ░██|                     -1.95% ***
http/set-header-rest.js duration=5 names='fixed' values='static' headers=12 benchmarker='wrk'                       |██████████████████░  +16.28% ***
http/set-header-rest.js duration=5 names='many' values='static' headers=12 benchmarker='wrk'                  ░█████|                     -4.54% ***
http/set-header-rest.js duration=5 names='fixed' values='dynamic' headers=12 benchmarker='wrk'                      |██████░              +6.23% ***
http/set-header-rest.js duration=5 names='many' values='dynamic' headers=12 benchmarker='wrk'              ░████████|                     -6.43% ***

Rates were scaled by 1000x into HdrHistogram (3 significant figures).
Use --scale to adjust precision if needed.

Be aware that when doing many comparisons the risk of a false-positive
result increases. In this case, there are 8 comparisons, you can thus
expect the following amount of false-positive results:
  0.40 false positives, when considering a   5% risk acceptance (*, **, ***),
  0.08 false positives, when considering a   1% risk acceptance (**, ***),
  0.01 false positives, when considering a 0.1% risk acceptance (***)

The stars above are per-benchmark and uncorrected. Adjusting for the size of
this comparison set (Holm-Bonferroni), 8 comparisons remain significant at 5%.
--max-regression uses the corrected values.

@araujogui

Copy link
Copy Markdown
Member Author

@Ethan-Arrowood I ran benchmark again after rebase

@Ethan-Arrowood Ethan-Arrowood 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.

I'm approving this, but I do want to see what other @nodejs/http members think. The many headers case regresses 6.4%, meanwhile the fixed case improves 16.3%. Is that sufficient enough to land this change? I'm not sure which scenario is more common. I also am unsure if the regression is significant enough compared to the improvement. If others believe the regression is significant enough, should we then gate this behind an option? So in circumstances where someone knows they'll have lots of header values they can disable this and not pay the cache penalty? Or better yet, could we make the cache size itself configurable? I think this is a sensible enough default in that case.

@araujogui

Copy link
Copy Markdown
Member Author

In real-world scenarios, most header names are fixed so I believe the gains would outweigh the regression.

@mcollina mcollina left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Lgtm

@mcollina mcollina added the request-ci Add this label to start a Jenkins CI on a PR. Only starts once the PR has an approving review. label Nov 21, 2026
@github-actions github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. Only starts once the PR has an approving review. label Nov 21, 2026
@nodejs-github-bot

Copy link
Copy Markdown
Collaborator

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

http Issues and PRs related to the http subsystem. needs-ci PRs that need a full CI run. review wanted PRs that need review.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants