Класс: 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.resolveTxt()
• resolver.reverse()
• resolver.setServers()

Resolver([options])

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

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

resolver.cancel()

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

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

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

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

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

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

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 } (см. ниже), в зависимости от DNS-резолвера системы возвращается один или оба IPv4- и IPv6-адреса. По умолчанию: 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.

Поддерживаемые флаги 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 <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> Получает значение Time-To-Live (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> Получает значение Time-To-Live (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.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 promises DNS

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

Класс: dnsPromises.Resolver

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

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

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

Доступны следующие методы из 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()

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

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

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

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}]
});

dnsPromises.lookupService(address, port)

• address <string>
• port <number>

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

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

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

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

dnsPromises.resolve(hostname[, rrtype])

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

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

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

dnsPromises.resolve4(hostname[, options])

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

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

dnsPromises.resolve6(hostname[, options])

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

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

dnsPromises.resolveAny(hostname)

• hostname <string>

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

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

dnsPromises.resolveCname(hostname)

• hostname <string>

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

dnsPromises.resolveMx(hostname)

• hostname <string>

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

dnsPromises.resolveNaptr(hostname)

• hostname <string>

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

Использует протокол 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. Если используется стандартный порт DNS IANA (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), однако изменение этих файлов повлияет на поведение всех остальных программ, работающих в той же операционной системе.

Хотя с точки зрения JavaScript вызов dns.lookup() является асинхронным, фактически это синхронный вызов 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.