dns/promises

API dns.promises предоставляет альтернативный набор асинхронных методов DNS, которые возвращают объекты Promise вместо использования функций обратного вызова. API доступен через import { promises as dnsPromises } from 'node:dns' или import dnsPromises from 'node:dns/promises'.

Использование в Deno

import * as mod from "node:dns/promises";

класс Resolver

Использование в Deno

import { Resolver } from "node:dns/promises";

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

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

import { promises } from 'node:dns';
const resolver = new promises.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(options?: ResolverOptions)

new

Свойства

getServers: getServers

resolve: resolve

resolve4: resolve4

resolve6: resolve6

resolveAny: resolveAny

resolveCaa: resolveCaa

resolveCname: resolveCname

resolveMx: resolveMx

resolveNaptr: resolveNaptr

resolveNs: resolveNs

resolvePtr: resolvePtr

resolveSoa: resolveSoa

resolveSrv: resolveSrv

resolveTxt: resolveTxt

reverse: reverse

setServers: setServers

Методы

cancel(): void

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

setLocalAddress(

ipv4?: string,

ipv6?: string,
): void

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

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

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

функция getDefaultResultOrder

Использование в Deno

import { getDefaultResultOrder } from "node:dns/promises";

getDefaultResultOrder(): "ipv4first" | "verbatim"

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

ipv4first: для verbatim значение по умолчанию — false.
verbatim: для verbatim значение по умолчанию — true.

Тип возвращаемого значения

"ipv4first" | "verbatim"

функция getServers

Использование в Deno

import { getServers } from "node:dns/promises";

getServers(): string[]

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

[
  '4.4.4.4',
  '2001:4860:4860::8888',
  '4.4.4.4:1053',
  '[2001:4860:4860::8888]:1053',
]

Тип возвращаемого значения

string[]

функция lookup

Использование в Deno

import { lookup } from "node:dns/promises";

Перегрузка 1

lookup(

hostname: string,

family: number,
): Promise<LookupAddress>

Разрешает имя узла (например, '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,
};

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

Параметры

hostname: string

family: number

Тип возвращаемого значения

Promise<LookupAddress>

Перегрузка 2

lookup(

hostname: string,

options: LookupOneOptions,
): Promise<LookupAddress>

Параметры

hostname: string

options: LookupOneOptions

Тип возвращаемого значения

Promise<LookupAddress>

Перегрузка 3

lookup(

hostname: string,

options: LookupAllOptions,
): Promise<LookupAddress[]>

Параметры

hostname: string

options: LookupAllOptions

Тип возвращаемого значения

Promise<LookupAddress[]>

Перегрузка 4

lookup(

hostname: string,

options: LookupOptions,
): Promise<LookupAddress | LookupAddress[]>

Параметры

hostname: string

options: LookupOptions

Тип возвращаемого значения

Promise<LookupAddress | LookupAddress[]>

Перегрузка 5

lookup(hostname: string): Promise<LookupAddress>

Параметры

hostname: string

Тип возвращаемого значения

Promise<LookupAddress>

функция lookupService

Использование в Deno

import { lookupService } from "node:dns/promises";

lookupService(

address: string,

port: number,
): Promise<{ hostname: string; service: string;  }>

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

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

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

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

Параметры

address: string

port: number

Тип возвращаемого значения

Promise<{ hostname: string; service: string; }>

функция resolve

Использование в Deno

import { resolve } from "node:dns/promises";

Перегрузка 1

resolve(hostname: string): Promise<string[]>

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

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

Параметры

hostname: string

Имя узла для разрешения.

Тип возвращаемого значения

Promise<string[]>

Перегрузка 2

resolve(

hostname: string,

rrtype: "A",
): Promise<string[]>

Параметры

hostname: string

rrtype: "A"

Тип возвращаемого значения

Promise<string[]>

Перегрузка 3

resolve(

hostname: string,

rrtype: "AAAA",
): Promise<string[]>

