DNS

Исходный код: lib/dns.js

Модуль dns позволяет выполнять разрешение имен. Например, используйте его для поиска IP-адресов хост-имен.

Несмотря на название, связанное с системой доменных имён (DNS), он не всегда использует протокол DNS для поиска. dns.lookup() использует средства операционной системы для выполнения разрешения имен. Возможно, не потребуется никакое сетевое взаимодействие. Чтобы выполнить разрешение имен так, как это делают другие приложения в этой системе, используйте dns.lookup().

const dns = require('dns');

dns.lookup('example.org', (err, address, family) => {
  console.log('address: %j family: IPv%s', address, family);
});
// address: "93.184.216.34" family: IPv4

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

const dns = require('dns');

dns.resolve4('archive.org', (err, addresses) => {
  if (err) throw err;

  console.log(`addresses: ${JSON.stringify(addresses)}`);

  addresses.forEach((a) => {
    dns.reverse(a, (err, hostnames) => {
      if (err) {
        throw err;
      }
      console.log(`reverse for ${a}: ${JSON.stringify(hostnames)}`);
    });
  });
});

Дополнительную информацию см. в разделе Учётные соображения реализации.

Класс: 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.resolveCname()
• resolver.resolveMx()
• resolver.resolveNaptr()
• resolver.resolveNs()
• resolver.resolvePtr()
• resolver.resolveSoa()
• resolver.resolveSrv()
• resolver.resolveTxt()
• resolver.reverse()
• resolver.setServers()

Resolver([options])

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

• options <Объект>
  • timeout <целое число> Время ожидания запроса в миллисекундах или -1 для использования значения по умолчанию.

resolver.cancel()

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

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 (адреса упорядочиваются), но ожидается, что это изменится в ближайшем будущем. Новый код должен использовать { 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().

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

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 <string>
• port <number>
• callback <Function>
  • err <Error>
  • hostname <string> например example.com
  • service <string> например http

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

dns.resolveAny(hostname, callback)

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

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

Вот пример объекта ret, переданного обратной функции:

[ { type: 'A', address: '127.0.0.1', ttl: 299 },
  { type: 'CNAME', value: 'example.com' },
  { type: 'MX', exchange: 'alt4.aspmx.l.example.com', priority: 50 },
  { type: 'NS', value: 'ns1.example.com' },
  { type: 'TXT', entries: [ 'v=spf1 include:_spf.example.com ~all' ] },
  { type: 'SOA',
    nsname: 'ns1.example.com',
    hostmaster: 'admin.example.com',
    serial: 156696742,
    refresh: 900,
    retry: 900,
    expire: 1800,
    minttl: 60 } ]

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

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
}

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

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

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

Метод 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('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 dnsPromises:

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

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 <число> Один или несколько поддерживаемых флагов. Несколько флагов могут быть переданы путём побитового объединения их значений.
  • all <логическое> Если true, то Promise разрешается со всеми адресами в массиве. В противном случае возвращается один адрес. По умолчанию: false.
  • verbatim <логическое> Если true, то Promise разрешается с IPv4 и IPv6 адресами в порядке, в котором их вернул DNS-решатель. Если false, IPv4 адреса ставятся перед IPv6 адресами. По умолчанию: в настоящее время false (адреса переупорядочиваются), но ожидается, что это изменится в ближайшем будущем. Новый код должен использовать { 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.lookupService(address, port).

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

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 <логическое значение> Получить значение TTL (Time-To-Live) каждой записи. Если true, промис Promise разрешается с массивом объектов { address: '1.2.3.4', ttl: 60 }, а не массивом строк, где TTL выражается в секундах.

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

dnsPromises.resolve6(hostname[, options])

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

Использует протокол DNS для разрешения 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.resolveCname(hostname)

• hostname <строка>

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

dnsPromises.resolveMx(hostname)

• hostname <строка>

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

dnsPromises.resolvePtr(hostname)

• hostname <строка>

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

dnsPromises.resolveSoa(hostname)

• hostname <строка>

Использует протокол DNS для разрешения записи SOA (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 <строка>

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

• priority
• weight
• port
• name

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

Разрешение TXT записей

• hostname <строка>

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

Обратный DNS запрос

• ip <строка>

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

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

Установка серверов DNS

• servers <массив строк> массив адресов в формате 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.