diff --git a/doc/api/dns.md b/doc/api/dns.md index 96d91b29ea3a30..ff825d53dc1e94 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -15,13 +15,22 @@ facilities to perform name resolution. It may not need to perform any network communication. To perform name resolution the way other applications on the same system do, use [`dns.lookup()`][]. -```js +```mjs +import dns from 'node:dns'; + +dns.lookup('example.org', (err, address, family) => { + console.log('address: %j family: IPv%s', address, family); +}); +// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6 +``` + +```cjs const dns = require('node:dns'); dns.lookup('example.org', (err, address, family) => { console.log('address: %j family: IPv%s', address, family); }); -// address: "93.184.216.34" family: IPv4 +// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6 ``` All other functions in the `node:dns` module connect to an actual DNS server to @@ -30,7 +39,26 @@ queries. These functions do not use the same set of configuration files used by [`dns.lookup()`][] (e.g. `/etc/hosts`). Use these functions to always perform DNS queries, bypassing other name-resolution facilities. -```js +```mjs +import dns from 'node:dns'; + +dns.resolve4('archive.org', (err, addresses) => { + if (err) throw err; + + console.log(`addresses: ${JSON.stringify(addresses)}`); + + addresses.forEach((a) => { + dns.reverse(a, (err, hostnames) => { + if (err) { + throw err; + } + console.log(`reverse for ${a}: ${JSON.stringify(hostnames)}`); + }); + }); +}); +``` + +```cjs const dns = require('node:dns'); dns.resolve4('archive.org', (err, addresses) => { @@ -64,7 +92,18 @@ the servers used for a resolver using [`resolver.setServers()`][`dns.setServers()`] does not affect other resolvers: -```js +```mjs +import { Resolver } from 'node:dns'; +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', (err, addresses) => { + // ... +}); +``` + +```cjs const { Resolver } = require('node:dns'); const resolver = new Resolver(); resolver.setServers(['4.4.4.4']); @@ -260,21 +299,38 @@ time to consult the [Implementation considerations section][] before using Example usage: -```js +```mjs +import dns from 'node:dns'; +const options = { + family: 6, + hints: dns.ADDRCONFIG | dns.V4MAPPED, +}; +dns.lookup('example.org', options, (err, address, family) => + console.log('address: %j family: IPv%s', address, family)); +// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6 + +// When options.all is true, the result will be an Array. +options.all = true; +dns.lookup('example.org', options, (err, addresses) => + console.log('addresses: %j', addresses)); +// addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}] +``` + +```cjs const dns = require('node:dns'); const options = { family: 6, hints: dns.ADDRCONFIG | dns.V4MAPPED, }; -dns.lookup('example.com', options, (err, address, family) => +dns.lookup('example.org', options, (err, address, family) => console.log('address: %j family: IPv%s', address, family)); -// address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6 +// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6 // When options.all is true, the result will be an Array. options.all = true; -dns.lookup('example.com', options, (err, addresses) => +dns.lookup('example.org', options, (err, addresses) => console.log('addresses: %j', addresses)); -// addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}] +// addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}] ``` If this method is invoked as its [`util.promisify()`][]ed version, and `all` @@ -331,7 +387,15 @@ will be thrown. On an error, `err` is an [`Error`][] object, where `err.code` is the error code. -```js +```mjs +import dns from 'node:dns'; +dns.lookupService('127.0.0.1', 22, (err, hostname, service) => { + console.log(hostname, service); + // Prints: localhost ssh +}); +``` + +```cjs const dns = require('node:dns'); dns.lookupService('127.0.0.1', 22, (err, hostname, service) => { console.log(hostname, service); @@ -898,7 +962,16 @@ the servers used for a resolver using [`resolver.setServers()`][`dnsPromises.setServers()`] does not affect other resolvers: -```js +```mjs +import { Resolver } from 'node: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. +const addresses = await resolver.resolve4('example.org'); +``` + +```cjs const { Resolver } = require('node:dns').promises; const resolver = new Resolver(); resolver.setServers(['4.4.4.4']); @@ -1028,7 +1101,28 @@ using `dnsPromises.lookup()`. Example usage: -```js +```mjs +import dns from 'node:dns'; +const dnsPromises = dns.promises; +const options = { + family: 6, + hints: dns.ADDRCONFIG | dns.V4MAPPED, +}; + +await dnsPromises.lookup('example.org', options).then((result) => { + console.log('address: %j family: IPv%s', result.address, result.family); + // address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6 +}); + +// When options.all is true, the result will be an Array. +options.all = true; +await dnsPromises.lookup('example.org', options).then((result) => { + console.log('addresses: %j', result); + // addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}] +}); +``` + +```cjs const dns = require('node:dns'); const dnsPromises = dns.promises; const options = { @@ -1036,16 +1130,16 @@ const options = { hints: dns.ADDRCONFIG | dns.V4MAPPED, }; -dnsPromises.lookup('example.com', options).then((result) => { +dnsPromises.lookup('example.org', 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 + // address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6 }); // When options.all is true, the result will be an Array. options.all = true; -dnsPromises.lookup('example.com', options).then((result) => { +dnsPromises.lookup('example.org', options).then((result) => { console.log('addresses: %j', result); - // addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}] + // addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}] }); ``` @@ -1068,7 +1162,14 @@ will be thrown. On error, the `Promise` is rejected with an [`Error`][] object, where `err.code` is the error code. -```js +```mjs +import dnsPromises from 'node:dns/promises'; +const result = await dnsPromises.lookupService('127.0.0.1', 22); + +console.log(result.hostname, result.service); // Prints: localhost ssh +``` + +```cjs const dnsPromises = require('node:dns').promises; dnsPromises.lookupService('127.0.0.1', 22).then((result) => { console.log(result.hostname, result.service);