fix: handle flat alternating header arrays in cache normalizeHeaders by mcollina · Pull Request #5536 · nodejs/undici

mcollina · 2026-07-09T08:47:08Z

Description

The cache interceptor's normalizeHeaders function only handled two header
formats:

Array-of-pairs: [['key', 'val'], ...]
Object: { key: 'val', ... }

However, undici internally uses flat alternating arrays:
['key', 'val', 'key', 'val', ...]. When the cache() interceptor is placed
before dns() in a compose chain (e.g., new Agent().compose(cache(), dns())),
the DNS interceptor converts headers to flat format before passing them to
the cache interceptor, causing normalizeHeaders to throw
'opts.headers is not a valid header map'.

Reproduction

import{Agent,interceptors,request}from"undici";const{ cache, dns }=interceptors;constcacheThenDns=newAgent().compose(cache(),dns());consturl="https://www.google.com";constheaders=[];constr=awaitrequest(url,{dispatcher: cacheThenDns, headers });

Fixes#5522

The cache interceptor's normalizeHeaders function only handled two header formats: array-of-pairs ([[key, val], ...]) and plain objects ({ key: val, ...}). However, undici internally uses flat alternating arrays ([key, val, key, val, ...]). When the cache() interceptor is placed before dns() in a compose chain, the DNS interceptor converts headers to flat alternating format before passing them to the cache interceptor, causing normalizeHeaders to throw 'opts.headers is not a valid header map'. Fixes#5522

codecov-commenter · 2026-07-09T09:06:04Z

Codecov Report

❌ Patch coverage is 83.67347% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.44%. Comparing base (cb4c2f1) to head (c16c29d).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/util/cache.js	83.67%	8 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #5536 +/- ##
=======================================
Coverage 93.44% 93.44% =======================================
Files 110 110 Lines 37328 37418 +90 =======================================
+ Hits 34881 34966 +85 - Misses 2447 2452 +5

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

The underlying normalizeHeaders bug was fixed in nodejs#5536, which covers the flat-header handling with unit tests. These integration tests exercise the path the bug was actually reported through - a dns interceptor re-dispatch landing in a composed cache() (and deduplicate(), which shares the same cache-key utility) - so the compose-chain scenario stays covered end to end.

mcollina · 2026-07-09T08:47:08Z

Description

The cache interceptor's normalizeHeaders function only handled two header
formats:

Array-of-pairs: [['key', 'val'], ...]
Object: { key: 'val', ... }

However, undici internally uses flat alternating arrays:
['key', 'val', 'key', 'val', ...]. When the cache() interceptor is placed
before dns() in a compose chain (e.g., new Agent().compose(cache(), dns())),
the DNS interceptor converts headers to flat format before passing them to
the cache interceptor, causing normalizeHeaders to throw
'opts.headers is not a valid header map'.

Reproduction

import{Agent,interceptors,request}from"undici";const{ cache, dns }=interceptors;constcacheThenDns=newAgent().compose(cache(),dns());consturl="https://www.google.com";constheaders=[];constr=awaitrequest(url,{dispatcher: cacheThenDns, headers });

Fixes#5522

The cache interceptor's normalizeHeaders function only handled two header formats: array-of-pairs ([[key, val], ...]) and plain objects ({ key: val, ...}). However, undici internally uses flat alternating arrays ([key, val, key, val, ...]). When the cache() interceptor is placed before dns() in a compose chain, the DNS interceptor converts headers to flat alternating format before passing them to the cache interceptor, causing normalizeHeaders to throw 'opts.headers is not a valid header map'. Fixes#5522

codecov-commenter · 2026-07-09T09:06:04Z

Codecov Report

❌ Patch coverage is 83.67347% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.44%. Comparing base (cb4c2f1) to head (c16c29d).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/util/cache.js	83.67%	8 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #5536 +/- ##
=======================================
Coverage 93.44% 93.44% =======================================
Files 110 110 Lines 37328 37418 +90 =======================================
+ Hits 34881 34966 +85 - Misses 2447 2452 +5

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

The underlying normalizeHeaders bug was fixed in nodejs#5536, which covers the flat-header handling with unit tests. These integration tests exercise the path the bug was actually reported through - a dns interceptor re-dispatch landing in a composed cache() (and deduplicate(), which shares the same cache-key utility) - so the compose-chain scenario stays covered end to end.

mcollina · 2026-07-09T08:47:08Z

Description

The cache interceptor's normalizeHeaders function only handled two header
formats:

