Класс: dns.Resolver

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

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

import { Resolver } from '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) => {
  // ...
});

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) => {
  // ...
});

Доступны следующие методы из модуля 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.resolveTlsa()
• resolver.resolveTxt()
• resolver.reverse()
• resolver.setServers()

dns.getServers()

• Возвращает: <string[]>

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

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

import dns from 'node:dns';
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
};
dns.lookup('example.org', options, (err, address, family) =>
  console.log('address: %j family: IPv%s', address, family));
// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6

// When options.all is true, the result will be an Array.
options.all = true;
dns.lookup('example.org', options, (err, addresses) =>
  console.log('addresses: %j', addresses));
// addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]

const dns = require('node:dns');
const options = {
  family: 6,
  hints: dns.ADDRCONFIG | dns.V4MAPPED,
};
dns.lookup('example.org', options, (err, address, family) =>
  console.log('address: %j family: IPv%s', address, family));
// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6

// When options.all is true, the result will be an Array.
options.all = true;
dns.lookup('example.org', options, (err, addresses) =>
  console.log('addresses: %j', addresses));
// addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]

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

dns.lookupService(address, port, callback)

• address <string>
• port <number>
• callback <Function>
  • err <Error>
  • hostname <string> например, example.com
  • service <string> например, http

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

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

В случае ошибки err является объектом Error, а err.code содержит код ошибки.

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

const dns = require('node: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 <string> Имя хоста для разрешения.
• rrtype <string> Тип ресурсной записи. По умолчанию: 'A'.
• callback <Function>
  • err <Error>
  • records <string[]> | <Object[]> | <Object>

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

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

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

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

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

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

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

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

dns.resolveAny(hostname, callback)

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

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

Пример объекта ret, передаваемого функции обратного вызова:

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

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

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

dns.resolveSrv(hostname, callback)

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

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

• priority
• weight
• port
• name

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

dns.resolveTlsa(hostname, callback)

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

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

• certUsage
• selector
• match
• data

{
  certUsage: 3,
  selector: 1,
  match: 1,
  data: [ArrayBuffer]
} copy

dns.resolveTxt(hostname, callback)

• hostname <string>
• callback <Function>
  • err <Error>
  • records <string[]>

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

dns.reverse(ip, callback)

• ip <string>
• callback <Function>
  • err <Error>
  • hostnames <string[]>

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

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

dns.setDefaultResultOrder(order)

• order <string> должно быть равно '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 по умолчанию, установленный IANA (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 с promises

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

import { Resolver } from '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.
const addresses = await resolver.resolve4('example.org');

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');
})();

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

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

await dnsPromises.lookup('example.org', options).then((result) => {
  console.log('address: %j family: IPv%s', result.address, result.family);
  // address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6
});

// When options.all is true, the result will be an Array.
options.all = true;
await dnsPromises.lookup('example.org', options).then((result) => {
  console.log('addresses: %j', result);
  // addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]
});

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

dnsPromises.lookup('example.org', options).then((result) => {
  console.log('address: %j family: IPv%s', result.address, result.family);
  // address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6
});

// When options.all is true, the result will be an Array.
options.all = true;
dnsPromises.lookup('example.org', options).then((result) => {
  console.log('addresses: %j', result);
  // addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]
});

import dnsPromises from 'node:dns/promises';
const result = await dnsPromises.lookupService('127.0.0.1', 22);

console.log(result.hostname, result.service); // Prints: localhost ssh

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

[ { 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

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

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

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

{
  certUsage: 3,
  selector: 1,
  match: 1,
  data: [ArrayBuffer]
} copy

Коды ошибок

Для каждого 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.