net: family option in net.connect

`dns.lookup` defaults to selecting IPv4 record even if IPv6 is available
for the desired zone. Generally, this approach works, but if IPv4
address is unavailable - there'll be no other way to opt-out and connect using
IPv6 address than calling `dns.lookup` and passing it to `.connect()`
directly.

This commit adds `family` option to `net.connect` method to figure out
this issue.

doc/api/net.markdown

@@ -64,6 +64,8 @@ For TCP sockets, `options` argument should be an object which specifies:
 
   - `localAddress`: Local interface to bind to for network connections.
 
+  - `family` : Version of IP stack. Defaults to `4`.
+
 For UNIX domain sockets, `options` argument should be an object which specifies:
 
   - `path`: Path the client should connect to (Required).

lib/net.js

@@ -857,8 +857,9 @@ Socket.prototype.connect = function(options, cb) {
 
   } else {
     var host = options.host;
+    var family = options.family || 4;
     debug('connect: find host ' + host);
-    require('dns').lookup(host, function(err, ip, addressType) {
+    require('dns').lookup(host, family, function(err, ip, addressType) {
       self.emit('lookup', err, ip, addressType);
 
       // It's possible we were destroyed while looking this up.

test/simple/test-net-connect-options-ipv6.js

@@ -0,0 +1,63 @@
+// Copyright Joyent, Inc. and other Node contributors.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the
+// "Software"), to deal in the Software without restriction, including
+// without limitation the rights to use, copy, modify, merge, publish,
+// distribute, sublicense, and/or sell copies of the Software, and to permit
+// persons to whom the Software is furnished to do so, subject to the
+// following conditions:
+//
+// The above copyright notice and this permission notice shall be included
+// in all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+// USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+var common = require('../common');
+var assert = require('assert');
+var net = require('net');
+
+var serverGotEnd = false;
+var clientGotEnd = false;
+
+var server = net.createServer({allowHalfOpen: true}, function(socket) {
+  socket.resume();
+  socket.on('end', function() {
+    serverGotEnd = true;
+  });
+  socket.end();
+});
+
+server.listen(common.PORT, '::1', function() {
+  var client = net.connect({
+    host: 'localhost',
+    port: common.PORT,
+    family: 6,
+    allowHalfOpen: true
+  }, function() {
+    console.error('client connect cb');
+    client.resume();
+    client.on('end', function() {
+      clientGotEnd = true;
+      setTimeout(function() {
+        assert(client.writable);
+        client.end();
+      }, 10);
+    });
+    client.on('close', function() {
+      server.close();
+    });
+  });
+});
+
+process.on('exit', function() {
+  console.error('exit', serverGotEnd, clientGotEnd);
+  assert(serverGotEnd);
+  assert(clientGotEnd);
+});