3e32d6df808976b7d12b9720d6d0654b3db73269443ddadbb329bb67f0ee314a83f2a62ad895a5e1a96df8e116e2af428e28f73197deb89364edff607c341d 35 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865
  1. /**
  2. * The `node:dns` module enables name resolution. For example, use it to look up IP
  3. * addresses of host names.
  4. *
  5. * Although named for the [Domain Name System (DNS)](https://en.wikipedia.org/wiki/Domain_Name_System), it does not always use the
  6. * DNS protocol for lookups. {@link lookup} uses the operating system
  7. * facilities to perform name resolution. It may not need to perform any network
  8. * communication. To perform name resolution the way other applications on the same
  9. * system do, use {@link lookup}.
  10. *
  11. * ```js
  12. * import dns from 'node:dns';
  13. *
  14. * dns.lookup('example.org', (err, address, family) => {
  15. * console.log('address: %j family: IPv%s', address, family);
  16. * });
  17. * // address: "93.184.216.34" family: IPv4
  18. * ```
  19. *
  20. * All other functions in the `node:dns` module connect to an actual DNS server to
  21. * perform name resolution. They will always use the network to perform DNS
  22. * queries. These functions do not use the same set of configuration files used by {@link lookup} (e.g. `/etc/hosts`). Use these functions to always perform
  23. * DNS queries, bypassing other name-resolution facilities.
  24. *
  25. * ```js
  26. * import dns from 'node:dns';
  27. *
  28. * dns.resolve4('archive.org', (err, addresses) => {
  29. * if (err) throw err;
  30. *
  31. * console.log(`addresses: ${JSON.stringify(addresses)}`);
  32. *
  33. * addresses.forEach((a) => {
  34. * dns.reverse(a, (err, hostnames) => {
  35. * if (err) {
  36. * throw err;
  37. * }
  38. * console.log(`reverse for ${a}: ${JSON.stringify(hostnames)}`);
  39. * });
  40. * });
  41. * });
  42. * ```
  43. *
  44. * See the [Implementation considerations section](https://nodejs.org/docs/latest-v22.x/api/dns.html#implementation-considerations) for more information.
  45. * @see [source](https://github.com/nodejs/node/blob/v22.x/lib/dns.js)
  46. */
  47. declare module "dns" {
  48. import * as dnsPromises from "node:dns/promises";
  49. // Supported getaddrinfo flags.
  50. /**
  51. * Limits returned address types to the types of non-loopback addresses configured on the system. For example, IPv4 addresses are
  52. * only returned if the current system has at least one IPv4 address configured.
  53. */
  54. export const ADDRCONFIG: number;
  55. /**
  56. * If the IPv6 family was specified, but no IPv6 addresses were found, then return IPv4 mapped IPv6 addresses. It is not supported
  57. * on some operating systems (e.g. FreeBSD 10.1).
  58. */
  59. export const V4MAPPED: number;
  60. /**
  61. * If `dns.V4MAPPED` is specified, return resolved IPv6 addresses as
  62. * well as IPv4 mapped IPv6 addresses.
  63. */
  64. export const ALL: number;
  65. export interface LookupOptions {
  66. /**
  67. * The record family. Must be `4`, `6`, or `0`. For backward compatibility reasons, `'IPv4'` and `'IPv6'` are interpreted
  68. * as `4` and `6` respectively. The value 0 indicates that either an IPv4 or IPv6 address is returned. If the value `0` is used
  69. * with `{ all: true } (see below)`, both IPv4 and IPv6 addresses are returned.
  70. * @default 0
  71. */
  72. family?: number | "IPv4" | "IPv6" | undefined;
  73. /**
  74. * One or more [supported `getaddrinfo`](https://nodejs.org/docs/latest-v22.x/api/dns.html#supported-getaddrinfo-flags) flags. Multiple flags may be
  75. * passed by bitwise `OR`ing their values.
  76. */
  77. hints?: number | undefined;
  78. /**
  79. * When `true`, the callback returns all resolved addresses in an array. Otherwise, returns a single address.
  80. * @default false
  81. */
  82. all?: boolean | undefined;
  83. /**
  84. * When `verbatim`, the resolved addresses are return unsorted. When `ipv4first`, the resolved addresses are sorted
  85. * by placing IPv4 addresses before IPv6 addresses. When `ipv6first`, the resolved addresses are sorted by placing IPv6
  86. * addresses before IPv4 addresses. Default value is configurable using
  87. * {@link setDefaultResultOrder} or [`--dns-result-order`](https://nodejs.org/docs/latest-v22.x/api/cli.html#--dns-result-orderorder).
  88. * @default `verbatim` (addresses are not reordered)
  89. * @since v22.1.0
  90. */
  91. order?: "ipv4first" | "ipv6first" | "verbatim" | undefined;
  92. /**
  93. * When `true`, the callback receives IPv4 and IPv6 addresses in the order the DNS resolver returned them. When `false`, IPv4
  94. * addresses are placed before IPv6 addresses. This option will be deprecated in favor of `order`. When both are specified,
  95. * `order` has higher precedence. New code should only use `order`. Default value is configurable using {@link setDefaultResultOrder}
  96. * @default true (addresses are not reordered)
  97. * @deprecated Please use `order` option
  98. */
  99. verbatim?: boolean | undefined;
  100. }
  101. export interface LookupOneOptions extends LookupOptions {
  102. all?: false | undefined;
  103. }
  104. export interface LookupAllOptions extends LookupOptions {
  105. all: true;
  106. }
  107. export interface LookupAddress {
  108. /**
  109. * A string representation of an IPv4 or IPv6 address.
  110. */
  111. address: string;
  112. /**
  113. * `4` or `6`, denoting the family of `address`, or `0` if the address is not an IPv4 or IPv6 address. `0` is a likely indicator of a
  114. * bug in the name resolution service used by the operating system.
  115. */
  116. family: number;
  117. }
  118. /**
  119. * Resolves a host name (e.g. `'nodejs.org'`) into the first found A (IPv4) or
  120. * AAAA (IPv6) record. All `option` properties are optional. If `options` is an
  121. * integer, then it must be `4` or `6` – if `options` is `0` or not provided, then
  122. * IPv4 and IPv6 addresses are both returned if found.
  123. *
  124. * With the `all` option set to `true`, the arguments for `callback` change to `(err, addresses)`, with `addresses` being an array of objects with the
  125. * properties `address` and `family`.
  126. *
  127. * On error, `err` is an `Error` object, where `err.code` is the error code.
  128. * Keep in mind that `err.code` will be set to `'ENOTFOUND'` not only when
  129. * the host name does not exist but also when the lookup fails in other ways
  130. * such as no available file descriptors.
  131. *
  132. * `dns.lookup()` does not necessarily have anything to do with the DNS protocol.
  133. * The implementation uses an operating system facility that can associate names
  134. * with addresses and vice versa. This implementation can have subtle but
  135. * important consequences on the behavior of any Node.js program. Please take some
  136. * time to consult the [Implementation considerations section](https://nodejs.org/docs/latest-v22.x/api/dns.html#implementation-considerations)
  137. * before using `dns.lookup()`.
  138. *
  139. * Example usage:
  140. *
  141. * ```js
  142. * import dns from 'node:dns';
  143. * const options = {
  144. * family: 6,
  145. * hints: dns.ADDRCONFIG | dns.V4MAPPED,
  146. * };
  147. * dns.lookup('example.com', options, (err, address, family) =>
  148. * console.log('address: %j family: IPv%s', address, family));
  149. * // address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6
  150. *
  151. * // When options.all is true, the result will be an Array.
  152. * options.all = true;
  153. * dns.lookup('example.com', options, (err, addresses) =>
  154. * console.log('addresses: %j', addresses));
  155. * // addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}]
  156. * ```
  157. *
  158. * If this method is invoked as its [util.promisify()](https://nodejs.org/docs/latest-v22.x/api/util.html#utilpromisifyoriginal) ed
  159. * version, and `all` is not set to `true`, it returns a `Promise` for an `Object` with `address` and `family` properties.
  160. * @since v0.1.90
  161. */
  162. export function lookup(
  163. hostname: string,
  164. family: number,
  165. callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void,
  166. ): void;
  167. export function lookup(
  168. hostname: string,
  169. options: LookupOneOptions,
  170. callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void,
  171. ): void;
  172. export function lookup(
  173. hostname: string,
  174. options: LookupAllOptions,
  175. callback: (err: NodeJS.ErrnoException | null, addresses: LookupAddress[]) => void,
  176. ): void;
  177. export function lookup(
  178. hostname: string,
  179. options: LookupOptions,
  180. callback: (err: NodeJS.ErrnoException | null, address: string | LookupAddress[], family: number) => void,
  181. ): void;
  182. export function lookup(
  183. hostname: string,
  184. callback: (err: NodeJS.ErrnoException | null, address: string, family: number) => void,
  185. ): void;
  186. export namespace lookup {
  187. function __promisify__(hostname: string, options: LookupAllOptions): Promise<LookupAddress[]>;
  188. function __promisify__(hostname: string, options?: LookupOneOptions | number): Promise<LookupAddress>;
  189. function __promisify__(hostname: string, options: LookupOptions): Promise<LookupAddress | LookupAddress[]>;
  190. }
  191. /**
  192. * Resolves the given `address` and `port` into a host name and service using
  193. * the operating system's underlying `getnameinfo` implementation.
  194. *
  195. * If `address` is not a valid IP address, a `TypeError` will be thrown.
  196. * The `port` will be coerced to a number. If it is not a legal port, a `TypeError` will be thrown.
  197. *
  198. * On an error, `err` is an [`Error`](https://nodejs.org/docs/latest-v22.x/api/errors.html#class-error) object,
  199. * where `err.code` is the error code.
  200. *
  201. * ```js
  202. * import dns from 'node:dns';
  203. * dns.lookupService('127.0.0.1', 22, (err, hostname, service) => {
  204. * console.log(hostname, service);
  205. * // Prints: localhost ssh
  206. * });
  207. * ```
  208. *
  209. * If this method is invoked as its [util.promisify()](https://nodejs.org/docs/latest-v22.x/api/util.html#utilpromisifyoriginal) ed
  210. * version, it returns a `Promise` for an `Object` with `hostname` and `service` properties.
  211. * @since v0.11.14
  212. */
  213. export function lookupService(
  214. address: string,
  215. port: number,
  216. callback: (err: NodeJS.ErrnoException | null, hostname: string, service: string) => void,
  217. ): void;
  218. export namespace lookupService {
  219. function __promisify__(
  220. address: string,
  221. port: number,
  222. ): Promise<{
  223. hostname: string;
  224. service: string;
  225. }>;
  226. }
  227. export interface ResolveOptions {
  228. ttl: boolean;
  229. }
  230. export interface ResolveWithTtlOptions extends ResolveOptions {
  231. ttl: true;
  232. }
  233. export interface RecordWithTtl {
  234. address: string;
  235. ttl: number;
  236. }
  237. /** @deprecated Use `AnyARecord` or `AnyAaaaRecord` instead. */
  238. export type AnyRecordWithTtl = AnyARecord | AnyAaaaRecord;
  239. export interface AnyARecord extends RecordWithTtl {
  240. type: "A";
  241. }
  242. export interface AnyAaaaRecord extends RecordWithTtl {
  243. type: "AAAA";
  244. }
  245. export interface CaaRecord {
  246. critical: number;
  247. issue?: string | undefined;
  248. issuewild?: string | undefined;
  249. iodef?: string | undefined;
  250. contactemail?: string | undefined;
  251. contactphone?: string | undefined;
  252. }
  253. export interface MxRecord {
  254. priority: number;
  255. exchange: string;
  256. }
  257. export interface AnyMxRecord extends MxRecord {
  258. type: "MX";
  259. }
  260. export interface NaptrRecord {
  261. flags: string;
  262. service: string;
  263. regexp: string;
  264. replacement: string;
  265. order: number;
  266. preference: number;
  267. }
  268. export interface AnyNaptrRecord extends NaptrRecord {
  269. type: "NAPTR";
  270. }
  271. export interface SoaRecord {
  272. nsname: string;
  273. hostmaster: string;
  274. serial: number;
  275. refresh: number;
  276. retry: number;
  277. expire: number;
  278. minttl: number;
  279. }
  280. export interface AnySoaRecord extends SoaRecord {
  281. type: "SOA";
  282. }
  283. export interface SrvRecord {
  284. priority: number;
  285. weight: number;
  286. port: number;
  287. name: string;
  288. }
  289. export interface AnySrvRecord extends SrvRecord {
  290. type: "SRV";
  291. }
  292. export interface AnyTxtRecord {
  293. type: "TXT";
  294. entries: string[];
  295. }
  296. export interface AnyNsRecord {
  297. type: "NS";
  298. value: string;
  299. }
  300. export interface AnyPtrRecord {
  301. type: "PTR";
  302. value: string;
  303. }
  304. export interface AnyCnameRecord {
  305. type: "CNAME";
  306. value: string;
  307. }
  308. export type AnyRecord =
  309. | AnyARecord
  310. | AnyAaaaRecord
  311. | AnyCnameRecord
  312. | AnyMxRecord
  313. | AnyNaptrRecord
  314. | AnyNsRecord
  315. | AnyPtrRecord
  316. | AnySoaRecord
  317. | AnySrvRecord
  318. | AnyTxtRecord;
  319. /**
  320. * Uses the DNS protocol to resolve a host name (e.g. `'nodejs.org'`) into an array
  321. * of the resource records. The `callback` function has arguments `(err, records)`. When successful, `records` will be an array of resource
  322. * records. The type and structure of individual results varies based on `rrtype`:
  323. *
  324. * <omitted>
  325. *
  326. * On error, `err` is an [`Error`](https://nodejs.org/docs/latest-v22.x/api/errors.html#class-error) object,
  327. * where `err.code` is one of the `DNS error codes`.
  328. * @since v0.1.27
  329. * @param hostname Host name to resolve.
  330. * @param [rrtype='A'] Resource record type.
  331. */
  332. export function resolve(
  333. hostname: string,
  334. callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void,
  335. ): void;
  336. export function resolve(
  337. hostname: string,
  338. rrtype: "A",
  339. callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void,
  340. ): void;
  341. export function resolve(
  342. hostname: string,
  343. rrtype: "AAAA",
  344. callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void,
  345. ): void;
  346. export function resolve(
  347. hostname: string,
  348. rrtype: "ANY",
  349. callback: (err: NodeJS.ErrnoException | null, addresses: AnyRecord[]) => void,
  350. ): void;
  351. export function resolve(
  352. hostname: string,
  353. rrtype: "CNAME",
  354. callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void,
  355. ): void;
  356. export function resolve(
  357. hostname: string,
  358. rrtype: "MX",
  359. callback: (err: NodeJS.ErrnoException | null, addresses: MxRecord[]) => void,
  360. ): void;
  361. export function resolve(
  362. hostname: string,
  363. rrtype: "NAPTR",
  364. callback: (err: NodeJS.ErrnoException | null, addresses: NaptrRecord[]) => void,
  365. ): void;
  366. export function resolve(
  367. hostname: string,
  368. rrtype: "NS",
  369. callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void,
  370. ): void;
  371. export function resolve(
  372. hostname: string,
  373. rrtype: "PTR",
  374. callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void,
  375. ): void;
  376. export function resolve(
  377. hostname: string,
  378. rrtype: "SOA",
  379. callback: (err: NodeJS.ErrnoException | null, addresses: SoaRecord) => void,
  380. ): void;
  381. export function resolve(
  382. hostname: string,
  383. rrtype: "SRV",
  384. callback: (err: NodeJS.ErrnoException | null, addresses: SrvRecord[]) => void,
  385. ): void;
  386. export function resolve(
  387. hostname: string,
  388. rrtype: "TXT",
  389. callback: (err: NodeJS.ErrnoException | null, addresses: string[][]) => void,
  390. ): void;
  391. export function resolve(
  392. hostname: string,
  393. rrtype: string,
  394. callback: (
  395. err: NodeJS.ErrnoException | null,
  396. addresses: string[] | MxRecord[] | NaptrRecord[] | SoaRecord | SrvRecord[] | string[][] | AnyRecord[],
  397. ) => void,
  398. ): void;
  399. export namespace resolve {
  400. function __promisify__(hostname: string, rrtype?: "A" | "AAAA" | "CNAME" | "NS" | "PTR"): Promise<string[]>;
  401. function __promisify__(hostname: string, rrtype: "ANY"): Promise<AnyRecord[]>;
  402. function __promisify__(hostname: string, rrtype: "MX"): Promise<MxRecord[]>;
  403. function __promisify__(hostname: string, rrtype: "NAPTR"): Promise<NaptrRecord[]>;
  404. function __promisify__(hostname: string, rrtype: "SOA"): Promise<SoaRecord>;
  405. function __promisify__(hostname: string, rrtype: "SRV"): Promise<SrvRecord[]>;
  406. function __promisify__(hostname: string, rrtype: "TXT"): Promise<string[][]>;
  407. function __promisify__(
  408. hostname: string,
  409. rrtype: string,
  410. ): Promise<string[] | MxRecord[] | NaptrRecord[] | SoaRecord | SrvRecord[] | string[][] | AnyRecord[]>;
  411. }
  412. /**
  413. * Uses the DNS protocol to resolve a IPv4 addresses (`A` records) for the `hostname`. The `addresses` argument passed to the `callback` function
  414. * will contain an array of IPv4 addresses (e.g.`['74.125.79.104', '74.125.79.105', '74.125.79.106']`).
  415. * @since v0.1.16
  416. * @param hostname Host name to resolve.
  417. */
  418. export function resolve4(
  419. hostname: string,
  420. callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void,
  421. ): void;
  422. export function resolve4(
  423. hostname: string,
  424. options: ResolveWithTtlOptions,
  425. callback: (err: NodeJS.ErrnoException | null, addresses: RecordWithTtl[]) => void,
  426. ): void;
  427. export function resolve4(
  428. hostname: string,
  429. options: ResolveOptions,
  430. callback: (err: NodeJS.ErrnoException | null, addresses: string[] | RecordWithTtl[]) => void,
  431. ): void;
  432. export namespace resolve4 {
  433. function __promisify__(hostname: string): Promise<string[]>;
  434. function __promisify__(hostname: string, options: ResolveWithTtlOptions): Promise<RecordWithTtl[]>;
  435. function __promisify__(hostname: string, options?: ResolveOptions): Promise<string[] | RecordWithTtl[]>;
  436. }
  437. /**
  438. * Uses the DNS protocol to resolve IPv6 addresses (`AAAA` records) for the `hostname`. The `addresses` argument passed to the `callback` function
  439. * will contain an array of IPv6 addresses.
  440. * @since v0.1.16
  441. * @param hostname Host name to resolve.
  442. */
  443. export function resolve6(
  444. hostname: string,
  445. callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void,
  446. ): void;
  447. export function resolve6(
  448. hostname: string,
  449. options: ResolveWithTtlOptions,
  450. callback: (err: NodeJS.ErrnoException | null, addresses: RecordWithTtl[]) => void,
  451. ): void;
  452. export function resolve6(
  453. hostname: string,
  454. options: ResolveOptions,
  455. callback: (err: NodeJS.ErrnoException | null, addresses: string[] | RecordWithTtl[]) => void,
  456. ): void;
  457. export namespace resolve6 {
  458. function __promisify__(hostname: string): Promise<string[]>;
  459. function __promisify__(hostname: string, options: ResolveWithTtlOptions): Promise<RecordWithTtl[]>;
  460. function __promisify__(hostname: string, options?: ResolveOptions): Promise<string[] | RecordWithTtl[]>;
  461. }
  462. /**
  463. * Uses the DNS protocol to resolve `CNAME` records for the `hostname`. The `addresses` argument passed to the `callback` function
  464. * will contain an array of canonical name records available for the `hostname` (e.g. `['bar.example.com']`).
  465. * @since v0.3.2
  466. */
  467. export function resolveCname(
  468. hostname: string,
  469. callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void,
  470. ): void;
  471. export namespace resolveCname {
  472. function __promisify__(hostname: string): Promise<string[]>;
  473. }
  474. /**
  475. * Uses the DNS protocol to resolve `CAA` records for the `hostname`. The `addresses` argument passed to the `callback` function
  476. * will contain an array of certification authority authorization records
  477. * available for the `hostname` (e.g. `[{critical: 0, iodef: 'mailto:pki@example.com'}, {critical: 128, issue: 'pki.example.com'}]`).
  478. * @since v15.0.0, v14.17.0
  479. */
  480. export function resolveCaa(
  481. hostname: string,
  482. callback: (err: NodeJS.ErrnoException | null, records: CaaRecord[]) => void,
  483. ): void;
  484. export namespace resolveCaa {
  485. function __promisify__(hostname: string): Promise<CaaRecord[]>;
  486. }
  487. /**
  488. * Uses the DNS protocol to resolve mail exchange records (`MX` records) for the `hostname`. The `addresses` argument passed to the `callback` function will
  489. * contain an array of objects containing both a `priority` and `exchange` property (e.g. `[{priority: 10, exchange: 'mx.example.com'}, ...]`).
  490. * @since v0.1.27
  491. */
  492. export function resolveMx(
  493. hostname: string,
  494. callback: (err: NodeJS.ErrnoException | null, addresses: MxRecord[]) => void,
  495. ): void;
  496. export namespace resolveMx {
  497. function __promisify__(hostname: string): Promise<MxRecord[]>;
  498. }
  499. /**
  500. * Uses the DNS protocol to resolve regular expression-based records (`NAPTR` records) for the `hostname`. The `addresses` argument passed to the `callback` function will contain an array of
  501. * objects with the following properties:
  502. *
  503. * * `flags`
  504. * * `service`
  505. * * `regexp`
  506. * * `replacement`
  507. * * `order`
  508. * * `preference`
  509. *
  510. * ```js
  511. * {
  512. * flags: 's',
  513. * service: 'SIP+D2U',
  514. * regexp: '',
  515. * replacement: '_sip._udp.example.com',
  516. * order: 30,
  517. * preference: 100
  518. * }
  519. * ```
  520. * @since v0.9.12
  521. */
  522. export function resolveNaptr(
  523. hostname: string,
  524. callback: (err: NodeJS.ErrnoException | null, addresses: NaptrRecord[]) => void,
  525. ): void;
  526. export namespace resolveNaptr {
  527. function __promisify__(hostname: string): Promise<NaptrRecord[]>;
  528. }
  529. /**
  530. * Uses the DNS protocol to resolve name server records (`NS` records) for the `hostname`. The `addresses` argument passed to the `callback` function will
  531. * contain an array of name server records available for `hostname` (e.g. `['ns1.example.com', 'ns2.example.com']`).
  532. * @since v0.1.90
  533. */
  534. export function resolveNs(
  535. hostname: string,
  536. callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void,
  537. ): void;
  538. export namespace resolveNs {
  539. function __promisify__(hostname: string): Promise<string[]>;
  540. }
  541. /**
  542. * Uses the DNS protocol to resolve pointer records (`PTR` records) for the `hostname`. The `addresses` argument passed to the `callback` function will
  543. * be an array of strings containing the reply records.
  544. * @since v6.0.0
  545. */
  546. export function resolvePtr(
  547. hostname: string,
  548. callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void,
  549. ): void;
  550. export namespace resolvePtr {
  551. function __promisify__(hostname: string): Promise<string[]>;
  552. }
  553. /**
  554. * Uses the DNS protocol to resolve a start of authority record (`SOA` record) for
  555. * the `hostname`. The `address` argument passed to the `callback` function will
  556. * be an object with the following properties:
  557. *
  558. * * `nsname`
  559. * * `hostmaster`
  560. * * `serial`
  561. * * `refresh`
  562. * * `retry`
  563. * * `expire`
  564. * * `minttl`
  565. *
  566. * ```js
  567. * {
  568. * nsname: 'ns.example.com',
  569. * hostmaster: 'root.example.com',
  570. * serial: 2013101809,
  571. * refresh: 10000,
  572. * retry: 2400,
  573. * expire: 604800,
  574. * minttl: 3600
  575. * }
  576. * ```
  577. * @since v0.11.10
  578. */
  579. export function resolveSoa(
  580. hostname: string,
  581. callback: (err: NodeJS.ErrnoException | null, address: SoaRecord) => void,
  582. ): void;
  583. export namespace resolveSoa {
  584. function __promisify__(hostname: string): Promise<SoaRecord>;
  585. }
  586. /**
  587. * Uses the DNS protocol to resolve service records (`SRV` records) for the `hostname`. The `addresses` argument passed to the `callback` function will
  588. * be an array of objects with the following properties:
  589. *
  590. * * `priority`
  591. * * `weight`
  592. * * `port`
  593. * * `name`
  594. *
  595. * ```js
  596. * {
  597. * priority: 10,
  598. * weight: 5,
  599. * port: 21223,
  600. * name: 'service.example.com'
  601. * }
  602. * ```
  603. * @since v0.1.27
  604. */
  605. export function resolveSrv(
  606. hostname: string,
  607. callback: (err: NodeJS.ErrnoException | null, addresses: SrvRecord[]) => void,
  608. ): void;
  609. export namespace resolveSrv {
  610. function __promisify__(hostname: string): Promise<SrvRecord[]>;
  611. }
  612. /**
  613. * Uses the DNS protocol to resolve text queries (`TXT` records) for the `hostname`. The `records` argument passed to the `callback` function is a
  614. * two-dimensional array of the text records available for `hostname` (e.g.`[ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]`). Each sub-array contains TXT chunks of
  615. * one record. Depending on the use case, these could be either joined together or
  616. * treated separately.
  617. * @since v0.1.27
  618. */
  619. export function resolveTxt(
  620. hostname: string,
  621. callback: (err: NodeJS.ErrnoException | null, addresses: string[][]) => void,
  622. ): void;
  623. export namespace resolveTxt {
  624. function __promisify__(hostname: string): Promise<string[][]>;
  625. }
  626. /**
  627. * Uses the DNS protocol to resolve all records (also known as `ANY` or `*` query).
  628. * The `ret` argument passed to the `callback` function will be an array containing
  629. * various types of records. Each object has a property `type` that indicates the
  630. * type of the current record. And depending on the `type`, additional properties
  631. * will be present on the object:
  632. *
  633. * <omitted>
  634. *
  635. * Here is an example of the `ret` object passed to the callback:
  636. *
  637. * ```js
  638. * [ { type: 'A', address: '127.0.0.1', ttl: 299 },
  639. * { type: 'CNAME', value: 'example.com' },
  640. * { type: 'MX', exchange: 'alt4.aspmx.l.example.com', priority: 50 },
  641. * { type: 'NS', value: 'ns1.example.com' },
  642. * { type: 'TXT', entries: [ 'v=spf1 include:_spf.example.com ~all' ] },
  643. * { type: 'SOA',
  644. * nsname: 'ns1.example.com',
  645. * hostmaster: 'admin.example.com',
  646. * serial: 156696742,
  647. * refresh: 900,
  648. * retry: 900,
  649. * expire: 1800,
  650. * minttl: 60 } ]
  651. * ```
  652. *
  653. * DNS server operators may choose not to respond to `ANY` queries. It may be better to call individual methods like {@link resolve4}, {@link resolveMx}, and so on. For more details, see
  654. * [RFC 8482](https://tools.ietf.org/html/rfc8482).
  655. */
  656. export function resolveAny(
  657. hostname: string,
  658. callback: (err: NodeJS.ErrnoException | null, addresses: AnyRecord[]) => void,
  659. ): void;
  660. export namespace resolveAny {
  661. function __promisify__(hostname: string): Promise<AnyRecord[]>;
  662. }
  663. /**
  664. * Performs a reverse DNS query that resolves an IPv4 or IPv6 address to an
  665. * array of host names.
  666. *
  667. * On error, `err` is an [`Error`](https://nodejs.org/docs/latest-v22.x/api/errors.html#class-error) object, where `err.code` is
  668. * one of the [DNS error codes](https://nodejs.org/docs/latest-v22.x/api/dns.html#error-codes).
  669. * @since v0.1.16
  670. */
  671. export function reverse(
  672. ip: string,
  673. callback: (err: NodeJS.ErrnoException | null, hostnames: string[]) => void,
  674. ): void;
  675. /**
  676. * Get the default value for `order` in {@link lookup} and [`dnsPromises.lookup()`](https://nodejs.org/docs/latest-v22.x/api/dns.html#dnspromiseslookuphostname-options).
  677. * The value could be:
  678. *
  679. * * `ipv4first`: for `order` defaulting to `ipv4first`.
  680. * * `ipv6first`: for `order` defaulting to `ipv6first`.
  681. * * `verbatim`: for `order` defaulting to `verbatim`.
  682. * @since v18.17.0
  683. */
  684. export function getDefaultResultOrder(): "ipv4first" | "ipv6first" | "verbatim";
  685. /**
  686. * Sets the IP address and port of servers to be used when performing DNS
  687. * resolution. The `servers` argument is an array of [RFC 5952](https://tools.ietf.org/html/rfc5952#section-6) formatted
  688. * addresses. If the port is the IANA default DNS port (53) it can be omitted.
  689. *
  690. * ```js
  691. * dns.setServers([
  692. * '4.4.4.4',
  693. * '[2001:4860:4860::8888]',
  694. * '4.4.4.4:1053',
  695. * '[2001:4860:4860::8888]:1053',
  696. * ]);
  697. * ```
  698. *
  699. * An error will be thrown if an invalid address is provided.
  700. *
  701. * The `dns.setServers()` method must not be called while a DNS query is in
  702. * progress.
  703. *
  704. * The {@link setServers} method affects only {@link resolve}, `dns.resolve*()` and {@link reverse} (and specifically _not_ {@link lookup}).
  705. *
  706. * This method works much like [resolve.conf](https://man7.org/linux/man-pages/man5/resolv.conf.5.html).
  707. * 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
  708. * subsequent servers provided. Fallback DNS servers will only be used if the
  709. * earlier ones time out or result in some other error.
  710. * @since v0.11.3
  711. * @param servers array of [RFC 5952](https://datatracker.ietf.org/doc/html/rfc5952#section-6) formatted addresses
  712. */
  713. export function setServers(servers: readonly string[]): void;
  714. /**
  715. * Returns an array of IP address strings, formatted according to [RFC 5952](https://tools.ietf.org/html/rfc5952#section-6),
  716. * that are currently configured for DNS resolution. A string will include a port
  717. * section if a custom port is used.
  718. *
  719. * ```js
  720. * [
  721. * '4.4.4.4',
  722. * '2001:4860:4860::8888',
  723. * '4.4.4.4:1053',
  724. * '[2001:4860:4860::8888]:1053',
  725. * ]
  726. * ```
  727. * @since v0.11.3
  728. */
  729. export function getServers(): string[];
  730. /**
  731. * Set the default value of `order` in {@link lookup} and [`dnsPromises.lookup()`](https://nodejs.org/docs/latest-v22.x/api/dns.html#dnspromiseslookuphostname-options).
  732. * The value could be:
  733. *
  734. * * `ipv4first`: sets default `order` to `ipv4first`.
  735. * * `ipv6first`: sets default `order` to `ipv6first`.
  736. * * `verbatim`: sets default `order` to `verbatim`.
  737. *
  738. * The default is `verbatim` and {@link setDefaultResultOrder} have higher
  739. * priority than [`--dns-result-order`](https://nodejs.org/docs/latest-v22.x/api/cli.html#--dns-result-orderorder). When using
  740. * [worker threads](https://nodejs.org/docs/latest-v22.x/api/worker_threads.html), {@link setDefaultResultOrder} from the main
  741. * thread won't affect the default dns orders in workers.
  742. * @since v16.4.0, v14.18.0
  743. * @param order must be `'ipv4first'`, `'ipv6first'` or `'verbatim'`.
  744. */
  745. export function setDefaultResultOrder(order: "ipv4first" | "ipv6first" | "verbatim"): void;
  746. // Error codes
  747. export const NODATA: "ENODATA";
  748. export const FORMERR: "EFORMERR";
  749. export const SERVFAIL: "ESERVFAIL";
  750. export const NOTFOUND: "ENOTFOUND";
  751. export const NOTIMP: "ENOTIMP";
  752. export const REFUSED: "EREFUSED";
  753. export const BADQUERY: "EBADQUERY";
  754. export const BADNAME: "EBADNAME";
  755. export const BADFAMILY: "EBADFAMILY";
  756. export const BADRESP: "EBADRESP";
  757. export const CONNREFUSED: "ECONNREFUSED";
  758. export const TIMEOUT: "ETIMEOUT";
  759. export const EOF: "EOF";
  760. export const FILE: "EFILE";
  761. export const NOMEM: "ENOMEM";
  762. export const DESTRUCTION: "EDESTRUCTION";
  763. export const BADSTR: "EBADSTR";
  764. export const BADFLAGS: "EBADFLAGS";
  765. export const NONAME: "ENONAME";
  766. export const BADHINTS: "EBADHINTS";
  767. export const NOTINITIALIZED: "ENOTINITIALIZED";
  768. export const LOADIPHLPAPI: "ELOADIPHLPAPI";
  769. export const ADDRGETNETWORKPARAMS: "EADDRGETNETWORKPARAMS";
  770. export const CANCELLED: "ECANCELLED";
  771. export interface ResolverOptions {
  772. /**
  773. * Query timeout in milliseconds, or `-1` to use the default timeout.
  774. */
  775. timeout?: number | undefined;
  776. /**
  777. * The number of tries the resolver will try contacting each name server before giving up.
  778. * @default 4
  779. */
  780. tries?: number;
  781. }
  782. /**
  783. * An independent resolver for DNS requests.
  784. *
  785. * Creating a new resolver uses the default server settings. Setting
  786. * the servers used for a resolver using [`resolver.setServers()`](https://nodejs.org/docs/latest-v22.x/api/dns.html#dnssetserversservers) does not affect
  787. * other resolvers:
  788. *
  789. * ```js
  790. * import { Resolver } from 'node:dns';
  791. * const resolver = new Resolver();
  792. * resolver.setServers(['4.4.4.4']);
  793. *
  794. * // This request will use the server at 4.4.4.4, independent of global settings.
  795. * resolver.resolve4('example.org', (err, addresses) => {
  796. * // ...
  797. * });
  798. * ```
  799. *
  800. * The following methods from the `node:dns` module are available:
  801. *
  802. * * `resolver.getServers()`
  803. * * `resolver.resolve()`
  804. * * `resolver.resolve4()`
  805. * * `resolver.resolve6()`
  806. * * `resolver.resolveAny()`
  807. * * `resolver.resolveCaa()`
  808. * * `resolver.resolveCname()`
  809. * * `resolver.resolveMx()`
  810. * * `resolver.resolveNaptr()`
  811. * * `resolver.resolveNs()`
  812. * * `resolver.resolvePtr()`
  813. * * `resolver.resolveSoa()`
  814. * * `resolver.resolveSrv()`
  815. * * `resolver.resolveTxt()`
  816. * * `resolver.reverse()`
  817. * * `resolver.setServers()`
  818. * @since v8.3.0
  819. */
  820. export class Resolver {
  821. constructor(options?: ResolverOptions);
  822. /**
  823. * Cancel all outstanding DNS queries made by this resolver. The corresponding
  824. * callbacks will be called with an error with code `ECANCELLED`.
  825. * @since v8.3.0
  826. */
  827. cancel(): void;
  828. getServers: typeof getServers;
  829. resolve: typeof resolve;
  830. resolve4: typeof resolve4;
  831. resolve6: typeof resolve6;
  832. resolveAny: typeof resolveAny;
  833. resolveCaa: typeof resolveCaa;
  834. resolveCname: typeof resolveCname;
  835. resolveMx: typeof resolveMx;
  836. resolveNaptr: typeof resolveNaptr;
  837. resolveNs: typeof resolveNs;
  838. resolvePtr: typeof resolvePtr;
  839. resolveSoa: typeof resolveSoa;
  840. resolveSrv: typeof resolveSrv;
  841. resolveTxt: typeof resolveTxt;
  842. reverse: typeof reverse;
  843. /**
  844. * The resolver instance will send its requests from the specified IP address.
  845. * This allows programs to specify outbound interfaces when used on multi-homed
  846. * systems.
  847. *
  848. * If a v4 or v6 address is not specified, it is set to the default and the
  849. * operating system will choose a local address automatically.
  850. *
  851. * The resolver will use the v4 local address when making requests to IPv4 DNS
  852. * servers, and the v6 local address when making requests to IPv6 DNS servers.
  853. * The `rrtype` of resolution requests has no impact on the local address used.
  854. * @since v15.1.0, v14.17.0
  855. * @param [ipv4='0.0.0.0'] A string representation of an IPv4 address.
  856. * @param [ipv6='::0'] A string representation of an IPv6 address.
  857. */
  858. setLocalAddress(ipv4?: string, ipv6?: string): void;
  859. setServers: typeof setServers;
  860. }
  861. export { dnsPromises as promises };
  862. }
  863. declare module "node:dns" {
  864. export * from "dns";
  865. }