Параметры

hostname: string

rrtype: "AAAA"

Тип возвращаемого значения

Promise<string[]>

Перегрузка 4

resolve(

hostname: string,

rrtype: "ANY",
): Promise<AnyRecord[]>

Параметры

hostname: string

rrtype: "ANY"

Тип возвращаемого значения

Promise<AnyRecord[]>

Перегрузка 5

resolve(

hostname: string,

rrtype: "CAA",
): Promise<CaaRecord[]>

Параметры

hostname: string

rrtype: "CAA"

Тип возвращаемого значения

Promise<CaaRecord[]>

Перегрузка 6

resolve(

hostname: string,

rrtype: "CNAME",
): Promise<string[]>

Параметры

hostname: string

rrtype: "CNAME"

Тип возвращаемого значения

Promise<string[]>

Перегрузка 7

resolve(

hostname: string,

rrtype: "MX",
): Promise<MxRecord[]>

Параметры

hostname: string

rrtype: "MX"

Тип возвращаемого значения

Promise<MxRecord[]>

Перегрузка 8

resolve(

hostname: string,

rrtype: "NAPTR",
): Promise<NaptrRecord[]>

Параметры

hostname: string

rrtype: "NAPTR"

Тип возвращаемого значения

Promise<NaptrRecord[]>

Перегрузка 9

resolve(

hostname: string,

rrtype: "NS",
): Promise<string[]>

Параметры

hostname: string

rrtype: "NS"

Тип возвращаемого значения

Promise<string[]>

Перегрузка 10

resolve(

hostname: string,

rrtype: "PTR",
): Promise<string[]>

Параметры

hostname: string

rrtype: "PTR"

Тип возвращаемого значения

Promise<string[]>

Перегрузка 11

resolve(

hostname: string,

rrtype: "SOA",
): Promise<SoaRecord>

Параметры

hostname: string

rrtype: "SOA"

Тип возвращаемого значения

Promise<SoaRecord>

Перегрузка 12

resolve(

hostname: string,

rrtype: "SRV",
): Promise<SrvRecord[]>

Параметры

hostname: string

rrtype: "SRV"

Тип возвращаемого значения

Promise<SrvRecord[]>

Перегрузка 13

resolve(

hostname: string,

rrtype: "TXT",
): Promise<string[][]>

Параметры

hostname: string

rrtype: "TXT"

Тип возвращаемого значения

Promise<string[][]>

Перегрузка 14

resolve(

hostname: string,

rrtype: string,
): Promise<
string[]
 | MxRecord[]
 | NaptrRecord[]
 | SoaRecord
 | SrvRecord[]
 | string[][]
 | AnyRecord[]
>

Параметры

hostname: string

rrtype: string

Тип возвращаемого значения

Promise<
string[]
 | MxRecord[]
 | NaptrRecord[]
 | SoaRecord
 | SrvRecord[]
 | string[][]
 | AnyRecord[]
>

функция resolve4

Использование в Deno

import { resolve4 } from "node:dns/promises";

Перегрузка 1

resolve4(hostname: string): Promise<string[]>

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

Параметры

hostname: string

Имя хоста для разрешения.

Тип возвращаемого значения

Promise<string[]>

Перегрузка 2

resolve4(

hostname: string,

options: ResolveWithTtlOptions,
): Promise<RecordWithTtl[]>

Параметры

hostname: string

options: ResolveWithTtlOptions

Тип возвращаемого значения

Promise<RecordWithTtl[]>

Перегрузка 3

resolve4(

hostname: string,

options: ResolveOptions,
): Promise<string[] | RecordWithTtl[]>

Параметры

hostname: string

options: ResolveOptions

Тип возвращаемого значения

Promise<string[] | RecordWithTtl[]>

функция resolve6

Использование в Deno

import { resolve6 } from "node:dns/promises";

Перегрузка 1

