Класс: dns.Resolver

Независимый резолвер для DNS-запросов.

При создании нового резолвера используются настройки сервера по умолчанию. Настройка серверов, используемых резолвером, с помощью resolver.setServers() не влияет на другие резолверы:

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) => {
  // ...
});

const { Resolver } = require('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) => {
  // ...
});

Доступны следующие методы модуля node:dns:

• resolver.getServers()
• resolver.resolve()
• resolver.resolve4()
• resolver.resolve6()
• resolver.resolveAny()
• resolver.resolveCaa()
• resolver.resolveCname()
• resolver.resolveMx()
• resolver.resolveNaptr()
• resolver.resolveNs()
• resolver.resolvePtr()
• resolver.resolveSoa()
• resolver.resolveSrv()
• resolver.resolveTlsa()
• resolver.resolveTxt()
• resolver.reverse()
• resolver.setServers()

dns.getServers()

• Возвращает: <string[]>

Возвращает массив строк с IP-адресами, отформатированными в соответствии с RFC 5952, которые в данный момент настроены для разрешения DNS-имен. Если используется пользовательский порт, строка будет содержать его номер.

[
  '8.8.8.8',
  '2001:4860:4860::8888',
  '8.8.8.8:1053',
  '[2001:4860:4860::8888]:1053',
] copy

dns.lookup(hostname[, options], callback)

• hostname <string>
• options <integer> | <Object>
  • family <integer> | <string> Семейство записи. Должно быть 4, 6 или 0. Для обратной совместимости значения 'IPv4' и 'IPv6' интерпретируются соответственно как 4 и 6. Значение 0 указывает, что возвращается адрес IPv4 или IPv6. Если значение 0 используется с { all: true } (см. ниже), возвращается один или оба адреса — IPv4 и IPv6, в зависимости от DNS-резолвера системы. По умолчанию: 0.
  • hints <number> Один или несколько поддерживаемых флагов getaddrinfo. Несколько флагов можно передать, объединив их значения побитовой операцией OR.
  • all <boolean> Если значение равно true, обратный вызов возвращает все разрешенные адреса в массиве. В противном случае возвращается один адрес. По умолчанию: false.
  • order <string> Если значение равно verbatim, разрешенные адреса возвращаются без сортировки. Если значение равно ipv4first, разрешенные адреса сортируются так, что адреса IPv4 идут перед адресами IPv6. Если значение равно ipv6first, разрешенные адреса сортируются так, что адреса IPv6 идут перед адресами IPv4. По умолчанию: verbatim (адреса не переупорядочиваются). Значение по умолчанию можно настроить с помощью dns.setDefaultResultOrder() или --dns-result-order.
  • verbatim <boolean> Если значение равно true, обратный вызов получает адреса IPv4 и IPv6 в том порядке, в котором их вернул DNS-резолвер. Если значение равно false, адреса IPv4 помещаются перед адресами IPv6. Этот параметр будет объявлен устаревшим в пользу order. Если указаны оба параметра, order имеет более высокий приоритет. В новом коде следует использовать только order. По умолчанию: true (адреса не переупорядочиваются). Значение по умолчанию можно настроить с помощью dns.setDefaultResultOrder() или --dns-result-order.
• callback <Function>
  • err <Error>
  • address <string> Строковое представление адреса IPv4 или IPv6.
  • family <integer> 4 или 6, обозначающие семейство address, либо 0, если адрес не является адресом IPv4 или IPv6. 0, вероятно, указывает на ошибку в службе разрешения имен, используемой операционной системой.

Разрешает имя хоста (например, 'nodejs.org') в первую найденную запись A (IPv4) или AAAA (IPv6). Все свойства option необязательны. Если options — целое число, оно должно быть равно 4 или 6; если options не задан, возвращаются найденные адреса IPv4, IPv6 или оба типа адресов.

Если для параметра all задано значение true, аргументы для callback меняются на (err, addresses), где addresses — массив объектов со свойствами address и family.

В случае ошибки err является объектом Error, где err.code — код ошибки. Обратите внимание, что err.code будет иметь значение 'ENOTFOUND' не только в том случае, если имя хоста не существует, но и при других сбоях поиска, например при отсутствии доступных файловых дескрипторов.

dns.lookup() не обязательно имеет отношение к протоколу DNS. Реализация использует средства операционной системы, которые могут сопоставлять имена с адресами и наоборот. Эта реализация может иметь тонкие, но важные последствия для поведения любой программы Node.js. Перед использованием dns.lookup() ознакомьтесь с разделом Особенности реализации.

Пример использования:

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}]

