From d14f709bff336ebd807befa79e44ee941567d08b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guilherme=20Ara=C3=BAjo?= Date: Tue, 3 Nov 2026 20:00:23 -0300 Subject: [PATCH 1/3] http: cache header validation in setHeader() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Assisted-by: Claude --- benchmark/http/set-header-rest.js | 50 +++++++++++++ lib/internal/http/outgoing.js | 73 ++++++++++++++----- .../test-http-set-header-validation-cache.js | 38 ++++++++++ 3 files changed, 143 insertions(+), 18 deletions(-) create mode 100644 benchmark/http/set-header-rest.js create mode 100644 test/parallel/test-http-set-header-validation-cache.js diff --git a/benchmark/http/set-header-rest.js b/benchmark/http/set-header-rest.js new file mode 100644 index 000000000000..ca8b9b3691c9 --- /dev/null +++ b/benchmark/http/set-header-rest.js @@ -0,0 +1,50 @@ +'use strict'; + +const common = require('../common.js'); +const http = require('http'); + +const bench = common.createBenchmark(main, { + headers: [2, 12], + values: ['static', 'dynamic'], + duration: 5, +}); + +const restHeaders = [ + ['Content-Type', 'application/json; charset=utf-8'], + ['Cache-Control', 'no-store'], + ['X-Content-Type-Options', 'nosniff'], + ['X-Frame-Options', 'DENY'], + ['Strict-Transport-Security', 'max-age=31536000; includeSubDomains'], + ['Access-Control-Allow-Origin', '*'], + ['Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE'], + ['Vary', 'Origin, Accept-Encoding'], + ['X-RateLimit-Limit', '1000'], + ['X-RateLimit-Remaining', '999'], + ['ETag', 'W/"2a-abc"'], + ['X-Request-Id', '00000000'], +]; + +function main({ headers, values, duration }) { + const list = restHeaders.slice(0, headers); + const body = '{"ok":true}'; + let id = 0; + + const server = http.createServer((req, res) => { + for (const { 0: name, 1: value } of list) { + res.setHeader(name, values === 'dynamic' ? `${value}-${id}` : value); + } + id++; + res.end(body); + }); + + server.listen(0, () => { + bench.http({ + path: '/', + connections: 100, + duration, + port: server.address().port, + }, () => { + server.close(); + }); + }); +} diff --git a/lib/internal/http/outgoing.js b/lib/internal/http/outgoing.js index c328ed2b06c5..51e078cec757 100644 --- a/lib/internal/http/outgoing.js +++ b/lib/internal/http/outgoing.js @@ -29,6 +29,7 @@ const { ObjectKeys, ObjectSetPrototypeOf, ObjectValues, + SafeMap, SafeSet, Symbol, } = primordials; @@ -760,6 +761,54 @@ const validateHeaderName = assignFunctionName('validateHeaderName', hideStackFra } })); +// Only strings are cached: arrays are mutable and must be re-validated. +const kMaxCachedHeaderNames = 256; +const kMaxCachedHeaderValueLength = 256; +const validatedHeaders = new SafeMap(); + +class ValidatedHeader { + constructor(name) { + this.lowerCaseName = name.toLowerCase(); + this.lastStrictValue = undefined; + this.lastLenientValue = undefined; + } +} + +function validateHeaderNameCached(name) { + let header = validatedHeaders.get(name); + if (header !== undefined) return header; + + if (!isValidHeaderName(name)) { + throw new ERR_INVALID_HTTP_TOKEN.HideStackFramesError('Header name', name); + } + header = new ValidatedHeader(name); + if (validatedHeaders.size < kMaxCachedHeaderNames) { + validatedHeaders.set(name, header); + } + return header; +} + +function validateHeaderValueCached(msg, header, name, value) { + if (value === undefined) { + throw new ERR_HTTP_INVALID_HEADER_VALUE(value, name); + } + const lenient = msg._isLenientHeaderValidation(); + const lastValid = lenient ? header.lastLenientValue : header.lastStrictValue; + if (value === lastValid) return; + + if (checkInvalidHeaderChar(value, lenient)) { + debug('Header "%s" contains invalid characters', name); + throw new ERR_INVALID_CHAR('header content', name); + } + if (typeof value !== 'string' || value.length > kMaxCachedHeaderValueLength) return; + + if (lenient) { + header.lastLenientValue = value; + } else { + header.lastStrictValue = value; + } +} + /** * Non-throwing counterpart of `validateHeaderName()`. * @param {any} name @@ -822,14 +871,8 @@ OutgoingMessage.prototype.setHeader = function setHeader(name, value) { if (this._header) { throw new ERR_HTTP_HEADERS_SENT('set'); } - validateHeaderName(name); - if (value === undefined) { - throw new ERR_HTTP_INVALID_HEADER_VALUE(value, name); - } - if (checkInvalidHeaderChar(value, this._isLenientHeaderValidation())) { - debug('Header "%s" contains invalid characters', name); - throw new ERR_INVALID_CHAR('header content', name); - } + const header = validateHeaderNameCached(name); + validateHeaderValueCached(this, header, name, value); let headers = this[kOutHeaders]; if (headers === null) @@ -837,7 +880,7 @@ OutgoingMessage.prototype.setHeader = function setHeader(name, value) { // Store a copy of an array value. appendHeader() pushes into the stored // array, which must not be the caller's (it may also be frozen). - headers[name.toLowerCase()] = [ + headers[header.lowerCaseName] = [ name, ArrayIsArray(value) ? value.slice() : value, ]; @@ -891,16 +934,10 @@ OutgoingMessage.prototype.appendHeader = function appendHeader(name, value) { if (this._header) { throw new ERR_HTTP_HEADERS_SENT('append'); } - validateHeaderName(name); - if (value === undefined) { - throw new ERR_HTTP_INVALID_HEADER_VALUE(value, name); - } - if (checkInvalidHeaderChar(value, this._isLenientHeaderValidation())) { - debug('Header "%s" contains invalid characters', name); - throw new ERR_INVALID_CHAR('header content', name); - } + const header = validateHeaderNameCached(name); + validateHeaderValueCached(this, header, name, value); + const field = header.lowerCaseName; - const field = name.toLowerCase(); const headers = this[kOutHeaders]; if (headers === null || !headers[field]) { return this.setHeader(name, value); diff --git a/test/parallel/test-http-set-header-validation-cache.js b/test/parallel/test-http-set-header-validation-cache.js new file mode 100644 index 000000000000..c56bad3a1242 --- /dev/null +++ b/test/parallel/test-http-set-header-validation-cache.js @@ -0,0 +1,38 @@ +'use strict'; + +const common = require('../common'); +const assert = require('assert'); +const http = require('http'); + +const server = http.createServer(common.mustCall((req, res) => { + res.setHeader('Content-Type', 'application/json; charset=utf-8'); + res.setHeader('X-Test', 'valid-value'); + res.setHeader('Content-Type', 'application/json; charset=utf-8'); + res.setHeader('X-Test', 'valid-value'); + + assert.throws(() => { + res.setHeader('X-Test', 'bad\u0007value'); + }, { code: 'ERR_INVALID_CHAR' }); + + const cookies = ['a=1', 'b=2']; + res.setHeader('Set-Cookie', cookies); + cookies[1] = 'bad\r\nvalue'; + assert.throws(() => { + res.setHeader('Set-Cookie', cookies); + }, { code: 'ERR_INVALID_CHAR' }); + res.setHeader('Set-Cookie', 'ok=1'); + + assert.throws(() => { + res.setHeader('Bad Header', 'v'); + }, { code: 'ERR_INVALID_HTTP_TOKEN' }); + + res.end('ok'); +})); + +server.listen(0, common.mustCall(() => { + http.get({ port: server.address().port }, common.mustCall((res) => { + assert.strictEqual(res.statusCode, 200); + res.resume(); + res.on('end', common.mustCall(() => server.close())); + })); +})); From bc9874bd66e55642b111d89c520ed3c1f362c191 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guilherme=20Ara=C3=BAjo?= Date: Tue, 17 Nov 2026 22:15:40 -0300 Subject: [PATCH 2/3] http: add eviction to header name cache MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- benchmark/http/set-header-rest.js | 15 +++++++++-- lib/internal/http/outgoing.js | 25 +++++++++++++------ .../test-http-set-header-validation-cache.js | 15 +++++++++++ 3 files changed, 45 insertions(+), 10 deletions(-) diff --git a/benchmark/http/set-header-rest.js b/benchmark/http/set-header-rest.js index ca8b9b3691c9..ff94eebd615b 100644 --- a/benchmark/http/set-header-rest.js +++ b/benchmark/http/set-header-rest.js @@ -6,9 +6,16 @@ const http = require('http'); const bench = common.createBenchmark(main, { headers: [2, 12], values: ['static', 'dynamic'], + // 'many' rotates through more unique names than the validation cache holds. + names: ['fixed', 'many'], duration: 5, }); +const manyNames = []; +for (let i = 0; i < 1024; i++) { + manyNames.push(`X-Custom-Header-${i}`); +} + const restHeaders = [ ['Content-Type', 'application/json; charset=utf-8'], ['Cache-Control', 'no-store'], @@ -24,14 +31,18 @@ const restHeaders = [ ['X-Request-Id', '00000000'], ]; -function main({ headers, values, duration }) { +function main({ headers, values, names, duration }) { const list = restHeaders.slice(0, headers); const body = '{"ok":true}'; let id = 0; + let next = 0; const server = http.createServer((req, res) => { for (const { 0: name, 1: value } of list) { - res.setHeader(name, values === 'dynamic' ? `${value}-${id}` : value); + res.setHeader( + names === 'many' ? manyNames[next++ % manyNames.length] : name, + values === 'dynamic' ? `${value}-${id}` : value, + ); } id++; res.end(body); diff --git a/lib/internal/http/outgoing.js b/lib/internal/http/outgoing.js index 51e078cec757..34adfb4636cd 100644 --- a/lib/internal/http/outgoing.js +++ b/lib/internal/http/outgoing.js @@ -764,7 +764,11 @@ const validateHeaderName = assignFunctionName('validateHeaderName', hideStackFra // Only strings are cached: arrays are mutable and must be re-validated. const kMaxCachedHeaderNames = 256; const kMaxCachedHeaderValueLength = 256; -const validatedHeaders = new SafeMap(); +// Two-generation approximate LRU: when the current generation fills up it +// becomes the previous one and the old previous one is dropped. Names used +// since the last rotation survive it. A hit costs one Map lookup. +let validatedHeaders = new SafeMap(); +let previousValidatedHeaders = new SafeMap(); class ValidatedHeader { constructor(name) { @@ -774,19 +778,24 @@ class ValidatedHeader { } } -function validateHeaderNameCached(name) { +const validateHeaderNameCached = hideStackFrames((name) => { let header = validatedHeaders.get(name); if (header !== undefined) return header; - if (!isValidHeaderName(name)) { - throw new ERR_INVALID_HTTP_TOKEN.HideStackFramesError('Header name', name); + header = previousValidatedHeaders.get(name); + if (header === undefined) { + if (!isValidHeaderName(name)) { + throw new ERR_INVALID_HTTP_TOKEN.HideStackFramesError('Header name', name); + } + header = new ValidatedHeader(name); } - header = new ValidatedHeader(name); - if (validatedHeaders.size < kMaxCachedHeaderNames) { - validatedHeaders.set(name, header); + if (validatedHeaders.size >= kMaxCachedHeaderNames) { + previousValidatedHeaders = validatedHeaders; + validatedHeaders = new SafeMap(); } + validatedHeaders.set(name, header); return header; -} +}); function validateHeaderValueCached(msg, header, name, value) { if (value === undefined) { diff --git a/test/parallel/test-http-set-header-validation-cache.js b/test/parallel/test-http-set-header-validation-cache.js index c56bad3a1242..4b2468d78bad 100644 --- a/test/parallel/test-http-set-header-validation-cache.js +++ b/test/parallel/test-http-set-header-validation-cache.js @@ -4,6 +4,21 @@ const common = require('../common'); const assert = require('assert'); const http = require('http'); +{ + // Rotate the name cache through several generations. + const msg = new http.OutgoingMessage(); + for (let i = 0; i < 1000; i++) { + msg.setHeader(`X-Many-${i}`, 'v'); + } + msg.setHeader('X-Many-0', 'evicted'); + msg.setHeader('X-Many-999', 'cached'); + assert.strictEqual(msg.getHeader('x-many-0'), 'evicted'); + assert.strictEqual(msg.getHeader('x-many-999'), 'cached'); + assert.throws(() => { + msg.setHeader('Bad Header', 'v'); + }, { code: 'ERR_INVALID_HTTP_TOKEN' }); +} + const server = http.createServer(common.mustCall((req, res) => { res.setHeader('Content-Type', 'application/json; charset=utf-8'); res.setHeader('X-Test', 'valid-value'); From a0bc32d320658b7f006812431e9dd219b5e481d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guilherme=20Ara=C3=BAjo?= Date: Tue, 17 Nov 2026 22:15:40 -0300 Subject: [PATCH 3/3] http: sample header name cache admissions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cache only one in eight new names, so most misses skip the allocation and insertion. Assisted-by: Claude Signed-off-by: Guilherme Araújo --- lib/internal/http/outgoing.js | 22 ++++++++++++++----- .../test-http-set-header-validation-cache.js | 12 +++++++--- 2 files changed, 26 insertions(+), 8 deletions(-) diff --git a/lib/internal/http/outgoing.js b/lib/internal/http/outgoing.js index 34adfb4636cd..fe478b0635df 100644 --- a/lib/internal/http/outgoing.js +++ b/lib/internal/http/outgoing.js @@ -764,11 +764,15 @@ const validateHeaderName = assignFunctionName('validateHeaderName', hideStackFra // Only strings are cached: arrays are mutable and must be re-validated. const kMaxCachedHeaderNames = 256; const kMaxCachedHeaderValueLength = 256; +// Admit one in eight unseen names, so one-off names do not churn the cache +// and a miss usually costs no allocation or insertion. +const kHeaderAdmissionMask = 7; // Two-generation approximate LRU: when the current generation fills up it // becomes the previous one and the old previous one is dropped. Names used // since the last rotation survive it. A hit costs one Map lookup. let validatedHeaders = new SafeMap(); let previousValidatedHeaders = new SafeMap(); +let headerAdmissionCounter = 0; class ValidatedHeader { constructor(name) { @@ -778,6 +782,7 @@ class ValidatedHeader { } } +// Returns undefined for a valid name that was not admitted to the cache. const validateHeaderNameCached = hideStackFrames((name) => { let header = validatedHeaders.get(name); if (header !== undefined) return header; @@ -787,6 +792,8 @@ const validateHeaderNameCached = hideStackFrames((name) => { if (!isValidHeaderName(name)) { throw new ERR_INVALID_HTTP_TOKEN.HideStackFramesError('Header name', name); } + headerAdmissionCounter = (headerAdmissionCounter + 1) & kHeaderAdmissionMask; + if (headerAdmissionCounter !== 0) return undefined; header = new ValidatedHeader(name); } if (validatedHeaders.size >= kMaxCachedHeaderNames) { @@ -802,14 +809,19 @@ function validateHeaderValueCached(msg, header, name, value) { throw new ERR_HTTP_INVALID_HEADER_VALUE(value, name); } const lenient = msg._isLenientHeaderValidation(); - const lastValid = lenient ? header.lastLenientValue : header.lastStrictValue; - if (value === lastValid) return; + if (header !== undefined && + value === (lenient ? header.lastLenientValue : header.lastStrictValue)) { + return; + } if (checkInvalidHeaderChar(value, lenient)) { debug('Header "%s" contains invalid characters', name); throw new ERR_INVALID_CHAR('header content', name); } - if (typeof value !== 'string' || value.length > kMaxCachedHeaderValueLength) return; + if (header === undefined || typeof value !== 'string' || + value.length > kMaxCachedHeaderValueLength) { + return; + } if (lenient) { header.lastLenientValue = value; @@ -889,7 +901,7 @@ OutgoingMessage.prototype.setHeader = function setHeader(name, value) { // Store a copy of an array value. appendHeader() pushes into the stored // array, which must not be the caller's (it may also be frozen). - headers[header.lowerCaseName] = [ + headers[header !== undefined ? header.lowerCaseName : name.toLowerCase()] = [ name, ArrayIsArray(value) ? value.slice() : value, ]; @@ -945,7 +957,7 @@ OutgoingMessage.prototype.appendHeader = function appendHeader(name, value) { } const header = validateHeaderNameCached(name); validateHeaderValueCached(this, header, name, value); - const field = header.lowerCaseName; + const field = header !== undefined ? header.lowerCaseName : name.toLowerCase(); const headers = this[kOutHeaders]; if (headers === null || !headers[field]) { diff --git a/test/parallel/test-http-set-header-validation-cache.js b/test/parallel/test-http-set-header-validation-cache.js index 4b2468d78bad..2142420232cd 100644 --- a/test/parallel/test-http-set-header-validation-cache.js +++ b/test/parallel/test-http-set-header-validation-cache.js @@ -7,13 +7,19 @@ const http = require('http'); { // Rotate the name cache through several generations. const msg = new http.OutgoingMessage(); - for (let i = 0; i < 1000; i++) { + for (let i = 0; i < 5000; i++) { msg.setHeader(`X-Many-${i}`, 'v'); } msg.setHeader('X-Many-0', 'evicted'); - msg.setHeader('X-Many-999', 'cached'); + msg.setHeader('X-Many-4999', 'cached'); assert.strictEqual(msg.getHeader('x-many-0'), 'evicted'); - assert.strictEqual(msg.getHeader('x-many-999'), 'cached'); + assert.strictEqual(msg.getHeader('x-many-4999'), 'cached'); + // Names that were not admitted to the cache still validate values. + for (let i = 0; i < 8; i++) { + assert.throws(() => { + msg.setHeader(`X-Uncached-${i}`, 'bad\u0007value'); + }, { code: 'ERR_INVALID_CHAR' }); + } assert.throws(() => { msg.setHeader('Bad Header', 'v'); }, { code: 'ERR_INVALID_HTTP_TOKEN' });