Array-of-pairs: [['key', 'val'], ...]
Object: { key: 'val', ... }

However, undici internally uses flat alternating arrays:
['key', 'val', 'key', 'val', ...]. When the cache() interceptor is placed
before dns() in a compose chain (e.g., new Agent().compose(cache(), dns())),
the DNS interceptor converts headers to flat format before passing them to
the cache interceptor, causing normalizeHeaders to throw
'opts.headers is not a valid header map'.

Reproduction

import{Agent,interceptors,request}from"undici";const{ cache, dns }=interceptors;constcacheThenDns=newAgent().compose(cache(),dns());consturl="https://www.google.com";constheaders=[];constr=awaitrequest(url,{dispatcher: cacheThenDns, headers });

Fixes#5522

The cache interceptor's normalizeHeaders function only handled two header formats: array-of-pairs ([[key, val], ...]) and plain objects ({ key: val, ...}). However, undici internally uses flat alternating arrays ([key, val, key, val, ...]). When the cache() interceptor is placed before dns() in a compose chain, the DNS interceptor converts headers to flat alternating format before passing them to the cache interceptor, causing normalizeHeaders to throw 'opts.headers is not a valid header map'. Fixes#5522

codecov-commenter · 2026-07-09T09:06:04Z

Codecov Report

❌ Patch coverage is 83.67347% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.44%. Comparing base (cb4c2f1) to head (c16c29d).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/util/cache.js	83.67%	8 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #5536 +/- ##
=======================================
Coverage 93.44% 93.44% =======================================
Files 110 110 Lines 37328 37418 +90 =======================================
+ Hits 34881 34966 +85 - Misses 2447 2452 +5

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

The underlying normalizeHeaders bug was fixed in nodejs#5536, which covers the flat-header handling with unit tests. These integration tests exercise the path the bug was actually reported through - a dns interceptor re-dispatch landing in a composed cache() (and deduplicate(), which shares the same cache-key utility) - so the compose-chain scenario stays covered end to end.

mcollina · 2026-07-09T08:47:08Z

Description

The cache interceptor's normalizeHeaders function only handled two header
formats:

Array-of-pairs: [['key', 'val'], ...]
Object: { key: 'val', ... }

However, undici internally uses flat alternating arrays:
['key', 'val', 'key', 'val', ...]. When the cache() interceptor is placed
before dns() in a compose chain (e.g., new Agent().compose(cache(), dns())),
the DNS interceptor converts headers to flat format before passing them to
the cache interceptor, causing normalizeHeaders to throw
'opts.headers is not a valid header map'.

Reproduction

import{Agent,interceptors,request}from"undici";const{ cache, dns }=interceptors;constcacheThenDns=newAgent().compose(cache(),dns());consturl="https://www.google.com";constheaders=[];constr=awaitrequest(url,{dispatcher: cacheThenDns, headers });

Fixes#5522

The cache interceptor's normalizeHeaders function only handled two header formats: array-of-pairs ([[key, val], ...]) and plain objects ({ key: val, ...}). However, undici internally uses flat alternating arrays ([key, val, key, val, ...]). When the cache() interceptor is placed before dns() in a compose chain, the DNS interceptor converts headers to flat alternating format before passing them to the cache interceptor, causing normalizeHeaders to throw 'opts.headers is not a valid header map'. Fixes#5522

codecov-commenter · 2026-07-09T09:06:04Z

Codecov Report

❌ Patch coverage is 83.67347% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.44%. Comparing base (cb4c2f1) to head (c16c29d).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/util/cache.js	83.67%	8 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #5536 +/- ##
=======================================
Coverage 93.44% 93.44% =======================================
Files 110 110 Lines 37328 37418 +90 =======================================
+ Hits 34881 34966 +85 - Misses 2447 2452 +5

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

The underlying normalizeHeaders bug was fixed in nodejs#5536, which covers the flat-header handling with unit tests. These integration tests exercise the path the bug was actually reported through - a dns interceptor re-dispatch landing in a composed cache() (and deduplicate(), which shares the same cache-key utility) - so the compose-chain scenario stays covered end to end.

mcollina · 2026-07-09T08:47:08Z

Description

The cache interceptor's normalizeHeaders function only handled two header
formats:

Array-of-pairs: [['key', 'val'], ...]
Object: { key: 'val', ... }

