dns: allow `--dns-result-order` to change default dns verbatim

Allow the `--dns-result-order` option to change the default value
of verbatim in `dns.lookup()`. This is useful when running
Node.js in ipv6-only environments to avoid possible ENETUNREACH
errors.

PR-URL: https://github.com/nodejs/node/pull/38099
Refs: https://github.com/nodejs/node/issues/31566
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>

1 files changed, 44 insertions, 4 deletions

diff --git a/doc/api/dns.md b/doc/api/dns.md
index a5a4432e2d9..72c7e09ee00 100644
--- a/doc/api/dns.md
+++ b/doc/api/dns.md
@@ -186,8 +186,9 @@ changes:
     addresses in the order the DNS resolver returned them. When `false`,
     IPv4 addresses are placed before IPv6 addresses.
     **Default:** currently `false` (addresses are reordered) but this is
-    expected to change in the not too distant future.
-    New code should use `{ verbatim: true }`.
+    expected to change in the not too distant future. Default value is
+    configurable using [`dns.setDefaultResultOrder()`][] or
+    [`--dns-result-order`][]. New code should use `{ verbatim: true }`.
 * `callback` {Function}
   * `err` {Error}
   * `address` {string} A string representation of an IPv4 or IPv6 address.
@@ -633,6 +634,23 @@ array of host names.
 On error, `err` is an [`Error`][] object, where `err.code` is
 one of the [DNS error codes][].
 
+## `dns.setDefaultResultOrder(order)`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `order` {string} must be `'ipv4first'` or `'verbatim'`.
+
+Set the default value of `verbatim` in [`dns.lookup()`][] and
+[`dnsPromises.lookup()`][]. The value could be:
+* `ipv4first`: sets default `verbatim` `false`.
+* `verbatim`: sets default `verbatim` `true`.
+
+The default is `ipv4first` and [`dns.setDefaultResultOrder()`][] have higher
+priority than [`--dns-result-order`][]. When using [worker threads][],
+[`dns.setDefaultResultOrder()`][] from the main thread won't affect the default
+dns orders in workers.
+
 ## `dns.setServers(servers)`
 <!-- YAML
 added: v0.11.3
@@ -783,8 +801,9 @@ added: v10.6.0
     IPv6 addresses in the order the DNS resolver returned them. When `false`,
     IPv4 addresses are placed before IPv6 addresses.
     **Default:** currently `false` (addresses are reordered) but this is
-    expected to change in the not too distant future.
-    New code should use `{ verbatim: true }`.
+    expected to change in the not too distant future. Default value is
+    configurable using [`dns.setDefaultResultOrder()`][] or
+    [`--dns-result-order`][]. New code should use `{ verbatim: true }`.
 
 Resolves a host name (e.g. `'nodejs.org'`) into the first found A (IPv4) or
 AAAA (IPv6) record. All `option` properties are optional. If `options` is an
@@ -1140,6 +1159,23 @@ array of host names.
 On error, the `Promise` is rejected with an [`Error`][] object, where `err.code`
 is one of the [DNS error codes](#dns_error_codes).
 
+### `dnsPromises.setDefaultResultOrder(order)`
+<!-- YAML
+added: REPLACEME
+-->
+
+* `order` {string} must be `'ipv4first'` or `'verbatim'`.
+
+Set the default value of `verbatim` in [`dns.lookup()`][] and
+[`dnsPromises.lookup()`][]. The value could be:
+* `ipv4first`: sets default `verbatim` `false`.
+* `verbatim`: sets default `verbatim` `true`.
+
+The default is `ipv4first` and [`dnsPromises.setDefaultResultOrder()`][] have
+higher priority than [`--dns-result-order`][]. When using [worker threads][],
+[`dnsPromises.setDefaultResultOrder()`][] from the main thread won't affect the
+default dns orders in workers.
+
 ### `dnsPromises.setServers(servers)`
 <!-- YAML
 added: v10.6.0
@@ -1249,6 +1285,7 @@ uses. For instance, _they do not use the configuration from `/etc/hosts`_.
 [Implementation considerations section]: #dns_implementation_considerations
 [RFC 5952]: https://tools.ietf.org/html/rfc5952#section-6
 [RFC 8482]: https://tools.ietf.org/html/rfc8482
+[`--dns-result-order`]: cli.md#cli_dns_result_order_order
 [`Error`]: errors.md#errors_class_error
 [`UV_THREADPOOL_SIZE`]: cli.md#cli_uv_threadpool_size_size
 [`dgram.createSocket()`]: dgram.md#dgram_dgram_createsocket_options_callback
@@ -1268,6 +1305,7 @@ uses. For instance, _they do not use the configuration from `/etc/hosts`_.
 [`dns.resolveSrv()`]: #dns_dns_resolvesrv_hostname_callback
 [`dns.resolveTxt()`]: #dns_dns_resolvetxt_hostname_callback
 [`dns.reverse()`]: #dns_dns_reverse_ip_callback
+[`dns.setDefaultResultOrder()`]: #dns_dns_setdefaultresultorder_order
 [`dns.setServers()`]: #dns_dns_setservers_servers
 [`dnsPromises.getServers()`]: #dns_dnspromises_getservers
 [`dnsPromises.lookup()`]: #dns_dnspromises_lookup_hostname_options
@@ -1285,7 +1323,9 @@ uses. For instance, _they do not use the configuration from `/etc/hosts`_.
 [`dnsPromises.resolveSrv()`]: #dns_dnspromises_resolvesrv_hostname
 [`dnsPromises.resolveTxt()`]: #dns_dnspromises_resolvetxt_hostname
 [`dnsPromises.reverse()`]: #dns_dnspromises_reverse_ip
+[`dnsPromises.setDefaultResultOrder()`]: #dns_dnspromises_setdefaultresultorder_order
 [`dnsPromises.setServers()`]: #dns_dnspromises_setservers_servers
 [`socket.connect()`]: net.md#net_socket_connect_options_connectlistener
 [`util.promisify()`]: util.md#util_util_promisify_original
 [supported `getaddrinfo` flags]: #dns_supported_getaddrinfo_flags
+[worker threads]: worker_threads.md