diff options
| -rw-r--r-- | doc/api/dns.markdown | 88 |
1 files changed, 78 insertions, 10 deletions
diff --git a/doc/api/dns.markdown b/doc/api/dns.markdown index 435516d4c9c..a959d55d69b 100644 --- a/doc/api/dns.markdown +++ b/doc/api/dns.markdown @@ -2,16 +2,32 @@ Stability: 3 - Stable -Use `require('dns')` to access this module. All methods in the dns module use -C-Ares except for `dns.lookup` which uses `getaddrinfo(3)` in a thread pool. -C-Ares is much faster than `getaddrinfo(3)` but, due to the way it is -configured by node, it doesn't use the same set of system configuration files. -For instance, _C- Ares will not use the configuration from `/etc/hosts`_. As a -result, __only `dns.lookup` should be expected to behave like other programs -running on the same system regarding name resolution.__ When a user does -`net.connect(80, 'google.com')` or `http.get({ host: 'google.com' })` the -`dns.lookup` method is used. Users who need to do a large number of lookups -quickly should use the methods that go through C-Ares. +Use `require('dns')` to access this module. + +This module contains functions that belong to two different categories: + +1) Functions that use the underlying operating system facilities to perform +name resolution, and that do not necessarily do any network communication. +This category contains only one function: `dns.lookup`. __Developers looking +to perform name resolution in the same way that other applications on the same +operating system behave should use `dns.lookup`.__ + +Here is an example that does a lookup of `www.google.com`. + + var dns = require('dns'); + + dns.lookup('www.google.com', function onLookup(err, addresses, family) { + console.log('addresses:', addresses); + }); + +2) Functions that connect to an actual DNS server to perform name resolution, +and that _always_ use the network to perform DNS queries. This category +contains all functions in the `dns` module but `dns.lookup`. These functions +do not use the same set of configuration files than what `dns.lookup` uses. +For instance, _they do not use the configuration from `/etc/hosts`_. These +functions should be used by developers who do not want to use the underlying +operating system's facilities for name resolution, and instead want to +_always_ perform DNS queries. Here is an example which resolves `'www.google.com'` then reverse resolves the IP addresses which are returned. @@ -34,6 +50,10 @@ resolves the IP addresses which are returned. }); }); +There are subtle consequences in choosing one or another, please consult the +[Implementation considerations section](#dns_implementation_considerations) +for more information. + ## dns.lookup(domain, [family], callback) Resolves a domain (e.g. `'google.com'`) into the first found A (IPv4) or @@ -51,6 +71,13 @@ Keep in mind that `err.code` will be set to `'ENOENT'` not only when the domain does not exist but also when the lookup fails in other ways such as no available file descriptors. +`dns.lookup` doesn't necessarily have anything to do with the DNS protocol. +It's only an operating system facility that can associate name with addresses, +and vice versa. + +Its 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](#dns_implementation_considerations) before using it. ## dns.resolve(domain, [rrtype], callback) @@ -149,3 +176,44 @@ Each DNS query can return one of the following error codes: - `dns.ADDRGETNETWORKPARAMS`: Could not find GetNetworkParams function. - `dns.CANCELLED`: DNS query cancelled. +## Implementation considerations + +Although `dns.lookup` and `dns.resolve*/dns.reverse` functions have the same +goal of associating a network name with a network address (or vice versa), +their behavior is quite different. These differences can have subtle but +significant consequences on the behavior of Node.js programs. + +### dns.lookup + +Under the hood, `dns.lookup` uses the same operating system facilities as most +other programs. For instance, `dns.lookup` will almost always resolve a given +name the same way as the `ping` command. On most POSIX-like operating systems, +the behavior of the `dns.lookup` function can be tweaked by changing settings +in `nsswitch.conf(5)` and/or `resolv.conf(5)`, but be careful that changing +these files will change the behavior of all other programs running on the same +operating system. + +Though the call will be asynchronous from JavaScript's perspective, it is +implemented as a synchronous call to `getaddrinfo(3)` that runs on libuv's +threadpool. Because libuv's threadpool has a fixed size, it means that if for +whatever reason the call to `getaddrinfo(3)` takes a long time, other +operations that could run on libuv's threadpool (such as filesystem +operations) will experience degraded performance. In order to mitigate this +issue, one potential solution is to increase the size of libuv's threadpool by +setting the 'UV_THREADPOOL_SIZE' environment variable to a value greater than +4 (its current default value). For more information on libuv's threadpool, see +[the official libuv +documentation](http://docs.libuv.org/en/latest/threadpool.html). + +### dns.resolve, functions starting with dns.resolve and dns.reverse + +These functions are implemented quite differently than `dns.lookup`. They do +not use `getaddrinfo(3)` and they _always_ perform a DNS query on the network. +This network communication is always done asynchronously, and does not use +libuv's threadpool. + +As a result, these functions cannot have the same negative impact on other +processing that happens on libuv's threadpool that `dns.lookup` can have. + +They do not use the same set of configuration files than what `dns.lookup` +uses. For instance, _they do not use the configuration from `/etc/hosts`_. |