feat(util): expose request header normalization

[GiHoon1123]

Refs #4336.

Request headers can reach composed interceptors as an object, flat array, Headers instance, or another iterable. This adds util.normalizeHeaders() so interceptors that inspect headers can convert those inputs to a lower-case object while preserving repeated values.

The cache and deduplicate interceptors now use the same helper. compose() no longer normalizes every request, avoiding extra header work for interceptors that do not inspect them.

Tests:

• npm run lint
• npm run test:typescript
• borp --timeout 180000 test/interceptors/interceptors-on-client.js test/interceptors/cache-query-params.js test/interceptors/redirect.js test/cache-interceptor/cache-utils.js test/node-test/util.js
• node --test --test-name-pattern '#5522' test/interceptors/dns.js

[codecov-commenter]

Codecov Report

❌ Patch coverage is 92.55319% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.51%. Comparing base (b73952a) to head (058d912).
⚠️ Report is 6 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/core/util.js	92.13%	7 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5780      +/-   ##
==========================================
- Coverage   93.51%   93.51%   -0.01%     
==========================================
  Files         110      110              
  Lines       39359    39552     +193     
==========================================
+ Hits        36808    36986     +178     
- Misses       2551     2566      +15     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 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.

[mcollina]

I'm not convinced by this change, as it's significantly perf cost.

Wdyt @ronag?

[ronag]

Yea. This is probably not a good idea...

[GiHoon1123]

That makes sense. The current implementation wraps every interceptor boundary, so it does more work than necessary for each request.

I’m thinking of changing it to normalize once at the composed dispatcher entry, skip plain objects that are already normalized, and keep the resulting object through interceptor redispatches. Would that address the performance concern, or would you prefer a different approach?

[GiHoon1123]

I reworked this to avoid wrapping each interceptor boundary. Headers are now normalized once when the composed dispatcher is entered, and already-normalized plain objects are passed through without a copy. The existing DNS redispatch cases still pass with the normalized object.

The updated commit is 88e54638. The relevant interceptor tests and lint pass locally.

[metcoder95]

let's try to prefer for-loops over array methods; this will sit in a hot-path if interceptors are used

[GiHoon1123]

Updated this to use a loop.

[metcoder95]

I'm a bit worried of all the branching, but unsure if it can be simplified

[GiHoon1123]

I took another look at the request path. Normalizing in compose() means walking the headers to build an object, then Request walks them again to build its internal array. It also adds that work for interceptors that never read request headers.

Would it be better to expose a shared normalization helper for interceptors that need it? If normalization should happen automatically, it seems like we’d need a shared internal representation that Request can reuse. What do you think?

[metcoder95]

That's a good idea, go for it

[GiHoon1123]

Implemented in 058d912. normalizeHeaders() is now exposed through util, and cache and deduplicate use the same helper. I removed eager normalization from compose(), so interceptors that do not inspect headers no longer pay the extra cost. Types, docs, and the relevant tests have been updated.