DNS

Модуль node:dns обеспечивает разрешение имён. Например, используйте его для поиска IP-адресов по именам хостов.

Хотя модуль назван в честь системы доменных имён (DNS), для поиска он не всегда использует протокол DNS. dns.lookup() использует средства операционной системы для разрешения имён. Для этого может не потребоваться сетевое взаимодействие. Чтобы разрешать имена так же, как это делают другие приложения в той же системе, используйте dns.lookup().

import dns from 'node:dns';

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

const dns = require('node:dns');

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

Все остальные функции модуля node:dns подключаются к настоящему DNS-серверу для разрешения имён. Для выполнения DNS-запросов они всегда используют сеть. Эти функции не используют тот же набор файлов конфигурации, что и dns.lookup() (например, /etc/hosts). Используйте эти функции, чтобы всегда выполнять DNS-запросы, минуя другие средства разрешения имён.

import dns from 'node: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)}`);
    });
  });
});

const dns = require('node: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.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()

Resolver([options])

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

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

resolver.cancel()

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

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

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

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

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

При запросах к DNS-серверам IPv4 резолвер будет использовать локальный адрес v4, а при запросах к DNS-серверам IPv6 — локальный адрес 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",
]
jsoncopy

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

• hostname <string>
• options <integer> | <Object>
  • family <integer> | <string> Семейство записей. Должно быть равно 4, 6 или 0. Для обеспечения обратной совместимости значения 'IPv4' и 'IPv6' интерпретируются соответственно как 4 и 6. Значение 0 означает, что возвращается IPv4- или IPv6-адрес. Если вместе с { all: true } (см. ниже) используется значение 0, возвращается один или оба 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-адреса. Не предоставляется, если options.all равно true.
  • family <integer> 4 или 6, обозначающее семейство address, либо 0, если адрес не является IPv4- или IPv6-адресом. Значение 0, вероятно, указывает на ошибку в службе разрешения имён, используемой операционной системой. Не предоставляется, если options.all равно true.
  • addresses <Object[]> Массив объектов адресов, если options.all равно true. Каждый объект имеет следующие свойства:
    • address <string> Строковое представление IPv4- или IPv6-адреса.
    • family <integer> 4 или 6, обозначающее семейство address.

Разрешает имя хоста (например, '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> Получает значение времени жизни (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 } ];
jscopy

Операторы 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,
});
jscopy

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

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

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

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 массив адресов в формате RFC 5952, представленных в виде <string[]>

Задает 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',
]);
jscopy

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

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

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

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

API промисов DNS

API dns.promises предоставляет альтернативный набор асинхронных методов DNS, которые возвращают объекты Promise вместо использования функций обратного вызова. API доступен через require('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.resolveTlsa()
• 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"
]
jsoncopy

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

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

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

dnsPromises.resolveSrv(hostname)

• hostname <string>

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

• priority
• weight
• port
• name

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

dnsPromises.resolveTlsa(hostname)

• hostname <string>

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

• certUsage
• selector
• match
• data

({
  certUsage: 3,
  selector: 1,
  match: 1,
  data: [ArrayBuffer],
});
jscopy

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',
]);
jscopy

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

Метод 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.