From a58e60553636b36a39c9825d4aaafc1bdde38358 Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Sun, 27 Sep 2026 02:18:02 +0000
Subject: [PATCH 1/2] http: add isValidHeaderName() and isValidHeaderValue()

Add non-throwing counterparts of http.validateHeaderName() and
http.validateHeaderValue() that return a boolean instead of throwing.

Rejecting an invalid header with the existing validators costs a few
microseconds, because an error object and its stack trace are created,
compared to ~20ns for the boolean check. Userland HTTP implementations
such as undici (fetch Headers, request options) therefore keep private
copies of the token and field-value tables from _http_common. These new
functions let them reuse the core implementation.

isValidHeaderValue() accepts an optional `httpValidation` option
('strict' or 'relaxed') that has the same meaning as the option of the
same name on http.createServer() and http.request().

Signed-off-by: James M Snell <jasnell@gmail.com>
---
 doc/api/http.md                            |  86 +++++++++++
 lib/_http_outgoing.js                      |  44 +++++-
 lib/http.js                                |   4 +
 test/parallel/test-http-is-valid-header.js | 168 +++++++++++++++++++++
 4 files changed, 300 insertions(+), 2 deletions(-)
 create mode 100644 test/parallel/test-http-is-valid-header.js

diff --git a/doc/api/http.md b/doc/api/http.md
index c4888f2bf660..5351b05eeaa9 100644
--- a/doc/api/http.md
+++ b/doc/api/http.md
@@ -4403,6 +4403,89 @@ request. Specifically, the `'error'` event will be emitted with an error with
 the message `'AbortError: The operation was aborted'`, the code `'ABORT_ERR'`
 and the `cause`, if one was provided.
 
+## `http.isValidHeaderName(name)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `name` {any}
+* Returns: {boolean}
+
+Returns `true` if `name` is a valid HTTP header name (a non-empty string that
+is an HTTP [token][]), and `false` otherwise. This is the same check that
+[`http.validateHeaderName()`][] performs, but the result is returned instead of
+an error being thrown, so it is suitable for use in hot paths where invalid
+input is expected.
+
+HTTP methods are also tokens, so this function can validate them as well.
+
+```mjs
+import { isValidHeaderName } from 'node:http';
+
+console.log(isValidHeaderName('content-type')); // true
+console.log(isValidHeaderName('X-Request-Id')); // true
+console.log(isValidHeaderName('')); // false
+console.log(isValidHeaderName('bad header')); // false
+console.log(isValidHeaderName(42)); // false
+```
+
+```cjs
+const { isValidHeaderName } = require('node:http');
+
+console.log(isValidHeaderName('content-type')); // true
+console.log(isValidHeaderName('X-Request-Id')); // true
+console.log(isValidHeaderName('')); // false
+console.log(isValidHeaderName('bad header')); // false
+console.log(isValidHeaderName(42)); // false
+```
+
+## `http.isValidHeaderValue(value[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `value` {any}
+* `options` {Object}
+  * `httpValidation` {string} Validation strictness, one of `'strict'` or
+    `'relaxed'`. These have the same meaning as the `httpValidation` option of
+    [`http.createServer()`][] and [`http.request()`][]. **Default:** `'strict'`.
+* Returns: {boolean}
+
+Returns `true` if `value` is a valid HTTP header value, and `false` otherwise.
+With the default options this is the same check that
+[`http.validateHeaderValue()`][] performs, but the result is returned instead
+of an error being thrown.
+
+`undefined` and symbols are never valid header values. Other non-string
+values are converted to strings before being checked, as they are when passed
+to [`outgoingMessage.setHeader(name, value)`][].
+
+Passing an invalid `options` argument throws.
+
+```mjs
+import { isValidHeaderValue } from 'node:http';
+
+console.log(isValidHeaderValue('text/html')); // true
+console.log(isValidHeaderValue(123)); // true
+console.log(isValidHeaderValue(undefined)); // false
+console.log(isValidHeaderValue('a\r\nb')); // false
+console.log(isValidHeaderValue('a\x01b')); // false
+console.log(isValidHeaderValue('a\x01b', { httpValidation: 'relaxed' })); // true
+```
+
+```cjs
+const { isValidHeaderValue } = require('node:http');
+
+console.log(isValidHeaderValue('text/html')); // true
+console.log(isValidHeaderValue(123)); // true
+console.log(isValidHeaderValue(undefined)); // false
+console.log(isValidHeaderValue('a\r\nb')); // false
+console.log(isValidHeaderValue('a\x01b')); // false
+console.log(isValidHeaderValue('a\x01b', { httpValidation: 'relaxed' })); // true
+```
+
 ## `http.validateHeaderName(name[, label])`
 
 <!-- YAML