resolve6(hostname: string): Promise<string[]>

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

Параметры

hostname: string

Имя хоста для разрешения.

Тип возвращаемого значения

Promise<string[]>

Перегрузка 2

resolve6(

hostname: string,

options: ResolveWithTtlOptions,
): Promise<RecordWithTtl[]>

Параметры

hostname: string

options: ResolveWithTtlOptions

Тип возвращаемого значения

Promise<RecordWithTtl[]>

Перегрузка 3

resolve6(

hostname: string,

options: ResolveOptions,
): Promise<string[] | RecordWithTtl[]>

Параметры

hostname: string

options: ResolveOptions

Тип возвращаемого значения

Promise<string[] | RecordWithTtl[]>

функция resolveAny

Использование в Deno

import { resolveAny } from "node:dns/promises";

resolveAny(hostname: string): Promise<AnyRecord[]>

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

Параметры

hostname: string

Тип возвращаемого значения

Promise<AnyRecord[]>

функция resolveCaa

Использование в Deno

import { resolveCaa } from "node:dns/promises";

resolveCaa(hostname: string): Promise<CaaRecord[]>

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

Параметры

hostname: string

Тип возвращаемого значения

Promise<CaaRecord[]>

функция resolveCname

Использование в Deno

import { resolveCname } from "node:dns/promises";

resolveCname(hostname: string): Promise<string[]>

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

Параметры

hostname: string

Тип возвращаемого значения

Promise<string[]>

функция resolveMx

Использование в Deno

import { resolveMx } from "node:dns/promises";

resolveMx(hostname: string): Promise<MxRecord[]>

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

Параметры

hostname: string

Тип возвращаемого значения

Promise<MxRecord[]>

функция resolveNaptr

Использование в Deno

import { resolveNaptr } from "node:dns/promises";

resolveNaptr(hostname: string): Promise<NaptrRecord[]>

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

Параметры

hostname: string

Тип возвращаемого значения

Promise<NaptrRecord[]>

функция resolveNs

Использование в Deno

import { resolveNs } from "node:dns/promises";

resolveNs(hostname: string): Promise<string[]>

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

Параметры

hostname: string

Тип возвращаемого значения

Promise<string[]>

функция resolvePtr

Использование в Deno

import { resolvePtr } from "node:dns/promises";

resolvePtr(hostname: string): Promise<string[]>

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

Параметры

hostname: string

Тип возвращаемого значения

Promise<string[]>

функция resolveSoa

Использование в Deno

import { resolveSoa } from "node:dns/promises";

resolveSoa(hostname: string): Promise<SoaRecord>

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

Параметры

hostname: string

Тип возвращаемого значения

Promise<SoaRecord>

функция resolveSrv

Использование в Deno

import { resolveSrv } from "node:dns/promises";

resolveSrv(hostname: string): Promise<SrvRecord[]>

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

priority
weight
port
name

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

Параметры

hostname: string

Тип возвращаемого значения

Promise<SrvRecord[]>

функция resolveTxt

Использование в Deno

import { resolveTxt } from "node:dns/promises";

resolveTxt(hostname: string): Promise<string[][]>

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

Параметры

hostname: string

Тип возвращаемого значения

Promise<string[][]>

функция reverse

Использование в Deno

import { reverse } from "node:dns/promises";

reverse(ip: string): Promise<string[]>

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

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

Параметры

ip: string

Тип возвращаемого значения

Promise<string[]>

функция setDefaultResultOrder

Использование в Deno

import { setDefaultResultOrder } from "node:dns/promises";

setDefaultResultOrder(order: 
"ipv4first"
 | "ipv6first"
 | "verbatim"
): void

