Node & Browser tested, Non-JSON DNS over HTTPS fetching with minimal dependencies.
npm install doh-queryNode & Browser tested, Non-JSON DNS over HTTPS 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.
By default doh-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.
``js`
const { query, endpoints } = require('doh-query')
const { cloudflare, google, opendns } = endpoints
try {
const { answers } = await query({
questions: [
{type: 'A', name: 'google.com'},
{type: 'A', name: 'twitter.com'}
]
}, {
/ Options (optional) /
endpoints: [cloudflare, google, opendns], // (optional) all known working unfiltered 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
}
}
You can install doh-query as a command-line tool using npm i doh-query -g
or by running .
`sh
$ doh-query
Execute a dns query over https.
Examples:
$ doh-query --json -e google \
'{ "questions": [{ "type": "A", "name": "google.com" }] }'
$ echo '{ "questions": [{ "type": "A", "name": "google.com" }] }' \
| doh-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 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
`
For an endpoint to work, it needs to satisfy this interface:
`typescript`
interface Endpoint {
/ Domain name, required! /
host: string
/ Path, prefixed with /, defaults to /dns-query /
path?: string
/ https port, defaults to 443 /
port?: number
/ true, if endpoint logs requests, defaults to false /
log?: boolean
/ true, if endpoint support CORS headers, defaults to false /
cors?: boolean
/ true, if endpoint filters/redirects DNS packets, defaults to false /
filter?: boolean
/ link to documentation, if available /
docs?: string
/ Known geographical location /
location?: string
/ Method to request dns, defaults to GET /
method?: 'post' | 'Post' | 'POST' | 'get' | 'Get' | 'GET'
/ DEBUG ONLY! false to use http to connect instead of https, defaults to true /
https?: boolean
}
Instead of passing an object you can also pass an endpoint matching a url, with an
amendmend as to whether its a POST or GET endpoint.
Examples:
foo.com → { host: 'foo.com' }
http://bar.com:81/query [post] →{ host: 'bar.com', path: '/query', port: 81, method: 'post', https: false }
_Note:_ If no path is given, such as foo.com, the path will be assumed as /dns-query, butfoo.com/
if a path is given such as it will assume that path /`!
- dns-packet
- DNS over HTTPS
- 1.1.1.1
- Google Public DNS