Skip to content

Latest commit

 

History

History
184 lines (141 loc) · 6.83 KB

README.md

File metadata and controls

184 lines (141 loc) · 6.83 KB

Classes

MethodNotAllowedError

Custom error class to be thrown when someone tries to send a DoH request with a request method other than "GET" or "POST"

DohResolver

A super lame DNS over HTTPS stub resolver

Constants

ALLOWED_REQUEST_METHODS : array

Allowed request methods for sending DNS over HTTPS requests.
Allowed method are "GET" and "POST"

Functions

isMethodAllowed(method) ⇒ boolean

Check if a request method is allowed

makeQuery(qname, qtype) ⇒ object

Make a DNS query message of type object (see dns-packet). Use this before calling sendDohMsg
The recursion desired flag will be set, and the ID in the header will be set to zero, per the RFC (section 4.1).

sendDohMsg(packet, url, method, headers, timeout) ⇒ Promise.<object>

Send a DNS message over HTTPS to url using the given request method

MethodNotAllowedError

Custom error class to be thrown when someone tries to send a DoH request with a request method other than "GET" or "POST"

Kind: global class

DohResolver

A super lame DNS over HTTPS stub resolver

Kind: global class

new DohResolver(nameserver_url)

Creates a new DoH resolver

Param Type Description
nameserver_url string The URL we're going to be sending DNS requests to

Example

// import the required stuff
const {DohResolver} = require('dohjs');

// create your resolver
const resolver = new DohResolver('https://dns.google/dns-query')

// lookup the A records for example.com
// print out the answer data
resolver.query('example.com', 'A')
  .then(response => {
    response.answer.forEach(ans => console.log(ans.data));
  })
  .catch(err => console.error(err));

dohResolver.query(qname, qtype, method, headers, timeout) ⇒ Promise.<object>

Perform a DNS lookup for the given query name and type.

Kind: instance method of DohResolver
Returns: Promise.<object> - The DNS response received
Throws:

  • MethodNotAllowedError If the method is not allowed (i.e. if it's not "GET" or "POST"), a MethodNotAllowedError will be thrown.
Param Type Default Description
qname string the domain name to query for (e.g. example.com)
qtype string "A" the type of record we're looking for (e.g. A, AAAA, TXT, MX)
method string "POST" Must be either "GET" or "POST"
headers object define HTTP headers to use in the DNS query
IMPORTANT: If you don't provide the "Accept: application/dns-message" header, you probably won't get the response you're hoping for. See RFC 8484 examples for examples of HTTPS headers for both GET and POST requests.
timeout number the number of milliseconds to wait for a response before aborting the request

ALLOWED_REQUEST_METHODS : array

Allowed request methods for sending DNS over HTTPS requests.
Allowed method are "GET" and "POST"

Kind: global constant

isMethodAllowed(method) ⇒ boolean

Check if a request method is allowed

Kind: global function
Returns: boolean - If method is "GET" or "POST", return true; return false otherwise.

Param Type Description
method string the request method to test

makeQuery(qname, qtype) ⇒ object

Make a DNS query message of type object (see dns-packet). Use this before calling sendDohMsg
The recursion desired flag will be set, and the ID in the header will be set to zero, per the RFC (section 4.1).

Kind: global function
Returns: object - The DNS query message

Param Type Default Description
qname string the domain name to put in the query message (e.g. example.com)
qtype string "A" the query type to put in the query message (e.g. A, AAAA, DS, DNSKEY)

Example

// imports
const {makeQuery} = require('dohjs');

// create a query message
const msg = makeQuery('example.com', 'TXT');

// print it out to the console
console.log(msg);
// -> { type: 'query',
// ->  id: 0,
// ->  flags: 256,
// ->  questions: [ { type: 'TXT', name: 'example.com' } ] }

sendDohMsg(packet, url, method, headers, timeout) ⇒ Promise.<object>

Send a DNS message over HTTPS to url using the given request method

Kind: global function
Returns: Promise.<object> - the response (if we got any)

Param Type Description
packet object the DNS message to send
url string the url to send the DNS message to
method string the request method to use ("GET" or "POST")
headers object headers to send in the DNS request. The default headers for GET requests are
timeout number the number of milliseconds to wait for a response before aborting the request

Example

// imports
 const {makeQuery, sendDohMsg} = require('dohjs');

 const url = 'https://cloudflare-dns.com/dns-query';
 const method = 'GET';

 // create a query message
 let msg = makeQuery('example.com', 'TXT');

 // send it and print out the response to the console
 sendDohMsg(msg, url, method)
 .then(response => response.answers.forEach(ans => console.log(ans.data.toString())))
 .catch(console.error);