Document H1 keep-alive trust tradeoff

README.md

@@ -717,8 +717,9 @@ Refs: https://tools.ietf.org/html/rfc7231#section-5.1.1
 #### Pipelining
 
 Undici will only use pipelining if configured with a `pipelining` factor
-greater than `1`. Also it is important to pass `blocking: false` to the
-request options to properly pipeline requests.
+greater than `1`. Only enable pipelining when the remote server is trusted.
+Also it is important to pass `blocking: false` to the request options to
+properly pipeline requests.
 
 Undici always assumes that connections are persistent and will immediately
 pipeline requests, without checking whether the connection is persistent.

SECURITY.md

@@ -153,6 +153,18 @@ lead to a loss of confidentiality, integrity, or availability.
   calling `body.formData()` on untrusted responses is considered an application
   responsibility, not a vulnerability in undici.
 
+#### HTTP/1.1 keep-alive with untrusted servers
+
+* HTTP/1.1 responses on a reused connection are ordered, but they do not carry a
+  request identifier. Once a request has been written on a reused connection,
+  a well-formed response sent by the server is the response to that next request
+  from the client's point of view. Undici avoids immediate reuse of
+  non-pipelined HTTP/1.1 connections when callers are already waiting to send
+  more work, but applications that require per-request connection isolation for
+  untrusted or user-controlled servers should disable reuse by using
+  `pipelining: 0` or `maxRequestsPerClient: 1`, or use a protocol with response
+  correlation such as HTTP/2.
+
 #### Application Misconfiguration
 
 * Issues arising from incorrect or insecure use of undici APIs (such as

docs/docs/api/Client.md

@@ -74,7 +74,8 @@ added: v1.0.0
   * `localAddress` {string|null} The local IP address the socket should connect
     from. **Default:** `null`.
   * `pipelining` {number|null} The number of concurrent requests sent over the
-    single connection, per [RFC 7230, section 6.3.2][]. Set to `0` to disable
+    single connection, per [RFC 7230, section 6.3.2][]. Only enable values
+    greater than `1` when the remote server is trusted. Set to `0` to disable
     keep-alive connections. Has no effect once HTTP/2 is negotiated; see
     `maxConcurrentStreams` for the HTTP/2 dispatch ceiling. **Default:** `1`.
   * `connect` {Object|Function|null} Configures how connections are established.
@@ -346,7 +347,8 @@ added: v1.0.0
 * Type: {number}
 
 The pipelining factor. This property can be read and written to adjust the
-number of concurrent requests sent over the connection.
+number of concurrent requests sent over the connection. Only enable pipelining
+with trusted remote servers.
 
 ### `client.stats`
 

docs/docs/getting-started.md

@@ -113,7 +113,8 @@ pool.close()
 ### `Client` — for a single connection
 
 `Client` maps to a single TCP connection. It supports pipelining (sending
-multiple requests before responses arrive):
+multiple requests before responses arrive), which should only be enabled for
+trusted remote servers:
 
 ```js
 import { Client } from 'undici'

docs/docs/index.md

@@ -704,8 +704,9 @@ Refs: https://tools.ietf.org/html/rfc7231#section-5.1.1
 #### Pipelining
 
 Undici will only use pipelining if configured with a `pipelining` factor
-greater than `1`. Also it is important to pass `blocking: false` to the
-request options to properly pipeline requests.
+greater than `1`. Only enable pipelining when the remote server is trusted.
+Also it is important to pass `blocking: false` to the request options to
+properly pipeline requests.
 
 Undici always assumes that connections are persistent and will immediately
 pipeline requests, without checking whether the connection is persistent.

types/client.d.ts

@@ -57,7 +57,7 @@ export declare namespace Client {
     keepAliveTimeoutThreshold?: number;
     /** An IPC endpoint, either a Unix domain socket or Windows named pipe. Default: `null`. */
     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). Only enable values greater than `1` when the remote server is trusted. Default: `1`. */
     pipelining?: number;
     /** @deprecated use the connect option instead */
     tls?: never;