dns: add promisified dns module

PR-URL: https://github.com/nodejs/node/pull/21264
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

1 files changed, 466 insertions, 0 deletions

diff --git a/doc/api/dns.md b/doc/api/dns.md
index 8d47556d7c..624bcc279d 100644
--- a/doc/api/dns.md
+++ b/doc/api/dns.md
@@ -568,6 +568,456 @@ An error will be thrown if an invalid address is provided.
 The `dns.setServers()` method must not be called while a DNS query is in
 progress.
 
+## DNS Promises API
+
+> Stability: 1 - Experimental
+
+The `dns.promises` API provides an alternative set of asynchronous DNS methods
+that return `Promise` objects rather than using callbacks. The API is accessible
+via `require('dns').promises`.
+
+### Class: dnsPromises.Resolver
+<!-- YAML
+added: REPLACEME
+-->
+
+An independent resolver for DNS requests.
+
+Note that creating a new resolver uses the default server settings. Setting
+the servers used for a resolver using
+[`resolver.setServers()`][`dnsPromises.setServers()`] does not affect
+other resolvers:
+
+```js
+const { Resolver } = require('dns').promises;
+const resolver = new Resolver();
+resolver.setServers(['4.4.4.4']);
+
+// This request will use the server at 4.4.4.4, independent of global settings.
+resolver.resolve4('example.org').then((addresses) => {
+  // ...
+});
+
+// Alternatively, the same code can be written using async-await style.
+(async function() {
+  const addresses = await resolver.resolve4('example.org');
+})();
+```
+
+The following methods from the `dnsPromises` API are available:
+
+* [`resolver.getServers()`][`dnsPromises.getServers()`]
+* [`resolver.setServers()`][`dnsPromises.setServers()`]
+* [`resolver.resolve()`][`dnsPromises.resolve()`]
+* [`resolver.resolve4()`][`dnsPromises.resolve4()`]
+* [`resolver.resolve6()`][`dnsPromises.resolve6()`]
+* [`resolver.resolveAny()`][`dnsPromises.resolveAny()`]
+* [`resolver.resolveCname()`][`dnsPromises.resolveCname()`]
+* [`resolver.resolveMx()`][`dnsPromises.resolveMx()`]
+* [`resolver.resolveNaptr()`][`dnsPromises.resolveNaptr()`]
+* [`resolver.resolveNs()`][`dnsPromises.resolveNs()`]
+* [`resolver.resolvePtr()`][`dnsPromises.resolvePtr()`]
+* [`resolver.resolveSoa()`][`dnsPromises.resolveSoa()`]
+* [`resolver.resolveSrv()`][`dnsPromises.resolveSrv()`]
+* [`resolver.resolveTxt()`][`dnsPromises.resolveTxt()`]
+* [`resolver.reverse()`][`dnsPromises.reverse()`]
+
+#### resolver.cancel()
+<!-- YAML
+added: REPLACEME
+-->
+
+Cancel all outstanding DNS queries made by this resolver. The corresponding
+`Promise`s will be rejected with an error with code `ECANCELLED`.
+
+### dnsPromises.getServers()
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {string[]}
+
+Returns an array of IP address strings, formatted according to [rfc5952][],
+that are currently configured for DNS resolution. A string will include a port
+section if a custom port is used.
+
+<!-- eslint-disable semi-->
+```js
+[
+  '4.4.4.4',
+  '2001:4860:4860::8888',
+  '4.4.4.4:1053',
+  '[2001:4860:4860::8888]:1053'
+]
+```
+
+### dnsPromises.lookup(hostname[, options])
+<!-- YAML
+added: REPLACEME
+-->
+- `hostname` {string}
+- `options` {integer | Object}
+  - `family` {integer} The record family. Must be `4` or `6`. IPv4
+    and IPv6 addresses are both returned by default.
+  - `hints` {number} One or more [supported `getaddrinfo` flags][]. Multiple
+    flags may be passed by bitwise `OR`ing their values.
+  - `all` {boolean} When `true`, the `Promise` is resolved with all addresses in
+    an array. Otherwise, returns a single address. **Default:** `false`.
+  - `verbatim` {boolean} When `true`, the `Promise` is resolved with IPv4 and
+    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 }`.
+
+Resolves a hostname (e.g. `'nodejs.org'`) into the first found A (IPv4) or
+AAAA (IPv6) record. All `option` properties are optional. If `options` is an
+integer, then it must be `4` or `6` – if `options` is not provided, then IPv4
+and IPv6 addresses are both returned if found.
+
+With the `all` option set to `true`, the `Promise` is resolved with `addresses`
+being an array of objects with the properties `address` and `family`.
+
+On error, the `Promise` is rejected with an [`Error`][] object, where `err.code`
+is the error code.
+Keep in mind that `err.code` will be set to `'ENOENT'` not only when
+the hostname does not exist but also when the lookup fails in other ways
+such as no available file descriptors.
+
+[`dnsPromises.lookup()`][] does not necessarily have anything to do with the DNS
+protocol. The implementation uses an operating system facility that can
+associate names with addresses, and vice versa. This implementation can have
+subtle but important consequences on the behavior of any Node.js program. Please
+take some time to consult the [Implementation considerations section][] before
+using `dnsPromises.lookup()`.
+
+Example usage:
+
+```js
+const dns = require('dns');
+const dnsPromises = dns.promises;
+const options = {
+  family: 6,
+  hints: dns.ADDRCONFIG | dns.V4MAPPED,
+};
+
+dnsPromises.lookup('example.com', options).then((result) => {
+  console.log('address: %j family: IPv%s', result.address, result.family);
+  // address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6
+});
+
+// When options.all is true, the result will be an Array.
+options.all = true;
+dnsPromises.lookup('example.com', options).then((result) => {
+  console.log('addresses: %j', result);
+  // addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}]
+});
+```
+
+### dnsPromises.lookupService(address, port)
+<!-- YAML
+added: REPLACEME
+-->
+- `address` {string}
+- `port` {number}
+
+Resolves the given `address` and `port` into a hostname and service using
+the operating system's underlying `getnameinfo` implementation.
+
+If `address` is not a valid IP address, a `TypeError` will be thrown.
+The `port` will be coerced to a number. If it is not a legal port, a `TypeError`
+will be thrown.
+
+On error, the `Promise` is rejected with an [`Error`][] object, where `err.code`
+is the error code.
+
+```js
+const dnsPromises = require('dns').promises;
+dnsPromises.lookupService('127.0.0.1', 22).then((result) => {
+  console.log(result.hostname, result.service);
+  // Prints: localhost ssh
+});
+```
+
+### dnsPromises.resolve(hostname[, rrtype])
+<!-- YAML
+added: REPLACEME
+-->
+- `hostname` {string} Hostname to resolve.
+- `rrtype` {string} Resource record type. **Default:** `'A'`.
+
+Uses the DNS protocol to resolve a hostname (e.g. `'nodejs.org'`) into an array
+of the resource records. When successful, the `Promise` is resolved with an
+array of resource records. The type and structure of individual results vary
+based on `rrtype`:
+
+|  `rrtype` | `records` contains             | Result type | Shorthand method         |
+|-----------|--------------------------------|-------------|--------------------------|
+| `'A'`     | IPv4 addresses (default)       | {string}    | [`dnsPromises.resolve4()`][]     |
+| `'AAAA'`  | IPv6 addresses                 | {string}    | [`dnsPromises.resolve6()`][]     |
+| `'CNAME'` | canonical name records         | {string}    | [`dnsPromises.resolveCname()`][] |
+| `'MX'`    | mail exchange records          | {Object}    | [`dnsPromises.resolveMx()`][]    |
+| `'NAPTR'` | name authority pointer records | {Object}    | [`dnsPromises.resolveNaptr()`][] |
+| `'NS'`    | name server records            | {string}    | [`dnsPromises.resolveNs()`][]    |
+| `'PTR'`   | pointer records                | {string}    | [`dnsPromises.resolvePtr()`][]   |
+| `'SOA'`   | start of authority records     | {Object}    | [`dnsPromises.resolveSoa()`][]   |
+| `'SRV'`   | service records                | {Object}    | [`dnsPromises.resolveSrv()`][]   |
+| `'TXT'`   | text records                   | {string[]}  | [`dnsPromises.resolveTxt()`][]   |
+| `'ANY'`   | any records                    | {Object}    | [`dnsPromises.resolveAny()`][]   |
+
+On error, the `Promise` is rejected with an [`Error`][] object, where `err.code`
+is one of the [DNS error codes](#dns_error_codes).
+
+### dnsPromises.resolve4(hostname[, options])
+<!-- YAML
+added: REPLACEME
+-->
+- `hostname` {string} Hostname to resolve.
+- `options` {Object}
+  - `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record.
+    When `true`, the `Promise` is resolved with an array of
+    `{ address: '1.2.3.4', ttl: 60 }` objects rather than an array of strings,
+    with the TTL expressed in seconds.
+
+Uses the DNS protocol to resolve IPv4 addresses (`A` records) for the
+`hostname`. On success, the `Promise` is resolved with an array of IPv4
+addresses (e.g. `['74.125.79.104', '74.125.79.105', '74.125.79.106']`).
+
+### dnsPromises.resolve6(hostname[, options])
+<!-- YAML
+added: REPLACEME
+-->
+- `hostname` {string} Hostname to resolve.
+- `options` {Object}
+  - `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record.
+    When `true`, the `Promise` is resolved with an array of
+    `{ address: '0:1:2:3:4:5:6:7', ttl: 60 }` objects rather than an array of
+    strings, with the TTL expressed in seconds.
+
+Uses the DNS protocol to resolve IPv6 addresses (`AAAA` records) for the
+`hostname`. On success, the `Promise` is resolved with an array of IPv6
+addresses.
+
+### dnsPromises.resolveCname(hostname)
+<!-- YAML
+added: REPLACEME
+-->
+- `hostname` {string}
+
+Uses the DNS protocol to resolve `CNAME` records for the `hostname`. On success,
+the `Promise` is resolved with an array of canonical name records available for
+the `hostname` (e.g. `['bar.example.com']`).
+
+### dnsPromises.resolveMx(hostname)
+<!-- YAML
+added: REPLACEME
+-->
+- `hostname` {string}
+
+Uses the DNS protocol to resolve mail exchange records (`MX` records) for the
+`hostname`. On success, the `Promise` is resolved with an array of objects
+containing both a `priority` and `exchange` property (e.g.
+`[{priority: 10, exchange: 'mx.example.com'}, ...]`).
+
+### dnsPromises.resolveNaptr(hostname)
+<!-- YAML
+added: REPLACEME
+-->
+- `hostname` {string}
+
+Uses the DNS protocol to resolve regular expression based records (`NAPTR`
+records) for the `hostname`. On success, the `Promise` is resolved with an array
+of objects with the following properties:
+
+* `flags`
+* `service`
+* `regexp`
+* `replacement`
+* `order`
+* `preference`
+
+<!-- eslint-skip -->
+```js
+{
+  flags: 's',
+  service: 'SIP+D2U',
+  regexp: '',
+  replacement: '_sip._udp.example.com',
+  order: 30,
+  preference: 100
+}
+```
+
+### dnsPromises.resolveNs(hostname)
+<!-- YAML
+added: REPLACEME
+-->
+- `hostname` {string}
+
+Uses the DNS protocol to resolve name server records (`NS` records) for the
+`hostname`. On success, the `Promise` is resolved with an array of name server
+records available for `hostname` (e.g.
+`['ns1.example.com', 'ns2.example.com']`).
+
+### dnsPromises.resolvePtr(hostname)
+<!-- YAML
+added: REPLACEME
+-->
+- `hostname` {string}
+
+Uses the DNS protocol to resolve pointer records (`PTR` records) for the
+`hostname`. On success, the `Promise` is resolved with an array of strings
+containing the reply records.
+
+### dnsPromises.resolveSoa(hostname)
+<!-- YAML
+added: REPLACEME
+-->
+- `hostname` {string}
+
+Uses the DNS protocol to resolve a start of authority record (`SOA` record) for
+the `hostname`. On success, the `Promise` is resolved with an object with the
+following properties:
+
+* `nsname`
+* `hostmaster`
+* `serial`
+* `refresh`
+* `retry`
+* `expire`
+* `minttl`
+
+<!-- eslint-skip -->
+```js
+{
+  nsname: 'ns.example.com',
+  hostmaster: 'root.example.com',
+  serial: 2013101809,
+  refresh: 10000,
+  retry: 2400,
+  expire: 604800,
+  minttl: 3600
+}
+```
+
+### dnsPromises.resolveSrv(hostname)
+<!-- YAML
+added: REPLACEME
+-->
+- `hostname` {string}
+
+Uses the DNS protocol to resolve service records (`SRV` records) for the
+`hostname`. On success, the `Promise` is resolved with an array of objects with
+the following properties:
+
+* `priority`
+* `weight`
+* `port`
+* `name`
+
+<!-- eslint-skip -->
+```js
+{
+  priority: 10,
+  weight: 5,
+  port: 21223,
+  name: 'service.example.com'
+}
+```
+
+### dnsPromises.resolveTxt(hostname)
+<!-- YAML
+added: REPLACEME
+-->
+- `hostname` {string}
+
+Uses the DNS protocol to resolve text queries (`TXT` records) for the
+`hostname`. On success, the `Promise` is resolved with a two-dimensional array
+of the text records available for `hostname` (e.g.
+`[ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]`). Each sub-array contains TXT chunks of
+one record. Depending on the use case, these could be either joined together or
+treated separately.
+
+### dnsPromises.resolveAny(hostname)
+<!-- YAML
+added: REPLACEME
+-->
+- `hostname` {string}
+
+Uses the DNS protocol to resolve all records (also known as `ANY` or `*` query).
+On success, the `Promise` is resolved with an array containing various types of
+records. Each object has a property `type` that indicates the type of the
+current record. And depending on the `type`, additional properties will be
+present on the object:
+
+| Type | Properties |
+|------|------------|
+| `'A'` | `address`/`ttl` |
+| `'AAAA'` | `address`/`ttl` |
+| `'CNAME'` | `value` |
+| `'MX'` | Refer to [`dnsPromises.resolveMx()`][] |
+| `'NAPTR'` | Refer to [`dnsPromises.resolveNaptr()`][] |
+| `'NS'` | `value` |
+| `'PTR'` | `value` |
+| `'SOA'` | Refer to [`dnsPromises.resolveSoa()`][] |
+| `'SRV'` | Refer to [`dnsPromises.resolveSrv()`][] |
+| `'TXT'` | This type of record contains an array property called `entries` which refers to [`dnsPromises.resolveTxt()`][], e.g. `{ entries: ['...'], type: 'TXT' }` |
+
+Here is an example of the result object:
+
+<!-- eslint-disable semi -->
+```js
+[ { type: 'A', address: '127.0.0.1', ttl: 299 },
+  { type: 'CNAME', value: 'example.com' },
+  { type: 'MX', exchange: 'alt4.aspmx.l.example.com', priority: 50 },
+  { type: 'NS', value: 'ns1.example.com' },
+  { type: 'TXT', entries: [ 'v=spf1 include:_spf.example.com ~all' ] },
+  { type: 'SOA',
+    nsname: 'ns1.example.com',
+    hostmaster: 'admin.example.com',
+    serial: 156696742,
+    refresh: 900,
+    retry: 900,
+    expire: 1800,
+    minttl: 60 } ]
+```
+
+### dnsPromises.reverse(ip)
+<!-- YAML
+added: REPLACEME
+-->
+- `ip` {string}
+
+Performs a reverse DNS query that resolves an IPv4 or IPv6 address to an
+array of hostnames.
+
+On error, the `Promise` is rejected with an [`Error`][] object, where `err.code`
+is one of the [DNS error codes](#dns_error_codes).
+
+### dnsPromises.setServers(servers)
+<!-- YAML
+added: REPLACEME
+-->
+- `servers` {string[]} array of [rfc5952][] formatted addresses
+
+Sets the IP address and port of servers to be used when performing DNS
+resolution. The `servers` argument is an array of [rfc5952][] formatted
+addresses. If the port is the IANA default DNS port (53) it can be omitted.
+
+```js
+dnsPromises.setServers([
+  '4.4.4.4',
+  '[2001:4860:4860::8888]',
+  '4.4.4.4:1053',
+  '[2001:4860:4860::8888]:1053'
+]);
+```
+
+An error will be thrown if an invalid address is provided.
+
+The `dnsPromises.setServers()` method must not be called while a DNS query is in
+progress.
+
 ## Error codes
 
 Each DNS query can return one of the following error codes:
@@ -659,6 +1109,22 @@ uses. For instance, _they do not use the configuration from `/etc/hosts`_.
 [`dns.resolveTxt()`]: #dns_dns_resolvetxt_hostname_callback
 [`dns.reverse()`]: #dns_dns_reverse_ip_callback
 [`dns.setServers()`]: #dns_dns_setservers_servers
+[`dnsPromises.getServers()`]: #dns_dnspromises_getservers
+[`dnsPromises.lookup()`]: #dns_dnspromises_lookup_hostname_options
+[`dnsPromises.resolve()`]: #dns_dnspromises_resolve_hostname_rrtype
+[`dnsPromises.resolve4()`]: #dns_dnspromises_resolve4_hostname_options
+[`dnsPromises.resolve6()`]: #dns_dnspromises_resolve6_hostname_options
+[`dnsPromises.resolveAny()`]: #dns_dnspromises_resolveany_hostname
+[`dnsPromises.resolveCname()`]: #dns_dnspromises_resolvecname_hostname
+[`dnsPromises.resolveMx()`]: #dns_dnspromises_resolvemx_hostname
+[`dnsPromises.resolveNaptr()`]: #dns_dnspromises_resolvenaptr_hostname
+[`dnsPromises.resolveNs()`]: #dns_dnspromises_resolvens_hostname
+[`dnsPromises.resolvePtr()`]: #dns_dnspromises_resolveptr_hostname
+[`dnsPromises.resolveSoa()`]: #dns_dnspromises_resolvesoa_hostname
+[`dnsPromises.resolveSrv()`]: #dns_dnspromises_resolvesrv_hostname
+[`dnsPromises.resolveTxt()`]: #dns_dnspromises_resolvetxt_hostname
+[`dnsPromises.reverse()`]: #dns_dnspromises_reverse_ip
+[`dnsPromises.setServers()`]: #dns_dnspromises_setservers_servers
 [`socket.connect()`]: net.html#net_socket_connect_options_connectlistener
 [`util.promisify()`]: util.html#util_util_promisify_original
 [DNS error codes]: #dns_error_codes