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