const dns = require('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}]

Если этот метод вызывается в версии, преобразованной с помощью util.promisify(), и для all не задано значение true, он возвращает Promise для Object со свойствами address и family.

dns.lookupService(address, port, callback)

• address <string>
• port <number>
• callback <Function>
  • err <Error>
  • hostname <string> например, example.com
  • service <string> например, http

Разрешает указанные address и port в имя хоста и службу с помощью встроенной реализации getnameinfo операционной системы.

Если address не является допустимым IP-адресом, будет выброшено исключение TypeError. Значение port будет преобразовано в число. Если это недопустимый порт, будет выброшено исключение TypeError.

В случае ошибки err является объектом Error, где err.code — код ошибки.

import dns from 'node:dns';
dns.lookupService('127.0.0.1', 22, (err, hostname, service) => {
  console.log(hostname, service);
  // Prints: localhost ssh
});

const dns = require('node:dns');
dns.lookupService('127.0.0.1', 22, (err, hostname, service) => {
  console.log(hostname, service);
  // Prints: localhost ssh
});

Если этот метод вызывается в версии, преобразованной с помощью util.promisify(), он возвращает Promise для Object со свойствами hostname и service.

dns.resolve(hostname[, rrtype], callback)

• hostname <string> Имя хоста для разрешения.
• rrtype <string> Тип ресурсной записи. По умолчанию: 'A'.
• callback <Function>
  • err <Error>
  • records <string[]> | <Object[]> | <Object>

Использует протокол DNS для разрешения имени хоста (например, 'nodejs.org') в массив ресурсных записей. Функция callback принимает аргументы (err, records). При успешном выполнении records будет массивом ресурсных записей. Тип и структура отдельных результатов зависят от rrtype:

В случае ошибки err является объектом Error, где err.code — один из кодов ошибок DNS.

dns.resolve4(hostname[, options], callback)

• hostname <string> Имя хоста для разрешения.
• options <Object>
  • ttl <boolean> Получает значение Time-To-Live (TTL) каждой записи. Если значение равно true, обратный вызов получает массив объектов { address: '1.2.3.4', ttl: 60 } вместо массива строк; значение TTL указывается в секундах.
• callback <Function>
  • err <Error>
  • addresses <string[]> | <Object[]>

Использует протокол DNS для разрешения адресов IPv4 (записей A) для hostname. Аргумент addresses, переданный функции callback, будет содержать массив адресов IPv4 (например, ['74.125.79.104', '74.125.79.105', '74.125.79.106']).

dns.resolve6(hostname[, options], callback)

• hostname <string> Имя хоста для разрешения.
• options <Object>
  • ttl <boolean> Получает значение Time-To-Live (TTL) каждой записи. Если значение равно true, обратный вызов получает массив объектов { address: '0:1:2:3:4:5:6:7', ttl: 60 } вместо массива строк; значение TTL указывается в секундах.
• callback <Function>
  • err <Error>
  • addresses <string[]> | <Object[]>

Использует протокол DNS для разрешения адресов IPv6 (записей AAAA) для hostname. Аргумент addresses, переданный функции callback, будет содержать массив адресов IPv6.

dns.resolveAny(hostname, callback)

• hostname <string>
• callback <Function>
  • err <Error>
  • ret <Object[]>

Использует протокол DNS для разрешения всех записей (также известных как запрос ANY или *). Аргумент ret, переданный функции callback, будет массивом, содержащим записи различных типов. У каждого объекта есть свойство type, указывающее тип текущей записи. В зависимости от type объект будет содержать дополнительные свойства:

Ниже приведен пример объекта ret, передаваемого функции обратного вызова:

[ { 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 } ] copy

Операторы DNS-серверов могут не отвечать на запросы ANY. Возможно, лучше вызывать отдельные методы, такие как dns.resolve4(), dns.resolveMx() и другие. Подробнее см. в документе RFC 8482.

dns.resolveCname(hostname, callback)

• hostname <string>
• callback <Function>
  • err <Error>
  • addresses <string[]>

Использует протокол DNS для разрешения записей CNAME для hostname. Аргумент addresses, переданный функции callback, будет содержать массив канонических записей имени, доступных для hostname (например, ['bar.example.com']).

dns.resolveCaa(hostname, callback)

• hostname <string>
• callback <Function>
  • err <Error>
  • records <Object[]>

Использует протокол DNS для разрешения записей CAA для hostname. Аргумент addresses, переданный функции callback, будет содержать массив записей авторизации центра сертификации, доступных для hostname (например, [{critical: 0, iodef: 'mailto:pki@example.com'}, {critical: 128, issue: 'pki.example.com'}]).

dns.resolveMx(hostname, callback)

• hostname <string>
• callback <Function>
  • err <Error>
  • addresses <Object[]>

Использует протокол DNS для разрешения записей почтового обмена (записей MX) для hostname. Аргумент addresses, переданный функции callback, будет содержать массив объектов со свойствами priority и exchange (например, [{priority: 10, exchange: 'mx.example.com'}, ...]).

dns.resolveNaptr(hostname, callback)

• hostname <string>
• callback <Function>
  • err <Error>
  • addresses <Object[]>

Использует протокол DNS для разрешения записей на основе регулярных выражений (записей NAPTR) для hostname. Аргумент addresses, переданный функции callback, будет содержать массив объектов со следующими свойствами:

• flags
• service
• regexp
• replacement
• order
• preference

{
  flags: 's',
  service: 'SIP+D2U',
  regexp: '',
  replacement: '_sip._udp.example.com',
  order: 30,
  preference: 100
} copy

dns.resolveNs(hostname, callback)

• hostname <string>
• callback <Function>
  • err <Error>
  • addresses <string[]>

Использует протокол DNS для разрешения записей сервера имен (записей NS) для hostname. Аргумент addresses, переданный функции callback, будет содержать массив записей серверов имен, доступных для hostname (например, ['ns1.example.com', 'ns2.example.com']).

dns.resolvePtr(hostname, callback)

• hostname <string>
• callback <Function>
  • err <Error>
  • addresses <string[]>

Использует протокол DNS для разрешения записей указателя (записей PTR) для hostname. Аргумент addresses, переданный функции callback, будет массивом строк, содержащих записи ответа.

dns.resolveSoa(hostname, callback)

• hostname <string>
• callback <Function>
  • err <Error>
  • address <Object>

Использует протокол DNS для разрешения записи начала полномочий (записи SOA) для hostname. Аргумент address, переданный функции callback, будет объектом со следующими свойствами:

• nsname
• hostmaster
• serial
• refresh
• retry
• expire
• minttl

{
  nsname: 'ns.example.com',
  hostmaster: 'root.example.com',
  serial: 2013101809,
  refresh: 10000,
  retry: 2400,
  expire: 604800,
  minttl: 3600
} copy

dns.resolveSrv(hostname, callback)

• hostname <string>
• callback <Function>
  • err <Error>
  • addresses <Object[]>

Использует протокол DNS для разрешения записей службы (записей SRV) для hostname. Аргумент addresses, переданный функции callback, будет массивом объектов со следующими свойствами:

• priority
• weight
• port
• name

{
  priority: 10,
  weight: 5,
  port: 21223,
  name: 'service.example.com'
} copy

dns.resolveTlsa(hostname, callback)

• hostname <string>
• callback <Function>
  • err <Error>
  • records <Object[]>

Использует протокол DNS для разрешения записей ассоциации сертификатов (записей TLSA) для hostname. Аргумент records, переданный функции callback, представляет собой массив объектов со следующими свойствами:

• certUsage
• selector
• match
• data

{
  certUsage: 3,
  selector: 1,
  match: 1,
  data: [ArrayBuffer]
} copy

dns.resolveTxt(hostname, callback)

• hostname <string>
• callback <Function>
  • err <Error>
  • records <string[]>

Использует протокол DNS для разрешения текстовых запросов (записей TXT) для hostname. Аргумент records, переданный функции callback, представляет собой двумерный массив текстовых записей, доступных для hostname (например, [ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]). Каждый вложенный массив содержит фрагменты TXT одной записи. В зависимости от сценария использования их можно объединить или обрабатывать по отдельности.

dns.reverse(ip, callback)

• ip <string>
• callback <Function>
  • err <Error>
  • hostnames <string[]>

Выполняет обратный DNS-запрос, преобразующий адрес IPv4 или IPv6 в массив имен хостов.

В случае ошибки err является объектом Error, где err.code — один из кодов ошибок DNS.

dns.setDefaultResultOrder(order)

• order <string> должно быть равно 'ipv4first', 'ipv6first' или 'verbatim'.

Задает значение по умолчанию для order в dns.lookup() и dnsPromises.lookup(). Возможные значения:

• ipv4first: задает значение order по умолчанию равным ipv4first.
• ipv6first: задает значение order по умолчанию равным ipv6first.
• verbatim: задает значение order по умолчанию равным verbatim.

По умолчанию используется значение verbatim, а dns.setDefaultResultOrder() имеет более высокий приоритет, чем --dns-result-order. При использовании рабочих потоков вызов dns.setDefaultResultOrder() в основном потоке не повлияет на порядок DNS по умолчанию в рабочих потоках.

dns.getDefaultResultOrder()

Возвращает значение по умолчанию для order в dns.lookup() и dnsPromises.lookup(). Возможные значения:

• ipv4first: для order со значением по умолчанию ipv4first.
• ipv6first: для order со значением по умолчанию ipv6first.
• verbatim: для order со значением по умолчанию verbatim.

dns.setServers(servers)

• servers <string[]> массив адресов в формате RFC 5952

Задает IP-адреса и порты серверов, используемых при разрешении DNS-имен. Аргумент servers — это массив адресов в формате RFC 5952. Если используется порт DNS по умолчанию, установленный IANA (53), его можно не указывать.

dns.setServers([
  '8.8.8.8',
  '[2001:4860:4860::8888]',
  '8.8.8.8:1053',
  '[2001:4860:4860::8888]:1053',
]); copy

Если указан недопустимый адрес, будет выброшено исключение.

Метод dns.setServers() нельзя вызывать, пока выполняется DNS-запрос.

Метод dns.setServers() влияет только на dns.resolve(), dns.resolve*() и dns.reverse() (и, в частности, не влияет на dns.lookup()).

Этот метод работает примерно так же, как resolve.conf. То есть, если попытка разрешения имени с помощью первого указанного сервера приводит к ошибке NOTFOUND, метод resolve() не будет пытаться выполнить разрешение с помощью последующих серверов. Резервные DNS-серверы будут использоваться только в том случае, если предыдущие серверы не отвечают вовремя или возвращают другую ошибку.

API promises DNS

API dns.promises предоставляет альтернативный набор асинхронных методов DNS, которые возвращают объекты Promise вместо использования обратных вызовов. Доступ к API осуществляется через require('node:dns').promises или require('node:dns/promises').

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');

const { Resolver } = require('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.
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');
})();