However, undici internally uses flat alternating arrays:
['key', 'val', 'key', 'val', ...]. When the cache() interceptor is placed
before dns() in a compose chain (e.g., new Agent().compose(cache(), dns())),
the DNS interceptor converts headers to flat format before passing them to
the cache interceptor, causing normalizeHeaders to throw
'opts.headers is not a valid header map'.

Reproduction

import{Agent,interceptors,request}from"undici";const{ cache, dns }=interceptors;constcacheThenDns=newAgent().compose(cache(),dns());consturl="https://www.google.com";constheaders=[];constr=awaitrequest(url,{dispatcher: cacheThenDns, headers });

Fixes#5522

The cache interceptor's normalizeHeaders function only handled two header formats: array-of-pairs ([[key, val], ...]) and plain objects ({ key: val, ...}). However, undici internally uses flat alternating arrays ([key, val, key, val, ...]). When the cache() interceptor is placed before dns() in a compose chain, the DNS interceptor converts headers to flat alternating format before passing them to the cache interceptor, causing normalizeHeaders to throw 'opts.headers is not a valid header map'. Fixes#5522

codecov-commenter · 2026-07-09T09:06:04Z

Codecov Report

❌ Patch coverage is 83.67347% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.44%. Comparing base (cb4c2f1) to head (c16c29d).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/util/cache.js	83.67%	8 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #5536 +/- ##
=======================================
Coverage 93.44% 93.44% =======================================
Files 110 110 Lines 37328 37418 +90 =======================================
+ Hits 34881 34966 +85 - Misses 2447 2452 +5

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

The underlying normalizeHeaders bug was fixed in nodejs#5536, which covers the flat-header handling with unit tests. These integration tests exercise the path the bug was actually reported through - a dns interceptor re-dispatch landing in a composed cache() (and deduplicate(), which shares the same cache-key utility) - so the compose-chain scenario stays covered end to end.

mcollina · 2026-07-09T08:47:08Z

Description

The cache interceptor's normalizeHeaders function only handled two header
formats:

Array-of-pairs: [['key', 'val'], ...]
Object: { key: 'val', ... }

However, undici internally uses flat alternating arrays:
['key', 'val', 'key', 'val', ...]. When the cache() interceptor is placed
before dns() in a compose chain (e.g., new Agent().compose(cache(), dns())),
the DNS interceptor converts headers to flat format before passing them to
the cache interceptor, causing normalizeHeaders to throw
'opts.headers is not a valid header map'.

Reproduction

import{Agent,interceptors,request}from"undici";const{ cache, dns }=interceptors;constcacheThenDns=newAgent().compose(cache(),dns());consturl="https://www.google.com";constheaders=[];constr=awaitrequest(url,{dispatcher: cacheThenDns, headers });

Fixes#5522

The cache interceptor's normalizeHeaders function only handled two header formats: array-of-pairs ([[key, val], ...]) and plain objects ({ key: val, ...}). However, undici internally uses flat alternating arrays ([key, val, key, val, ...]). When the cache() interceptor is placed before dns() in a compose chain, the DNS interceptor converts headers to flat alternating format before passing them to the cache interceptor, causing normalizeHeaders to throw 'opts.headers is not a valid header map'. Fixes#5522

codecov-commenter · 2026-07-09T09:06:04Z

Codecov Report

❌ Patch coverage is 83.67347% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.44%. Comparing base (cb4c2f1) to head (c16c29d).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/util/cache.js	83.67%	8 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #5536 +/- ##
=======================================
Coverage 93.44% 93.44% =======================================
Files 110 110 Lines 37328 37418 +90 =======================================
+ Hits 34881 34966 +85 - Misses 2447 2452 +5

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

The underlying normalizeHeaders bug was fixed in nodejs#5536, which covers the flat-header handling with unit tests. These integration tests exercise the path the bug was actually reported through - a dns interceptor re-dispatch landing in a composed cache() (and deduplicate(), which shares the same cache-key utility) - so the compose-chain scenario stays covered end to end.

mcollina · 2026-07-09T08:47:08Z

Description

The cache interceptor's normalizeHeaders function only handled two header
formats:

Array-of-pairs: [['key', 'val'], ...]
Object: { key: 'val', ... }

However, undici internally uses flat alternating arrays:
['key', 'val', 'key', 'val', ...]. When the cache() interceptor is placed
before dns() in a compose chain (e.g., new Agent().compose(cache(), dns())),
the DNS interceptor converts headers to flat format before passing them to
the cache interceptor, causing normalizeHeaders to throw
'opts.headers is not a valid header map'.

