tls: support the hints option

Make `tls.connect()` support the `hints` option for feature parity with
`net.connect()`.

PR-URL: #27816
Reviewed-By: Ruben Bridgewater <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Yongsheng Zhang <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Sam Roberts <[email protected]>
Reviewed-By: Rich Trott <[email protected]>

Author: lpinca

doc/api/tls.md

@@ -1178,6 +1178,9 @@ being issued by trusted CA (`options.ca`).
 <!-- YAML
 added: v0.11.3
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/27816
+    description: The `hints` option is now supported.
   - version: v12.2.0
     pr-url: https://github.com/nodejs/node/pull/27497
     description: The `enableTrace` option is now supported.
@@ -1248,13 +1251,9 @@ changes:
     [`tls.createSecureContext()`][]. If a `secureContext` is _not_ provided, one
     will be created by passing the entire `options` object to
     `tls.createSecureContext()`.
-  * `lookup`: {Function} Custom lookup function. **Default:**
-    [`dns.lookup()`][].
-  * `timeout`: {number} If set and if a socket is created internally, will call
-    [`socket.setTimeout(timeout)`][] after the socket is created, but before it
-    starts the connection.
   * ...: [`tls.createSecureContext()`][] options that are used if the
     `secureContext` option is missing, otherwise they are ignored.
+  * ...: Any [`socket.connect()`][] option not already listed.
 * `callback` {Function}
 * Returns: {tls.TLSSocket}
 
@@ -1771,7 +1770,6 @@ where `secureSocket` has the same API as `pair.cleartext`.
 [`--tls-cipher-list`]: cli.html#cli_tls_cipher_list_list
 [`NODE_OPTIONS`]: cli.html#cli_node_options_options
 [`crypto.getCurves()`]: crypto.html#crypto_crypto_getcurves
-[`dns.lookup()`]: dns.html#dns_dns_lookup_hostname_options_callback
 [`net.createServer()`]: net.html#net_net_createserver_options_connectionlistener
 [`net.Server.address()`]: net.html#net_server_address
 [`net.Server`]: net.html#net_class_net_server
@@ -1781,7 +1779,7 @@ where `secureSocket` has the same API as `pair.cleartext`.
 [`server.getTicketKeys()`]: #tls_server_getticketkeys
 [`server.listen()`]: net.html#net_server_listen
 [`server.setTicketKeys()`]: #tls_server_setticketkeys_keys
-[`socket.setTimeout(timeout)`]: #net_socket_settimeout_timeout_callback
+[`socket.connect()`]: net.html#net_socket_connect_options_connectlistener
 [`tls.DEFAULT_ECDH_CURVE`]: #tls_tls_default_ecdh_curve
 [`tls.DEFAULT_MAX_VERSION`]: #tls_tls_default_max_version
 [`tls.DEFAULT_MIN_VERSION`]: #tls_tls_default_min_version

lib/_tls_wrap.js

@@ -1420,23 +1420,13 @@ exports.connect = function connect(...args) {
     tlssock.once('secureConnect', cb);
 
   if (!options.socket) {
-    // If user provided the socket, its their responsibility to manage its
+    // If user provided the socket, it's their responsibility to manage its
     // connectivity. If we created one internally, we connect it.
-    const connectOpt = {
-      path: options.path,
-      port: options.port,
-      host: options.host,
-      family: options.family,
-      localAddress: options.localAddress,
-      localPort: options.localPort,
-      lookup: options.lookup
-    };
-
     if (options.timeout) {
       tlssock.setTimeout(options.timeout);
     }
 
-    tlssock.connect(connectOpt, tlssock._start);
+    tlssock.connect(options, tlssock._start);
   }
 
   tlssock._releaseControl();

test/parallel/test-tls-connect-hints-option.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const common = require('../common');
+
+// This test verifies that `tls.connect()` honors the `hints` option.
+
+if (!common.hasCrypto)
+  common.skip('missing crypto');
+
+const assert = require('assert');
+const dns = require('dns');
+const tls = require('tls');
+
+const hints = 512;
+
+assert.notStrictEqual(hints, dns.ADDRCONFIG);
+assert.notStrictEqual(hints, dns.V4MAPPED);
+assert.notStrictEqual(hints, dns.ADDRCONFIG | dns.V4MAPPED);
+
+tls.connect({
+  lookup: common.mustCall((host, options) => {
+    assert.strictEqual(host, 'localhost');
+    assert.deepStrictEqual(options, { family: undefined, hints });
+  }),
+  hints
+});