DNS

В модуле dns содержатся функции, относящиеся к двум различным категориям:

1) Функции, использующие средства операционной системы для выполнения разрешения имен и не обязательно выполняющие сетевое взаимодействие. Эта категория содержит только одну функцию: dns.lookup(). Разработчикам, желающим выполнить разрешение имен таким же образом, как и другие приложения в той же операционной системе, следует использовать dns.lookup().

Например, поиск iana.org.

const dns = require('dns');

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

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

Ниже приведён пример, который разрешает 'archive.org', а затем обратное разрешение IP-адресов, которые возвращаются.

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.cancel()

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

dns.getServers()

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

Возвращает массив строк IP-адресов, отформатированных в соответствии с rfc5952, которые в настоящее время настроены для разрешения 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 . IPv4 и IPv6 адреса возвращаются по умолчанию.
  • 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.

Разрешает имя хоста (например, '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 будет установлено в 'ENOENT' не только когда имя хоста не существует, но и когда поиск терпит неудачу другими способами, например, отсутствием доступных дескрипторов файлов.

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

• callback <Функция>

  • err <Ошибка>
  • addresses <массив строк> | <массив объектов>

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

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

• hostname <строка> Имя хоста для разрешения.

• options <объект>

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

• callback <Функция>

  • err <Ошибка>
  • addresses <массив строк> | <массив объектов>

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

dns.resolveAny(hostname, callback)

• hostname <строка>

• callback <Функция>

  • err <Ошибка>
  • ret <массив объектов>

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

Вот пример объекта ret передаваемого в обратный вызов:

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

Операторы 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 <массив строк> массив адресов в формате rfc5952

Устанавливает IP-адрес и порт серверов, которые будут использоваться при выполнении DNS-разрешения. Аргумент servers — это массив адресов в формате rfc5952. Если порт равен стандартному порту 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 Promises

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-адресов, отформатированных в соответствии с rfc5952, которые в настоящее время настроены для 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. IPv4 и IPv6 адреса возвращаются по умолчанию.
  • hints <число> Один или несколько поддерживаемых getaddrinfo флагов. Несколько флагов могут быть переданы с помощью побитового OR объединения их значений.
  • 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 будет установлено в 'ENOENT' не только в случае, если имя хоста не существует, но и при других сбоях, таких как отсутствие доступных дескрипторов файлов.

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 разрешается массивом 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 } ]

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 <строка>

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

dnsPromises.resolveSoa(hostname)

• hostname <строка>

Использует протокол 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 <строка>

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

• priority
• weight
• port
• name

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

dnsPromises.resolveTxt(hostname)

• hostname <строка>

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

dnsPromises.reverse(ip)

• ip <строка>

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

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

dnsPromises.setServers(servers)

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

Устанавливает IP-адрес и порт серверов, которые будут использоваться при выполнении разрешения DNS. Аргумент servers — массив адресов в формате rfc5952. Если порт равен стандартному порту 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.