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.71%. Comparing base (3ea9547) to head (8c04114).

Additional details and impacted files
@@           Coverage Diff           @@
##             main   #67232   +/-   ##
=======================================
  Coverage   90.71%   90.71%           
=======================================
  Files         801      801           
  Lines      280705   280763   +58     
  Branches    54168    54200   +32     
=======================================
+ Hits       254640   254699   +59     
- Misses      16247    16252    +5     
+ Partials     9818     9812    -6     
Files with missing lines Coverage Δ
lib/internal/http/outgoing.js 98.26% <100.00%> (+0.26%) ⬆️

... and 25 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
}));

// Only strings are cached: arrays are mutable and must be re-validated.
const kMaxCachedHeaderNames = 256;

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.

So what happens after 256? Lets add a benchmark for this case too. In some networking applications it is very common for there to be over 256 unique header names across all the requests a process might receive.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Good question: I implemented a two-generation LRU (256 names per generation), so new names keep getting cached after the first 256, and hits are still a single Map.get().

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Only 1 in 8 new names gets admitted, so one-off names don't churn it.

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.

Does the benchmark result include this change too?

@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
araujogui force-pushed the http-cache-header-validation branch from 8c04114 to a0bc32d Compare November 20, 2026 11:41
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.

5 participants