http2: address review feedback on httpValidation option

- Disable strictFieldWhitespaceValidation in relaxed/insecure mode so it
  does not conflict with the relaxed behaviour (per @pimterry review).
- Document that relaxed/insecure subsumes strictSingleValueFields and
  strictFieldWhitespaceValidation.
- Add integration tests for the http2.connect() httpValidation option.

Author: mcollina

doc/api/http2.md

@@ -1129,8 +1129,8 @@ creates and returns an `Http2Stream` instance that can be used to send an
 HTTP/2 request to the connected server.
 
 When sending a request, header values must not contain characters outside the
-`latin1` encoding. The `:path` pseudo-header must not contain unescaped
-characters.
+`latin1` encoding, and the `:path` pseudo-header must not contain unescaped
+characters (this `:path` check is always enforced).
 
 This strict validation can be relaxed via the `httpValidation` option of
 [`http2.connect()`](#http2connectauthority-options-listener). The `'relaxed'`
@@ -3312,6 +3312,9 @@ server.listen(8443);
 <!-- YAML
 added: v8.4.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/63571
+    description: Added the `httpValidation` option.
   - version: v26.11.0
     pr-url: https://github.com/nodejs/node/pull/65619
     description: Added the `connectionWindowSize` option.
@@ -3441,8 +3444,9 @@ changes:
       [Fetch specification][].
     * `'insecure'`: Skips header value validation (equivalent to
       `insecureHTTPParser` in HTTP/1).
-      When set to `'relaxed'` or `'insecure'`, `strictSingleValueFields` is
-      automatically disabled.
+      When set to `'relaxed'` or `'insecure'`, `strictSingleValueFields` and
+      `strictFieldWhitespaceValidation` are automatically disabled, as they
+      would otherwise conflict with the relaxed behaviour.
       **Default:** `'strict'`.
 * `listener` {Function} Will be registered as a one-time listener of the
   [`'connect'`][] event.

test/parallel/test-http2-httpvalidation.js

@@ -0,0 +1,105 @@
+'use strict';
+const common = require('../common');
+if (!common.hasCrypto) { common.skip('missing crypto'); }
+const assert = require('assert');
+const http2 = require('http2');
+
+// Integration tests for the http2.connect() `httpValidation` option.
+// See also test-http2-util-headers-list.js for the per-value validation logic.
+
+const server = http2.createServer();
+// Consume any stream that is actually created. Control characters and
+// duplicate pseudo-headers may be rejected by nghttp2 asynchronously, so
+// swallow any stream errors rather than letting them become uncaught.
+server.on('stream', (stream) => {
+  stream.on('error', () => {});
+});
+
+server.listen(0, common.mustCall(() => {
+  const origin = `http://localhost:${server.address().port}`;
+
+  function swallow(stream) {
+    stream.on('error', () => {});
+    stream.destroy();
+    return stream;
+  }
+
+  // -- strict (default) --
+  {
+    const session = http2.connect(origin);
+    session.on('error', () => {});
+    // Non-latin1 characters are rejected by default.
+    assert.throws(() => session.request({ 'x-bad-char': 'oʊmɪɡə' }), {
+      code: 'ERR_HTTP2_INVALID_HEADER_VALUE',
+    });
+    // Control characters are rejected by default per the HTTP RFCs.
+    assert.throws(() => session.request({ 'x-control': 'value\x01here' }), {
+      code: 'ERR_HTTP2_INVALID_HEADER_VALUE',
+    });
+    // strictSingleValueFields is enabled by default.
+    assert.throws(() => session.request([
+      [':method', 'GET'],
+      [':method', 'POST'],
+    ]), {
+      code: 'ERR_HTTP2_HEADER_SINGLE_VALUE',
+    });
+    // The :path pseudo-header must not contain unescaped characters.
+    assert.throws(() => session.request({ ':path': 'bad\u0100path' }), {
+      code: 'ERR_UNESCAPED_CHARACTERS',
+    });
+    session.close();
+  }
+
+  // -- relaxed --
+  {
+    const session = http2.connect(origin, { httpValidation: 'relaxed' });
+    session.on('error', () => {});
+    // Control characters permitted by the Fetch specification are allowed.
+    swallow(session.request({ 'x-control': 'value\x01here' }));
+    // relaxed/insecure mode subsumes and disables strictSingleValueFields.
+    swallow(session.request([
+      [':method', 'GET'],
+      [':method', 'POST'],
+    ]));
+    // Non-latin1 characters are still rejected in relaxed mode.
+    assert.throws(() => session.request({ 'x-bad-char': 'oʊmɪɡə' }), {
+      code: 'ERR_HTTP2_INVALID_HEADER_VALUE',
+    });
+    // NUL is always rejected.
+    assert.throws(() => session.request({ 'x-nul': 'value\x00here' }), {
+      code: 'ERR_HTTP2_INVALID_HEADER_VALUE',
+    });
+    // The :path pseudo-header check is always enforced.
+    assert.throws(() => session.request({ ':path': 'bad\u0100path' }), {
+      code: 'ERR_UNESCAPED_CHARACTERS',
+    });
+    session.close();
+  }
+
+  // -- insecure --
+  {
+    const session = http2.connect(origin, { httpValidation: 'insecure' });
+    session.on('error', () => {});
+    // All header value validation is skipped, including newlines.
+    swallow(session.request({ 'x-newline': 'value\nhere' }));
+    // strictSingleValueFields is disabled in insecure mode too.
+    swallow(session.request([
+      [':method', 'GET'],
+      [':method', 'POST'],
+    ]));
+    // The :path pseudo-header check is still enforced.
+    assert.throws(() => session.request({ ':path': 'bad\u0100path' }), {
+      code: 'ERR_UNESCAPED_CHARACTERS',
+    });
+    session.close();
+  }
+
+  // -- invalid option value --
+  {
+    assert.throws(() => http2.connect(origin, { httpValidation: 'bogus' }), {
+      code: 'ERR_INVALID_ARG_VALUE',
+    });
+  }
+
+  server.close();
+}));