http: add uniqueHeaders option to request and createServer

Author: ShogunPanda

doc/api/http.md

@@ -2223,8 +2223,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`
 
@@ -2358,6 +2378,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
@@ -2455,7 +2487,7 @@ Adds HTTP trailers (headers but at the end of the message) to the message.
 Trailers are **only** be emitted if the message is chunked encoded. If not,
 the trailer 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 fields in its value, e.g.
 
 ```js
@@ -2469,6 +2501,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
@@ -2865,6 +2919,9 @@ changes:
     [`--max-http-header-size`][] for requests received by this server, i.e.
     the maximum length of request headers in bytes.
     **Default:** 16384 (16 KB).
+  * `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}
 
@@ -3099,12 +3156,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}
 
@@ -3407,11 +3467,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

lib/_http_client.js

@@ -52,7 +52,11 @@ const {
   isLenient,
   prepareError,
 } = require('_http_common');
-const { OutgoingMessage } = require('_http_outgoing');
+const {
+  kUniqueHeaders,
+  parseUniqueHeaders,
+  OutgoingMessage
+} = require('_http_outgoing');
 const Agent = require('_http_agent');
 const { Buffer } = require('buffer');
 const { defaultTriggerAsyncIdScope } = require('internal/async_hooks');
@@ -294,6 +298,8 @@ function ClientRequest(input, options, cb) {
                       options.headers);
   }
 
+  this[kUniqueHeaders] = parseUniqueHeaders(options.uniqueHeaders);
+
   let optsWithoutSignal = options;
   if (optsWithoutSignal.signal) {
     optsWithoutSignal = ObjectAssign({}, options);

lib/_http_incoming.js

@@ -33,8 +33,10 @@ const {
 const { Readable, finished } = require('stream');
 
 const kHeaders = Symbol('kHeaders');
+const kHeadersDistinct = Symbol('kHeadersDistinct');
 const kHeadersCount = Symbol('kHeadersCount');
 const kTrailers = Symbol('kTrailers');
+const kTrailersDistinct = Symbol('kTrailersDistinct');
 const kTrailersCount = Symbol('kTrailersCount');
 
 function readStart(socket) {
@@ -123,6 +125,25 @@ ObjectDefineProperty(IncomingMessage.prototype, 'headers', {
   }
 });
 
+ObjectDefineProperty(IncomingMessage.prototype, 'headersDistinct', {
+  get: function() {
+    if (!this[kHeadersDistinct]) {
+      this[kHeadersDistinct] = {};
+
+      const src = this.rawHeaders;
+      const dst = this[kHeadersDistinct];
+
+      for (let n = 0; n < this[kHeadersCount]; n += 2) {
+        this._addHeaderLineDistinct(src[n + 0], src[n + 1], dst);
+      }
+    }
+    return this[kHeadersDistinct];
+  },
+  set: function(val) {
+    this[kHeadersDistinct] = val;
+  }
+});
+
 ObjectDefineProperty(IncomingMessage.prototype, 'trailers', {
   get: function() {
     if (!this[kTrailers]) {
@@ -142,6 +163,25 @@ ObjectDefineProperty(IncomingMessage.prototype, 'trailers', {
   }
 });
 
+ObjectDefineProperty(IncomingMessage.prototype, 'trailersDistinct', {
+  get: function() {
+    if (!this[kTrailersDistinct]) {
+      this[kTrailersDistinct] = {};
+
+      const src = this.rawTrailers;
+      const dst = this[kTrailersDistinct];
+
+      for (let n = 0; n < this[kTrailersCount]; n += 2) {
+        this._addHeaderLineDistinct(src[n + 0], src[n + 1], dst);
+      }
+    }
+    return this[kTrailersDistinct];
+  },
+  set: function(val) {
+    this[kTrailersDistinct] = val;
+  }
+});
+
 IncomingMessage.prototype.setTimeout = function setTimeout(msecs, callback) {
   if (callback)
     this.on('timeout', callback);
@@ -361,6 +401,16 @@ function _addHeaderLine(field, value, dest) {
   }
 }
 
+IncomingMessage.prototype._addHeaderLineDistinct = _addHeaderLineDistinct;
+function _addHeaderLineDistinct(field, value, dest) {
+  field = StringPrototypeToLowerCase(field);
+  if (!dest[field]) {
+    dest[field] = [value];
+  } else {
+    dest[field].push(value);
+  }
+}
+
 
 // Call this instead of resume() if we want to just
 // dump all the data to /dev/null

lib/_http_outgoing.js

@@ -24,6 +24,7 @@
 const {
   Array,
   ArrayIsArray,
+  ArrayPrototypeIncludes,
   ArrayPrototypeJoin,
   MathFloor,
   NumberPrototypeToString,
@@ -82,6 +83,7 @@ let debug = require('internal/util/debuglog').debuglog('http', (fn) => {
 const HIGH_WATER_MARK = getDefaultHighWaterMark();
 
 const kCorked = Symbol('corked');
+const kUniqueHeaders = Symbol('kUniqueHeaders');
 
 const nop = () => {};
 
@@ -502,14 +504,19 @@ function processHeader(self, state, key, value, validate) {
   if (validate)
     validateHeaderName(key);
   if (ArrayIsArray(value)) {
-    if (value.length < 2 || !isCookieField(key)) {
+    if (
+      (value.length < 2 || !isCookieField(key)) &&
+      !ArrayPrototypeIncludes(
+        self[kUniqueHeaders], StringPrototypeToLowerCase(key)
+      )
+    ) {
       // Retain for(;;) loop for performance reasons
       // Refs: https://github.com/nodejs/node/pull/30958
       for (let i = 0; i < value.length; i++)
         storeHeader(self, state, key, value[i], validate);
       return;
     }
-    value = ArrayPrototypeJoin(value, '; ');
+    value = ArrayPrototypeJoin(value, ', ');
   }
   storeHeader(self, state, key, value, validate);
 }
@@ -571,6 +578,20 @@ const validateHeaderValue = hideStackFrames((name, value) => {
   }
 });
 
+function parseUniqueHeaders(headers) {
+  if (!ArrayIsArray(headers)) {
+    return [];
+  }
+
+  const l = headers.length;
+  const unique = Array(l);
+  for (let i = 0; i < l; i++) {
+    unique[i] = StringPrototypeToLowerCase(headers[i]);
+  }
+
+  return unique;
+}
+
 OutgoingMessage.prototype.setHeader = function setHeader(name, value) {
   if (this._header) {
     throw new ERR_HTTP_HEADERS_SENT('set');
@@ -586,6 +607,36 @@ OutgoingMessage.prototype.setHeader = function setHeader(name, value) {
   return this;
 };
 
+OutgoingMessage.prototype.appendHeader = function appendHeader(name, value) {
+  if (this._header) {
+    throw new ERR_HTTP_HEADERS_SENT('append');
+  }
+  validateHeaderName(name);
+  validateHeaderValue(name, value);
+
+  const field = StringPrototypeToLowerCase(name);
+  const headers = this[kOutHeaders];
+  if (headers === null || !headers[field]) {
+    return this.setHeader(name, value);
+  }
+
+  // Prepare the field for appending, if required
+  if (!ArrayIsArray(headers[field][1])) {
+    headers[field][1] = [headers[field][1]];
+  }
+
+  const existingValues = headers[field][1];
+  if (ArrayIsArray(value)) {
+    for (let i = 0, length = value.length; i < length; i++) {
+      existingValues.push(value[i]);
+    }
+  } else {
+    existingValues.push(value);
+  }
+
+  return this;
+};
+
 
 OutgoingMessage.prototype.getHeader = function getHeader(name) {
   validateString(name, 'name');
@@ -817,11 +868,33 @@ OutgoingMessage.prototype.addTrailers = function addTrailers(headers) {
     if (typeof field !== 'string' || !field || !checkIsHttpToken(field)) {
       throw new ERR_INVALID_HTTP_TOKEN('Trailer name', field);
     }
-    if (checkInvalidHeaderChar(value)) {
-      debug('Trailer "%s" contains invalid characters', field);
-      throw new ERR_INVALID_CHAR('trailer content', field);
+
+    // Check if the field must be sent several times
+    const isArrayValue = ArrayIsArray(value);
+    if (
+      isArrayValue && value.length > 1 &&
+      !ArrayPrototypeIncludes(
+        this[kUniqueHeaders], StringPrototypeToLowerCase(field)
+      )
+    ) {
+      for (let j = 0, l = value.length; j < l; j++) {
+        if (checkInvalidHeaderChar(value[j])) {
+          debug('Trailer "%s"[%d] contains invalid characters', field, j);
+          throw new ERR_INVALID_CHAR('trailer content', field);
+        }
+        this._trailer += field + ': ' + value[j] + '\r\n';
+      }
+    } else {
+      if (isArrayValue) {
+        value = ArrayPrototypeJoin(value, ', ');
+      }
+
+      if (checkInvalidHeaderChar(value)) {
+        debug('Trailer "%s" contains invalid characters', field);
+        throw new ERR_INVALID_CHAR('trailer content', field);
+      }
+      this._trailer += field + ': ' + value + '\r\n';
     }
-    this._trailer += field + ': ' + value + '\r\n';
   }
 };
 
@@ -997,6 +1070,8 @@ function(err, event) {
 };
 
 module.exports = {
+  kUniqueHeaders,
+  parseUniqueHeaders,
   validateHeaderName,
   validateHeaderValue,
   OutgoingMessage