[
  '8.8.8.8',
  '2001:4860:4860::8888',
  '8.8.8.8:1053',
  '[2001:4860:4860::8888]:1053',
] copy

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}]
});

const dns = require('node:dns');
const dnsPromises = dns.promises;
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
};

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;
dnsPromises.lookup('example.org', options).then((result) => {
  console.log('addresses: %j', result);
  // addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]
});

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

const dnsPromises = require('node:dns').promises;
dnsPromises.lookupService('127.0.0.1', 22).then((result) => {
  console.log(result.hostname, result.service);
  // Prints: localhost ssh
});

[ { 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 } ] copy

{
  flags: 's',
  service: 'SIP+D2U',
  regexp: '',
  replacement: '_sip._udp.example.com',
  order: 30,
  preference: 100
} copy

{
  nsname: 'ns.example.com',
  hostmaster: 'root.example.com',
  serial: 2013101809,
  refresh: 10000,
  retry: 2400,
  expire: 604800,
  minttl: 3600
} copy

{
  priority: 10,
  weight: 5,
  port: 21223,
  name: 'service.example.com'
} copy

{
  certUsage: 3,
  selector: 1,
  match: 1,
  data: [ArrayBuffer]
} copy

dnsPromises.setServers([
  '8.8.8.8',
  '[2001:4860:4860::8888]',
  '8.8.8.8:1053',
  '[2001:4860:4860::8888]:1053',
]); copy

