Класс: dns.Resolver

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

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

const { Resolver } = require('node:dns');
const resolver = new Resolver();
resolver.setServers(['4.4.4.4']);

// This request will use the server at 4.4.4.4, independent of global settings.
resolver.resolve4('example.org', (err, addresses) => {
  // ...
}); copy

Доступны следующие методы из модуля node:dns:

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

Resolver([options])

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

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

resolver.cancel()

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

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

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

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

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

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

dns.getServers()

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

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

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

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

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

Разрешает имя хоста (например, 'nodejs.org') в первую найденную запись A (IPv4) или AAAA (IPv6). Все option свойства необязательны. Если options является целым числом, то оно должно быть 4 или 6 — если options не указано, то возвращаются либо адреса IPv4 или IPv6, или оба, если они найдены.

С опцией all, установленной в true, аргументы для callback изменяются на (err, addresses), где addresses — массив объектов со свойствами address и family.

При ошибке err — это объект Error, где err.code — код ошибки. Имейте в виду, что err.code будет установлено в 'ENOTFOUND' не только в том случае, когда имя хоста не существует, но и когда поиск по другим причинам, таким как отсутствие доступных дескрипторов файлов, не удается.

dns.lookup() не обязательно связано с протоколом DNS. Реализация использует средство операционной системы, которое может ассоциировать имена с адресами и наоборот. Эта реализация может иметь тонкие, но важные последствия для поведения любой программы Node.js. Пожалуйста, уделите время, чтобы ознакомиться с разделом Рассмотрение реализации, прежде чем использовать dns.lookup().

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

const dns = require('node:dns');
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
};
dns.lookup('example.com', options, (err, address, family) =>
  console.log('address: %j family: IPv%s', address, family));
// address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6

// When options.all is true, the result will be an Array.
options.all = true;
dns.lookup('example.com', options, (err, addresses) =>
  console.log('addresses: %j', addresses));
// addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}] copy

Если этот метод вызывается как его util.promisify() версия, и all не установлено в true, он возвращает Promise для Object с свойствами address и family.

Поддерживаемые флаги getaddrinfo

Следующие флаги могут быть переданы в качестве подсказок для dns.lookup().

• dns.ADDRCONFIG: Ограничивает возвращаемые типы адресов типами адресов, не являющихся адресами петли, настроенных в системе. Например, адреса IPv4 возвращаются только в том случае, если в текущей системе настроен хотя бы один адрес IPv4.
• dns.V4MAPPED: Если было указано семейство IPv6, но адресов IPv6 не найдено, тогда возвращаются адреса IPv4, отображаемые как IPv6. Не поддерживается на некоторых операционных системах (например, FreeBSD 10.1).
• dns.ALL: Если указан dns.V4MAPPED, возвращаются разрешенные адреса IPv6, а также адреса IPv4, отображаемые как IPv6.

dns.lookupService(address, port, callback)

• address <строка>
• port <число>
• callback <функция>
  • err <ошибка>
  • hostname <строка> например, example.com
  • service <строка> например, http

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

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

При ошибке err — это объект Error, где err.code — код ошибки.

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

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

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

• hostname <строка> Имя хоста для разрешения.
• rrtype <строка> Тип записи ресурса. По умолчанию: 'A'.
• callback <Функция>
  • err <Ошибка>
  • records <строка[]> | <Объект[]> | <Объект>

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

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

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

• hostname <строка> Имя хоста для разрешения.
• options <Объект>
  • ttl <булево> Получает значение 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 } ] copy

Операторы DNS-серверов могут выбрать не отвечать на запросы ANY. Лучше вызвать отдельные методы, такие как dns.resolve4(), dns.resolveMx() и т. д. Дополнительные сведения см. в RFC 8482.

dns.resolveCname(hostname, callback)

• hostname <строка>
• callback <Функция>
  • err <Ошибка>
  • addresses <Массив строк>

Использует протокол DNS для разрешения записей CNAME для hostname. Аргумент addresses, переданный функции callback, будет содержать массив канонических имен записей, доступных для hostname (например, ['bar.example.com']).

dns.resolveCaa(hostname, callback)

