dnsbench

Benchmark DNS-over-HTTPS (DoH) providers and rank them by real-world latency, consistency, and success rate.

Requirements

• Node.js 20+
• ESM only

Installation

npm install -g dnsbench

Or run from source:

git clone <repo-url>
cd dnsbench
npm install
npm run build
npm link

Quick Start

# Benchmark all built-in providers (default command)
dnsbench

# With options
dnsbench --iterations 10 --providers cloudflare,google

# List available providers
dnsbench list

# Compare two providers
dnsbench compare cloudflare google

Built-in Providers

| Provider | Endpoint | |------------|-----------------------------------------------| | Cloudflare | https://cloudflare-dns.com/dns-query | | Google | https://dns.google/dns-query | | Quad9 | https://dns.quad9.net/dns-query | | AdGuard | https://dns.adguard-dns.com/dns-query | | ControlD | https://freedns.controld.com/p0 | | Mullvad | https://dns.mullvad.net/dns-query | | NextDNS | https://dns.nextdns.io/{profile}/dns-query |

NextDNS Configuration

NextDNS requires a profile ID. Set the environment variable before benchmarking:

export DNSBENCH_NEXTDNS_PROFILE=your-config-id
dnsbench

Without this variable, NextDNS is excluded from default benchmarks but still appears in dnsbench list.

Usage

Running dnsbench with no subcommand benchmarks all built-in providers and displays a ranked table.

Default test domains: google.com, github.com, cloudflare.com, microsoft.com, amazon.com

| Option | Default | Description | |--------|---------|-------------| | --iterations <n> | 5 | Queries per domain | | --domains <list> | built-in list | Comma-separated domains | | --providers <list> | all (except unconfigured NextDNS) | Comma-separated provider IDs | | --timeout <ms> | 5000 | Request timeout | | --retries <n> | 1 | Retries on network/timeout errors | | --json | — | JSON output | | --csv | — | CSV output | | --markdown | — | Markdown output |

Examples:

dnsbench
dnsbench --iterations 10
dnsbench --providers cloudflare,google,quad9
dnsbench --domains example.com,openai.com --json
dnsbench --csv > results.csv

dnsbench list

Display built-in providers and their endpoints.

dnsbench list

dnsbench compare

Compare two providers side by side.

dnsbench compare cloudflare google
dnsbench compare adguard mullvad --iterations 10 --markdown

Output Formats

• Table (default): Colored terminal table with fastest provider highlighted
• JSON: Machine-readable full report
• CSV: Spreadsheet-friendly ranked results
• Markdown: Documentation-friendly tables

Example table output: examples/benchmark-table.txt

Architecture

src/
  cli.ts              # Commander entry point
  commands/           # benchmark, list, compare
  benchmark/          # Engine and per-provider runner
  providers/          # Provider registry
  output/             # Table, JSON, CSV, Markdown formatters
  utils/              # DNS wire format, HTTP client, statistics
  types/              # Shared TypeScript types

Benchmark flow:

1. Providers run concurrently (Promise.all)
2. Queries per provider run sequentially (domains × iterations)
3. Each query uses RFC 8484 DoH POST with native fetch
4. Results ranked by avg latency → p95 → success rate

Development

npm run dev -- --iterations 2 --providers cloudflare,google
npm run build
npm run lint
npm run test

License

MIT — see LICENSE.