Коды ошибок

Каждый DNS-запрос может вернуть один из следующих кодов ошибок:

• dns.NODATA: DNS-сервер вернул ответ без данных.
• dns.FORMERR: DNS-сервер сообщает, что запрос имеет неверный формат.
• dns.SERVFAIL: DNS-сервер вернул общую ошибку.
• dns.NOTFOUND: Доменное имя не найдено.
• dns.NOTIMP: DNS-сервер не поддерживает запрошенную операцию.
• dns.REFUSED: DNS-сервер отклонил запрос.
• dns.BADQUERY: DNS-запрос имеет неверный формат.
• dns.BADNAME: Имя узла имеет неверный формат.
• dns.BADFAMILY: Неподдерживаемое семейство адресов.
• dns.BADRESP: Ответ DNS имеет неверный формат.
• dns.CONNREFUSED: Не удалось связаться с DNS-серверами.
• dns.TIMEOUT: Истекло время ожидания при обращении к DNS-серверам.
• dns.EOF: Конец файла.
• dns.FILE: Ошибка чтения файла.
• dns.NOMEM: Недостаточно памяти.
• dns.DESTRUCTION: Канал уничтожается.
• dns.BADSTR: Строка имеет неверный формат.
• dns.BADFLAGS: Указаны недопустимые флаги.
• dns.NONAME: Указанное имя узла не является числовым.
• dns.BADHINTS: Указаны недопустимые флаги подсказок.
• dns.NOTINITIALIZED: Инициализация библиотеки c-ares еще не выполнена.
• dns.LOADIPHLPAPI: Не удалось загрузить iphlpapi.dll.
• dns.ADDRGETNETWORKPARAMS: Не удалось найти функцию GetNetworkParams.
• dns.CANCELLED: DNS-запрос отменен.

API dnsPromises также экспортирует приведенные выше коды ошибок, например, dnsPromises.NODATA.

Особенности реализации

Хотя dns.lookup() и различные функции dns.resolve*()/dns.reverse() предназначены для одной цели — сопоставления сетевого имени с сетевым адресом (или наоборот), их поведение существенно различается. Эти различия могут иметь неочевидные, но значительные последствия для работы программ Node.js.