DNS
[Stabile: 2 - Stabile]
Stabile: 2 Stabilità: 2 - Stabile
Codice sorgente: lib/dns.js
Il modulo node:dns
abilita la risoluzione dei nomi. Ad esempio, usalo per cercare gli indirizzi IP dei nomi host.
Sebbene denominato come Domain Name System (DNS), non utilizza sempre il protocollo DNS per le ricerche. dns.lookup()
utilizza le funzionalità del sistema operativo per eseguire la risoluzione dei nomi. Potrebbe non essere necessario eseguire alcuna comunicazione di rete. Per eseguire la risoluzione dei nomi nello stesso modo in cui lo fanno altre applicazioni sullo stesso sistema, usa dns.lookup()
.
import dns from 'node:dns'
dns.lookup('example.org', (err, address, family) => {
console.log('indirizzo: %j famiglia: IPv%s', address, family)
})
// indirizzo: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" famiglia: IPv6
const dns = require('node:dns')
dns.lookup('example.org', (err, address, family) => {
console.log('indirizzo: %j famiglia: IPv%s', address, family)
})
// indirizzo: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" famiglia: IPv6
Tutte le altre funzioni nel modulo node:dns
si connettono a un server DNS effettivo per eseguire la risoluzione dei nomi. Utilizzeranno sempre la rete per eseguire query DNS. Queste funzioni non utilizzano lo stesso set di file di configurazione utilizzato da dns.lookup()
(ad es. /etc/hosts
). Utilizza queste funzioni per eseguire sempre query DNS, bypassando altre funzionalità di risoluzione dei nomi.
import dns from 'node:dns'
dns.resolve4('archive.org', (err, addresses) => {
if (err) throw err
console.log(`indirizzi: ${JSON.stringify(addresses)}`)
addresses.forEach(a => {
dns.reverse(a, (err, hostnames) => {
if (err) {
throw err
}
console.log(`inverso per ${a}: ${JSON.stringify(hostnames)}`)
})
})
})
const dns = require('node:dns')
dns.resolve4('archive.org', (err, addresses) => {
if (err) throw err
console.log(`indirizzi: ${JSON.stringify(addresses)}`)
addresses.forEach(a => {
dns.reverse(a, (err, hostnames) => {
if (err) {
throw err
}
console.log(`inverso per ${a}: ${JSON.stringify(hostnames)}`)
})
})
})
Consulta la sezione Considerazioni sull'implementazione per maggiori informazioni.
Classe: dns.Resolver
Aggiunto in: v8.3.0
Un resolver indipendente per le richieste DNS.
La creazione di un nuovo resolver utilizza le impostazioni predefinite del server. L'impostazione dei server utilizzati per un resolver utilizzando resolver.setServers()
non influenza altri resolver:
import { Resolver } from 'node:dns'
const resolver = new Resolver()
resolver.setServers(['4.4.4.4'])
// Questa richiesta utilizzerà il server all'indirizzo 4.4.4.4, indipendentemente dalle impostazioni globali.
resolver.resolve4('example.org', (err, addresses) => {
// ...
})
const { Resolver } = require('node:dns')
const resolver = new Resolver()
resolver.setServers(['4.4.4.4'])
// Questa richiesta utilizzerà il server all'indirizzo 4.4.4.4, indipendentemente dalle impostazioni globali.
resolver.resolve4('example.org', (err, addresses) => {
// ...
})
Sono disponibili i seguenti metodi dal modulo node:dns
:
resolver.getServers()
resolver.resolve()
resolver.resolve4()
resolver.resolve6()
resolver.resolveAny()
resolver.resolveCaa()
resolver.resolveCname()
resolver.resolveMx()
resolver.resolveNaptr()
resolver.resolveNs()
resolver.resolvePtr()
resolver.resolveSoa()
resolver.resolveSrv()
resolver.resolveTxt()
resolver.reverse()
resolver.setServers()
Resolver([options])
[Cronologia]
Versione | Modifiche |
---|---|
v16.7.0, v14.18.0 | L'oggetto options ora accetta un'opzione tries . |
v12.18.3 | Il costruttore ora accetta un oggetto options . L'unica opzione supportata è timeout . |
v8.3.0 | Aggiunto in: v8.3.0 |
Crea un nuovo resolver.
options
<Oggetto>timeout
<numero intero> Timeout della query in millisecondi, o-1
per utilizzare il timeout predefinito.tries
<numero intero> Il numero di tentativi che il resolver proverà a contattare ciascun nameserver prima di arrendersi. Predefinito:4
resolver.cancel()
Aggiunto in: v8.3.0
Annulla tutte le query DNS in sospeso effettuate da questo resolver. Le callback corrispondenti verranno chiamate con un errore con codice ECANCELLED
.
resolver.setLocalAddress([ipv4][, ipv6])
Aggiunto in: v15.1.0, v14.17.0
ipv4
<stringa> Una rappresentazione stringa di un indirizzo IPv4. Predefinito:'0.0.0.0'
ipv6
<stringa> Una rappresentazione stringa di un indirizzo IPv6. Predefinito:'::0'
L'istanza del resolver invierà le sue richieste dall'indirizzo IP specificato. Ciò consente ai programmi di specificare le interfacce in uscita quando vengono utilizzati su sistemi multi-homed.
Se non viene specificato un indirizzo v4 o v6, viene impostato sul valore predefinito e il sistema operativo sceglierà automaticamente un indirizzo locale.
Il resolver utilizzerà l'indirizzo locale v4 quando effettua richieste ai server DNS IPv4 e l'indirizzo locale v6 quando effettua richieste ai server DNS IPv6. Il rrtype
delle richieste di risoluzione non ha alcun impatto sull'indirizzo locale utilizzato.
dns.getServers()
Aggiunto in: v0.11.3
- Restituisce: <stringa[]>
Restituisce un array di stringhe di indirizzi IP, formattate secondo RFC 5952, attualmente configurate per la risoluzione DNS. Una stringa includerà una sezione di porta se viene utilizzata una porta personalizzata.
;['8.8.8.8', '2001:4860:4860::8888', '8.8.8.8:1053', '[2001:4860:4860::8888]:1053']
dns.lookup(hostname[, options], callback)
[Cronologia]
Versione | Modifiche |
---|---|
v22.1.0, v20.13.0 | L'opzione verbatim è ora deprecata a favore della nuova opzione order . |
v18.4.0 | Per compatibilità con node:net , quando si passa un oggetto opzioni, l'opzione family può essere la stringa 'IPv4' o la stringa 'IPv6' . |
v18.0.0 | Passare una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK . |
v17.0.0 | Le opzioni verbatim ora hanno come valore predefinito true . |
v8.5.0 | L'opzione verbatim è ora supportata. |
v1.2.0 | L'opzione all è ora supportata. |
v0.1.90 | Aggiunto in: v0.1.90 |
hostname
<stringa>options
<numero intero> | <Oggetto>family
<numero intero> | <stringa> La famiglia del record. Deve essere4
,6
o0
. Per ragioni di retrocompatibilità,'IPv4'
e'IPv6'
vengono interpretate rispettivamente come4
e6
. Il valore0
indica che viene restituito un indirizzo IPv4 o IPv6. Se il valore0
viene utilizzato con{ all: true }
(vedi sotto), viene restituito uno o entrambi gli indirizzi IPv4 e IPv6, a seconda del resolver DNS del sistema. Predefinito:0
.hints
<numero> Uno o più flaggetaddrinfo
supportati. È possibile passare più flag mediante l'operatore bit a bitOR
dei loro valori.all
<booleano> Quandotrue
, la callback restituisce tutti gli indirizzi risolti in un array. Altrimenti, restituisce un singolo indirizzo. Predefinito:false
.order
<stringa> Quandoverbatim
, gli indirizzi risolti vengono restituiti non ordinati. Quandoipv4first
, gli indirizzi risolti vengono ordinati posizionando gli indirizzi IPv4 prima degli indirizzi IPv6. Quandoipv6first
, gli indirizzi risolti vengono ordinati posizionando gli indirizzi IPv6 prima degli indirizzi IPv4. Predefinito:verbatim
(gli indirizzi non vengono riordinati). Il valore predefinito è configurabile tramitedns.setDefaultResultOrder()
o--dns-result-order
.verbatim
<booleano> Quandotrue
, la callback riceve indirizzi IPv4 e IPv6 nell'ordine in cui il resolver DNS li ha restituiti. Quandofalse
, gli indirizzi IPv4 vengono posizionati prima degli indirizzi IPv6. Questa opzione verrà deprecata a favore diorder
. Quando entrambi sono specificati,order
ha una precedenza maggiore. Il nuovo codice dovrebbe utilizzare soloorder
. Predefinito:true
(gli indirizzi non vengono riordinati). Il valore predefinito è configurabile tramitedns.setDefaultResultOrder()
o--dns-result-order
.
callback
<Funzione>err
<Errore>address
<stringa> Una rappresentazione stringa di un indirizzo IPv4 o IPv6.family
<numero intero>4
o6
, che denota la famiglia diaddress
, o0
se l'indirizzo non è un indirizzo IPv4 o IPv6.0
è un probabile indicatore di un bug nel servizio di risoluzione dei nomi utilizzato dal sistema operativo.
Risolve un nome host (ad es. 'nodejs.org'
) nel primo record A (IPv4) o AAAA (IPv6) trovato. Tutte le proprietà di option
sono opzionali. Se options
è un numero intero, allora deve essere 4
o 6
- se options
non viene fornito, allora vengono restituiti indirizzi IPv4 o IPv6, o entrambi, se trovati.
Con l'opzione all
impostata su true
, gli argomenti per callback
cambiano in (err, addresses)
, con addresses
che è un array di oggetti con le proprietà address
e family
.
In caso di errore, err
è un oggetto Error
, dove err.code
è il codice di errore. Tieni presente che err.code
verrà impostato su 'ENOTFOUND'
non solo quando il nome host non esiste ma anche quando la ricerca fallisce in altri modi come l'assenza di descrittori di file disponibili.
dns.lookup()
non ha necessariamente nulla a che fare con il protocollo DNS. L'implementazione utilizza una funzione del sistema operativo che può associare i nomi agli indirizzi e viceversa. Questa implementazione può avere conseguenze sottili ma importanti sul comportamento di qualsiasi programma Node.js. Ti preghiamo di dedicare del tempo alla consultazione della sezione Considerazioni sull'implementazione prima di utilizzare dns.lookup()
.
Esempio di utilizzo:
import dns from 'node:dns'
const options = {
family: 6,
hints: dns.ADDRCONFIG | dns.V4MAPPED,
}
dns.lookup('example.org', options, (err, address, family) => console.log('address: %j family: IPv%s', address, family))
// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6
// Quando options.all è true, il risultato sarà un Array.
options.all = true
dns.lookup('example.org', options, (err, addresses) => console.log('addresses: %j', addresses))
// addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]
const dns = require('node:dns')
const options = {
family: 6,
hints: dns.ADDRCONFIG | dns.V4MAPPED,
}
dns.lookup('example.org', options, (err, address, family) => console.log('address: %j family: IPv%s', address, family))
// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6
// Quando options.all è true, il risultato sarà un Array.
options.all = true
dns.lookup('example.org', options, (err, addresses) => console.log('addresses: %j', addresses))
// addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]
Se questo metodo viene richiamato come versione util.promisify()
izzata e all
non è impostato su true
, restituisce una Promise
per un Oggetto
con le proprietà address
e family
.
Flag getaddrinfo supportate
[Cronologia]
Versione | Modifiche |
---|---|
v13.13.0, v12.17.0 | Aggiunto il supporto per il flag dns.ALL . |
I seguenti flag possono essere passati come suggerimenti a dns.lookup()
.
dns.ADDRCONFIG
: Limita i tipi di indirizzi restituiti ai tipi di indirizzi non-loopback configurati nel sistema. Ad esempio, gli indirizzi IPv4 vengono restituiti solo se il sistema attuale ha almeno un indirizzo IPv4 configurato.dns.V4MAPPED
: Se è stata specificata la famiglia IPv6, ma non sono stati trovati indirizzi IPv6, restituisce gli indirizzi IPv6 mappati IPv4. Non è supportato su alcuni sistemi operativi (ad es. FreeBSD 10.1).dns.ALL
: Sedns.V4MAPPED
è specificato, restituisce gli indirizzi IPv6 risolti e gli indirizzi IPv6 mappati IPv4.
dns.lookupService(indirizzo, porta, callback)
[Cronologia]
Versione | Modifiche |
---|---|
v18.0.0 | Il passaggio di una callback non valida all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK . |
v0.11.14 | Aggiunto in: v0.11.14 |
indirizzo
<string>porta
<number>callback
<Function>
Risolve l'indirizzo
e la porta
specificati in un nome host e servizio utilizzando l'implementazione getnameinfo
sottostante del sistema operativo.
Se indirizzo
non è un indirizzo IP valido, verrà generato un TypeError
. La porta
verrà convertita in un numero. Se non è una porta legale, verrà generato un TypeError
.
In caso di errore, err
è un oggetto Error
, dove err.code
è il codice di errore.
import dns from 'node:dns'
dns.lookupService('127.0.0.1', 22, (err, hostname, service) => {
console.log(hostname, service)
// Stampa: localhost ssh
})
const dns = require('node:dns')
dns.lookupService('127.0.0.1', 22, (err, hostname, service) => {
console.log(hostname, service)
// Stampa: localhost ssh
})
Se questo metodo viene invocato come versione util.promisify()
ed, restituisce una Promise
per un Object
con le proprietà hostname
e service
.
dns.resolve(hostname[, rrtype], callback)
[Cronologia]
Versione | Modifiche |
---|---|
v18.0.0 | Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK . |
v0.1.27 | Aggiunto in: v0.1.27 |
hostname
<stringa> Nome host da risolvere.rrtype
<stringa> Tipo di record di risorsa. Predefinito:'A'
.callback
<Funzione>err
<Errore>records
<stringa[]> | <Oggetto[]> | <Oggetto>
Utilizza il protocollo DNS per risolvere un nome host (ad es. 'nodejs.org'
) in un array di record di risorsa. La funzione callback
ha argomenti (err, records)
. In caso di successo, records
sarà un array di record di risorsa. Il tipo e la struttura dei singoli risultati variano in base a rrtype
:
rrtype | records contiene | Tipo di risultato | Metodo abbreviato |
---|---|---|---|
'A' | Indirizzi IPv4 (predefinito) | <stringa> | dns.resolve4() |
'AAAA' | Indirizzi IPv6 | <stringa> | dns.resolve6() |
'ANY' | qualsiasi record | <Oggetto> | dns.resolveAny() |
'CAA' | record di autorizzazione CA | <Oggetto> | dns.resolveCaa() |
'CNAME' | record di nome canonico | <stringa> | dns.resolveCname() |
'MX' | record di scambio di posta | <Oggetto> | dns.resolveMx() |
'NAPTR' | record di puntatore di autorità del nome | <Oggetto> | dns.resolveNaptr() |
'NS' | record del server dei nomi | <stringa> | dns.resolveNs() |
'PTR' | record puntatore | <stringa> | dns.resolvePtr() |
'SOA' | record di inizio autorità | <Oggetto> | dns.resolveSoa() |
'SRV' | record di servizio | <Oggetto> | dns.resolveSrv() |
'TXT' | record di testo | <stringa[]> | dns.resolveTxt() |
In caso di errore, err
è un oggetto Error
, dove err.code
è uno dei codici di errore DNS.
dns.resolve4(hostname[, options], callback)
[Cronologia]
Versione | Modifiche |
---|---|
v18.0.0 | Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK . |
v7.2.0 | Questo metodo ora supporta il passaggio di options , in particolare options.ttl . |
v0.1.16 | Aggiunto in: v0.1.16 |
hostname
<string> Nome host da risolvere.options
<Object>ttl
<boolean> Recupera il valore Time-To-Live (TTL) di ogni record. Quandotrue
, il callback riceve un array di oggetti{ address: '1.2.3.4', ttl: 60 }
anziché un array di stringhe, con il TTL espresso in secondi.
callback
<Function>err
<Error>addresses
<string[]> | <Object[]>
Utilizza il protocollo DNS per risolvere gli indirizzi IPv4 (record A
) per l'hostname
. L'argomento addresses
passato alla funzione callback
conterrà un array di indirizzi IPv4 (ad es. ['74.125.79.104', '74.125.79.105', '74.125.79.106']
).
dns.resolve6(hostname[, options], callback)
[Cronologia]
Versione | Modifiche |
---|---|
v18.0.0 | Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK . |
v7.2.0 | Questo metodo ora supporta il passaggio di options , in particolare options.ttl . |
v0.1.16 | Aggiunto in: v0.1.16 |
hostname
<string> Nome host da risolvere.options
<Object>ttl
<boolean> Recupera il valore Time-To-Live (TTL) di ogni record. Quandotrue
, il callback riceve un array di oggetti{ address: '0:1:2:3:4:5:6:7', ttl: 60 }
anziché un array di stringhe, con il TTL espresso in secondi.
callback
<Function>err
<Error>addresses
<string[]> | <Object[]>
Utilizza il protocollo DNS per risolvere gli indirizzi IPv6 (record AAAA
) per l'hostname
. L'argomento addresses
passato alla funzione callback
conterrà un array di indirizzi IPv6.
dns.resolveAny(hostname, callback)
[Cronologia]
Versione | Cambiamenti |
---|---|
v18.0.0 | Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK . |
hostname
<stringa>callback
<Funzione>err
<Errore>ret
<Oggetto[]>
Utilizza il protocollo DNS per risolvere tutti i record (noti anche come query ANY
o *
). L'argomento ret
passato alla funzione callback
sarà un array contenente vari tipi di record. Ogni oggetto ha una proprietà type
che indica il tipo del record corrente. E a seconda del type
, nell'oggetto saranno presenti proprietà aggiuntive:
Tipo | Proprietà |
---|---|
'A' | address / ttl |
'AAAA' | address / ttl |
'CNAME' | value |
'MX' | Fai riferimento a dns.resolveMx() |
'NAPTR' | Fai riferimento a dns.resolveNaptr() |
'NS' | value |
'PTR' | value |
'SOA' | Fai riferimento a dns.resolveSoa() |
'SRV' | Fai riferimento a dns.resolveSrv() |
'TXT' | Questo tipo di record contiene una proprietà array chiamata entries che fa riferimento a dns.resolveTxt() , ad es. { entries: ['...'], type: 'TXT' } |
Ecco un esempio dell'oggetto ret
passato al callback:
;[
{ type: 'A', address: '127.0.0.1', ttl: 299 },
{ type: 'CNAME', value: 'example.com' },
{ type: 'MX', exchange: 'alt4.aspmx.l.example.com', priority: 50 },
{ type: 'NS', value: 'ns1.example.com' },
{ type: 'TXT', entries: ['v=spf1 include:_spf.example.com ~all'] },
{
type: 'SOA',
nsname: 'ns1.example.com',
hostmaster: 'admin.example.com',
serial: 156696742,
refresh: 900,
retry: 900,
expire: 1800,
minttl: 60,
},
]
Gli operatori dei server DNS possono scegliere di non rispondere alle query ANY
. Potrebbe essere meglio chiamare singoli metodi come dns.resolve4()
, dns.resolveMx()
e così via. Per maggiori dettagli, vedi RFC 8482.
dns.resolveCname(hostname, callback)
[Cronologia]
Versione | Modifiche |
---|---|
v18.0.0 | Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK . |
v0.3.2 | Aggiunto in: v0.3.2 |
hostname
<stringa>callback
<Funzione>err
<Errore>addresses
<stringa[]>
Utilizza il protocollo DNS per risolvere i record CNAME
per hostname
. L'argomento addresses
passato alla funzione callback
conterrà un array di record di nomi canonici disponibili per hostname
(ad es. ['bar.example.com']
).
dns.resolveCaa(hostname, callback)
[Cronologia]
Versione | Modifiche |
---|---|
v18.0.0 | Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK . |
v15.0.0, v14.17.0 | Aggiunto in: v15.0.0, v14.17.0 |
hostname
<stringa>callback
<Funzione>err
<Errore>records
<Oggetto[]>
Utilizza il protocollo DNS per risolvere i record CAA
per hostname
. L'argomento addresses
passato alla funzione callback
conterrà un array di record di autorizzazione dell'autorità di certificazione disponibili per hostname
(ad es. [{critical: 0, iodef: 'mailto:[email protected]'}, {critical: 128, issue: 'pki.example.com'}]
).
dns.resolveMx(hostname, callback)
[Cronologia]
Versione | Modifiche |
---|---|
v18.0.0 | Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK . |
v0.1.27 | Aggiunto in: v0.1.27 |
hostname
<stringa>callback
<Funzione>err
<Errore>indirizzi
<Oggetto[]>
Utilizza il protocollo DNS per risolvere i record di scambio di posta (MX
record) per l'hostname
. L'argomento indirizzi
passato alla funzione callback
conterrà un array di oggetti contenenti sia una proprietà priority
che exchange
(es. [{priority: 10, exchange: 'mx.example.com'}, ...]
).
dns.resolveNaptr(hostname, callback)
[Cronologia]
Versione | Modifiche |
---|---|
v18.0.0 | Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK . |
v0.9.12 | Aggiunto in: v0.9.12 |
hostname
<stringa>callback
<Funzione>err
<Errore>indirizzi
<Oggetto[]>
Utilizza il protocollo DNS per risolvere i record basati su espressioni regolari (NAPTR
record) per l'hostname
. L'argomento indirizzi
passato alla funzione callback
conterrà un array di oggetti con le seguenti proprietà:
flags
service
regexp
replacement
order
preference
{
flags: 's',
service: 'SIP+D2U',
regexp: '',
replacement: '_sip._udp.example.com',
order: 30,
preference: 100
}
dns.resolveNs(hostname, callback)
[Cronologia]
Versione | Modifiche |
---|---|
v18.0.0 | Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK . |
v0.1.90 | Aggiunto in: v0.1.90 |
hostname
<stringa>callback
<Funzione>err
<Errore>addresses
<stringa[]>
Utilizza il protocollo DNS per risolvere i record del server dei nomi (record NS
) per l'hostname
. L'argomento addresses
passato alla funzione callback
conterrà un array di record del server dei nomi disponibili per l'hostname
(ad es. ['ns1.example.com', 'ns2.example.com']
).
dns.resolvePtr(hostname, callback)
[Cronologia]
Versione | Modifiche |
---|---|
v18.0.0 | Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK . |
v6.0.0 | Aggiunto in: v6.0.0 |
hostname
<stringa>callback
<Funzione>err
<Errore>addresses
<stringa[]>
Utilizza il protocollo DNS per risolvere i record puntatore (record PTR
) per l'hostname
. L'argomento addresses
passato alla funzione callback
sarà un array di stringhe contenente i record di risposta.
dns.resolveSoa(hostname, callback)
[Cronologia]
Versione | Modifiche |
---|---|
v18.0.0 | Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK . |
v0.11.10 | Aggiunto in: v0.11.10 |
hostname
<stringa>callback
<Funzione>
Utilizza il protocollo DNS per risolvere un record di inizio autorità (record SOA
) per l'hostname
. L'argomento address
passato alla funzione callback
sarà un oggetto con le seguenti proprietà:
nsname
hostmaster
serial
refresh
retry
expire
minttl
{
nsname: 'ns.example.com',
hostmaster: 'root.example.com',
serial: 2013101809,
refresh: 10000,
retry: 2400,
expire: 604800,
minttl: 3600
}
dns.resolveSrv(hostname, callback)
[Cronologia]
Versione | Cambiamenti |
---|---|
v18.0.0 | Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK . |
v0.1.27 | Aggiunto in: v0.1.27 |
hostname
<stringa>callback
<Funzione>err
<Errore>addresses
<Oggetto[]>
Utilizza il protocollo DNS per risolvere i record di servizio (record SRV
) per l'hostname
. L'argomento addresses
passato alla funzione callback
sarà un array di oggetti con le seguenti proprietà:
priority
weight
port
name
{
priority: 10,
weight: 5,
port: 21223,
name: 'service.example.com'
}
dns.resolveTxt(hostname, callback)
[Cronologia]
Versione | Cambiamenti |
---|---|
v18.0.0 | Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK . |
v0.1.27 | Aggiunto in: v0.1.27 |
hostname
<stringa>callback
<Funzione>err
<Errore>records
<stringa[][]>
Utilizza il protocollo DNS per risolvere le query di testo (record TXT
) per l'hostname
. L'argomento records
passato alla funzione callback
è un array bidimensionale dei record di testo disponibili per hostname
(es. [ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]
). Ogni sotto-array contiene chunk TXT di un record. A seconda del caso d'uso, questi potrebbero essere uniti o trattati separatamente.
dns.reverse(ip, callback)
Aggiunto in: v0.1.16
ip
<stringa>callback
<Funzione>err
<Errore>hostnames
<stringa[]>
Esegue una query DNS inversa che risolve un indirizzo IPv4 o IPv6 in un array di nomi host.
In caso di errore, err
è un oggetto Errore
, dove err.code
è uno dei codici di errore DNS.
dns.setDefaultResultOrder(order)
[Cronologia]
Versione | Modifiche |
---|---|
v22.1.0, v20.13.0 | Il valore ipv6first è ora supportato. |
v17.0.0 | Modificato il valore predefinito in verbatim . |
v16.4.0, v14.18.0 | Aggiunto in: v16.4.0, v14.18.0 |
order
<stringa> deve essere'ipv4first'
,'ipv6first'
o'verbatim'
.
Imposta il valore predefinito di order
in dns.lookup()
e dnsPromises.lookup()
. Il valore potrebbe essere:
ipv4first
: impostaorder
predefinito suipv4first
.ipv6first
: impostaorder
predefinito suipv6first
.verbatim
: impostaorder
predefinito suverbatim
.
Il valore predefinito è verbatim
e dns.setDefaultResultOrder()
ha una priorità maggiore rispetto a --dns-result-order
. Quando si utilizzano thread di lavoro, dns.setDefaultResultOrder()
dal thread principale non influirà sugli ordini DNS predefiniti nei worker.
dns.getDefaultResultOrder()
[Cronologia]
Versione | Modifiche |
---|---|
v22.1.0, v20.13.0 | Il valore ipv6first è ora supportato. |
v20.1.0, v18.17.0 | Aggiunto in: v20.1.0, v18.17.0 |
Ottieni il valore predefinito per order
in dns.lookup()
e dnsPromises.lookup()
. Il valore potrebbe essere:
ipv4first
: perorder
che per impostazione predefinita èipv4first
.ipv6first
: perorder
che per impostazione predefinita èipv6first
.verbatim
: perorder
che per impostazione predefinita èverbatim
.
dns.setServers(servers)
Aggiunto in: v0.11.3
servers
<string[]> array di indirizzi formattati secondo RFC 5952
Imposta l'indirizzo IP e la porta dei server da utilizzare per la risoluzione DNS. L'argomento servers
è un array di indirizzi formattati secondo RFC 5952. Se la porta è la porta DNS predefinita IANA (53), può essere omessa.
dns.setServers(['8.8.8.8', '[2001:4860:4860::8888]', '8.8.8.8:1053', '[2001:4860:4860::8888]:1053'])
Verrà generato un errore se viene fornito un indirizzo non valido.
Il metodo dns.setServers()
non deve essere chiamato mentre è in corso una query DNS.
Il metodo dns.setServers()
influisce solo su dns.resolve()
, dns.resolve*()
e dns.reverse()
(e specificamente non dns.lookup()
).
Questo metodo funziona in modo molto simile a resolve.conf. Cioè, se il tentativo di risoluzione con il primo server fornito restituisce un errore NOTFOUND
, il metodo resolve()
non tenterà di eseguire la risoluzione con i server successivi forniti. I server DNS di fallback verranno utilizzati solo se i precedenti vanno in timeout o generano qualche altro errore.
API DNS basate su promise
[Storia]
Versione | Modifiche |
---|---|
v15.0.0 | Esposto come require('dns/promises') . |
v11.14.0, v10.17.0 | Questa API non è più sperimentale. |
v10.6.0 | Aggiunto in: v10.6.0 |
L'API dns.promises
fornisce un set alternativo di metodi DNS asincroni che restituiscono oggetti Promise
anziché utilizzare callback. L'API è accessibile tramite require('node:dns').promises
o require('node:dns/promises')
.
Classe: dnsPromises.Resolver
Aggiunto in: v10.6.0
Un resolver indipendente per le richieste DNS.
La creazione di un nuovo resolver utilizza le impostazioni predefinite del server. L'impostazione dei server utilizzati per un resolver utilizzando resolver.setServers()
non influisce su altri resolver:
import { Resolver } from 'node:dns/promises'
const resolver = new Resolver()
resolver.setServers(['4.4.4.4'])
// Questa richiesta utilizzerà il server all'indirizzo 4.4.4.4, indipendentemente dalle impostazioni globali.
const addresses = await resolver.resolve4('example.org')
const { Resolver } = require('node:dns').promises
const resolver = new Resolver()
resolver.setServers(['4.4.4.4'])
// Questa richiesta utilizzerà il server all'indirizzo 4.4.4.4, indipendentemente dalle impostazioni globali.
resolver.resolve4('example.org').then(addresses => {
// ...
})
// In alternativa, lo stesso codice può essere scritto utilizzando lo stile async-await.
;(async function () {
const addresses = await resolver.resolve4('example.org')
})()
Sono disponibili i seguenti metodi dell'API dnsPromises
:
resolver.getServers()
resolver.resolve()
resolver.resolve4()
resolver.resolve6()
resolver.resolveAny()
resolver.resolveCaa()
resolver.resolveCname()
resolver.resolveMx()
resolver.resolveNaptr()
resolver.resolveNs()
resolver.resolvePtr()
resolver.resolveSoa()
resolver.resolveSrv()
resolver.resolveTxt()
resolver.reverse()
resolver.setServers()
resolver.cancel()
Aggiunto in: v15.3.0, v14.17.0
Annulla tutte le query DNS in sospeso effettuate da questo resolver. Le promesse corrispondenti verranno rifiutate con un errore con codice ECANCELLED
.
dnsPromises.getServers()
Aggiunto in: v10.6.0
- Restituisce: <string[]>
Restituisce un array di stringhe di indirizzi IP, formattati secondo RFC 5952, che sono attualmente configurati per la risoluzione DNS. Una stringa includerà una sezione di porta se viene utilizzata una porta personalizzata.
;['8.8.8.8', '2001:4860:4860::8888', '8.8.8.8:1053', '[2001:4860:4860::8888]:1053']
dnsPromises.lookup(hostname[, options])
[Cronologia]
Versione | Modifiche |
---|---|
v22.1.0, v20.13.0 | L'opzione verbatim è ora deprecata a favore della nuova opzione order . |
v10.6.0 | Aggiunto in: v10.6.0 |
hostname
<string>options
<integer> | <Object>family
<integer> La famiglia di record. Deve essere4
,6
o0
. Il valore0
indica che viene restituito un indirizzo IPv4 o IPv6. Se il valore0
viene utilizzato con{ all: true }
(vedi sotto), viene restituito uno o entrambi gli indirizzi IPv4 e IPv6, a seconda del resolver DNS del sistema. Predefinito:0
.hints
<number> Uno o più flaggetaddrinfo
supportati. È possibile passare più flag tramite unOR
bit a bit dei loro valori.all
<boolean> Quandotrue
, laPromise
viene risolta con tutti gli indirizzi in un array. Altrimenti, restituisce un singolo indirizzo. Predefinito:false
.order
<string> Quandoverbatim
, laPromise
viene risolta con gli indirizzi IPv4 e IPv6 nell'ordine in cui il resolver DNS li ha restituiti. Quandoipv4first
, gli indirizzi IPv4 vengono inseriti prima degli indirizzi IPv6. Quandoipv6first
, gli indirizzi IPv6 vengono inseriti prima degli indirizzi IPv4. Predefinito:verbatim
(gli indirizzi non vengono riordinati). Il valore predefinito è configurabile utilizzandodns.setDefaultResultOrder()
o--dns-result-order
. Il nuovo codice dovrebbe utilizzare{ order: 'verbatim' }
.verbatim
<boolean> Quandotrue
, laPromise
viene risolta con gli indirizzi IPv4 e IPv6 nell'ordine in cui il resolver DNS li ha restituiti. Quandofalse
, gli indirizzi IPv4 vengono inseriti prima degli indirizzi IPv6. Questa opzione verrà deprecata a favore diorder
. Quando entrambi sono specificati,order
ha una priorità maggiore. Il nuovo codice dovrebbe utilizzare soloorder
. Predefinito: attualmentefalse
(gli indirizzi vengono riordinati), ma si prevede che cambierà in un futuro non troppo lontano. Il valore predefinito è configurabile utilizzandodns.setDefaultResultOrder()
o--dns-result-order
.
Risolve un nome host (ad esempio 'nodejs.org'
) nel primo record A (IPv4) o AAAA (IPv6) trovato. Tutte le proprietà option
sono opzionali. Se options
è un numero intero, deve essere 4
o 6
- se options
non viene fornito, vengono restituiti sia gli indirizzi IPv4 che IPv6, o entrambi, se trovati.
Con l'opzione all
impostata su true
, la Promise
viene risolta con addresses
che è un array di oggetti con le proprietà address
e family
.
In caso di errore, la Promise
viene rifiutata con un oggetto Error
, dove err.code
è il codice di errore. Tieni presente che err.code
sarà impostato su 'ENOTFOUND'
non solo quando il nome host non esiste, ma anche quando la ricerca fallisce in altri modi, ad esempio l'assenza di descrittori di file disponibili.
dnsPromises.lookup()
non ha necessariamente nulla a che fare con il protocollo DNS. L'implementazione utilizza una funzione del sistema operativo che può associare nomi a indirizzi e viceversa. Questa implementazione può avere conseguenze sottili ma importanti sul comportamento di qualsiasi programma Node.js. Si prega di dedicare un po' di tempo a consultare la sezione Considerazioni sull'implementazione prima di utilizzare dnsPromises.lookup()
.
Esempio di utilizzo:
import dns from 'node:dns'
const dnsPromises = dns.promises
const options = {
family: 6,
hints: dns.ADDRCONFIG | dns.V4MAPPED,
}
await dnsPromises.lookup('example.org', options).then(result => {
console.log('address: %j family: IPv%s', result.address, result.family)
// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6
})
// Quando options.all è true, il risultato sarà un Array.
options.all = true
await dnsPromises.lookup('example.org', options).then(result => {
console.log('addresses: %j', result)
// addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]
})
const dns = require('node:dns')
const dnsPromises = dns.promises
const options = {
family: 6,
hints: dns.ADDRCONFIG | dns.V4MAPPED,
}
dnsPromises.lookup('example.org', options).then(result => {
console.log('address: %j family: IPv%s', result.address, result.family)
// address: "2606:2800:21f:cb07:6820:80da:af6b:8b2c" family: IPv6
})
// Quando options.all è true, il risultato sarà un Array.
options.all = true
dnsPromises.lookup('example.org', options).then(result => {
console.log('addresses: %j', result)
// addresses: [{"address":"2606:2800:21f:cb07:6820:80da:af6b:8b2c","family":6}]
})
dnsPromises.lookupService(address, port)
Aggiunto in: v10.6.0
Risolve l'indirizzo address
e la port
forniti in un nome host e un servizio utilizzando l'implementazione getnameinfo
sottostante del sistema operativo.
Se address
non è un indirizzo IP valido, verrà generato un TypeError
. La port
verrà forzata a un numero. Se non è una porta legale, verrà generato un TypeError
.
In caso di errore, la Promise
viene rifiutata con un oggetto Error
, dove err.code
è il codice di errore.
import dnsPromises from 'node:dns/promises'
const result = await dnsPromises.lookupService('127.0.0.1', 22)
console.log(result.hostname, result.service) // Stampa: localhost ssh
const dnsPromises = require('node:dns').promises
dnsPromises.lookupService('127.0.0.1', 22).then(result => {
console.log(result.hostname, result.service)
// Stampa: localhost ssh
})
dnsPromises.resolve(hostname[, rrtype])
Aggiunto in: v10.6.0
hostname
<string> Nome host da risolvere.rrtype
<string> Tipo di record di risorse. Predefinito:'A'
.
Utilizza il protocollo DNS per risolvere un nome host (ad esempio, 'nodejs.org'
) in un array di record di risorse. In caso di successo, la Promise
viene risolta con un array di record di risorse. Il tipo e la struttura dei singoli risultati variano in base a rrtype
:
rrtype | records contiene | Tipo di risultato | Metodo abbreviato |
---|---|---|---|
'A' | Indirizzi IPv4 (predefinito) | <string> | dnsPromises.resolve4() |
'AAAA' | Indirizzi IPv6 | <string> | dnsPromises.resolve6() |
'ANY' | qualsiasi record | <Object> | dnsPromises.resolveAny() |
'CAA' | record di autorizzazione CA | <Object> | dnsPromises.resolveCaa() |
'CNAME' | record di nomi canonici | <string> | dnsPromises.resolveCname() |
'MX' | record di scambio di posta | <Object> | dnsPromises.resolveMx() |
'NAPTR' | record di puntatore di autorità del nome | <Object> | dnsPromises.resolveNaptr() |
'NS' | record del server dei nomi | <string> | dnsPromises.resolveNs() |
'PTR' | record puntatore | <string> | dnsPromises.resolvePtr() |
'SOA' | record di inizio dell'autorità | <Object> | dnsPromises.resolveSoa() |
'SRV' | record di servizio | <Object> | dnsPromises.resolveSrv() |
'TXT' | record di testo | <string[]> | dnsPromises.resolveTxt() |
In caso di errore, la Promise
viene rifiutata con un oggetto Error
, dove err.code
è uno dei codici di errore DNS.
dnsPromises.resolve4(hostname[, options])
Aggiunto in: v10.6.0
hostname
<stringa> Nome host da risolvere.options
<Oggetto>ttl
<booleano> Recupera il valore Time-To-Live (TTL) di ogni record. Quandotrue
, laPromise
viene risolta con un array di oggetti{ address: '1.2.3.4', ttl: 60 }
anziché con un array di stringhe, con il TTL espresso in secondi.
Utilizza il protocollo DNS per risolvere gli indirizzi IPv4 (record A
) per l'hostname
. In caso di successo, la Promise
viene risolta con un array di indirizzi IPv4 (es. ['74.125.79.104', '74.125.79.105', '74.125.79.106']
).
dnsPromises.resolve6(hostname[, options])
Aggiunto in: v10.6.0
hostname
<stringa> Nome host da risolvere.options
<Oggetto>ttl
<booleano> Recupera il valore Time-To-Live (TTL) di ogni record. Quandotrue
, laPromise
viene risolta con un array di oggetti{ address: '0:1:2:3:4:5:6:7', ttl: 60 }
anziché con un array di stringhe, con il TTL espresso in secondi.
Utilizza il protocollo DNS per risolvere gli indirizzi IPv6 (record AAAA
) per l'hostname
. In caso di successo, la Promise
viene risolta con un array di indirizzi IPv6.
dnsPromises.resolveAny(hostname)
Aggiunto in: v10.6.0
hostname
<stringa>
Utilizza il protocollo DNS per risolvere tutti i record (noti anche come query ANY
o *
). In caso di successo, la Promise
viene risolta con un array contenente vari tipi di record. Ogni oggetto ha una proprietà type
che indica il tipo del record corrente. E a seconda del type
, sull'oggetto saranno presenti proprietà aggiuntive:
Tipo | Proprietà |
---|---|
'A' | address / ttl |
'AAAA' | address / ttl |
'CNAME' | value |
'MX' | Fare riferimento a dnsPromises.resolveMx() |
'NAPTR' | Fare riferimento a dnsPromises.resolveNaptr() |
'NS' | value |
'PTR' | value |
'SOA' | Fare riferimento a dnsPromises.resolveSoa() |
'SRV' | Fare riferimento a dnsPromises.resolveSrv() |
'TXT' | Questo tipo di record contiene una proprietà array chiamata entries che fa riferimento a dnsPromises.resolveTxt() , ad es. { entries: ['...'], type: 'TXT' } |
Ecco un esempio dell'oggetto risultato:
;[
{ type: 'A', address: '127.0.0.1', ttl: 299 },
{ type: 'CNAME', value: 'example.com' },
{ type: 'MX', exchange: 'alt4.aspmx.l.example.com', priority: 50 },
{ type: 'NS', value: 'ns1.example.com' },
{ type: 'TXT', entries: ['v=spf1 include:_spf.example.com ~all'] },
{
type: 'SOA',
nsname: 'ns1.example.com',
hostmaster: 'admin.example.com',
serial: 156696742,
refresh: 900,
retry: 900,
expire: 1800,
minttl: 60,
},
]
dnsPromises.resolveCaa(hostname)
Aggiunto in: v15.0.0, v14.17.0
hostname
<stringa>
Utilizza il protocollo DNS per risolvere i record CAA
per il hostname
. In caso di successo, la Promise
viene risolta con un array di oggetti contenenti i record di autorizzazione dell'autorità di certificazione disponibili per il hostname
(ad es. [{critical: 0, iodef: 'mailto:[email protected]'},{critical: 128, issue: 'pki.example.com'}]
).
dnsPromises.resolveCname(hostname)
Aggiunto in: v10.6.0
hostname
<stringa>
Utilizza il protocollo DNS per risolvere i record CNAME
per il hostname
. In caso di successo, la Promise
viene risolta con un array di record di nome canonico disponibili per il hostname
(ad es. ['bar.example.com']
).
dnsPromises.resolveMx(hostname)
Aggiunto in: v10.6.0
hostname
<stringa>
Utilizza il protocollo DNS per risolvere i record di scambio di posta (MX
record) per il hostname
. In caso di successo, la Promise
viene risolta con un array di oggetti contenenti sia una proprietà priority
che exchange
(ad es. [{priority: 10, exchange: 'mx.example.com'}, ...]
).
dnsPromises.resolveNaptr(hostname)
Aggiunto in: v10.6.0
hostname
<stringa>
Utilizza il protocollo DNS per risolvere i record basati su espressioni regolari (NAPTR
record) per il hostname
. In caso di successo, la Promise
viene risolta con un array di oggetti con le seguenti proprietà:
flags
service
regexp
replacement
order
preference
{
flags: 's',
service: 'SIP+D2U',
regexp: '',
replacement: '_sip._udp.example.com',
order: 30,
preference: 100
}
dnsPromises.resolveNs(hostname)
Aggiunto in: v10.6.0
hostname
<stringa>
Utilizza il protocollo DNS per risolvere i record del server dei nomi (NS
record) per il hostname
. In caso di successo, la Promise
viene risolta con un array di record del server dei nomi disponibili per hostname
(ad es. ['ns1.example.com', 'ns2.example.com']
).
dnsPromises.resolvePtr(hostname)
Aggiunto in: v10.6.0
hostname
<stringa>
Utilizza il protocollo DNS per risolvere i record pointer (record PTR
) per l'hostname
. In caso di successo, la Promise
viene risolta con un array di stringhe contenenti i record di risposta.
dnsPromises.resolveSoa(hostname)
Aggiunto in: v10.6.0
hostname
<stringa>
Utilizza il protocollo DNS per risolvere un record di inizio autorità (record SOA
) per l'hostname
. In caso di successo, la Promise
viene risolta con un oggetto con le seguenti proprietà:
nsname
hostmaster
serial
refresh
retry
expire
minttl
{
nsname: 'ns.example.com',
hostmaster: 'root.example.com',
serial: 2013101809,
refresh: 10000,
retry: 2400,
expire: 604800,
minttl: 3600
}
dnsPromises.resolveSrv(hostname)
Aggiunto in: v10.6.0
hostname
<stringa>
Utilizza il protocollo DNS per risolvere i record di servizio (record SRV
) per l'hostname
. In caso di successo, la Promise
viene risolta con un array di oggetti con le seguenti proprietà:
priority
weight
port
name
{
priority: 10,
weight: 5,
port: 21223,
name: 'service.example.com'
}
dnsPromises.resolveTxt(hostname)
Aggiunto in: v10.6.0
hostname
<stringa>
Utilizza il protocollo DNS per risolvere le query di testo (record TXT
) per l'hostname
. In caso di successo, la Promise
viene risolta con un array bidimensionale dei record di testo disponibili per hostname
(ad es. [ [ 'v=spf1 ip4:0.0.0.0 ', '~all' ] ]
). Ogni sotto-array contiene blocchi TXT di un record. A seconda del caso d'uso, questi possono essere uniti o trattati separatamente.
dnsPromises.reverse(ip)
Aggiunto in: v10.6.0
ip
<string>
Esegue una query DNS inversa che risolve un indirizzo IPv4 o IPv6 in un array di nomi host.
In caso di errore, la Promise
viene rifiutata con un oggetto Error
, dove err.code
è uno dei codici di errore DNS.
dnsPromises.setDefaultResultOrder(order)
[Cronologia]
Versione | Modifiche |
---|---|
v22.1.0, v20.13.0 | Ora il valore ipv6first è supportato. |
v17.0.0 | Modificato il valore predefinito in verbatim . |
v16.4.0, v14.18.0 | Aggiunto in: v16.4.0, v14.18.0 |
order
<string> deve essere'ipv4first'
,'ipv6first'
o'verbatim'
.
Imposta il valore predefinito di order
in dns.lookup()
e dnsPromises.lookup()
. Il valore può essere:
ipv4first
: impostaorder
predefinito suipv4first
.ipv6first
: impostaorder
predefinito suipv6first
.verbatim
: impostaorder
predefinito suverbatim
.
Il valore predefinito è verbatim
e dnsPromises.setDefaultResultOrder()
ha una priorità maggiore di --dns-result-order
. Quando si utilizzano thread di worker, dnsPromises.setDefaultResultOrder()
dal thread principale non influirà sugli ordini DNS predefiniti nei worker.
dnsPromises.getDefaultResultOrder()
Aggiunto in: v20.1.0, v18.17.0
Ottiene il valore di dnsOrder
.
dnsPromises.setServers(servers)
Aggiunto in: v10.6.0
servers
<string[]> array di indirizzi formattati RFC 5952
Imposta l'indirizzo IP e la porta dei server da utilizzare durante l'esecuzione della risoluzione DNS. L'argomento servers
è un array di indirizzi formattati RFC 5952. Se la porta è la porta DNS predefinita IANA (53) può essere omessa.
dnsPromises.setServers(['8.8.8.8', '[2001:4860:4860::8888]', '8.8.8.8:1053', '[2001:4860:4860::8888]:1053'])
Viene generato un errore se viene fornito un indirizzo non valido.
Il metodo dnsPromises.setServers()
non deve essere chiamato mentre è in corso una query DNS.
Questo metodo funziona in modo molto simile a resolve.conf. In altre parole, se il tentativo di risoluzione con il primo server fornito restituisce un errore NOTFOUND
, il metodo resolve()
non tenterà di risolvere con i server successivi forniti. I server DNS di fallback verranno utilizzati solo se i precedenti scadono o restituiscono qualche altro errore.
Codici di errore
Ogni query DNS può restituire uno dei seguenti codici di errore:
dns.NODATA
: Il server DNS ha restituito una risposta senza dati.dns.FORMERR
: Il server DNS afferma che la query è stata formattata in modo errato.dns.SERVFAIL
: Il server DNS ha restituito un errore generale.dns.NOTFOUND
: Nome di dominio non trovato.dns.NOTIMP
: Il server DNS non implementa l'operazione richiesta.dns.REFUSED
: Il server DNS ha rifiutato la query.dns.BADQUERY
: Query DNS formattata in modo errato.dns.BADNAME
: Nome host formattato in modo errato.dns.BADFAMILY
: Famiglia di indirizzi non supportata.dns.BADRESP
: Risposta DNS formattata in modo errato.dns.CONNREFUSED
: Impossibile contattare i server DNS.dns.TIMEOUT
: Timeout durante il contatto con i server DNS.dns.EOF
: Fine del file.dns.FILE
: Errore durante la lettura del file.dns.NOMEM
: Memoria insufficiente.dns.DESTRUCTION
: Il canale è in fase di distruzione.dns.BADSTR
: Stringa formattata in modo errato.dns.BADFLAGS
: Flag illegali specificati.dns.NONAME
: Il nome host fornito non è numerico.dns.BADHINTS
: Flag di suggerimento illegali specificati.dns.NOTINITIALIZED
: Inizializzazione della libreria c-ares non ancora eseguita.dns.LOADIPHLPAPI
: Errore durante il caricamento diiphlpapi.dll
.dns.ADDRGETNETWORKPARAMS
: Impossibile trovare la funzioneGetNetworkParams
.dns.CANCELLED
: Query DNS annullata.
L'API dnsPromises
esporta anche i codici di errore di cui sopra, ad es. dnsPromises.NODATA
.
Considerazioni sull'implementazione
Sebbene dns.lookup()
e le varie funzioni dns.resolve*()/dns.reverse()
abbiano lo stesso scopo di associare un nome di rete a un indirizzo di rete (o viceversa), il loro comportamento è piuttosto diverso. Queste differenze possono avere conseguenze sottili ma significative sul comportamento dei programmi Node.js.
dns.lookup()
Sotto il cofano, dns.lookup()
utilizza le stesse funzionalità del sistema operativo della maggior parte degli altri programmi. Ad esempio, dns.lookup()
risolverà quasi sempre un determinato nome nello stesso modo del comando ping
. Nella maggior parte dei sistemi operativi di tipo POSIX, il comportamento della funzione dns.lookup()
può essere modificato modificando le impostazioni in nsswitch.conf(5)
e/o resolv.conf(5)
, ma la modifica di questi file cambierà il comportamento di tutti gli altri programmi in esecuzione sullo stesso sistema operativo.
Sebbene la chiamata a dns.lookup()
sia asincrona dal punto di vista di JavaScript, viene implementata come chiamata sincrona a getaddrinfo(3)
che viene eseguita sul threadpool di libuv. Ciò può avere sorprendenti implicazioni negative sulle prestazioni per alcune applicazioni, vedere la documentazione UV_THREADPOOL_SIZE
per maggiori informazioni.
Varie API di rete chiameranno internamente dns.lookup()
per risolvere i nomi host. Se questo è un problema, valuta la possibilità di risolvere il nome host in un indirizzo utilizzando dns.resolve()
e di utilizzare l'indirizzo invece di un nome host. Inoltre, alcune API di rete (come socket.connect()
e dgram.createSocket()
) consentono di sostituire il resolver predefinito, dns.lookup()
.
dns.resolve()
, dns.resolve*()
e dns.reverse()
Queste funzioni sono implementate in modo abbastanza diverso da dns.lookup()
. Non utilizzano getaddrinfo(3)
ed eseguono sempre una query DNS sulla rete. Questa comunicazione di rete viene sempre eseguita in modo asincrono e non utilizza il threadpool di libuv.
Di conseguenza, queste funzioni non possono avere lo stesso impatto negativo sull'elaborazione che avviene nel threadpool di libuv che può avere dns.lookup()
.
Non utilizzano lo stesso set di file di configurazione utilizzati da dns.lookup()
. Ad esempio, non utilizzano la configurazione da /etc/hosts
.