dns-over-http

0.2.0 verified Sat Apr 25 auth: no javascript

DNS over HTTPS (DoH) client and middleware for Node.js. Version 0.2.0 provides both a server middleware for `http.createServer()` and a client for querying DNS via HTTPS. It uses centralized DNS servers (e.g., Quad9, Google, Cloudflare) and caches answers. This is an early-stage work-in-progress with limited features and no active maintenance. It differs from mature DoH libraries by offering a simple middleware interface and low-level wire format (dns-packet) support.

Common errors

error TypeError: doh is not a function ↓

cause ESM import of CJS module without default handling.

fix

Use const doh = require('dns-over-http') or const { default: doh } = await import('dns-over-http').

error Error: getaddrinfo ENOTFOUND ↓

cause Missing or invalid DNS server address in options.servers.

fix

Provide valid IP addresses like '8.8.8.8' in servers array.

error TypeError: Cannot read properties of undefined (reading 'answers') ↓

cause Response callback may receive null or undefined for failed queries.

fix

Check err first; if no error, ensure res has answers property: if (res && res.answers).

Warnings

gotcha Client query URL must be full HTTPS URL; path '/experimental' is specific to Google DNS. ↓

fix Use URL like 'https://dns.google.com:443/experimental' or check provider's endpoint.

gotcha Server middleware does not validate HTTPS; you must wrap with https.createServer or use reverse proxy. ↓

fix Use https.createServer with valid cert and key, or terminate SSL upstream.

gotcha doh() returns a single request handler; cannot be used as Express middleware directly (expects (req, res)). ↓

fix Use doh() directly with http.createServer or adapt for Express via (req, res) signature.

deprecated Package is early WIP (version 0.2.0) with no recent updates. Not recommended for production use. ↓

fix Consider mature alternatives like node-doh or dns-over-https.

Install

npm install dns-over-http

yarn add dns-over-http

pnpm add dns-over-http

Imports

doh
wrong
```
import doh from 'dns-over-http'
```
correct
```
const doh = require('dns-over-http')
```
CJS module; ESM import may not work without bundler or esm package.
doh
```
const { default: doh } = await import('dns-over-http')
```
If using ESM, dynamic import with .default may be required.

doh.query

wrong

doh.query('/dns-query', questions, callback)

correct

const doh = require('dns-over-http'); doh.query({url}, questions, callback)

First argument is an options object (including url), not a path string.

doh(opts)

wrong

const handler = doh.createServer({ servers: ['1.1.1.1'] })

correct

const handler = doh({ servers: ['1.1.1.1'] })

doh() returns a request handler directly; no createServer method.

Quickstart

Creates a DoH server with HTTPS and performs two DNS queries via client.

const https = require('https');
const doh = require('dns-over-http');

const server = https.createServer({
  cert: process.env.SSL_CERT || '',
  key: process.env.SSL_KEY || ''
}, doh({
  servers: ['9.9.9.9', '8.8.8.8', '1.1.1.1'],
  maxAge: 600000
}));

server.listen(3000, () => {
  console.log('DoH server listening on port 3000');
});

// Client example
const results = [];
const lookups = [
  { type: 'A', name: 'google.com' },
  { type: 'AAAA', name: 'google.com' }
];

for (const lookup of lookups) {
  doh.query({
    url: 'https://dns.google.com:443/experimental'
  }, [lookup], (err, res) => {
    if (err) throw err;
    results.push(res.answers);
    if (results.length === lookups.length) {
      console.log(JSON.stringify(results, null, 2));
    }
  });
}