dns_client #

Dart implementation of DNS-over-HTTPS (DoH).

Korean (한국어)

Features #

• Multiple DNS Providers - Google, Cloudflare, AdGuard, NextDNS, Quad9, OpenDNS, or custom DoH endpoints
• Wire Format Support - RFC 1035/8484 compliant DNS wire format with HTTP/2 for Quad9
• 36 DNS Record Types - A, AAAA, MX, TXT, SRV, CAA, HTTPS, SVCB, DNSKEY, DS, and more
• Privacy Protection - Hide client IP from authoritative nameservers
• Error Handling - Detailed exceptions for DNS and HTTP failures
• Dart 3 Support - Requires Dart SDK 3.7.0+

Installation #

Add to your pubspec.yaml:

dependencies:
  dns_client: ^1.0.0

Then run:

dart pub get

Quick Start #

import 'package:dns_client/dns_client.dart';

void main() async {
  final dns = DnsOverHttps.google();

  final addresses = await dns.lookup('google.com');
  for (final address in addresses) {
    print(address.address);
  }

  dns.close();
}

Usage Examples #

Basic DNS Lookup #

// Using Google DNS
final dns = DnsOverHttps.google();
final addresses = await dns.lookup('example.com');
dns.close();

// Using Cloudflare DNS
final dns = DnsOverHttps.cloudflare();
final addresses = await dns.lookup('example.com');
dns.close();

// Using AdGuard DNS (blocks ads and trackers)
final dns = DnsOverHttps.adguard();
final addresses = await dns.lookup('example.com');
dns.close();

// Using AdGuard DNS (no filtering)
final dns = DnsOverHttps.adguardNonFiltering();
final addresses = await dns.lookup('example.com');
dns.close();

// Using AdGuard DNS (family protection)
final dns = DnsOverHttps.adguardFamily();
final addresses = await dns.lookup('example.com');
dns.close();

// Using Quad9 DNS (malware blocking + DNSSEC)
final dns = DnsOverHttpsWire.quad9();
final addresses = await dns.lookup('example.com');
dns.close();

// Using Quad9 DNS with ECS (geolocation hints)
final dns = DnsOverHttpsWire.quad9Ecs();
final addresses = await dns.lookup('example.com');
dns.close();

// Using Quad9 DNS (no filtering)
final dns = DnsOverHttpsWire.quad9Unsecured();
final addresses = await dns.lookup('example.com');
dns.close();

// Using NextDNS
final dns = DnsOverHttps.nextdns();
final addresses = await dns.lookup('example.com');
dns.close();

// Using NextDNS with custom configuration
final dns = DnsOverHttps.nextdns(configId: 'abc123');
final addresses = await dns.lookup('example.com');
dns.close();

// Using OpenDNS
final dns = DnsOverHttpsWire.opendns();
final addresses = await dns.lookup('example.com');
dns.close();

// Using OpenDNS FamilyShield (blocks adult content)
final dns = DnsOverHttpsWire.opendnsFamilyShield();
final addresses = await dns.lookup('example.com');
dns.close();

Query Specific Record Types #

final dns = DnsOverHttps.google();

// MX records (mail servers)
final mxRecords = await dns.lookupDataByRRType('example.com', RRType.MX);
print('Mail servers: $mxRecords');

// TXT records (SPF, DKIM, domain verification)
final txtRecords = await dns.lookupDataByRRType('example.com', RRType.TXT);
print('TXT records: $txtRecords');

// SRV records (service discovery)
final srvRecords = await dns.lookupDataByRRType(
  '_jmap._tcp.fastmail.com',
  RRType.SRV,
);
print('SRV records: $srvRecords');

// CAA records (certificate authority authorization)
final caaRecords = await dns.lookupDataByRRType('example.com', RRType.CAA);
print('CAA records: $caaRecords');

// HTTPS records (service binding)
final httpsRecords = await dns.lookupDataByRRType('example.com', RRType.HTTPS);
print('HTTPS records: $httpsRecords');

dns.close();

Custom DNS Provider #

final dns = DnsOverHttps(
  'https://dns.quad9.net:5053/dns-query',
  timeout: Duration(seconds: 10),
);

final addresses = await dns.lookup('example.com');
dns.close();

Privacy Settings #

Hide your IP address from authoritative nameservers:

final dns = DnsOverHttps(
  'https://dns.google/resolve',
  maximalPrivacy: true,  // Sets edns_client_subnet=0.0.0.0/0
);

final addresses = await dns.lookup('example.com');
dns.close();

Timeout Configuration #

final dns = DnsOverHttps.google(
  timeout: Duration(seconds: 10),  // Default is 5 seconds
);

final addresses = await dns.lookup('example.com');
dns.close();

Error Handling #

final dns = DnsOverHttps.google();

try {
  final records = await dns.lookupDataByRRType(
    'nonexistent.invalid',
    RRType.A,
  );
} on DnsLookupException catch (e) {
  // DNS-level error (NXDOMAIN, SERVFAIL, etc.)
  print('DNS error: ${e.message}');
  print('Hostname: ${e.hostname}');
  print('Status: ${e.status}');  // 3 = NXDOMAIN, 2 = SERVFAIL
} on DnsHttpException catch (e) {
  // HTTP-level error
  print('HTTP error: ${e.statusCode}');
  print('Message: ${e.message}');
} finally {
  dns.close();
}

Full Response Inspection #

Access the complete DNS response for detailed information:

final dns = DnsOverHttps.google();

final record = await dns.lookupHttpsByRRType('example.com', RRType.MX);

if (record.isSuccess) {
  print('Status: ${record.status}');  // 0 = NOERROR

  for (final answer in record.answer ?? []) {
    print('Name: ${answer.name}');
    print('Type: ${answer.type}');
    print('TTL: ${answer.TTL} seconds');
    print('Data: ${answer.data}');
  }
} else if (record.isNxDomain) {
  print('Domain does not exist');
} else if (record.isServerFailure) {
  print('Server failure');
}

dns.close();

API Reference #

DnsOverHttps #

Constructors:

Methods:

DnsOverHttpsWire #

Wire format DoH client using HTTP/2 (RFC 1035/8484). Required for Quad9 and OpenDNS.

Constructors:

Methods:

Supported Record Types (RRType) #

Custom record types:

// TLSA record (type 52)
final tlsaType = RRType('TLSA', 52);
final tlsaRecords = await dns.lookupDataByRRType('example.com', tlsaType);

Response Classes #

DnsRecord:

Answer:

Exceptions #

DnsLookupException - Thrown when DNS query fails:

• hostname - The queried hostname
• status - DNS status code (2=SERVFAIL, 3=NXDOMAIN, etc.)
• message - Error description

DnsHttpException - Thrown when HTTP request fails:

• statusCode - HTTP status code
• message - Error description

DnsWireFormatException - Thrown when wire format parsing fails:

• message - Error description
• offset - Byte offset where error occurred

Requirements #

• Dart SDK: >=3.7.0 <4.0.0

License #

See LICENSE file.

Contributing #

Please file feature requests and bugs at the issue tracker.