• hostname <строка>
• callback <Функция>
  • err <Ошибка>
  • records <Массив объектов>

Использует протокол DNS для разрешения записей CAA для hostname. Аргумент addresses, переданный функции callback, будет содержать массив записей авторизации центра сертификации, доступных для hostname (например, [{critical: 0, iodef: 'mailto:pki@example.com'}, {critical: 128, issue: 'pki.example.com'}]).

dns.resolveMx(hostname, callback)

• hostname <строка>
• callback <Функция>
  • err <Ошибка>
  • addresses <Массив объектов>

Использует протокол DNS для разрешения записей обмена почтой (MX записи) для hostname. Аргумент addresses, переданный функции callback, будет содержать массив объектов, содержащих как свойство priority, так и свойство exchange (например, [{priority: 10, exchange: 'mx.example.com'}, ...]).

dns.resolveNaptr(hostname, callback)

• hostname <строка>
• callback <Функция>
  • err <Ошибка>
  • addresses <Массив объектов>

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

• flags
• service
• regexp
• replacement
• order
• preference

{
  flags: 's',
  service: 'SIP+D2U',
  regexp: '',
  replacement: '_sip._udp.example.com',
  order: 30,
  preference: 100
} copy

dns.resolveNs(hostname, callback)

• hostname <строка>
• callback <Функция>
  • err <Ошибка>
  • addresses <Массив строк>

Использует протокол DNS для разрешения записей сервера имен (NS записи) для hostname. Аргумент addresses, переданный функции callback, будет содержать массив записей серверов имен, доступных для hostname (например, ['ns1.example.com', 'ns2.example.com']).

dns.resolvePtr(hostname, callback)

• hostname <строка>
• callback <Функция>
  • err <Ошибка>
  • addresses <массив строк>

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

dns.resolveSoa(hostname, callback)

• hostname <строка>
• callback <Функция>
  • err <Ошибка>
  • address <Объект>

Использует протокол DNS для разрешения записи начала зоны ответственности (SOA запись) для hostname. Аргумент address, передаваемый функции callback, будет объектом со следующими свойствами:

• nsname
• hostmaster
• serial
• refresh
• retry
• expire
• minttl

{
  nsname: 'ns.example.com',
  hostmaster: 'root.example.com',
  serial: 2013101809,
  refresh: 10000,
  retry: 2400,
  expire: 604800,
  minttl: 3600
} copy

dns.resolveSrv(hostname, callback)

• hostname <строка>
• callback <Функция>
  • err <Ошибка>
  • addresses <Массив объектов>

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

• priority
• weight
• port
• name

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

dns.resolveTxt(hostname, callback)

• hostname <строка>
• callback <Функция>
  • err <Ошибка>
  • records <двумерный массив строк>

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

dns.reverse(ip, callback)

• ip <строка>
• callback <Функция>
  • err <Ошибка>
  • hostnames <массив строк>

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

При ошибке err — это объект Error, где err.code — один из кодов ошибок DNS.

dns.setDefaultResultOrder(order)

• order <строка> должна быть 'ipv4first', 'ipv6first' или 'verbatim'.

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

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

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

dns.getDefaultResultOrder()

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

• ipv4first: для order по умолчанию ipv4first.
• ipv6first: для order по умолчанию ipv6first.
• verbatim: для order по умолчанию verbatim.

dns.setServers(servers)

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

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

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

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

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

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

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

API обещаний DNS

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

Класс: dnsPromises.Resolver

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

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

const { Resolver } = require('node:dns').promises;
const resolver = new Resolver();
resolver.setServers(['4.4.4.4']);

// This request will use the server at 4.4.4.4, independent of global settings.
resolver.resolve4('example.org').then((addresses) => {
  // ...
});

// Alternatively, the same code can be written using async-await style.
(async function() {
  const addresses = await resolver.resolve4('example.org');
})(); copy

Доступны следующие методы из API обещаний 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. Строка будет включать раздел порта, если используется пользовательский порт.

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

dnsPromises.lookup(hostname[, options])

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

