doh-query
Node & 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.
Important Note before getting started
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.
JavaScript API
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
}
}CLI
You can install doh-query as a command-line tool using npm i doh-query -g
or by running npx doh-query.
$ doh-query <options> <input>
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 <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: 30000Endpoints
For an endpoint to work, it needs to satisfy this interface:
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, but
if a path is given such as foo.com/ it will assume that path /!