Класс: dns.Resolver

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

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

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

Доступны следующие методы из модуля 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.resolveTxt()
• resolver.reverse()
• resolver.setServers()

Resolver([options])

Создать новый решатель.

• options <Объект>
  • timeout <целое число> Таймаут запроса в миллисекундах или -1 для использования значения по умолчанию.
  • tries <целое число> Количество попыток, которое решатель предпримет для контакта с каждым сервером имён, прежде чем сдастся. По умолчанию: 4

resolver.cancel()

Отменить все активные запросы DNS, выполненные этим решателем. Соответствующие обратные вызовы будут вызваны с ошибкой с кодом ECANCELLED.

resolver.setLocalAddress([ipv4][, ipv6])

• ipv4 <строка> Строковое представление IPv4-адреса. По умолчанию: '0.0.0.0'
• ipv6 <строка> Строковое представление IPv6-адреса. По умолчанию: '::0'

Экземпляр решателя будет отправлять запросы с указанного IP-адреса. Это позволяет программам указывать исходящие интерфейсы при использовании на многоадресных системах.

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

Решатель будет использовать локальный адрес v4 при отправке запросов на IPv4-серверы DNS и локальный адрес v6 при отправке запросов на IPv6-серверы DNS. rrtype запросов разрешения не влияет на используемый локальный адрес.

dns.getServers()

• Возвращает: <массив строк>

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

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

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

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

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

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

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

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

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

const dns = require('node:dns');
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
};
dns.lookup('example.com', options, (err, address, family) =>
  console.log('address: %j family: IPv%s', address, family));
// address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6

// When options.all is true, the result will be an Array.
options.all = true;
dns.lookup('example.com', options, (err, addresses) =>
  console.log('addresses: %j', addresses));
// addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}] copy

Если этот метод вызван как его util.promisify()-версия, и all не установлено в true, он возвращает Promise для Object с свойствами address и family.

Поддерживаемые флаги getaddrinfo

Следующие флаги могут быть переданы в качестве подсказок к dns.lookup().

• dns.ADDRCONFIG: Ограничивает типы возвращаемых адресов типами адресов, не являющихся адресами обратной связи, настроенных в системе. Например, IPv4 адреса возвращаются только если в текущей системе настроен хотя бы один IPv4 адрес.
• dns.V4MAPPED: Если было указано семейство IPv6, но IPv6 адреса не были найдены, то возвращаются IPv4-mapped IPv6 адреса. Не поддерживается на некоторых операционных системах (например, FreeBSD 10.1).
• dns.ALL: Если dns.V4MAPPED указан, возвращаются разрешённые IPv6 адреса, а также IPv4-mapped IPv6 адреса.

dns.lookupService(address, port, callback)

• address <строка>
• port <число>
• callback <Функция>
  • err <Ошибка>
  • hostname <строка> например, example.com
  • service <строка> например, http

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

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

При ошибке err является объектом Error, где err.code – код ошибки.

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

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

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

• hostname <строка> Имя хоста для разрешения.
• rrtype <строка> Тип записи ресурса. По умолчанию: 'A'.
• callback <Функция>
  • err <Ошибка>
  • records <массив строк> | <массив объектов> | <объект>

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

При ошибке err — это объект Error, где err.code — один из кодов ошибок DNS.

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

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

Использует протокол 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 <строка> Имя хоста для разрешения.
• options <объект>
  • ttl <логическое> Получает значение Time-To-Live (TTL) каждой записи. Если true, обратный вызов получает массив объектов { address: '0:1:2:3:4:5:6:7', ttl: 60 }, а не массив строк, с TTL, выраженным в секундах.
• callback <Функция>
  • err <Ошибка>
  • addresses <массив строк> | <массив объектов>

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

dns.resolveAny(hostname, callback)

• hostname <строка>
• callback <Функция>
  • err <Ошибка>
  • ret <Массив объектов>

Использует протокол 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 <строка>
• callback <Функция>
  • err <Ошибка>
  • addresses <Массив строк>

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

dns.resolveCaa(hostname, callback)

• hostname <строка>
• callback <Функция>
  • err <Ошибка>
  • records <Массив объектов>

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

dns.resolveMx(hostname, callback)

• hostname <строка>
• callback <Функция>
  • err <Ошибка>
  • addresses <Массив объектов>

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

dns.resolveNaptr(hostname, callback)

• hostname <строка>
• callback <Функция>
  • err <Ошибка>
  • addresses <Массив объектов>

Использует протокол 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 <строка>
• callback <Функция>
  • err <Ошибка>
  • addresses <Массив строк>

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

dns.resolvePtr(hostname, callback)

• hostname <строка>
• callback <Функция>
  • err <Ошибка>
  • addresses <массив строк>

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

