feat!: use maxConcurrentStreams as multiplexing factor

For H2 sessions pipelining is misleading and is a concept of HTTP/1.1.

This makes use of `maxConcurrentStreams` parameter to be equivalent of
what H2 calls multiplexing. It makes sure that clients do not have to
change `pipelining` in order to achieve multiplexing over a H2 stream.

Closes nodejs#4143.

Author: slagiewka

benchmarks/benchmark-http2.js

@@ -15,7 +15,7 @@ const servername = 'agent1'
 const iterations = (parseInt(process.env.SAMPLES, 10) || 10) + 1
 const errorThreshold = parseInt(process.env.ERROR_THRESHOLD, 10) || 3
 const connections = parseInt(process.env.CONNECTIONS, 10) || 50
-const pipelining = parseInt(process.env.PIPELINING, 10) || 10
+const maxConcurrentStreams = parseInt(process.env.MULTIPLEXING, 10) || 10
 const parallelRequests = parseInt(process.env.PARALLEL, 10) || 100
 const headersTimeout = parseInt(process.env.HEADERS_TIMEOUT, 10) || 0
 const bodyTimeout = parseInt(process.env.BODY_TIMEOUT, 10) || 0
@@ -61,7 +61,7 @@ const http2NativeClient = http2.connect(httpsBaseOptions.url, {
 const Class = connections > 1 ? Pool : Client
 const dispatcher = new Class(httpsBaseOptions.url, {
   allowH2: true,
-  pipelining,
+  maxConcurrentStreams,
   connections,
   connect: {
     rejectUnauthorized: false,
@@ -73,7 +73,7 @@ const dispatcher = new Class(httpsBaseOptions.url, {
 
 setGlobalDispatcher(new Agent({
   allowH2: true,
-  pipelining,
+  maxConcurrentStreams,
   connections,
   connect: {
     rejectUnauthorized: false,

docs/docs/api/Client.md

@@ -24,7 +24,7 @@ Returns: `Client`
 * **keepAliveTimeoutThreshold** `number | null` (optional) - Default: `2e3` - A number of milliseconds subtracted from server *keep-alive* hints when overriding `keepAliveTimeout` to account for timing inaccuracies caused by e.g. transport latency. Defaults to 2 seconds.
 * **maxHeaderSize** `number | null` (optional) - Default: `--max-http-header-size` or `16384` - The maximum length of request headers in bytes. Defaults to Node.js' --max-http-header-size or 16KiB.
 * **maxResponseSize** `number | null` (optional) - Default: `-1` - The maximum length of response body in bytes. Set to `-1` to disable.
-* **pipelining** `number | null` (optional) - Default: `1` - The amount of concurrent requests to be sent over the single TCP/TLS connection according to [RFC7230](https://tools.ietf.org/html/rfc7230#section-6.3.2). Carefully consider your workload and environment before enabling concurrent requests as pipelining may reduce performance if used incorrectly. Pipelining is sensitive to network stack settings as well as head of line blocking caused by e.g. long running requests. Set to `0` to disable keep-alive connections.
+* **pipelining** `number | null` (optional) - Default: `1` - The amount of concurrent requests to be sent over the single TCP/TLS connection according to [RFC7230](https://tools.ietf.org/html/rfc7230#section-6.3.2). Carefully consider your workload and environment before enabling concurrent requests as pipelining may reduce performance if used incorrectly. Pipelining is sensitive to network stack settings as well as head of line blocking caused by e.g. long running requests. Set to `0` to disable keep-alive connections. Ineffective for H2 sessions.
 * **connect** `ConnectOptions | Function | null` (optional) - Default: `null`.
 * **strictContentLength** `Boolean` (optional) - Default: `true` - Whether to treat request content length mismatches as errors. If true, an error is thrown when the request content-length header doesn't match the length of the request body.
 * **autoSelectFamily**: `boolean` (optional) - Default: depends on local Node version, on Node 18.13.0 and above is `false`. Enables a family autodetection algorithm that loosely implements section 5 of [RFC 8305](https://tools.ietf.org/html/rfc8305#section-5). See [here](https://nodejs.org/api/net.html#socketconnectoptions-connectlistener) for more details. This option is ignored if not supported by the current Node version.

lib/dispatcher/client.js

@@ -68,6 +68,10 @@ const getDefaultNodeMaxHeaderSize = http &&
 const noop = () => {}
 
 function getPipelining (client) {
+  if (client[kHTTPContext]?.version === 'h2') {
+    return client[kMaxConcurrentStreams] ?? client[kHTTPContext]?.defaultPipelining ?? 100
+  }
+
   return client[kPipelining] ?? client[kHTTPContext]?.defaultPipelining ?? 1
 }
 

types/client.d.ts

@@ -59,7 +59,7 @@ export declare namespace Client {
     keepAliveTimeoutThreshold?: number;
     /** TODO */
     socketPath?: string;
-    /** The amount of concurrent requests to be sent over the single TCP/TLS connection according to [RFC7230](https://tools.ietf.org/html/rfc7230#section-6.3.2). Default: `1`. */
+    /** The amount of concurrent requests to be sent over the single TCP/TLS connection according to [RFC7230](https://tools.ietf.org/html/rfc7230#section-6.3.2). Ineffective for H2 sessions. Default: `1`. */
     pipelining?: number;
     /** @deprecated use the connect option instead */
     tls?: never;