@@ -4795,6 +4878,8 @@ const agent2 = new http.Agent({ proxyEnv: process.env });
 [`http.globalAgent`]: #httpglobalagent
 [`http.request()`]: #httprequestoptions-callback
 [`http.setGlobalProxyFromEnv()`]: #httpsetglobalproxyfromenvproxyenv
+[`http.validateHeaderName()`]: #httpvalidateheadernamename-label
+[`http.validateHeaderValue()`]: #httpvalidateheadervaluename-value
 [`message.headers`]: #messageheaders
 [`message.rawHeaders`]: #messagerawheaders
 [`message.socket`]: #messagesocket
@@ -4857,3 +4942,4 @@ const agent2 = new http.Agent({ proxyEnv: process.env });
 [information event]: #event-information
 [initial delay]: net.md#socketsetkeepaliveenable-initialdelay-interval-count
 [request target]: https://datatracker.ietf.org/doc/html/rfc9112#section-3.2
+[token]: https://datatracker.ietf.org/doc/html/rfc9110#section-5.6.2
diff --git a/lib/_http_outgoing.js b/lib/_http_outgoing.js
index 0b728f6ae4d4..f6713d7b06a4 100644
--- a/lib/_http_outgoing.js
+++ b/lib/_http_outgoing.js
@@ -71,7 +71,11 @@ const {
   },
   hideStackFrames,
 } = require('internal/errors');