dns.resolveSoa(hostname, callback)

• hostname <строка>
• callback <Функция>
  • err <Ошибка>
  • address <Объект>

Использует протокол 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 <строка>
• callback <Функция>
  • err <Ошибка>
  • addresses <Массив объектов>

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

• priority
• weight
• port
• name

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

dns.resolveTxt(hostname, callback)

• hostname <строка>
• callback <Функция>
  • err <Ошибка>
  • records <двумерный массив строк>

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

dns.reverse(ip, callback)

• ip <строка>
• callback <Функция>
  • err <Ошибка>
  • hostnames <массив строк>

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

При ошибке err — это объект Error, где err.code — один из кодов ошибок DNS.

dns.setDefaultResultOrder(order)

• order <строка> должна быть 'ipv4first' или 'verbatim'.

Устанавливает значение по умолчанию verbatim в dns.lookup() и dnsPromises.lookup(). Значение может быть:

• ipv4first: устанавливает по умолчанию verbatim false.
• verbatim: устанавливает по умолчанию verbatim true.

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

dns.getDefaultResultOrder()

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

• ipv4first: для verbatim по умолчанию false.
• verbatim: для verbatim по умолчанию true.

dns.setServers(servers)

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

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

dns.setServers([
  '4.4.4.4',
  '[2001:4860:4860::8888]',
  '4.4.4.4: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 обещанных значений DNS

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

Класс: dnsPromises.Resolver

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

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

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');
})(); copy

Доступны следующие методы из API dnsPromises:

• 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.resolveTxt()
• resolver.reverse()
• resolver.setServers()

resolver.cancel()

Отмена всех открытых запросов DNS, выполненных этим решателем. Соответствующие обещания будут отклонены с ошибкой с кодом ECANCELLED.

dnsPromises.getServers()

• Возвращает: <массив строк>

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

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

dnsPromises.lookup(hostname[, options])

• hostname <строка>
• options <целое число> | <объект>
  • family <целое число> Семейство записей. Должно быть 4, 6, или 0. Значение 0 указывает на то, что возвращаются и IPv4, и IPv6 адреса. По умолчанию: 0.
  • hints <число> Один или несколько поддерживаемых getaddrinfo флагов. Несколько флагов могут быть переданы с помощью побитового OR их значений.
  • all <логическое значение> При true, Promise разрешается со всеми адресами в массиве. В противном случае возвращается один адрес. По умолчанию: false.
  • verbatim <логическое значение> При true, Promise разрешается с IPv4 и IPv6 адресами в порядке, в котором их вернул решатель DNS. При false, IPv4 адреса ставятся перед IPv6 адресами. По умолчанию: в настоящее время false (адреса переупорядочиваются), но ожидается, что это изменится в ближайшем будущем. Значение по умолчанию настраивается с помощью dns.setDefaultResultOrder() или --dns-result-order. Новый код должен использовать { verbatim: true }.

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

С параметром all, установленным на true, Promise разрешается с addresses являющимся массивом объектов со свойствами address и family.

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

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

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

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

dnsPromises.lookup('example.com', 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
});

// When options.all is true, the result will be an Array.
options.all = true;
dnsPromises.lookup('example.com', options).then((result) => {
  console.log('addresses: %j', result);
  // addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}]
}); copy

dnsPromises.lookupService(address, port)

• address <строка>
• port <число>

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

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

При ошибке обещание Promise отклоняется с объектом Error, где err.code — код ошибки.

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

dnsPromises.resolve(hostname[, rrtype])

• hostname <строка> Имя хоста для разрешения.
• rrtype <строка> Тип записи ресурса. По умолчанию: 'A'.

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

При ошибке Promise отклоняется с объектом Error, где err.code — один из кодов ошибок DNS.

dnsPromises.resolve4(hostname[, options])

• hostname <строка> Имя хоста для разрешения.
• options <Объект>
  • ttl <логическое значение> Получить значение времени жизни (TTL) каждой записи. Если true, то Promise разрешается с массивом объектов { address: '1.2.3.4', ttl: 60 }, а не массивом строк, при этом TTL выражается в секундах.

Использует протокол DNS для разрешения IP-адресов IPv4 (A записей) для hostname. При успехе Promise разрешается массивом IP-адресов IPv4 (например, ['74.125.79.104', '74.125.79.105', '74.125.79.106']).

dnsPromises.resolve6(hostname[, options])

• hostname <строка> Имя хоста для разрешения.
• options <Объект>
  • ttl <логическое значение> Получить значение времени жизни (TTL) каждой записи. Если true, то Promise разрешается с массивом объектов { address: '0:1:2:3:4:5:6:7', ttl: 60 }, а не массивом строк, при этом TTL выражается в секундах.

