Перейти к содержанию

DNS

v18.x.x

Стабильность: 2 – Стабильная

АПИ является удовлетворительным. Совместимость с NPM имеет высший приоритет и не будет нарушена кроме случаев явной необходимости.

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const dns = require('node:dns');

dns.lookup('example.org', (err, address, family) => {
    console.log(
        'address: %j family: IPv%s',
        address,
        family
    );
});
// address: "93.184.216.34" family: IPv4

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
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() не влияет на другие резолверы:

1
2
3
4
5
6
7
8
const { Resolver } = require('node:dns');
const resolver = new Resolver();
resolver.setServers(['4.4.4.4']);

// Этот запрос будет использовать сервер по адресу 4.4.4.4, независимо от глобальных настроек.
resolver.resolve4('example.org', (err, addresses) => {
    // ...
});

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

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.0.
  • ipv6 <string> Строковое представление адреса IPv6. По умолчанию: ::0.

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

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

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

dns.getServers()

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

1
2
3
4
5
6
[
    '4.4.4.4',
    '2001:4860:4860::8888',
    '4.4.4.4:1053',
    '[2001:4860:4860::8888]:1053',
];

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

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

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

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

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

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
const dns = require('node:dns');
const options = {
    family: 6,
    hints: dns.ADDRCONFIG | dns.V4MAPPED,
};
dns.lookup('example.com', options, (err, address, family) =>
    console.log(
        'address: %j family: IPv%s',
        address,
        family
    )
);
// address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6

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

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

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

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

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

dns.lookupService(address, port, callback)

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

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

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

1
2
3
4
5
6
7
8
9
const dns = require('node:dns');
dns.lookupService(
    '127.0.0.1',
    22,
    (err, hostname, service) => {
        console.log(hostname, service);
        // Опечатка: localhost ssh
    }
);

Если этот метод вызывается как его util.promisify()ed версия, он возвращает 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:

rrtype records содержит Тип результата Метод сокращения .
'A' IPv4-адреса (по умолчанию) <string> dns.resolve4()
'AAAA' IPv6-адреса <string> dns.resolve6()
'ANY' любые записи <Object> dns.resolveAny() <Object>
'CAA' записи авторизации CA <Object> dns.resolveCaa()
'CNAME' записи канонических имен <string> dns.resolveCname()
'MX' записи почтового обмена <Object> dns.resolveMx() <Object>
'NAPTR' записи указателей полномочий на имя <Object> dns.resolveNaptr()
'NS' записи сервера имен <string> dns.resolveNs()
'PTR' записи указателей <string> dns.resolvePtr()
'SOA' начало авторитетных записей <Object> dns.resolveSoa()
'SRV' служебные записи <Object> dns.resolveSrv()
'TXT' текстовые записи <string[]> dns.resolveTxt()

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

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

  • hostname <string> Имя хоста для разрешения.
  • options <Object>
    • ttl <boolean> Извлекает значение времени жизни (TTL) каждой записи. Если true, обратный вызов получает массив {адрес: '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)

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

Type Properties
'A' address/ttl
'AAAA' | |address/ttl`
`CNAME' | value.
'MX' См. dns.resolveMx()
'NAPTR'
'NS' значение
'PTR'
'SOA' См. dns.resolveSoa()
'SRV'
'TXT'

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
[
    { 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,
    },
];

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

dns.resolveCname(hostname, callback)

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

dns.resolveCaa(hostname, callback)

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

dns.resolveMx(hostname, callback)

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

dns.resolveNaptr(hostname, callback)

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

  • flags
  • service
  • regexp
  • replacement
  • order
  • preference
1
2
3
4
5
6
7
8
{
  flags: 's',
  service: 'SIP+D2U',
  regexp: '',
  replacement: '_sip._udp.example.com',
  order: 30,
  preference: 100
}

dns.resolveNs(hostname, callback)

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

dns.resolvePtr(hostname, callback)

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

dns.resolveSoa(hostname, callback)

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

  • nsname
  • hostmaster
  • serial
  • refresh
  • retry
  • expire
  • minttl
1
2
3
4
5
6
7
8
9
{
  nsname: 'ns.example.com',
  hostmaster: 'root.example.com',
  serial: 2013101809,
  refresh: 10000,
  retry: 2400,
  expire: 604800,
  minttl: 3600
}

dns.resolveSrv(hostname, callback)

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

  • priority
  • weight
  • port
  • name
1
2
3
4
5
6
{
  priority: 10,
  weight: 5,
  port: 21223,
  name: 'service.example.com'
}

dns.resolveTxt(hostname, callback)

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

dns.reverse(ip, callback)

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

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

dns.setDefaultResultOrder(order)

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

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

  • ipv4first: устанавливает по умолчанию verbatim false.
  • verbatim: устанавливает значение по умолчанию verbatim true.

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

dns.setServers(servers)

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

1
2
3
4
5
6
dns.setServers([
    '4.4.4.4',
    '[2001:4860:4860::8888]',
    '4.4.4.4:1053',
    '[2001:4860:4860::8888]:1053',
]);

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

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

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

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

DNS promises API

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

Класс: dnsPromises.Resolver

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

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
const { Resolver } = require('node:dns').promises;
const resolver = new Resolver();
resolver.setServers(['4.4.4.4']);

// Этот запрос будет использовать сервер по адресу 4.4.4.4, независимо от глобальных настроек.
resolver.resolve4('example.org').then((addresses) => {
    // ...
});

// Альтернативно, тот же код можно написать, используя стиль async-await.
(async function () {
    const addresses = await resolver.resolve4(
        'example.org'
    );
})();

Доступны следующие методы из API dnsPromises:

resolver.cancel()

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

dnsPromises.getServers()

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

1
2
3
4
5
6
[
    '4.4.4.4',
    '2001:4860:4860::8888',
    '4.4.4.4:1053',
    '[2001:4860:4860::8888]:1053',
];

dnsPromises.lookup(hostname[, options])

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

Разрешает имя хоста (например, '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.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
const dns = require('node:dns');
const dnsPromises = dns.promises;
const options = {
    family: 6,
    hints: dns.ADDRCONFIG | dns.V4MAPPED,
};

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

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

dnsPromises.lookupService(address, port)

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

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

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

1
2
3
4
5
6
7
const dnsPromises = require('node:dns').promises;
dnsPromises
    .lookupService('127.0.0.1', 22)
    .then((result) => {
        console.log(result.hostname, result.service);
        // Опечатка: localhost ssh
    });

dnsPromises.resolve(hostname[, rrtype])

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

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

rrtype records contains Result type Shorthand method
'A' IPv4-адреса (по умолчанию) <string> dnsPromises.resolve4()
'AAAA' IPv6-адреса <string> dnsPromises.resolve6()
'ANY' любые записи <Object> dnsPromises.resolveAny()
'CAA' записи авторизации CA <Object> dnsPromises.resolveCaa()
'CNAME' записи канонических имен <string> dnsPromises.resolveCname()
'MX' записи почтового обмена <Object> dnsPromises.resolveMx()
'NAPTR' записи указателей полномочий на имя <Object> dnsPromises.resolveNaptr()
'NS' записи сервера имен <string> dnsPromises.resolveNs()
'PTR' записи указателей <string> dnsPromises.resolvePtr()
'SOA' начало авторитетных записей <Object> dnsPromises.resolveSoa()
'SRV' служебные записи <Object> dnsPromises.resolveSrv()
'TXT' текстовые записи <string[]> dnsPromises.resolveTxt()

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

dnsPromises.resolve4(hostname[, options])

  • hostname <string> Имя хоста для разрешения.
  • options <Object>
    • ttl <boolean> Получение значения времени жизни (TTL) каждой записи. Если true, то Promise разрешается с массивом {адрес: '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)

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

Type Properties
'A' address/ttl
'AAAA' | |address/ttl`
`CNAME' | value.
'MX' См. dnsPromises.resolveMx()
'NAPTR' Обратитесь к dnsPromises.resolveNaptr()
'NS' значение
'PTR' value
'SOA' См. dnsPromises.resolveSoa()
'SRV'
'TXT' Этот тип записи содержит свойство массива entries, которое ссылается на dnsPromises.resolveTxt(), например { entries: ['...'], type: 'TXT' }

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
[
    { 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,
    },
];

dnsPromises.resolveCaa(hostname)

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

dnsPromises.resolveCname(hostname)

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

dnsPromises.resolveMx(hostname)

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

dnsPromises.resolveNaptr(hostname)

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

  • flags
  • service
  • regexp
  • replacement
  • order
  • preference
1
2
3
4
5
6
7
8
{
  flags: 's',
  service: 'SIP+D2U',
  regexp: '',
  replacement: '_sip._udp.example.com',
  order: 30,
  preference: 100
}

dnsPromises.resolveNs(hostname)

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

dnsPromises.resolvePtr(hostname)

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

dnsPromises.resolveSoa(hostname)

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

  • nsname
  • hostmaster
  • serial
  • refresh
  • retry
  • expire
  • minttl
1
2
3
4
5
6
7
8
9
{
  nsname: 'ns.example.com',
  hostmaster: 'root.example.com',
  serial: 2013101809,
  refresh: 10000,
  retry: 2400,
  expire: 604800,
  minttl: 3600
}

dnsPromises.resolveSrv(hostname)

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

  • priority
  • weight
  • port
  • name
1
2
3
4
5
6
{
  priority: 10,
  weight: 5,
  port: 21223,
  name: 'service.example.com'
}

dnsPromises.resolveTxt(hostname)

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

dnsPromises.reverse(ip)

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

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

dnsPromises.setDefaultResultOrder(order)

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

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

  • ipv4first: устанавливает по умолчанию verbatim false.
  • verbatim: устанавливает значение по умолчанию verbatim true.

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

dnsPromises.setServers(servers)

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

1
2
3
4
5
6
dnsPromises.setServers([
    '4.4.4.4',
    '[2001:4860:4860::8888]',
    '4.4.4.4:1053',
    '[2001:4860:4860::8888]:1053',
]);

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

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

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

Коды ошибок

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

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

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

Соображения по реализации

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

dns.lookup()

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

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

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

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

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

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

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

Комментарии