5759901fc9e9c591950d8a4745e7b828efdaaeb4fdc72f31fde16492f99e3606d5d1073f069d35d36cbad23e4bb1272552d865ef5be79c4e11ee26f3ba4887 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503
  1. /**
  2. * The `dns.promises` API provides an alternative set of asynchronous DNS methods
  3. * that return `Promise` objects rather than using callbacks. The API is accessible
  4. * via `import { promises as dnsPromises } from 'node:dns'` or `import dnsPromises from 'node:dns/promises'`.
  5. * @since v10.6.0
  6. */
  7. declare module "dns/promises" {
  8. import {
  9. AnyRecord,
  10. CaaRecord,
  11. LookupAddress,
  12. LookupAllOptions,
  13. LookupOneOptions,
  14. LookupOptions,
  15. MxRecord,
  16. NaptrRecord,
  17. RecordWithTtl,
  18. ResolveOptions,
  19. ResolverOptions,
  20. ResolveWithTtlOptions,
  21. SoaRecord,
  22. SrvRecord,
  23. TlsaRecord,
  24. } from "node:dns";
  25. /**
  26. * Returns an array of IP address strings, formatted according to [RFC 5952](https://tools.ietf.org/html/rfc5952#section-6),
  27. * that are currently configured for DNS resolution. A string will include a port
  28. * section if a custom port is used.
  29. *
  30. * ```js
  31. * [
  32. * '4.4.4.4',
  33. * '2001:4860:4860::8888',
  34. * '4.4.4.4:1053',
  35. * '[2001:4860:4860::8888]:1053',
  36. * ]
  37. * ```
  38. * @since v10.6.0
  39. */
  40. function getServers(): string[];
  41. /**
  42. * Resolves a host name (e.g. `'nodejs.org'`) into the first found A (IPv4) or
  43. * AAAA (IPv6) record. All `option` properties are optional. If `options` is an
  44. * integer, then it must be `4` or `6` – if `options` is not provided, then IPv4
  45. * and IPv6 addresses are both returned if found.
  46. *
  47. * With the `all` option set to `true`, the `Promise` is resolved with `addresses` being an array of objects with the properties `address` and `family`.
  48. *
  49. * On error, the `Promise` is rejected with an [`Error`](https://nodejs.org/docs/latest-v20.x/api/errors.html#class-error) object, where `err.code` is the error code.
  50. * Keep in mind that `err.code` will be set to `'ENOTFOUND'` not only when
  51. * the host name does not exist but also when the lookup fails in other ways
  52. * such as no available file descriptors.
  53. *
  54. * [`dnsPromises.lookup()`](https://nodejs.org/docs/latest-v20.x/api/dns.html#dnspromiseslookuphostname-options) does not necessarily have anything to do with the DNS
  55. * protocol. The implementation uses an operating system facility that can
  56. * associate names with addresses and vice versa. This implementation can have
  57. * subtle but important consequences on the behavior of any Node.js program. Please
  58. * take some time to consult the [Implementation considerations section](https://nodejs.org/docs/latest-v20.x/api/dns.html#implementation-considerations) before
  59. * using `dnsPromises.lookup()`.
  60. *
  61. * Example usage:
  62. *
  63. * ```js
  64. * import dns from 'node:dns';
  65. * const dnsPromises = dns.promises;
  66. * const options = {
  67. * family: 6,
  68. * hints: dns.ADDRCONFIG | dns.V4MAPPED,
  69. * };
  70. *
  71. * dnsPromises.lookup('example.com', options).then((result) => {
  72. * console.log('address: %j family: IPv%s', result.address, result.family);
  73. * // address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6
  74. * });
  75. *
  76. * // When options.all is true, the result will be an Array.
  77. * options.all = true;
  78. * dnsPromises.lookup('example.com', options).then((result) => {
  79. * console.log('addresses: %j', result);
  80. * // addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}]
  81. * });
  82. * ```
  83. * @since v10.6.0
  84. */
  85. function lookup(hostname: string, family: number): Promise<LookupAddress>;
  86. function lookup(hostname: string, options: LookupOneOptions): Promise<LookupAddress>;
  87. function lookup(hostname: string, options: LookupAllOptions): Promise<LookupAddress[]>;
  88. function lookup(hostname: string, options: LookupOptions): Promise<LookupAddress | LookupAddress[]>;
  89. function lookup(hostname: string): Promise<LookupAddress>;
  90. /**
  91. * Resolves the given `address` and `port` into a host name and service using
  92. * the operating system's underlying `getnameinfo` implementation.
  93. *
  94. * If `address` is not a valid IP address, a `TypeError` will be thrown.
  95. * The `port` will be coerced to a number. If it is not a legal port, a `TypeError` will be thrown.
  96. *
  97. * On error, the `Promise` is rejected with an [`Error`](https://nodejs.org/docs/latest-v20.x/api/errors.html#class-error) object, where `err.code` is the error code.
  98. *
  99. * ```js
  100. * import dnsPromises from 'node:dns';
  101. * dnsPromises.lookupService('127.0.0.1', 22).then((result) => {
  102. * console.log(result.hostname, result.service);
  103. * // Prints: localhost ssh
  104. * });
  105. * ```
  106. * @since v10.6.0
  107. */
  108. function lookupService(
  109. address: string,
  110. port: number,
  111. ): Promise<{
  112. hostname: string;
  113. service: string;
  114. }>;
  115. /**
  116. * Uses the DNS protocol to resolve a host name (e.g. `'nodejs.org'`) into an array
  117. * of the resource records. When successful, the `Promise` is resolved with an
  118. * array of resource records. The type and structure of individual results vary
  119. * based on `rrtype`:
  120. *
  121. * <omitted>
  122. *
  123. * On error, the `Promise` is rejected with an [`Error`](https://nodejs.org/docs/latest-v20.x/api/errors.html#class-error) object, where `err.code`
  124. * is one of the [DNS error codes](https://nodejs.org/docs/latest-v20.x/api/dns.html#error-codes).
  125. * @since v10.6.0
  126. * @param hostname Host name to resolve.
  127. * @param [rrtype='A'] Resource record type.
  128. */
  129. function resolve(hostname: string): Promise<string[]>;
  130. function resolve(hostname: string, rrtype: "A" | "AAAA" | "CNAME" | "NS" | "PTR"): Promise<string[]>;
  131. function resolve(hostname: string, rrtype: "ANY"): Promise<AnyRecord[]>;
  132. function resolve(hostname: string, rrtype: "CAA"): Promise<CaaRecord[]>;
  133. function resolve(hostname: string, rrtype: "MX"): Promise<MxRecord[]>;
  134. function resolve(hostname: string, rrtype: "NAPTR"): Promise<NaptrRecord[]>;
  135. function resolve(hostname: string, rrtype: "SOA"): Promise<SoaRecord>;
  136. function resolve(hostname: string, rrtype: "SRV"): Promise<SrvRecord[]>;
  137. function resolve(hostname: string, rrtype: "TLSA"): Promise<TlsaRecord[]>;
  138. function resolve(hostname: string, rrtype: "TXT"): Promise<string[][]>;
  139. function resolve(hostname: string, rrtype: string): Promise<
  140. | string[]
  141. | CaaRecord[]
  142. | MxRecord[]
  143. | NaptrRecord[]
  144. | SoaRecord
  145. | SrvRecord[]
  146. | TlsaRecord[]
  147. | string[][]
  148. | AnyRecord[]
  149. >;
  150. /**
  151. * Uses the DNS protocol to resolve IPv4 addresses (`A` records) for the `hostname`. On success, the `Promise` is resolved with an array of IPv4
  152. * addresses (e.g. `['74.125.79.104', '74.125.79.105', '74.125.79.106']`).
  153. * @since v10.6.0
  154. * @param hostname Host name to resolve.
  155. */
  156. function resolve4(hostname: string): Promise<string[]>;
  157. function resolve4(hostname: string, options: ResolveWithTtlOptions): Promise<RecordWithTtl[]>;
  158. function resolve4(hostname: string, options: ResolveOptions): Promise<string[] | RecordWithTtl[]>;
  159. /**
  160. * Uses the DNS protocol to resolve IPv6 addresses (`AAAA` records) for the `hostname`. On success, the `Promise` is resolved with an array of IPv6
  161. * addresses.
  162. * @since v10.6.0
  163. * @param hostname Host name to resolve.
  164. */
  165. function resolve6(hostname: string): Promise<string[]>;
  166. function resolve6(hostname: string, options: ResolveWithTtlOptions): Promise<RecordWithTtl[]>;
  167. function resolve6(hostname: string, options: ResolveOptions): Promise<string[] | RecordWithTtl[]>;
  168. /**
  169. * Uses the DNS protocol to resolve all records (also known as `ANY` or `*` query).
  170. * On success, the `Promise` is resolved with an array containing various types of
  171. * records. Each object has a property `type` that indicates the type of the
  172. * current record. And depending on the `type`, additional properties will be
  173. * present on the object:
  174. *
  175. * <omitted>
  176. *
  177. * Here is an example of the result object:
  178. *
  179. * ```js
  180. * [ { type: 'A', address: '127.0.0.1', ttl: 299 },
  181. * { type: 'CNAME', value: 'example.com' },
  182. * { type: 'MX', exchange: 'alt4.aspmx.l.example.com', priority: 50 },
  183. * { type: 'NS', value: 'ns1.example.com' },
  184. * { type: 'TXT', entries: [ 'v=spf1 include:_spf.example.com ~all' ] },
  185. * { type: 'SOA',
  186. * nsname: 'ns1.example.com',
  187. * hostmaster: 'admin.example.com',
  188. * serial: 156696742,
  189. * refresh: 900,
  190. * retry: 900,
  191. * expire: 1800,
  192. * minttl: 60 } ]
  193. * ```
  194. * @since v10.6.0
  195. */
  196. function resolveAny(hostname: string): Promise<AnyRecord[]>;
  197. /**
  198. * Uses the DNS protocol to resolve `CAA` records for the `hostname`. On success,
  199. * the `Promise` is resolved with an array of objects containing available
  200. * certification authority authorization records available for the `hostname` (e.g. `[{critical: 0, iodef: 'mailto:pki@example.com'},{critical: 128, issue: 'pki.example.com'}]`).
  201. * @since v15.0.0, v14.17.0
  202. */
  203. function resolveCaa(hostname: string): Promise<CaaRecord[]>;
  204. /**
  205. * Uses the DNS protocol to resolve `CNAME` records for the `hostname`. On success,
  206. * the `Promise` is resolved with an array of canonical name records available for
  207. * the `hostname` (e.g. `['bar.example.com']`).
  208. * @since v10.6.0
  209. */
  210. function resolveCname(hostname: string): Promise<string[]>;
  211. /**
  212. * Uses the DNS protocol to resolve mail exchange records (`MX` records) for the `hostname`. On success, the `Promise` is resolved with an array of objects
  213. * containing both a `priority` and `exchange` property (e.g.`[{priority: 10, exchange: 'mx.example.com'}, ...]`).
  214. * @since v10.6.0
  215. */
  216. function resolveMx(hostname: string): Promise<MxRecord[]>;
  217. /**
  218. * Uses the DNS protocol to resolve regular expression-based records (`NAPTR` records) for the `hostname`. On success, the `Promise` is resolved with an array
  219. * of objects with the following properties:
  220. *
  221. * * `flags`
  222. * * `service`
  223. * * `regexp`
  224. * * `replacement`
  225. * * `order`
  226. * * `preference`
  227. *
  228. * ```js
  229. * {
  230. * flags: 's',
  231. * service: 'SIP+D2U',
  232. * regexp: '',
  233. * replacement: '_sip._udp.example.com',
  234. * order: 30,
  235. * preference: 100
  236. * }
  237. * ```
  238. * @since v10.6.0
  239. */
  240. function resolveNaptr(hostname: string): Promise<NaptrRecord[]>;
  241. /**
  242. * Uses the DNS protocol to resolve name server records (`NS` records) for the `hostname`. On success, the `Promise` is resolved with an array of name server
  243. * records available for `hostname` (e.g.`['ns1.example.com', 'ns2.example.com']`).
  244. * @since v10.6.0
  245. */
  246. function resolveNs(hostname: string): Promise<string[]>;
  247. /**
  248. * Uses the DNS protocol to resolve pointer records (`PTR` records) for the `hostname`. On success, the `Promise` is resolved with an array of strings
  249. * containing the reply records.
  250. * @since v10.6.0
  251. */
  252. function resolvePtr(hostname: string): Promise<string[]>;
  253. /**
  254. * Uses the DNS protocol to resolve a start of authority record (`SOA` record) for
  255. * the `hostname`. On success, the `Promise` is resolved with an object with the
  256. * following properties:
  257. *
  258. * * `nsname`
  259. * * `hostmaster`
  260. * * `serial`
  261. * * `refresh`
  262. * * `retry`
  263. * * `expire`
  264. * * `minttl`
  265. *
  266. * ```js
  267. * {
  268. * nsname: 'ns.example.com',
  269. * hostmaster: 'root.example.com',
  270. * serial: 2013101809,
  271. * refresh: 10000,
  272. * retry: 2400,
  273. * expire: 604800,
  274. * minttl: 3600
  275. * }
  276. * ```
  277. * @since v10.6.0
  278. */
  279. function resolveSoa(hostname: string): Promise<SoaRecord>;
  280. /**
  281. * Uses the DNS protocol to resolve service records (`SRV` records) for the `hostname`. On success, the `Promise` is resolved with an array of objects with
  282. * the following properties:
  283. *
  284. * * `priority`
  285. * * `weight`
  286. * * `port`
  287. * * `name`
  288. *
  289. * ```js
  290. * {
  291. * priority: 10,
  292. * weight: 5,
  293. * port: 21223,
  294. * name: 'service.example.com'
  295. * }
  296. * ```
  297. * @since v10.6.0
  298. */
  299. function resolveSrv(hostname: string): Promise<SrvRecord[]>;
  300. /**
  301. * Uses the DNS protocol to resolve certificate associations (`TLSA` records) for
  302. * the `hostname`. On success, the `Promise` is resolved with an array of objectsAdd commentMore actions
  303. * with these properties:
  304. *
  305. * * `certUsage`
  306. * * `selector`
  307. * * `match`
  308. * * `data`
  309. *
  310. * ```js
  311. * {
  312. * certUsage: 3,
  313. * selector: 1,
  314. * match: 1,
  315. * data: [ArrayBuffer]
  316. * }
  317. * ```
  318. * @since v23.9.0, v22.15.0
  319. */
  320. function resolveTlsa(hostname: string): Promise<TlsaRecord[]>;
  321. /**
  322. * Uses the DNS protocol to resolve text queries (`TXT` records) for the `hostname`. On success, the `Promise` is resolved with a two-dimensional array
  323. * of the text records available for `hostname` (e.g.`[ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]`). Each sub-array contains TXT chunks of
  324. * one record. Depending on the use case, these could be either joined together or
  325. * treated separately.
  326. * @since v10.6.0
  327. */
  328. function resolveTxt(hostname: string): Promise<string[][]>;
  329. /**
  330. * Performs a reverse DNS query that resolves an IPv4 or IPv6 address to an
  331. * array of host names.
  332. *
  333. * On error, the `Promise` is rejected with an [`Error`](https://nodejs.org/docs/latest-v20.x/api/errors.html#class-error) object, where `err.code`
  334. * is one of the [DNS error codes](https://nodejs.org/docs/latest-v20.x/api/dns.html#error-codes).
  335. * @since v10.6.0
  336. */
  337. function reverse(ip: string): Promise<string[]>;
  338. /**
  339. * Get the default value for `verbatim` in {@link lookup} and [dnsPromises.lookup()](https://nodejs.org/docs/latest-v20.x/api/dns.html#dnspromiseslookuphostname-options).
  340. * The value could be:
  341. *
  342. * * `ipv4first`: for `verbatim` defaulting to `false`.
  343. * * `verbatim`: for `verbatim` defaulting to `true`.
  344. * @since v20.1.0
  345. */
  346. function getDefaultResultOrder(): "ipv4first" | "verbatim";
  347. /**
  348. * Sets the IP address and port of servers to be used when performing DNS
  349. * resolution. The `servers` argument is an array of [RFC 5952](https://tools.ietf.org/html/rfc5952#section-6) formatted
  350. * addresses. If the port is the IANA default DNS port (53) it can be omitted.
  351. *
  352. * ```js
  353. * dnsPromises.setServers([
  354. * '4.4.4.4',
  355. * '[2001:4860:4860::8888]',
  356. * '4.4.4.4:1053',
  357. * '[2001:4860:4860::8888]:1053',
  358. * ]);
  359. * ```
  360. *
  361. * An error will be thrown if an invalid address is provided.
  362. *
  363. * The `dnsPromises.setServers()` method must not be called while a DNS query is in
  364. * progress.
  365. *
  366. * This method works much like [resolve.conf](https://man7.org/linux/man-pages/man5/resolv.conf.5.html).
  367. * That is, if attempting to resolve with the first server provided results in a `NOTFOUND` error, the `resolve()` method will _not_ attempt to resolve with
  368. * subsequent servers provided. Fallback DNS servers will only be used if the
  369. * earlier ones time out or result in some other error.
  370. * @since v10.6.0
  371. * @param servers array of `RFC 5952` formatted addresses
  372. */
  373. function setServers(servers: readonly string[]): void;
  374. /**
  375. * Set the default value of `order` in `dns.lookup()` and `{@link lookup}`. The value could be:
  376. *
  377. * * `ipv4first`: sets default `order` to `ipv4first`.
  378. * * `ipv6first`: sets default `order` to `ipv6first`.
  379. * * `verbatim`: sets default `order` to `verbatim`.
  380. *
  381. * The default is `verbatim` and [dnsPromises.setDefaultResultOrder()](https://nodejs.org/docs/latest-v20.x/api/dns.html#dnspromisessetdefaultresultorderorder)
  382. * have higher priority than [`--dns-result-order`](https://nodejs.org/docs/latest-v20.x/api/cli.html#--dns-result-orderorder).
  383. * When using [worker threads](https://nodejs.org/docs/latest-v20.x/api/worker_threads.html), [`dnsPromises.setDefaultResultOrder()`](https://nodejs.org/docs/latest-v20.x/api/dns.html#dnspromisessetdefaultresultorderorder)
  384. * from the main thread won't affect the default dns orders in workers.
  385. * @since v16.4.0, v14.18.0
  386. * @param order must be `'ipv4first'`, `'ipv6first'` or `'verbatim'`.
  387. */
  388. function setDefaultResultOrder(order: "ipv4first" | "ipv6first" | "verbatim"): void;
  389. // Error codes
  390. const NODATA: "ENODATA";
  391. const FORMERR: "EFORMERR";
  392. const SERVFAIL: "ESERVFAIL";
  393. const NOTFOUND: "ENOTFOUND";
  394. const NOTIMP: "ENOTIMP";
  395. const REFUSED: "EREFUSED";
  396. const BADQUERY: "EBADQUERY";
  397. const BADNAME: "EBADNAME";
  398. const BADFAMILY: "EBADFAMILY";
  399. const BADRESP: "EBADRESP";
  400. const CONNREFUSED: "ECONNREFUSED";
  401. const TIMEOUT: "ETIMEOUT";
  402. const EOF: "EOF";
  403. const FILE: "EFILE";
  404. const NOMEM: "ENOMEM";
  405. const DESTRUCTION: "EDESTRUCTION";
  406. const BADSTR: "EBADSTR";
  407. const BADFLAGS: "EBADFLAGS";
  408. const NONAME: "ENONAME";
  409. const BADHINTS: "EBADHINTS";
  410. const NOTINITIALIZED: "ENOTINITIALIZED";
  411. const LOADIPHLPAPI: "ELOADIPHLPAPI";
  412. const ADDRGETNETWORKPARAMS: "EADDRGETNETWORKPARAMS";
  413. const CANCELLED: "ECANCELLED";
  414. /**
  415. * An independent resolver for DNS requests.
  416. *
  417. * Creating a new resolver uses the default server settings. Setting
  418. * the servers used for a resolver using [`resolver.setServers()`](https://nodejs.org/docs/latest-v20.x/api/dns.html#dnspromisessetserversservers) does not affect
  419. * other resolvers:
  420. *
  421. * ```js
  422. * import { promises } from 'node:dns';
  423. * const resolver = new promises.Resolver();
  424. * resolver.setServers(['4.4.4.4']);
  425. *
  426. * // This request will use the server at 4.4.4.4, independent of global settings.
  427. * resolver.resolve4('example.org').then((addresses) => {
  428. * // ...
  429. * });
  430. *
  431. * // Alternatively, the same code can be written using async-await style.
  432. * (async function() {
  433. * const addresses = await resolver.resolve4('example.org');
  434. * })();
  435. * ```
  436. *
  437. * The following methods from the `dnsPromises` API are available:
  438. *
  439. * * `resolver.getServers()`
  440. * * `resolver.resolve()`
  441. * * `resolver.resolve4()`
  442. * * `resolver.resolve6()`
  443. * * `resolver.resolveAny()`
  444. * * `resolver.resolveCaa()`
  445. * * `resolver.resolveCname()`
  446. * * `resolver.resolveMx()`
  447. * * `resolver.resolveNaptr()`
  448. * * `resolver.resolveNs()`
  449. * * `resolver.resolvePtr()`
  450. * * `resolver.resolveSoa()`
  451. * * `resolver.resolveSrv()`
  452. * * `resolver.resolveTxt()`
  453. * * `resolver.reverse()`
  454. * * `resolver.setServers()`
  455. * @since v10.6.0
  456. */
  457. class Resolver {
  458. constructor(options?: ResolverOptions);
  459. /**
  460. * Cancel all outstanding DNS queries made by this resolver. The corresponding
  461. * callbacks will be called with an error with code `ECANCELLED`.
  462. * @since v8.3.0
  463. */
  464. cancel(): void;
  465. getServers: typeof getServers;
  466. resolve: typeof resolve;
  467. resolve4: typeof resolve4;
  468. resolve6: typeof resolve6;
  469. resolveAny: typeof resolveAny;
  470. resolveCaa: typeof resolveCaa;
  471. resolveCname: typeof resolveCname;
  472. resolveMx: typeof resolveMx;
  473. resolveNaptr: typeof resolveNaptr;
  474. resolveNs: typeof resolveNs;
  475. resolvePtr: typeof resolvePtr;
  476. resolveSoa: typeof resolveSoa;
  477. resolveSrv: typeof resolveSrv;
  478. resolveTlsa: typeof resolveTlsa;
  479. resolveTxt: typeof resolveTxt;
  480. reverse: typeof reverse;
  481. /**
  482. * The resolver instance will send its requests from the specified IP address.
  483. * This allows programs to specify outbound interfaces when used on multi-homed
  484. * systems.
  485. *
  486. * If a v4 or v6 address is not specified, it is set to the default and the
  487. * operating system will choose a local address automatically.
  488. *
  489. * The resolver will use the v4 local address when making requests to IPv4 DNS
  490. * servers, and the v6 local address when making requests to IPv6 DNS servers.
  491. * The `rrtype` of resolution requests has no impact on the local address used.
  492. * @since v15.1.0, v14.17.0
  493. * @param [ipv4='0.0.0.0'] A string representation of an IPv4 address.
  494. * @param [ipv6='::0'] A string representation of an IPv6 address.
  495. */
  496. setLocalAddress(ipv4?: string, ipv6?: string): void;
  497. setServers: typeof setServers;
  498. }
  499. }
  500. declare module "node:dns/promises" {
  501. export * from "dns/promises";
  502. }