Задаёт значение по умолчанию для order в dns.lookup() и [lookup](/api/node/dns/promises/. Возможны следующие значения:

ipv4first: задаёт значение order по умолчанию как ipv4first.
ipv6first: задаёт значение order по умолчанию как ipv6first.
verbatim: задаёт значение order по умолчанию как verbatim.

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

Параметры

order: 
"ipv4first"
 | "ipv6first"
 | "verbatim"

должно иметь значение 'ipv4first', 'ipv6first' или 'verbatim'.

Тип возвращаемого значения

void

функция setServers

Использование в Deno

import { setServers } from "node:dns/promises";

setServers(servers: readonly string[]): void

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

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-серверы будут использоваться, только если предыдущие серверы не ответят вовремя или возникнет какая-либо другая ошибка.

Параметры

servers: readonly string[]

массив адресов в формате RFC 5952

Тип возвращаемого значения

void

переменная ADDRGETNETWORKPARAMS

Использование в Deno

import { ADDRGETNETWORKPARAMS } from "node:dns/promises";

Тип

"EADDRGETNETWORKPARAMS"

переменная BADFAMILY

Использование в Deno

import { BADFAMILY } from "node:dns/promises";

Тип

"EBADFAMILY"

переменная BADFLAGS

Использование в Deno

import { BADFLAGS } from "node:dns/promises";

Тип

"EBADFLAGS"

переменная BADHINTS

Использование в Deno

import { BADHINTS } from "node:dns/promises";

Тип

"EBADHINTS"

переменная BADNAME

Использование в Deno

import { BADNAME } from "node:dns/promises";

Тип

"EBADNAME"

переменная BADQUERY

Использование в Deno

import { BADQUERY } from "node:dns/promises";

Тип

"EBADQUERY"

переменная BADRESP

Использование в Deno

import { BADRESP } from "node:dns/promises";

Тип

"EBADRESP"

переменная BADSTR

Использование в Deno

import { BADSTR } from "node:dns/promises";

Тип

"EBADSTR"

переменная CANCELLED

Использование в Deno

import { CANCELLED } from "node:dns/promises";

Тип

"ECANCELLED"

переменная CONNREFUSED

Использование в Deno

import { CONNREFUSED } from "node:dns/promises";

Тип

"ECONNREFUSED"

переменная DESTRUCTION

Использование в Deno

import { DESTRUCTION } from "node:dns/promises";

Тип

"EDESTRUCTION"

переменная EOF

Использование в Deno

import { EOF } from "node:dns/promises";

Тип

"EOF"

переменная FILE

Использование в Deno

import { FILE } from "node:dns/promises";

Тип

"EFILE"

переменная FORMERR

Использование в Deno

import { FORMERR } from "node:dns/promises";

Тип

"EFORMERR"

переменная LOADIPHLPAPI

Использование в Deno

import { LOADIPHLPAPI } from "node:dns/promises";

Тип

"ELOADIPHLPAPI"

переменная NODATA

Использование в Deno

import { NODATA } from "node:dns/promises";

Тип

"ENODATA"

переменная NOMEM

Использование в Deno

import { NOMEM } from "node:dns/promises";

Тип

"ENOMEM"

переменная NONAME

Использование в Deno

import { NONAME } from "node:dns/promises";

Тип

"ENONAME"

переменная NOTFOUND

Использование в Deno

import { NOTFOUND } from "node:dns/promises";

Тип

"ENOTFOUND"

переменная NOTIMP

Использование в Deno

import { NOTIMP } from "node:dns/promises";

Тип

"ENOTIMP"

переменная NOTINITIALIZED

Использование в Deno

import { NOTINITIALIZED } from "node:dns/promises";

Тип

"ENOTINITIALIZED"

переменная REFUSED

Использование в Deno

import { REFUSED } from "node:dns/promises";

Тип

"EREFUSED"

переменная SERVFAIL

Использование в Deno

import { SERVFAIL } from "node:dns/promises";

Тип

"ESERVFAIL"

переменная TIMEOUT

Использование в Deno

import { TIMEOUT } from "node:dns/promises";

Тип

"ETIMEOUT"