Разрешает имя хоста (например, 'nodejs.org') в первую найденную запись A (IPv4) или AAAA (IPv6). Все свойства option необязательны. Если options — целое число, то оно должно быть 4 или 6 — если options не предоставлено, тогда возвращаются либо IPv4, либо IPv6 адреса, или оба, если найдены.

При установке опции all в true, Promise разрешается с addresses в виде массива объектов со свойствами address и family.

При ошибке обещание Promise отклоняется с объектом Error, где err.code — код ошибки. Имейте в виду, что err.code будет установлено в 'ENOTFOUND' не только в случае, если имя хоста не существует, но также и при провале поиска другими способами, такими как отсутствие доступных дескрипторов файлов.

dnsPromises.lookup() не обязательно имеет отношение к протоколу DNS. Реализация использует операционную систему, которая может связывать имена с адресами и наоборот. Эта реализация может иметь тонкие, но важные последствия для поведения любой программы Node.js. Пожалуйста, уделите время, чтобы проконсультироваться с разделом Учет реализации перед использованием dnsPromises.lookup().

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

const dns = require('node:dns');
const dnsPromises = dns.promises;
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
};

dnsPromises.lookup('example.com', options).then((result) => {
  console.log('address: %j family: IPv%s', result.address, result.family);
  // address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6
});

// When options.all is true, the result will be an Array.
options.all = true;
dnsPromises.lookup('example.com', options).then((result) => {
  console.log('addresses: %j', result);
  // addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}]
}); copy

dnsPromises.lookupService(address, port)

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

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

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

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

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

dnsPromises.resolve(hostname[, rrtype])

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

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

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

dnsPromises.resolve4(hostname[, options])

• hostname <строка> Имя хоста для разрешения.
• options <Объект>
  • ttl <логическое значение> Получить значение времени жизни (TTL) каждой записи. Если true, то Promise разрешается массивом объектов { address: '1.2.3.4', ttl: 60 }, а не массивом строк, где TTL выражено в секундах.

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

dnsPromises.resolve6(hostname[, options])

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

Использует протокол DNS для разрешения IP-адресов IPv6 (AAAA записи) для hostname. При успехе, Promise разрешается массивом IP-адресов IPv6.

dnsPromises.resolveAny(hostname)

• hostname <строка>

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

Вот пример объекта результата:

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

dnsPromises.resolveCaa(hostname)

• hostname <строка>

Использует протокол DNS для разрешения CAA записей для hostname. При успехе, Promise разрешается массивом объектов, содержащих доступные записи авторизации сертификационных центров, доступные для hostname (например, [{critical: 0, iodef: 'mailto:pki@example.com'},{critical: 128, issue: 'pki.example.com'}]).

dnsPromises.resolveCname(hostname)

• hostname <строка>

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

dnsPromises.resolveMx(hostname)

• hostname <строка>

Использует протокол DNS для разрешения записей обмена почтой (MX записи) для hostname. При успехе, Promise разрешается массивом объектов, содержащих как свойство priority, так и свойство exchange (например, [{priority: 10, exchange: 'mx.example.com'}, ...]).

dnsPromises.resolveNaptr(hostname)

• hostname <строка>

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

• flags
• service
• regexp
• replacement
• order
• preference

{
  flags: 's',
  service: 'SIP+D2U',
  regexp: '',
  replacement: '_sip._udp.example.com',
  order: 30,
  preference: 100
} copy

dnsPromises.resolveNs(hostname)

• hostname <строка>

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

dnsPromises.resolvePtr(hostname)

• hostname <string>

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

dnsPromises.resolveSoa(hostname)

• hostname <string>

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

• nsname
• hostmaster
• serial
• refresh
• retry
• expire
• minttl

{
  nsname: 'ns.example.com',
  hostmaster: 'root.example.com',
  serial: 2013101809,
  refresh: 10000,
  retry: 2400,
  expire: 604800,
  minttl: 3600
} copy

dnsPromises.resolveSrv(hostname)

• hostname <string>

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

• priority
• weight
• port
• name

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

dnsPromises.resolveTxt(hostname)

• hostname <string>

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

dnsPromises.reverse(ip)

• ip <string>

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

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