Использует протокол DNS для разрешения IP-адресов IPv6 (AAAA записей) для hostname. При успехе Promise разрешается массивом IP-адресов IPv6.

dnsPromises.resolveAny(hostname)

• hostname <строка>

Использует протокол DNS для разрешения всех записей (также известен как ANY или * запрос). При успехе Promise разрешается массивом, содержащим различные типы записей. Каждый объект имеет свойство type, которое указывает тип текущей записи. В зависимости от type, в объекте будут присутствовать дополнительные свойства:

Вот пример объекта результата:

[ { 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

dnsPromises.resolveCaa(hostname)

• hostname <строка>

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

dnsPromises.resolveCname(hostname)

• hostname <строка>

Использует протокол DNS для разрешения CNAME записей для hostname. При успехе Promise разрешается массивом канонических имен записей, доступных для hostname (например, ['bar.example.com']).

dnsPromises.resolveMx(hostname)

• hostname <строка>

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

dnsPromises.resolveNaptr(hostname)

• hostname <строка>

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

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

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

dnsPromises.resolveNs(hostname)

• hostname <строка>

Использует протокол DNS для разрешения записей серверов имен (NS записей) для hostname. При успехе Promise разрешается массивом записей серверов имен, доступных для hostname (например, ['ns1.example.com', 'ns2.example.com']).

dnsPromises.resolvePtr(hostname)

• hostname <string>

Использует протокол DNS для разрешения записей указателей (PTR записей) для hostname. При успехе, Promise разрешается массивом строк, содержащих записи ответа.

dnsPromises.resolveSoa(hostname)

• hostname <string>

Использует протокол DNS для разрешения записи начала зоны ответственности (SOA запись) для hostname. При успехе, Promise разрешается объектом со следующими свойствами:

• 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

dnsPromises.resolveSrv(hostname)

• hostname <string>

Использует протокол DNS для разрешения записей сервисов (SRV записи) для hostname. При успехе, Promise разрешается массивом объектов со следующими свойствами:

• priority
• weight
• port
• name

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

dnsPromises.resolveTxt(hostname)

• hostname <string>

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

dnsPromises.reverse(ip)

• ip <string>

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

При ошибке, Promise отклоняется с объектом Error, где err.code — один из кодов ошибок DNS.

dnsPromises.setDefaultResultOrder(order)

• order <string> должно быть 'ipv4first' или 'verbatim'.

Устанавливает значение по умолчанию для verbatim в dns.lookup() и dnsPromises.lookup(). Значение может быть:

• ipv4first: устанавливает значение по умолчанию для verbatim false.
• verbatim: устанавливает значение по умолчанию для verbatim true.

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

dnsPromises.getDefaultResultOrder()

Получить значение dnsOrder.

dnsPromises.setServers(servers)

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

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

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

При указании некорректного адреса будет выброшено исключение.

Метод dnsPromises.setServers() не должен вызываться во время выполнения запроса DNS.

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

Коды ошибок

Каждый запрос 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.

dns.lookup()

Внутри dns.lookup() используются те же средства операционной системы, что и в большинстве других программ. Например, dns.lookup() почти всегда разрешает данное имя так же, как команда ping. На большинстве операционных систем семейства POSIX поведение функции dns.lookup() можно изменить, изменив настройки в nsswitch.conf(5) и/или resolv.conf(5), но изменение этих файлов повлияет на поведение всех других программ, работающих на той же операционной системе.

Хотя вызов dns.lookup() асинхронный с точки зрения JavaScript, он реализован как синхронный вызов getaddrinfo(3) в пуле потоков libuv. Это может иметь неожиданно негативные последствия для производительности некоторых приложений, см. документацию UV_THREADPOOL_SIZE для получения дополнительной информации.

Различные сетевые API вызывают dns.lookup() внутри для разрешения имён хостов. Если это проблема, рассмотрите возможность разрешения имени хоста до адреса с помощью dns.resolve() и использование адреса вместо имени хоста. Также некоторые сетевые API (например, socket.connect() и dgram.createSocket()) позволяют заменить стандартный разрешитель dns.lookup().

dns.resolve(), dns.resolve*(), и dns.reverse()

Эти функции реализованы совершенно по-другому, чем dns.lookup(). Они не используют getaddrinfo(3) и всегда выполняют запрос DNS в сети. Это сетевое взаимодействие всегда выполняется асинхронно и не использует пул потоков libuv.

В результате эти функции не могут иметь такого же негативного воздействия на другие процессы, выполняемые в пуле потоков libuv, как dns.lookup().

Они не используют тот же набор конфигурационных файлов, что и dns.lookup(). Например, они не используют конфигурацию из /etc/hosts.