From 5fbe6692c8d3b7c6b5451c59fa26b569cefaf621 Mon Sep 17 00:00:00 2001 From: Julien Gilli Date: Tue, 18 Nov 2014 12:56:28 -0800 Subject: [PATCH 1/2] doc: improve dns module's documentation Make the difference between dns.lookup and other functions even clearer. --- doc/api/dns.markdown | 87 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 77 insertions(+), 10 deletions(-) diff --git a/doc/api/dns.markdown b/doc/api/dns.markdown index 435516d4c9c..fd643d28e6d 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,43 @@ 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. + +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`_. From 9cc27f6305c17b872ed5e186157207e6fe8ac2ee Mon Sep 17 00:00:00 2001 From: Julien Gilli Date: Thu, 27 Nov 2014 17:09:29 -0800 Subject: [PATCH 2/2] Make dns.lookup's implementation details clearer. --- doc/api/dns.markdown | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/api/dns.markdown b/doc/api/dns.markdown index fd643d28e6d..a959d55d69b 100644 --- a/doc/api/dns.markdown +++ b/doc/api/dns.markdown @@ -193,9 +193,10 @@ 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. -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 +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