34ff64c39b768af35bf93663cf6ad0ae23cdf0dc4381146480f04cf9f3dd21afc1eb937aa947f1683ddce5a85d61cfdb950623a3fd9a2d29d6fde8fee72992 36 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923
  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-v24.x/api/dns.html#implementation-considerations) for more information.
  45. * @see [source](https://github.com/nodejs/node/blob/v24.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-v24.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-v24.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-v24.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-v24.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-v24.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-v24.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 AnyCaaRecord extends CaaRecord {
  254. type: "CAA";
  255. }
  256. export interface MxRecord {
  257. priority: number;
  258. exchange: string;
  259. }
  260. export interface AnyMxRecord extends MxRecord {
  261. type: "MX";
  262. }
  263. export interface NaptrRecord {
  264. flags: string;
  265. service: string;
  266. regexp: string;
  267. replacement: string;
  268. order: number;
  269. preference: number;
  270. }
  271. export interface AnyNaptrRecord extends NaptrRecord {
  272. type: "NAPTR";
  273. }
  274. export interface SoaRecord {
  275. nsname: string;
  276. hostmaster: string;
  277. serial: number;
  278. refresh: number;
  279. retry: number;
  280. expire: number;
  281. minttl: number;
  282. }
  283. export interface AnySoaRecord extends SoaRecord {
  284. type: "SOA";
  285. }
  286. export interface SrvRecord {
  287. priority: number;
  288. weight: number;
  289. port: number;
  290. name: string;
  291. }
  292. export interface AnySrvRecord extends SrvRecord {
  293. type: "SRV";
  294. }
  295. export interface TlsaRecord {
  296. certUsage: number;
  297. selector: number;
  298. match: number;
  299. data: ArrayBuffer;
  300. }
  301. export interface AnyTlsaRecord extends TlsaRecord {
  302. type: "TLSA";
  303. }
  304. export interface AnyTxtRecord {
  305. type: "TXT";
  306. entries: string[];
  307. }
  308. export interface AnyNsRecord {
  309. type: "NS";
  310. value: string;
  311. }
  312. export interface AnyPtrRecord {
  313. type: "PTR";
  314. value: string;
  315. }
  316. export interface AnyCnameRecord {
  317. type: "CNAME";
  318. value: string;
  319. }
  320. export type AnyRecord =
  321. | AnyARecord
  322. | AnyAaaaRecord
  323. | AnyCaaRecord
  324. | AnyCnameRecord
  325. | AnyMxRecord
  326. | AnyNaptrRecord
  327. | AnyNsRecord
  328. | AnyPtrRecord
  329. | AnySoaRecord
  330. | AnySrvRecord
  331. | AnyTlsaRecord
  332. | AnyTxtRecord;
  333. /**
  334. * Uses the DNS protocol to resolve a host name (e.g. `'nodejs.org'`) into an array
  335. * of the resource records. The `callback` function has arguments `(err, records)`. When successful, `records` will be an array of resource
  336. * records. The type and structure of individual results varies based on `rrtype`:
  337. *
  338. * <omitted>
  339. *
  340. * On error, `err` is an [`Error`](https://nodejs.org/docs/latest-v24.x/api/errors.html#class-error) object,
  341. * where `err.code` is one of the `DNS error codes`.
  342. * @since v0.1.27
  343. * @param hostname Host name to resolve.
  344. * @param [rrtype='A'] Resource record type.
  345. */
  346. export function resolve(
  347. hostname: string,
  348. callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void,
  349. ): void;
  350. export function resolve(
  351. hostname: string,
  352. rrtype: "A" | "AAAA" | "CNAME" | "NS" | "PTR",
  353. callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void,
  354. ): void;
  355. export function resolve(
  356. hostname: string,
  357. rrtype: "ANY",
  358. callback: (err: NodeJS.ErrnoException | null, addresses: AnyRecord[]) => void,
  359. ): void;
  360. export function resolve(
  361. hostname: string,
  362. rrtype: "CAA",
  363. callback: (err: NodeJS.ErrnoException | null, address: CaaRecord[]) => void,
  364. ): void;
  365. export function resolve(
  366. hostname: string,
  367. rrtype: "MX",
  368. callback: (err: NodeJS.ErrnoException | null, addresses: MxRecord[]) => void,
  369. ): void;
  370. export function resolve(
  371. hostname: string,
  372. rrtype: "NAPTR",
  373. callback: (err: NodeJS.ErrnoException | null, addresses: NaptrRecord[]) => void,
  374. ): void;
  375. export function resolve(
  376. hostname: string,
  377. rrtype: "SOA",
  378. callback: (err: NodeJS.ErrnoException | null, addresses: SoaRecord) => void,
  379. ): void;
  380. export function resolve(
  381. hostname: string,
  382. rrtype: "SRV",
  383. callback: (err: NodeJS.ErrnoException | null, addresses: SrvRecord[]) => void,
  384. ): void;
  385. export function resolve(
  386. hostname: string,
  387. rrtype: "TLSA",
  388. callback: (err: NodeJS.ErrnoException | null, addresses: TlsaRecord[]) => void,
  389. ): void;
  390. export function resolve(
  391. hostname: string,
  392. rrtype: "TXT",
  393. callback: (err: NodeJS.ErrnoException | null, addresses: string[][]) => void,
  394. ): void;
  395. export function resolve(
  396. hostname: string,
  397. rrtype: string,
  398. callback: (
  399. err: NodeJS.ErrnoException | null,
  400. addresses:
  401. | string[]
  402. | CaaRecord[]
  403. | MxRecord[]
  404. | NaptrRecord[]
  405. | SoaRecord
  406. | SrvRecord[]
  407. | TlsaRecord[]
  408. | string[][]
  409. | AnyRecord[],
  410. ) => void,
  411. ): void;
  412. export namespace resolve {
  413. function __promisify__(hostname: string, rrtype?: "A" | "AAAA" | "CNAME" | "NS" | "PTR"): Promise<string[]>;
  414. function __promisify__(hostname: string, rrtype: "ANY"): Promise<AnyRecord[]>;
  415. function __promisify__(hostname: string, rrtype: "CAA"): Promise<CaaRecord[]>;
  416. function __promisify__(hostname: string, rrtype: "MX"): Promise<MxRecord[]>;
  417. function __promisify__(hostname: string, rrtype: "NAPTR"): Promise<NaptrRecord[]>;
  418. function __promisify__(hostname: string, rrtype: "SOA"): Promise<SoaRecord>;
  419. function __promisify__(hostname: string, rrtype: "SRV"): Promise<SrvRecord[]>;
  420. function __promisify__(hostname: string, rrtype: "TLSA"): Promise<TlsaRecord[]>;
  421. function __promisify__(hostname: string, rrtype: "TXT"): Promise<string[][]>;
  422. function __promisify__(
  423. hostname: string,
  424. rrtype: string,
  425. ): Promise<
  426. | string[]
  427. | CaaRecord[]
  428. | MxRecord[]
  429. | NaptrRecord[]
  430. | SoaRecord
  431. | SrvRecord[]
  432. | TlsaRecord[]
  433. | string[][]
  434. | AnyRecord[]
  435. >;
  436. }
  437. /**
  438. * Uses the DNS protocol to resolve a IPv4 addresses (`A` records) for the `hostname`. The `addresses` argument passed to the `callback` function
  439. * will contain an array of IPv4 addresses (e.g.`['74.125.79.104', '74.125.79.105', '74.125.79.106']`).
  440. * @since v0.1.16
  441. * @param hostname Host name to resolve.
  442. */
  443. export function resolve4(
  444. hostname: string,
  445. callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void,
  446. ): void;
  447. export function resolve4(
  448. hostname: string,
  449. options: ResolveWithTtlOptions,
  450. callback: (err: NodeJS.ErrnoException | null, addresses: RecordWithTtl[]) => void,
  451. ): void;
  452. export function resolve4(
  453. hostname: string,
  454. options: ResolveOptions,
  455. callback: (err: NodeJS.ErrnoException | null, addresses: string[] | RecordWithTtl[]) => void,
  456. ): void;
  457. export namespace resolve4 {
  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 IPv6 addresses (`AAAA` records) for the `hostname`. The `addresses` argument passed to the `callback` function
  464. * will contain an array of IPv6 addresses.
  465. * @since v0.1.16
  466. * @param hostname Host name to resolve.
  467. */
  468. export function resolve6(
  469. hostname: string,
  470. callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void,
  471. ): void;
  472. export function resolve6(
  473. hostname: string,
  474. options: ResolveWithTtlOptions,
  475. callback: (err: NodeJS.ErrnoException | null, addresses: RecordWithTtl[]) => void,
  476. ): void;
  477. export function resolve6(
  478. hostname: string,
  479. options: ResolveOptions,
  480. callback: (err: NodeJS.ErrnoException | null, addresses: string[] | RecordWithTtl[]) => void,
  481. ): void;
  482. export namespace resolve6 {
  483. function __promisify__(hostname: string): Promise<string[]>;
  484. function __promisify__(hostname: string, options: ResolveWithTtlOptions): Promise<RecordWithTtl[]>;
  485. function __promisify__(hostname: string, options?: ResolveOptions): Promise<string[] | RecordWithTtl[]>;
  486. }
  487. /**
  488. * Uses the DNS protocol to resolve `CNAME` records for the `hostname`. The `addresses` argument passed to the `callback` function
  489. * will contain an array of canonical name records available for the `hostname` (e.g. `['bar.example.com']`).
  490. * @since v0.3.2
  491. */
  492. export function resolveCname(
  493. hostname: string,
  494. callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void,
  495. ): void;
  496. export namespace resolveCname {
  497. function __promisify__(hostname: string): Promise<string[]>;
  498. }
  499. /**
  500. * Uses the DNS protocol to resolve `CAA` records for the `hostname`. The `addresses` argument passed to the `callback` function
  501. * will contain an array of certification authority authorization records
  502. * available for the `hostname` (e.g. `[{critical: 0, iodef: 'mailto:pki@example.com'}, {critical: 128, issue: 'pki.example.com'}]`).
  503. * @since v15.0.0, v14.17.0
  504. */
  505. export function resolveCaa(
  506. hostname: string,
  507. callback: (err: NodeJS.ErrnoException | null, records: CaaRecord[]) => void,
  508. ): void;
  509. export namespace resolveCaa {
  510. function __promisify__(hostname: string): Promise<CaaRecord[]>;
  511. }
  512. /**
  513. * Uses the DNS protocol to resolve mail exchange records (`MX` records) for the `hostname`. The `addresses` argument passed to the `callback` function will
  514. * contain an array of objects containing both a `priority` and `exchange` property (e.g. `[{priority: 10, exchange: 'mx.example.com'}, ...]`).
  515. * @since v0.1.27
  516. */
  517. export function resolveMx(
  518. hostname: string,
  519. callback: (err: NodeJS.ErrnoException | null, addresses: MxRecord[]) => void,
  520. ): void;
  521. export namespace resolveMx {
  522. function __promisify__(hostname: string): Promise<MxRecord[]>;
  523. }
  524. /**
  525. * 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
  526. * objects with the following properties:
  527. *
  528. * * `flags`
  529. * * `service`
  530. * * `regexp`
  531. * * `replacement`
  532. * * `order`
  533. * * `preference`
  534. *
  535. * ```js
  536. * {
  537. * flags: 's',
  538. * service: 'SIP+D2U',
  539. * regexp: '',
  540. * replacement: '_sip._udp.example.com',
  541. * order: 30,
  542. * preference: 100
  543. * }
  544. * ```
  545. * @since v0.9.12
  546. */
  547. export function resolveNaptr(
  548. hostname: string,
  549. callback: (err: NodeJS.ErrnoException | null, addresses: NaptrRecord[]) => void,
  550. ): void;
  551. export namespace resolveNaptr {
  552. function __promisify__(hostname: string): Promise<NaptrRecord[]>;
  553. }
  554. /**
  555. * Uses the DNS protocol to resolve name server records (`NS` records) for the `hostname`. The `addresses` argument passed to the `callback` function will
  556. * contain an array of name server records available for `hostname` (e.g. `['ns1.example.com', 'ns2.example.com']`).
  557. * @since v0.1.90
  558. */
  559. export function resolveNs(
  560. hostname: string,
  561. callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void,
  562. ): void;
  563. export namespace resolveNs {
  564. function __promisify__(hostname: string): Promise<string[]>;
  565. }
  566. /**
  567. * Uses the DNS protocol to resolve pointer records (`PTR` records) for the `hostname`. The `addresses` argument passed to the `callback` function will
  568. * be an array of strings containing the reply records.
  569. * @since v6.0.0
  570. */
  571. export function resolvePtr(
  572. hostname: string,
  573. callback: (err: NodeJS.ErrnoException | null, addresses: string[]) => void,
  574. ): void;
  575. export namespace resolvePtr {
  576. function __promisify__(hostname: string): Promise<string[]>;
  577. }
  578. /**
  579. * Uses the DNS protocol to resolve a start of authority record (`SOA` record) for
  580. * the `hostname`. The `address` argument passed to the `callback` function will
  581. * be an object with the following properties:
  582. *
  583. * * `nsname`
  584. * * `hostmaster`
  585. * * `serial`
  586. * * `refresh`
  587. * * `retry`
  588. * * `expire`
  589. * * `minttl`
  590. *
  591. * ```js
  592. * {
  593. * nsname: 'ns.example.com',
  594. * hostmaster: 'root.example.com',
  595. * serial: 2013101809,
  596. * refresh: 10000,
  597. * retry: 2400,
  598. * expire: 604800,
  599. * minttl: 3600
  600. * }
  601. * ```
  602. * @since v0.11.10
  603. */
  604. export function resolveSoa(
  605. hostname: string,
  606. callback: (err: NodeJS.ErrnoException | null, address: SoaRecord) => void,
  607. ): void;
  608. export namespace resolveSoa {
  609. function __promisify__(hostname: string): Promise<SoaRecord>;
  610. }
  611. /**
  612. * Uses the DNS protocol to resolve service records (`SRV` records) for the `hostname`. The `addresses` argument passed to the `callback` function will
  613. * be an array of objects with the following properties:
  614. *
  615. * * `priority`
  616. * * `weight`
  617. * * `port`
  618. * * `name`
  619. *
  620. * ```js
  621. * {
  622. * priority: 10,
  623. * weight: 5,
  624. * port: 21223,
  625. * name: 'service.example.com'
  626. * }
  627. * ```
  628. * @since v0.1.27
  629. */
  630. export function resolveSrv(
  631. hostname: string,
  632. callback: (err: NodeJS.ErrnoException | null, addresses: SrvRecord[]) => void,
  633. ): void;
  634. export namespace resolveSrv {
  635. function __promisify__(hostname: string): Promise<SrvRecord[]>;
  636. }
  637. /**
  638. * Uses the DNS protocol to resolve certificate associations (`TLSA` records) for
  639. * the `hostname`. The `records` argument passed to the `callback` function is an
  640. * array of objects with these properties:
  641. *
  642. * * `certUsage`
  643. * * `selector`
  644. * * `match`
  645. * * `data`
  646. *
  647. * ```js
  648. * {
  649. * certUsage: 3,
  650. * selector: 1,
  651. * match: 1,
  652. * data: [ArrayBuffer]
  653. * }
  654. * ```
  655. * @since v23.9.0, v22.15.0
  656. */
  657. export function resolveTlsa(
  658. hostname: string,
  659. callback: (err: NodeJS.ErrnoException | null, addresses: TlsaRecord[]) => void,
  660. ): void;
  661. export namespace resolveTlsa {
  662. function __promisify__(hostname: string): Promise<TlsaRecord[]>;
  663. }
  664. /**
  665. * Uses the DNS protocol to resolve text queries (`TXT` records) for the `hostname`. The `records` argument passed to the `callback` function is a
  666. * 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
  667. * one record. Depending on the use case, these could be either joined together or
  668. * treated separately.
  669. * @since v0.1.27
  670. */
  671. export function resolveTxt(
  672. hostname: string,
  673. callback: (err: NodeJS.ErrnoException | null, addresses: string[][]) => void,
  674. ): void;
  675. export namespace resolveTxt {
  676. function __promisify__(hostname: string): Promise<string[][]>;
  677. }
  678. /**
  679. * Uses the DNS protocol to resolve all records (also known as `ANY` or `*` query).
  680. * The `ret` argument passed to the `callback` function will be an array containing
  681. * various types of records. Each object has a property `type` that indicates the
  682. * type of the current record. And depending on the `type`, additional properties
  683. * will be present on the object:
  684. *
  685. * <omitted>
  686. *
  687. * Here is an example of the `ret` object passed to the callback:
  688. *
  689. * ```js
  690. * [ { type: 'A', address: '127.0.0.1', ttl: 299 },
  691. * { type: 'CNAME', value: 'example.com' },
  692. * { type: 'MX', exchange: 'alt4.aspmx.l.example.com', priority: 50 },
  693. * { type: 'NS', value: 'ns1.example.com' },
  694. * { type: 'TXT', entries: [ 'v=spf1 include:_spf.example.com ~all' ] },
  695. * { type: 'SOA',
  696. * nsname: 'ns1.example.com',
  697. * hostmaster: 'admin.example.com',
  698. * serial: 156696742,
  699. * refresh: 900,
  700. * retry: 900,
  701. * expire: 1800,
  702. * minttl: 60 } ]
  703. * ```
  704. *
  705. * 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
  706. * [RFC 8482](https://tools.ietf.org/html/rfc8482).
  707. */
  708. export function resolveAny(
  709. hostname: string,
  710. callback: (err: NodeJS.ErrnoException | null, addresses: AnyRecord[]) => void,
  711. ): void;
  712. export namespace resolveAny {
  713. function __promisify__(hostname: string): Promise<AnyRecord[]>;
  714. }
  715. /**
  716. * Performs a reverse DNS query that resolves an IPv4 or IPv6 address to an
  717. * array of host names.
  718. *
  719. * On error, `err` is an [`Error`](https://nodejs.org/docs/latest-v24.x/api/errors.html#class-error) object, where `err.code` is
  720. * one of the [DNS error codes](https://nodejs.org/docs/latest-v24.x/api/dns.html#error-codes).
  721. * @since v0.1.16
  722. */
  723. export function reverse(
  724. ip: string,
  725. callback: (err: NodeJS.ErrnoException | null, hostnames: string[]) => void,
  726. ): void;
  727. /**
  728. * Get the default value for `order` in {@link lookup} and [`dnsPromises.lookup()`](https://nodejs.org/docs/latest-v24.x/api/dns.html#dnspromiseslookuphostname-options).
  729. * The value could be:
  730. *
  731. * * `ipv4first`: for `order` defaulting to `ipv4first`.
  732. * * `ipv6first`: for `order` defaulting to `ipv6first`.
  733. * * `verbatim`: for `order` defaulting to `verbatim`.
  734. * @since v18.17.0
  735. */
  736. export function getDefaultResultOrder(): "ipv4first" | "ipv6first" | "verbatim";
  737. /**
  738. * Sets the IP address and port of servers to be used when performing DNS
  739. * resolution. The `servers` argument is an array of [RFC 5952](https://tools.ietf.org/html/rfc5952#section-6) formatted
  740. * addresses. If the port is the IANA default DNS port (53) it can be omitted.
  741. *
  742. * ```js
  743. * dns.setServers([
  744. * '4.4.4.4',
  745. * '[2001:4860:4860::8888]',
  746. * '4.4.4.4:1053',
  747. * '[2001:4860:4860::8888]:1053',
  748. * ]);
  749. * ```
  750. *
  751. * An error will be thrown if an invalid address is provided.
  752. *
  753. * The `dns.setServers()` method must not be called while a DNS query is in
  754. * progress.
  755. *
  756. * The {@link setServers} method affects only {@link resolve}, `dns.resolve*()` and {@link reverse} (and specifically _not_ {@link lookup}).
  757. *
  758. * This method works much like [resolve.conf](https://man7.org/linux/man-pages/man5/resolv.conf.5.html).
  759. * 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
  760. * subsequent servers provided. Fallback DNS servers will only be used if the
  761. * earlier ones time out or result in some other error.
  762. * @since v0.11.3
  763. * @param servers array of [RFC 5952](https://datatracker.ietf.org/doc/html/rfc5952#section-6) formatted addresses
  764. */
  765. export function setServers(servers: readonly string[]): void;
  766. /**
  767. * Returns an array of IP address strings, formatted according to [RFC 5952](https://tools.ietf.org/html/rfc5952#section-6),
  768. * that are currently configured for DNS resolution. A string will include a port
  769. * section if a custom port is used.
  770. *
  771. * ```js
  772. * [
  773. * '4.4.4.4',
  774. * '2001:4860:4860::8888',
  775. * '4.4.4.4:1053',
  776. * '[2001:4860:4860::8888]:1053',
  777. * ]
  778. * ```
  779. * @since v0.11.3
  780. */
  781. export function getServers(): string[];
  782. /**
  783. * Set the default value of `order` in {@link lookup} and [`dnsPromises.lookup()`](https://nodejs.org/docs/latest-v24.x/api/dns.html#dnspromiseslookuphostname-options).
  784. * The value could be:
  785. *
  786. * * `ipv4first`: sets default `order` to `ipv4first`.
  787. * * `ipv6first`: sets default `order` to `ipv6first`.
  788. * * `verbatim`: sets default `order` to `verbatim`.
  789. *
  790. * The default is `verbatim` and {@link setDefaultResultOrder} have higher
  791. * priority than [`--dns-result-order`](https://nodejs.org/docs/latest-v24.x/api/cli.html#--dns-result-orderorder). When using
  792. * [worker threads](https://nodejs.org/docs/latest-v24.x/api/worker_threads.html), {@link setDefaultResultOrder} from the main
  793. * thread won't affect the default dns orders in workers.
  794. * @since v16.4.0, v14.18.0
  795. * @param order must be `'ipv4first'`, `'ipv6first'` or `'verbatim'`.
  796. */
  797. export function setDefaultResultOrder(order: "ipv4first" | "ipv6first" | "verbatim"): void;
  798. // Error codes
  799. export const NODATA: "ENODATA";
  800. export const FORMERR: "EFORMERR";
  801. export const SERVFAIL: "ESERVFAIL";
  802. export const NOTFOUND: "ENOTFOUND";
  803. export const NOTIMP: "ENOTIMP";
  804. export const REFUSED: "EREFUSED";
  805. export const BADQUERY: "EBADQUERY";
  806. export const BADNAME: "EBADNAME";
  807. export const BADFAMILY: "EBADFAMILY";
  808. export const BADRESP: "EBADRESP";
  809. export const CONNREFUSED: "ECONNREFUSED";
  810. export const TIMEOUT: "ETIMEOUT";
  811. export const EOF: "EOF";
  812. export const FILE: "EFILE";
  813. export const NOMEM: "ENOMEM";
  814. export const DESTRUCTION: "EDESTRUCTION";
  815. export const BADSTR: "EBADSTR";
  816. export const BADFLAGS: "EBADFLAGS";
  817. export const NONAME: "ENONAME";
  818. export const BADHINTS: "EBADHINTS";
  819. export const NOTINITIALIZED: "ENOTINITIALIZED";
  820. export const LOADIPHLPAPI: "ELOADIPHLPAPI";
  821. export const ADDRGETNETWORKPARAMS: "EADDRGETNETWORKPARAMS";
  822. export const CANCELLED: "ECANCELLED";
  823. export interface ResolverOptions {
  824. /**
  825. * Query timeout in milliseconds, or `-1` to use the default timeout.
  826. */
  827. timeout?: number | undefined;
  828. /**
  829. * The number of tries the resolver will try contacting each name server before giving up.
  830. * @default 4
  831. */
  832. tries?: number;
  833. /**
  834. * The max retry timeout, in milliseconds.
  835. * @default 0
  836. */
  837. maxTimeout?: number | undefined;
  838. }
  839. /**
  840. * An independent resolver for DNS requests.
  841. *
  842. * Creating a new resolver uses the default server settings. Setting
  843. * the servers used for a resolver using [`resolver.setServers()`](https://nodejs.org/docs/latest-v24.x/api/dns.html#dnssetserversservers) does not affect
  844. * other resolvers:
  845. *
  846. * ```js
  847. * import { Resolver } from 'node:dns';
  848. * const resolver = new Resolver();
  849. * resolver.setServers(['4.4.4.4']);
  850. *
  851. * // This request will use the server at 4.4.4.4, independent of global settings.
  852. * resolver.resolve4('example.org', (err, addresses) => {
  853. * // ...
  854. * });
  855. * ```
  856. *
  857. * The following methods from the `node:dns` module are available:
  858. *
  859. * * `resolver.getServers()`
  860. * * `resolver.resolve()`
  861. * * `resolver.resolve4()`
  862. * * `resolver.resolve6()`
  863. * * `resolver.resolveAny()`
  864. * * `resolver.resolveCaa()`
  865. * * `resolver.resolveCname()`
  866. * * `resolver.resolveMx()`
  867. * * `resolver.resolveNaptr()`
  868. * * `resolver.resolveNs()`
  869. * * `resolver.resolvePtr()`
  870. * * `resolver.resolveSoa()`
  871. * * `resolver.resolveSrv()`
  872. * * `resolver.resolveTxt()`
  873. * * `resolver.reverse()`
  874. * * `resolver.setServers()`
  875. * @since v8.3.0
  876. */
  877. export class Resolver {
  878. constructor(options?: ResolverOptions);
  879. /**
  880. * Cancel all outstanding DNS queries made by this resolver. The corresponding
  881. * callbacks will be called with an error with code `ECANCELLED`.
  882. * @since v8.3.0
  883. */
  884. cancel(): void;
  885. getServers: typeof getServers;
  886. resolve: typeof resolve;
  887. resolve4: typeof resolve4;
  888. resolve6: typeof resolve6;
  889. resolveAny: typeof resolveAny;
  890. resolveCaa: typeof resolveCaa;
  891. resolveCname: typeof resolveCname;
  892. resolveMx: typeof resolveMx;
  893. resolveNaptr: typeof resolveNaptr;
  894. resolveNs: typeof resolveNs;
  895. resolvePtr: typeof resolvePtr;
  896. resolveSoa: typeof resolveSoa;
  897. resolveSrv: typeof resolveSrv;
  898. resolveTlsa: typeof resolveTlsa;
  899. resolveTxt: typeof resolveTxt;
  900. reverse: typeof reverse;
  901. /**
  902. * The resolver instance will send its requests from the specified IP address.
  903. * This allows programs to specify outbound interfaces when used on multi-homed
  904. * systems.
  905. *
  906. * If a v4 or v6 address is not specified, it is set to the default and the
  907. * operating system will choose a local address automatically.
  908. *
  909. * The resolver will use the v4 local address when making requests to IPv4 DNS
  910. * servers, and the v6 local address when making requests to IPv6 DNS servers.
  911. * The `rrtype` of resolution requests has no impact on the local address used.
  912. * @since v15.1.0, v14.17.0
  913. * @param [ipv4='0.0.0.0'] A string representation of an IPv4 address.
  914. * @param [ipv6='::0'] A string representation of an IPv6 address.
  915. */
  916. setLocalAddress(ipv4?: string, ipv6?: string): void;
  917. setServers: typeof setServers;
  918. }
  919. export { dnsPromises as promises };
  920. }
  921. declare module "node:dns" {
  922. export * from "dns";
  923. }