Reproduction

import{Agent,interceptors,request}from"undici";const{ cache, dns }=interceptors;constcacheThenDns=newAgent().compose(cache(),dns());consturl="https://www.google.com";constheaders=[];constr=awaitrequest(url,{dispatcher: cacheThenDns, headers });

Fixes#5522

The cache interceptor's normalizeHeaders function only handled two header formats: array-of-pairs ([[key, val], ...]) and plain objects ({ key: val, ...}). However, undici internally uses flat alternating arrays ([key, val, key, val, ...]). When the cache() interceptor is placed before dns() in a compose chain, the DNS interceptor converts headers to flat alternating format before passing them to the cache interceptor, causing normalizeHeaders to throw 'opts.headers is not a valid header map'. Fixes#5522

codecov-commenter · 2026-07-09T09:06:04Z

Codecov Report

❌ Patch coverage is 83.67347% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.44%. Comparing base (cb4c2f1) to head (c16c29d).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/util/cache.js	83.67%	8 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #5536 +/- ##
=======================================
Coverage 93.44% 93.44% =======================================
Files 110 110 Lines 37328 37418 +90 =======================================
+ Hits 34881 34966 +85 - Misses 2447 2452 +5

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

The underlying normalizeHeaders bug was fixed in nodejs#5536, which covers the flat-header handling with unit tests. These integration tests exercise the path the bug was actually reported through - a dns interceptor re-dispatch landing in a composed cache() (and deduplicate(), which shares the same cache-key utility) - so the compose-chain scenario stays covered end to end.

mcollina · 2026-07-09T08:47:08Z

Description

The cache interceptor's normalizeHeaders function only handled two header
formats:

Array-of-pairs: [['key', 'val'], ...]
Object: { key: 'val', ... }

However, undici internally uses flat alternating arrays:
['key', 'val', 'key', 'val', ...]. When the cache() interceptor is placed
before dns() in a compose chain (e.g., new Agent().compose(cache(), dns())),
the DNS interceptor converts headers to flat format before passing them to
the cache interceptor, causing normalizeHeaders to throw
'opts.headers is not a valid header map'.

Reproduction

import{Agent,interceptors,request}from"undici";const{ cache, dns }=interceptors;constcacheThenDns=newAgent().compose(cache(),dns());consturl="https://www.google.com";constheaders=[];constr=awaitrequest(url,{dispatcher: cacheThenDns, headers });

Fixes#5522

The cache interceptor's normalizeHeaders function only handled two header formats: array-of-pairs ([[key, val], ...]) and plain objects ({ key: val, ...}). However, undici internally uses flat alternating arrays ([key, val, key, val, ...]). When the cache() interceptor is placed before dns() in a compose chain, the DNS interceptor converts headers to flat alternating format before passing them to the cache interceptor, causing normalizeHeaders to throw 'opts.headers is not a valid header map'. Fixes#5522

codecov-commenter · 2026-07-09T09:06:04Z

Codecov Report

❌ Patch coverage is 83.67347% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.44%. Comparing base (cb4c2f1) to head (c16c29d).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/util/cache.js	83.67%	8 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #5536 +/- ##
=======================================
Coverage 93.44% 93.44% =======================================
Files 110 110 Lines 37328 37418 +90 =======================================
+ Hits 34881 34966 +85 - Misses 2447 2452 +5

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

The underlying normalizeHeaders bug was fixed in nodejs#5536, which covers the flat-header handling with unit tests. These integration tests exercise the path the bug was actually reported through - a dns interceptor re-dispatch landing in a composed cache() (and deduplicate(), which shares the same cache-key utility) - so the compose-chain scenario stays covered end to end.

ronag approved these changes Jul 9, 2026
View reviewed changes

mcollina added 2 commits July 9, 2026 09:24

test: add normalizeHeaders tests for flat alternating header arrays
db1be8f

refactor: replace .map() with for loop in normalizeHeaders
c16c29d

ronag approved these changes Jul 10, 2026
View reviewed changes

mcollina merged commit d65a9f9 into mainJul 11, 2026
36 checks passed

mcollina deleted the fix-cache-normalize-headers-flat-array branch July 11, 2026 15:38

GiHoon1123 mentioned this pull request Jul 12, 2026
test: add cache/dedupe + dns re-dispatch integration tests #5535
Merged

github-actionsBot mentioned this pull request Jul 20, 2026
[Release] v8.8.0 #5575
Merged