README
dns-query
Node & Browser tested, Non-JSON DNS over HTTPS (and DNS) fetching with minimal dependencies.
DNS over HTTPS (DoH) is protocol designed for performing remote Domain Name System resolution over HTTPS. Requests are made of HTTP to increase user security and privacy. See DNS over HTTPS for more information.
This package provides simple function to make DoH queries both in node and the browser.
Important Note before getting started
By default dns-query uses well-known public dns-over-https servers to execute
queries! These servers come with caveats, please look at ./endpoints.md
for more information.
DNS support
Node.js's dns support is limited, primary example being: lookupTXT does not support ttl
results. For that reason, when using dns-query in node you can also specify dns endpoints.
JavaScript API
const { query, endpoints: defaultEndpoints } = require('dns-query')
const { cloudflare, google, opendns } = defaultEndpoints
let endpoints // If undefined endpoints will be assumed to use one of the dns or doh endpoints!
endpoints = 'doh' // Use any of the given defaultEndpoints to resolve
endpoints = 'dns' // Use the system default dns servers to resolve (Node.js only!)
endpoints = [cloudflare, google, opendns] // Use predefined, well-known endpoints
endpoints = ['cloudflare', 'google', 'opendns'] // Use predefined, well-known endpoints by their name
endpoints = ['https://cloudflare-dns.com/dns-query'] // Use a custom endpoint
endpoints = [{ host: 'cloudflare-dns.com' }] // Specify using properties
try {
const { answers } = await query({
questions: [
{type: 'A', name: 'google.com'},
{type: 'A', name: 'twitter.com'}
]
}, {
/* Options (optional) */
endpoints,
retry: 3, // (optional) retries if a given endpoint fails; -1 = infinite retries; 0 = no retry
timeout: 4000, // (optional, default=30000) timeout for single requests
signal, // (optional) an AbortSignal to abort the request
})
} catch (error) {
switch (error.code) {
case 'HTTP_STATUS': // request failed, http status error
case 'RESPONSE_ERR': // request failed, invalid response
case 'ABORT_ERR': // request aborted
default: // Unexpected error
}
}
CLI
You can install dns-query as a command-line tool using npm i dns-query -g
or by running npx dns-query.
$ dns-query <options> <input>
Execute a dns query over https.
Examples:
$ dns-query --json -e google \
'{ "questions": [{ "type": "A", "name": "google.com" }] }'
$ echo '{ "questions": [{ "type": "A", "name": "google.com" }] }' \
| dns-query --stdin --endpoint cloudflare
--help, -h ....... Show this help
--version, -v .... Show the version
--json ........... --type=json
--base64 ......... --type=base64
--binary ......... --type=binary
--type ........... Input type. Options: json, base64, binary; Default: json
--out ............ Output type. Defaults to the input --type.
--stdin .......... Get <input> from stdin instead of cli arguments
--endpoint, -e ... Use a specific endpoint. Can be either the name of a known
endpoint, a json object or an url. By default uses one of the known endpoints.
If multiple are provided, one at random will be used.
--endpoints ...... Lists all known endpoints as json.
--retry .......... Number of retries to do in case a request fails, default: 3
--timeout ........ Timeout for the request in milliseconds, default: 30000
Endpoints
For an endpoint to work, it needs to satisfy this interface:
interface EndpointProps {
/* https is the default for DoH endpoints, udp4:/upd6: for regular dns endpoints and http for debug only! defaults to https: */
protocol?: 'http:' | 'https:' | 'udp4:' | 'udp6:';
/* Host to look up */
host: string;
/* Path, prefixed with /, defaults to /dns-query for the http/https protocol, ignored for udp */
path?: string;
/* https port, defaults to 443 for https, 80 for http and 53 for udp*/
port?: number;
/* true, if endpoint is known to log requests, defaults to false */
log?: boolean;
/* true, if endpoint supports http/https CORS headers, defaults to false */
cors?: boolean;
/* true, if endpoint is known to filters/redirects DNS packets, defaults to false */
filter?: boolean;
/* link to documentation, if available */
docs?: string;
/* Known geographical location */
location?: string;
/* Method to request in case of http/https, defaults to GET */
method?: 'post' | 'Post' | 'POST' | 'get' | 'Get' | 'GET';
}
String endpoints
Instead of passing an object you can also pass a string. If the string matches the name
of one of the endpoints, that endpoint will be used, else it needs
to be a url, with a possible [post] or [get] suffix to indicate the method.
Examples:
foo.com → { host: 'foo.com' }
http://bar.com:81/query [post] →
{ host: 'bar.com', path: '/query', port: 81, method: 'post', protocol: 'http:' }
Note: If no path is given, such as foo.com, the path will be assumed as /dns-query, but
if a path is given such as foo.com/ it will assume that path /!
To specify DNS endpoints you need to prefix them using udp: (or udp4:, udp6)
udp://1.1.1.1 → { host: '1.1.1.1', protocol: 'udp4' }