DNS

Модуль dns содержит функции, относящиеся к двум категориям:

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

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

const dns = require('dns');

dns.lookup('nodejs.org', (err, addresses, family) => {
  console.log('addresses:', addresses);
});
// 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.getServers()

Возвращает массив строк IP-адресов, используемых для разрешения имен.

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

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

В качестве альтернативы, options может быть объектом, содержащим следующие свойства:

• family <число> - Семейство записей. Если присутствует, должно быть целым числом 4 или 6. Если не указано, принимаются оба IP-адреса v4 и v6.
• hints: <число> - Если присутствует, оно должно быть одним или несколькими поддерживаемыми флагами getaddrinfo. Если hints не указано, то в getaddrinfo не передаются никакие флаги. Несколько флагов могут быть переданы через hints с помощью побитового OR. См. поддерживаемые getaddrinfo флаги для получения дополнительной информации о поддерживаемых флагах.
• all: <логическое значение> - Когда true, обратный вызов возвращает все разрешенные адреса в массиве, в противном случае возвращает единственный адрес. По умолчанию false.

Все свойства являются необязательными.

Функция callback имеет аргументы (err, address, family). address — строковое представление IPv4 или IPv6 адреса. family — либо целое число 4 или 6 и обозначает семейство address (не обязательно значение, первоначально переданное в lookup).

При установке параметра all в значение true, аргументы изменяются на (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}]

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

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

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

dns.lookupService(address, port, callback)

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

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

Обратный вызов имеет аргументы (err, hostname, service). Аргументы hostname и service являются строками (например, 'localhost' и 'http' соответственно).

При ошибке 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
});

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)

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

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

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

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

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

dns.resolveCname(hostname, callback)

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

dns.resolveMx(hostname, callback)

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

dns.resolveNaptr(hostname, callback)

Использует протокол DNS для разрешения записей на основе регулярных выражений (NAPTR записи) для hostname. Функция обратного вызова callback имеет аргументы (err, addresses). Аргумент 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)

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

dns.resolveSoa(hostname, callback)

Использует протокол DNS для разрешения записи начала области авторитета (SOA запись) для hostname. Аргумент addresses , переданный в функцию 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)

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

• priority
• weight
• port
• name

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

dns.resolvePtr(hostname, callback)

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

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)

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

Функция обратного вызова callback имеет аргументы (err, hostnames), где hostnames — массив разрешённых имён хостов для данного ip.

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

dns.setServers(servers)

Устанавливает IP-адреса серверов, которые будут использоваться при разрешении имен. Аргумент servers — массив IPv4 или IPv6 адресов.

Если порт указан в адресе, он будет удалён.

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

Метод dns.setServers() не должен вызываться во время выполнения запроса 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. Поскольку пул потоков libuv имеет фиксированный размер, это означает, что если по какой-либо причине вызов getaddrinfo(3) занимает много времени, другие операции, которые могут выполняться в пуле потоков libuv (например, операции с файловой системой), будут испытывать снижение производительности. Для решения этой проблемы можно увеличить размер пула потоков libuv, установив переменную окружения 'UV_THREADPOOL_SIZE' на значение больше 4 (текущего значения по умолчанию). Подробнее о пуле потоков libuv см. в официальной документации libuv.

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

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

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

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