[feature] Accept hostname lookup family option (#962)

Author: hansonw

doc/ws.md

@@ -174,6 +174,7 @@ This class represents a WebSocket. It extends the `EventEmitter`.
     depending on the `protocolVersion`.
   - `agent` {http.Agent|https.Agent} Use the specified Agent,
   - `host` {String} Value of the `Host` header.
+  - `family` {Number} IP address family to use during hostname lookup (4 or 6).
   - `checkServerIdentity` {Function} A function to validate the server hostname.
   - `rejectUnauthorized` {Boolean} Verify or not the server certificate.
   - `passphrase` {String} The passphrase for the private key or pfx.

lib/WebSocket.js

@@ -472,14 +472,15 @@ function initAsServerClient (req, socket, head, options) {
  * @param {String} address The URL to which to connect
  * @param {String[]} protocols The list of subprotocols
  * @param {Object} options Connection options
- * @param {String} option.protocol Value of the `Sec-WebSocket-Protocol` header
+ * @param {String} options.protocol Value of the `Sec-WebSocket-Protocol` header
  * @param {(Boolean|Object)} options.perMessageDeflate Enable/disable permessage-deflate
  * @param {String} options.localAddress Local interface to bind for network connections
  * @param {Number} options.protocolVersion Value of the `Sec-WebSocket-Version` header
  * @param {Object} options.headers An object containing request headers
  * @param {String} options.origin Value of the `Origin` or `Sec-WebSocket-Origin` header
  * @param {http.Agent} options.agent Use the specified Agent
  * @param {String} options.host Value of the `Host` header
+ * @param {Number} options.family IP address family to use during hostname lookup (4 or 6).
  * @param {Function} options.checkServerIdentity A function to validate the server hostname
  * @param {Boolean} options.rejectUnauthorized Verify or not the server certificate
  * @param {String} options.passphrase The passphrase for the private key or pfx
@@ -500,6 +501,7 @@ function initAsClient (address, protocols, options) {
     origin: null,
     agent: null,
     host: null,
+    family: null,
 
     //
     // SSL options.
@@ -572,6 +574,7 @@ function initAsClient (address, protocols, options) {
     }
   }
   if (options.host) requestOptions.headers.Host = options.host;
+  if (options.family) requestOptions.family = options.family;
 
   if (options.localAddress) requestOptions.localAddress = options.localAddress;
   if (isUnixSocket) requestOptions.socketPath = serverUrl.pathname;

test/WebSocket.test.js

@@ -80,6 +80,17 @@ describe('WebSocket', function () {
         /must be a valid IP: 123.456.789.428/
       );
     });
+
+    it('should accept the family option', function (done) {
+      const wss = new WebSocketServer({ host: '::1', port: ++port }, () => {
+        const ws = new WebSocket(`ws://localhost:${port}`, { family: 6 });
+      });
+
+      wss.on('connection', (ws) => {
+        assert.strictEqual(ws.upgradeReq.connection.remoteAddress, '::1');
+        wss.close(done);
+      });
+    });
   });
 
   describe('properties', function () {