dnsPromises.setDefaultResultOrder(order)

• order <string> должен быть 'ipv4first', 'ipv6first' или 'verbatim'.

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

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

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

dnsPromises.getDefaultResultOrder()

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

dnsPromises.setServers(servers)

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

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

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

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

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

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

Коды ошибок

Каждый запрос DNS может вернуть один из следующих кодов ошибок:

• dns.NODATA: DNS-сервер вернул ответ без данных.
• dns.FORMERR: DNS-сервер утверждает, что запрос был неправильно отформатирован.
• dns.SERVFAIL: DNS-сервер вернул общую ошибку.
• dns.NOTFOUND: Имя домена не найдено.
• dns.NOTIMP: DNS-сервер не поддерживает запрошенную операцию.
• dns.REFUSED: DNS-сервер отклонил запрос.
• dns.BADQUERY: Неправильно отформатированный запрос DNS.
• dns.BADNAME: Неправильно отформатированное имя хоста.
• dns.BADFAMILY: Неподдерживаемая семейство адресов.
• dns.BADRESP: Неправильно отформатированный ответ DNS.
• dns.CONNREFUSED: Не удалось связаться с DNS-серверами.
• dns.TIMEOUT: Истекло время ожидания при попытке связаться с DNS-серверами.
• dns.EOF: Конец файла.
• dns.FILE: Ошибка чтения файла.
• dns.NOMEM: Нет памяти.
• dns.DESTRUCTION: Канал уничтожается.
• dns.BADSTR: Неправильно отформатированная строка.
• dns.BADFLAGS: Указаны недопустимые флаги.
• dns.NONAME: Указанное имя хоста не является числовым.
• dns.BADHINTS: Указаны недопустимые флаги.
• dns.NOTINITIALIZED: Инициализация библиотеки c-ares ещё не выполнена.
• dns.LOADIPHLPAPI: Ошибка загрузки iphlpapi.dll.
• dns.ADDRGETNETWORKPARAMS: Не удалось найти функцию GetNetworkParams.
• dns.CANCELLED: Запрос DNS отменён.

API dnsPromises также экспортирует вышеперечисленные коды ошибок, например, dnsPromises.NODATA.

Рекомендации по реализации

Хотя dns.lookup() и различные dns.resolve*()/dns.reverse() функции имеют одинаковую цель — связывание сетевого имени с сетевым адресом (или наоборот), их поведение существенно различается. Эти различия могут оказывать тонкое, но значительное влияние на поведение программ Node.js.

dns.lookup()

Внутренне dns.lookup() использует те же средства операционной системы, что и большинство других программ. Например, dns.lookup() почти всегда будет разрешать данное имя так же, как и команда ping. В большинстве операционных систем, похожих на POSIX, поведение функции dns.lookup() можно изменить, изменив настройки в nsswitch.conf(5) и/или resolv.conf(5), но изменение этих файлов повлияет на поведение всех других программ, работающих в той же операционной системе.

Хотя вызов dns.lookup() асинхронный с точки зрения JavaScript, он реализован как синхронный вызов getaddrinfo(3), выполняемый в пуле потоков libuv. Это может иметь неожиданно негативное влияние на производительность некоторых приложений, см. документацию UV_THREADPOOL_SIZE для получения дополнительной информации.

Различные сетевые API будут вызывать dns.lookup() для разрешения имен хостов во внутренней работе. Если это проблема, рассмотрите возможность разрешения имени хоста до адреса с помощью dns.resolve() и использования адреса вместо имени хоста. Кроме того, некоторые сетевые API (такие как socket.connect() и dgram.createSocket()) позволяют заменить стандартный разрешитель dns.lookup().

dns.resolve(), dns.resolve*() и dns.reverse()

Эти функции реализованы совершенно иначе, чем dns.lookup(). Они не используют getaddrinfo(3) и всегда выполняют DNS-запрос в сети. Эта сетевая коммуникация всегда асинхронна и не использует пул потоков libuv.

В результате эти функции не могут оказывать такое же негативное влияние на другие процессы, выполняемые в пуле потоков libuv, как dns.lookup().

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