Класс: dns.Resolver

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

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

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

Доступны следующие методы из модуля 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. 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',
]

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

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

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

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

Если этот метод вызывается как его 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('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 <строка> Имя хоста для разрешения.
• 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 (времени жизни) каждой записи. Если 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 (времени жизни) каждой записи. Если 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 <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 } ]

Операторы 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
}

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
}

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

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' ] ]). Каждый подмассив содержит текстовые фрагменты одной записи. В зависимости от случая использования, их можно объединить или обработать по отдельности.

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' или 'verbatim'.

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

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

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

dns.setServers(servers)

• servers <string[]> массив адресов в формате 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',
]);

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

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

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

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

API обещаний DNS

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

Класс: dnsPromises.Resolver

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

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

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

Доступны следующие методы из API обещаний 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.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',
]

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

dnsPromises.lookupService(address, port)

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

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

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

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

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

dnsPromises.resolve(hostname[, rrtype])

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

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

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

dnsPromises.resolve4(hostname[, options])

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

Использует протокол DNS для разрешения IP-адресов IPv6 (AAAA записи) для hostname. При успехе Promise разрешается массивом 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 } ]

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
}

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
}

dnsPromises.resolveSrv(hostname)

• hostname <string>

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

• priority
• weight
• port
• name

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

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.

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

dnsPromises.setServers(servers)

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

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

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

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

Метод 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-запрос отменён.

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

Хотя 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.