Node.js Reference ยท HTTP, HTTPS, net, TLS, dgram and dns
Node.js dns.Resolver class
Reference for the dns.Resolver class in Node.js: use your own DNS servers, set timeouts and retries, cancel pending queries and isolate settings.
A Resolver is an independent DNS client. It has its own list of servers and its own timeout and retry settings, and it offers the same resolve*() and reverse() methods as the dns module. The module-level functions share one hidden default resolver; creating your own lets you query a specific server (a company DNS server, 1.1.1.1, a test server) without changing global state.
A resolver can also cancel everything that is in flight with cancel(), which the module functions cannot do. Both node:dns and node:dns/promises export a Resolver class: the first reports results in callbacks, the second in promises.
import { Resolver } from 'node:dns/promises'; const resolver = new Resolver({ timeout: 2000, tries: 2 }); resolver.setServers(['1.1.1.1', '8.8.8.8']);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
new dns.Resolver([options]) new dnsPromises.Resolver([options])
| Option | Description |
|---|---|
timeout |
Milliseconds to wait for a reply before retrying. The default -1 uses the c-ares default. |
tries |
How many times each server is tried before giving up. Default 4. |
Methods (the promise version returns promises instead of taking callbacks):
| Method | Description |
|---|---|
getServers() |
Array of strings such as '192.0.2.53' or '198.51.100.53:5353' (port 53 is omitted). |
setServers(servers) |
Replace the server list. Entries are 'address' or 'address:port'; IPv6 with a port is '[2001:db8::53]:5353'. Throws ERR_INVALID_IP_ADDRESS for a bad entry. Do not call it while queries are running. |
setLocalAddress([ipv4][, ipv6]) |
Choose the local address that outgoing queries use. |
cancel() |
Fail every outstanding query with code ECANCELLED. |
resolve(), resolve4(), resolve6(), resolveAny(), resolveCaa(), resolveCname(), resolveMx(), resolveNaptr(), resolveNs(), resolvePtr(), resolveSoa(), resolveSrv(), resolveTlsa(), resolveTxt(), reverse() |
Same as the module functions, see dns.resolve() and dns.reverse(). |
Errors: queries fail with codes such as ENOTFOUND, ENODATA, ETIMEOUT, ECONNREFUSED and ECANCELLED.
Usage notes
- A new resolver starts with the system's servers, the same ones
dns.getServers()shows. CallsetServers()only if you want something different. - There is no
lookup()on a resolver.dns.lookup()always uses the operating system, so aResolvercannot change it. To make HTTP clients use your servers, resolve the name yourself and pass a customlookupfunction tonet.connect()or an agent. - Set
timeoutandtriesdeliberately. With the defaults a dead server costs many seconds. A short timeout with two tries fails faster and lets the next server answer. - Use one resolver per purpose. Sharing a long-lived resolver for a service is cheap; creating one per request is not necessary.
cancel()is the only way to stop a query. Promise-based calls do not accept anAbortSignal; cancel the resolver, or race the call against a timer.- IPv6 servers work in
setServers()and the entries come back fromgetServers()exactly as stored. dns.setServers()on the module changes the default resolver for the entire process, including servers used bydns.resolve*()calls in your dependencies. Prefer your ownResolverin libraries.
Related
dns.resolve(),dns.reverse(),dns.lookup(),dns/promises- Lessons: UDP and DNS