Класс: 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 для использования значения по умолчанию.

resolver.cancel()

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

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

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

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

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

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

dns.getServers()

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

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

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

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 <строка>
• 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 для разрешения IP-адресов IPv4 (A записей) для hostname. Аргумент addresses передаваемый функции callback будет содержать массив IP-адресов 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 для разрешения IP-адресов IPv6 (AAAA записей) для hostname. Аргумент addresses передаваемый функции callback будет содержать массив IP-адресов 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 <строка>
• 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.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 (адреса переупорядочиваются), но ожидается, что это изменится в ближайшем будущем. Новый код должен использовать { 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 разрешается массивом 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' ] ]). Каждый подмассив содержит текстовые фрагменты одной записи. В зависимости от случая использования, их можно объединить или обработать по отдельности.

dnsPromises.reverse(ip)

• ip <string>

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

При ошибке, Promise отклоняется с объектом Error, где err.code — один из кодов ошибок 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.