-const { validateString } = require('internal/validators');
+const {
+  validateObject,
+  validateOneOf,
+  validateString,
+} = require('internal/validators');
 const {
   assignFunctionName,
   deprecateInstantiation,
@@ -723,11 +727,45 @@ function matchHeader(self, state, field, value) {
 }
 
 const validateHeaderName = assignFunctionName('validateHeaderName', hideStackFrames((name, label) => {
-  if (typeof name !== 'string' || !name || !checkIsHttpToken(name)) {
+  if (!isValidHeaderName(name)) {
     throw new ERR_INVALID_HTTP_TOKEN.HideStackFramesError(label || 'Header name', name);
   }
 }));
 
+/**
+ * Non-throwing counterpart of `validateHeaderName()`.
+ * @param {any} name
+ * @returns {boolean}
+ */
+function isValidHeaderName(name) {
+  return typeof name === 'string' && checkIsHttpToken(name);
+}
+
+const kHttpValidationValues = ['strict', 'relaxed'];
+
+/**
+ * Non-throwing counterpart of `validateHeaderValue()`.
+ * @param {any} value
+ * @param {{ httpValidation?: 'strict' | 'relaxed' }} [options]
+ * @returns {boolean}
+ */
+function isValidHeaderValue(value, options) {
+  let lenient = false;
+  if (options !== undefined) {
+    validateObject(options, 'options');
+    const { httpValidation } = options;
+    if (httpValidation === 'relaxed') {
+      lenient = true;
+    } else if (httpValidation !== undefined && httpValidation !== 'strict') {
+      validateOneOf(httpValidation, 'options.httpValidation', kHttpValidationValues);
+    }
+  }
+  if (value === undefined || typeof value === 'symbol') {
+    return false;
+  }
+  return !checkInvalidHeaderChar(value, lenient);
+}
+
 const validateHeaderValue = assignFunctionName('validateHeaderValue', hideStackFrames((name, value, lenient) => {
   if (value === undefined) {
     throw new ERR_HTTP_INVALID_HEADER_VALUE.HideStackFramesError(value, name);
@@ -1424,6 +1462,8 @@ module.exports = {
   kHighWaterMark,
   kUniqueHeaders,
   parseUniqueHeadersOption,
+  isValidHeaderName,
+  isValidHeaderValue,
   validateHeaderName,
   validateHeaderValue,
   OutgoingMessage,
diff --git a/lib/http.js b/lib/http.js
index 934d0b14bfdc..783366e9fac4 100644
--- a/lib/http.js
+++ b/lib/http.js
@@ -32,6 +32,8 @@ const { methods, parsers } = require('_http_common');
 const { IncomingMessage } = require('_http_incoming');
 const { ERR_PROXY_INVALID_CONFIG } = require('internal/errors').codes;
 const {
+  isValidHeaderName,
+  isValidHeaderValue,
   validateHeaderName,
   validateHeaderValue,
   OutgoingMessage,
@@ -192,6 +194,8 @@ module.exports = {
   Server,
   ServerResponse,
   createServer,
+  isValidHeaderName,
+  isValidHeaderValue,
   validateHeaderName,
   validateHeaderValue,
   get,
diff --git a/test/parallel/test-http-is-valid-header.js b/test/parallel/test-http-is-valid-header.js
new file mode 100644
index 000000000000..ddaacdd4b2b2
--- /dev/null
+++ b/test/parallel/test-http-is-valid-header.js
@@ -0,0 +1,168 @@
+'use strict';
+require('../common');
+const assert = require('assert');
+const {
+  isValidHeaderName,
+  isValidHeaderValue,
+  validateHeaderName,
+  validateHeaderValue,
+} = require('http');
+
+function succeeds(fn) {
+  try {
+    fn();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// isValidHeaderName
+{
+  const valid = [
+    'a',
+    'user-agent',
+    'USER-AGENT',
+    'User-Agent',
+    'x-forwarded-for',
+    'x-request-id-with-a-long-name',
+    "!#$%&'*+-.^_`|~",
+    '0123456789',
+  ];
+  const invalid = [
+    '',
+    ' ',
+    'bad header',
+    'bad:header',
+    'x-forwarded-fםr',
+    'איקס-פורוורד-פור',
+    'x\r\ny',
+    'x\0',
+    '(comment)',
+    '"quoted"',
+    'a,b',
+    'long-invalid-header-name\u00e9',
+  ];
+  const nonStrings = [
+    undefined, null, 0, 1, true, false, {}, [], ['a'],
+    Symbol('a'), () => {}, 1n, Buffer.from('a'),
+  ];
+
+  for (const name of valid) {
+    assert.strictEqual(isValidHeaderName(name), true, name);
+  }
+  for (const name of [...invalid, ...nonStrings]) {
+    assert.strictEqual(isValidHeaderName(name), false, String(name?.toString?.()));
+  }
+
+  // Must agree with validateHeaderName() for every input.
+  for (const name of [...valid, ...invalid, ...nonStrings]) {
+    assert.strictEqual(
+      isValidHeaderName(name),
+      succeeds(() => validateHeaderName(name)),
+    );
+  }
+
+  // Every single-character name agrees with validateHeaderName(), for both
+  // the short (lookup table) and long (regexp) code paths.
+  for (let c = 0; c <= 0x10ff; c++) {
+    const ch = String.fromCharCode(c);
+    for (const name of [ch, `${ch}xxxxxxxxxxxx`]) {
+      assert.strictEqual(
+        isValidHeaderName(name),
+        succeeds(() => validateHeaderName(name)),
+        `char code ${c}`,
+      );
+    }
+  }
+}
+
+// isValidHeaderValue
+{
+  const valid = [
+    '',
+    'text/html',
+    'a b\tc',
+    '\u00e9\u00ff',
+    '\x80',
+    1,
+    0,
+    null,
+    true,
+    ['a', 'b'],
+  ];
+  const invalid = [
+    undefined,
+    'a\r\nb',
+    'a\nb',
+    'a\rb',
+    'a\0b',
+    'a\x01b',
+    'a\x7fb',
+    'לא תקין',
+    '\u0100',
+    ['a', 'b\n'],
+    Symbol('a'),
+  ];
+
+  for (const value of valid) {
+    assert.strictEqual(isValidHeaderValue(value), true, String(value));
+  }
+  for (const value of invalid) {
+    assert.strictEqual(isValidHeaderValue(value), false, String(value));
+  }
+
+  // Must agree with validateHeaderValue() for every input.
+  for (const value of [...valid, ...invalid]) {
+    assert.strictEqual(
+      isValidHeaderValue(value),
+      succeeds(() => validateHeaderValue('x-test', value)),
+    );
+  }
+
+  for (let c = 0; c <= 0x10ff; c++) {
+    const value = `a${String.fromCharCode(c)}b`;
+    assert.strictEqual(
+      isValidHeaderValue(value),
+      succeeds(() => validateHeaderValue('x-test', value)),
+      `char code ${c}`,
+    );
+    // Explicit 'strict' is the same as the default.
+    assert.strictEqual(
+      isValidHeaderValue(value, { httpValidation: 'strict' }),
+      isValidHeaderValue(value),
+      `char code ${c}`,
+    );
+  }
+
+  // 'relaxed' follows the Fetch spec: only NUL, CR, LF and code points above
+  // U+00FF are rejected.
+  const relaxed = { httpValidation: 'relaxed' };
+  for (let c = 0; c <= 0x10ff; c++) {
+    const expected = !(c === 0x00 || c === 0x0a || c === 0x0d || c > 0xff);
+    assert.strictEqual(
+      isValidHeaderValue(`a${String.fromCharCode(c)}b`, relaxed),
+      expected,
+      `char code ${c}`,
+    );
+  }
+  assert.strictEqual(isValidHeaderValue(undefined, relaxed), false);
+  assert.strictEqual(isValidHeaderValue('a\x01b', relaxed), true);
+  assert.strictEqual(isValidHeaderValue('a\x7fb', relaxed), true);
+
+  // An empty options object uses the default.
+  assert.strictEqual(isValidHeaderValue('a\x01b', {}), false);
+  assert.strictEqual(isValidHeaderValue('a\x01b', { httpValidation: undefined }), false);
+
+  // Invalid options throw.
+  for (const options of [null, 1, 'relaxed', true]) {
+    assert.throws(() => isValidHeaderValue('a', options), {
+      code: 'ERR_INVALID_ARG_TYPE',
+    });
+  }
+  for (const httpValidation of ['insecure', 'RELAXED', '', 1, null]) {
+    assert.throws(() => isValidHeaderValue('a', { httpValidation }), {
+      code: 'ERR_INVALID_ARG_VALUE',
+    });
+  }
+}

From 1b50a1d4a2a4bab095ab252976abaeb456852480 Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Sun, 27 Sep 2026 02:23:34 +0000
Subject: [PATCH 2/2] benchmark: add http header validator benchmark

Compare http.isValidHeaderName() and http.isValidHeaderValue() with
http.validateHeaderName() and http.validateHeaderValue() wrapped in
try/catch, for valid and invalid input, and for both 'strict' and
'relaxed' header value validation.

Signed-off-by: James M Snell <jasnell@gmail.com>
---
 benchmark/http/is_valid_header.js | 120 ++++++++++++++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 benchmark/http/is_valid_header.js

diff --git a/benchmark/http/is_valid_header.js b/benchmark/http/is_valid_header.js
new file mode 100644
index 000000000000..cefe5c1f87ce
--- /dev/null
+++ b/benchmark/http/is_valid_header.js
@@ -0,0 +1,120 @@
+'use strict';
+
+// Compares the non-throwing header validators (http.isValidHeaderName() and
+// http.isValidHeaderValue()) with the throwing ones (http.validateHeaderName()
+// and http.validateHeaderValue()) used inside try/catch.
+
+const common = require('../common.js');
+const assert = require('assert');
+const {
+  isValidHeaderName,
+  isValidHeaderValue,
+  validateHeaderName,
+  validateHeaderValue,
+} = require('http');
+
+const inputs = {
+  name: {
+    valid: [
+      'ETag', 'date', 'Vary', 'server', 'Expires', 'location', 'Connection',
+      'content-type', 'Cache-Control', 'content-length', 'x-frame-options',
+      'Transfer-Encoding', 'x-request-id',
+    ],
+    invalid: [
+      '', ':', 'bad header', 'x-forwarded-fםr', '中文呢', '((((())))',
+      ':alternate-protocol', 'alternate-protocol:', 'x\r\ninjected',
+    ],
+  },
+  value: {
+    valid: [
+      'W/"2-d4cbb29"', 'OK', 'Express', 'application/json',
+      'application/json; charset=utf-8', 'sessionid=; Path=/',
+      'text/html; charset=utf-8', '10', 'max-age=0, no-cache', 'gzip, br',
+    ],
+    // Invalid under both 'strict' and 'relaxed' validation.
+    invalid: [
+      'a\r\nb', 'value\n', 'cr\r', 'nul\0byte', 'לא תקין', 'emoji \u{1F600}',
+      'x'.repeat(64) + '\r\n',
+    ],
+  },
+};
+
+const bench = common.createBenchmark(main, {
+  method: [
+    'isValidHeaderName',
+    'validateHeaderName',
+    'isValidHeaderValue',
+    'validateHeaderValue',
+  ],
+  input: ['valid', 'invalid'],
+  httpValidation: ['strict', 'relaxed'],
+  n: [1e6],
+}, {
+  // httpValidation only applies to isValidHeaderValue().
+  combinationFilter: (p) =>
+    p.httpValidation === 'strict' || p.method === 'isValidHeaderValue',
+});
+
+function main({ n, method, input, httpValidation }) {
+  let valid = 0;
+
+  switch (method) {
+    case 'isValidHeaderName': {
+      const list = inputs.name[input];
+      const len = list.length;
+      bench.start();
+      for (let i = 0; i < n; i++) {
+        if (isValidHeaderName(list[i % len])) valid++;
+      }
+      bench.end(n);
+      break;
+    }
+    case 'validateHeaderName': {
+      const list = inputs.name[input];
+      const len = list.length;
+      bench.start();
+      for (let i = 0; i < n; i++) {
+        try {
+          validateHeaderName(list[i % len]);
+          valid++;
+        } catch {
+          // Invalid name.
+        }
+      }
+      bench.end(n);
+      break;
+    }
+    case 'isValidHeaderValue': {
+      const list = inputs.value[input];
+      const len = list.length;
+      const options = httpValidation === 'strict' ? undefined : { httpValidation };
+      bench.start();
+      for (let i = 0; i < n; i++) {
+        if (isValidHeaderValue(list[i % len], options)) valid++;
+      }
+      bench.end(n);
+      break;
+    }
+    case 'validateHeaderValue': {
+      const list = inputs.value[input];
+      const len = list.length;
+      bench.start();
+      for (let i = 0; i < n; i++) {
+        try {
+          validateHeaderValue('x-header', list[i % len]);
+          valid++;
+        } catch {
+          // Invalid value.
+        }
+      }
+      bench.end(n);
+      break;
+    }
+    default:
+      throw new Error(`Unexpected method: ${method}`);
+  }
+
+  // Consume the result so the loop cannot be optimized away, and make sure
+  // the inputs are what they claim to be.
+  assert.strictEqual(valid, input === 'valid' ? n : 0);
+}