Класс: 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-адреса. Это позволяет программам указывать исходящие интерфейсы при использовании на системах с несколькими IP-адресами.

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

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

dns.getServers()

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

Возвращает массив строк 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 <строка>
• options <целое число> | <объект>
  • family <целое число> | <строка> Семейство записей. Должно быть 4, 6 или 0. Для обратной совместимости, 'IPv4' и 'IPv6' интерпретируются как 4 и 6 соответственно. Значение 0 указывает, что возвращается либо IPv4, либо IPv6 адрес. Если значение 0 используется с { all: true } (см. ниже), возвращаются либо один, либо оба IPv4 и IPv6 адреса в зависимости от DNS-резолвера системы. По умолчанию: 0.
  • hints <число> Один или несколько поддерживаемых getaddrinfo флагов. Несколько флагов могут быть переданы с помощью побитового OR оператора.
  • all <логическое значение> Если true, обратный вызов возвращает все разрешенные адреса в массиве. В противном случае возвращается единственный адрес. По умолчанию: false.
  • order <строка> Если verbatim, разрешенные адреса возвращаются в неупорядоченном виде. Если ipv4first, разрешенные адреса сортируются, помещая IPv4 адреса перед IPv6 адресами. Если ipv6first, разрешенные адреса сортируются, помещая IPv6 адреса перед IPv4 адресами. По умолчанию: verbatim (адреса не переупорядочиваются). Значение по умолчанию можно настроить с помощью dns.setDefaultResultOrder() или --dns-result-order.
  • verbatim <логическое значение> Если true, обратный вызов получает IPv4 и IPv6 адреса в том порядке, в котором их вернул DNS-резолвер. Если false, IPv4 адреса ставятся перед IPv6 адресами. Эта опция будет устаревшей в пользу order. Если оба значения указаны, приоритет имеет order. Новый код должен использовать только order. По умолчанию: 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 не указано, то возвращаются либо 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-сопоставленные IPv6 адреса. На некоторых операционных системах (например, FreeBSD 10.1) не поддерживается.
• dns.ALL: Если dns.V4MAPPED указан, возвращаются разрешенные IPv6 адреса и IPv4-сопоставленные 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 <логическое значение> Извлекает значение TTL (Time-To-Live) каждой записи. Если 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 <логическое значение> Извлекает значение TTL (Time-To-Live) каждой записи. Если 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', '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 (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 обещаний 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. Строка будет включать раздел порта, если используется пользовательский порт.

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

dnsPromises.lookup(hostname[, options])

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

Разрешает имя хоста (например, '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', 'ipv6first' или 'verbatim'.

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

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

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

dnsPromises.getDefaultResultOrder()

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

dnsPromises.setServers(servers)

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

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

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

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

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

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

Коды ошибок

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