http: add uniqueHeaders option to request and createServer

PR-URL: https://github.com/nodejs/node/pull/41397
Reviewed-By: Robert Nagy <ronagy@icloud.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>

1 files changed, 67 insertions, 5 deletions

diff --git a/doc/api/http.md b/doc/api/http.md
index 01c97ec4e67..838cdd0e05f 100644
--- a/doc/api/http.md
+++ b/doc/api/http.md
@@ -2364,8 +2364,28 @@ header name:
   `last-modified`, `location`, `max-forwards`, `proxy-authorization`, `referer`,
   `retry-after`, `server`, or `user-agent` are discarded.
 * `set-cookie` is always an array. Duplicates are added to the array.
-* For duplicate `cookie` headers, the values are joined together with '; '.
-* For all other headers, the values are joined together with ', '.
+* For duplicate `cookie` headers, the values are joined together with `; `.
+* For all other headers, the values are joined together with `, `.
+
+### `message.headersDistinct`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {Object}
+
+Similar to [`message.headers`][], but there is no join logic and the values are
+always arrays of strings, even for headers received just once.
+
+```js
+// Prints something like:
+//
+// { 'user-agent': ['curl/7.22.0'],
+//   host: ['127.0.0.1:8000'],
+//   accept: ['*/*'] }
+console.log(request.headersDistinct);
+```
 
 ### `message.httpVersion`
 
@@ -2499,6 +2519,18 @@ added: v0.3.0
 
 The request/response trailers object. Only populated at the `'end'` event.
 
+### `message.trailersDistinct`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* {Object}
+
+Similar to [`message.trailers`][], but there is no join logic and the values are
+always arrays of strings, even for headers received just once.
+Only populated at the `'end'` event.
+
 ### `message.url`
 
 <!-- YAML
@@ -2596,7 +2628,7 @@ Adds HTTP trailers (headers but at the end of the message) to the message.
 Trailers will **only** be emitted if the message is chunked encoded. If not,
 the trailers will be silently discarded.
 
-HTTP requires the  `Trailer` header to be sent to emit trailers,
+HTTP requires the `Trailer` header to be sent to emit trailers,
 with a list of header field names in its value, e.g.
 
 ```js
@@ -2610,6 +2642,28 @@ message.end();
 Attempting to set a header field name or value that contains invalid characters
 will result in a `TypeError` being thrown.
 
+### `outgoingMessage.appendHeader(name, value)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `name` {string} Header name
+* `value` {string|string\[]} Header value
+* Returns: {this}
+
+Append a single header value for the header object.
+
+If the value is an array, this is equivalent of calling this method multiple
+times.
+
+If there were no previous value for the header, this is equivalent of calling
+[`outgoingMessage.setHeader(name, value)`][].
+
+Depending of the value of `options.uniqueHeaders` when the client request or the
+server were created, this will end up in the header being sent multiple times or
+a single time with values joined using `; `.
+
 ### `outgoingMessage.connection`
 
 <!-- YAML
@@ -3026,6 +3080,9 @@ changes:
   * `keepAliveInitialDelay` {number} If set to a positive number, it sets the
     initial delay before the first keepalive probe is sent on an idle socket.
     **Default:** `0`.
+  * `uniqueHeaders` {Array} A list of response headers that should be sent only
+    once. If the header's value is an array, the items will be joined
+    using `; `.
 
 * `requestListener` {Function}
 
@@ -3260,12 +3317,15 @@ changes:
   * `protocol` {string} Protocol to use. **Default:** `'http:'`.
   * `setHost` {boolean}: Specifies whether or not to automatically add the
     `Host` header. Defaults to `true`.
+  * `signal` {AbortSignal}: An AbortSignal that may be used to abort an ongoing
+    request.
   * `socketPath` {string} Unix domain socket. Cannot be used if one of `host`
     or `port` is specified, as those specify a TCP Socket.
   * `timeout` {number}: A number specifying the socket timeout in milliseconds.
     This will set the timeout before the socket is connected.
-  * `signal` {AbortSignal}: An AbortSignal that may be used to abort an ongoing
-    request.
+  * `uniqueHeaders` {Array} A list of request headers that should be sent
+    only once. If the header's value is an array, the items will be joined
+    using `; `.
 * `callback` {Function}
 * Returns: {http.ClientRequest}
 
@@ -3571,11 +3631,13 @@ try {
 [`http.request()`]: #httprequestoptions-callback
 [`message.headers`]: #messageheaders
 [`message.socket`]: #messagesocket
+[`message.trailers`]: #messagetrailers
 [`net.Server.close()`]: net.md#serverclosecallback
 [`net.Server`]: net.md#class-netserver
 [`net.Socket`]: net.md#class-netsocket
 [`net.createConnection()`]: net.md#netcreateconnectionoptions-connectlistener
 [`new URL()`]: url.md#new-urlinput-base
+[`outgoingMessage.setHeader(name, value)`]: #outgoingmessagesetheadername-value
 [`outgoingMessage.socket`]: #outgoingmessagesocket
 [`removeHeader(name)`]: #requestremoveheadername
 [`request.destroy()`]: #requestdestroyerror