idoh 0.2.3

Fast and secure DNS over HTTPS resolution / 极速安全的 DoH 解析库
Documentation

English | 中文

idoh : Fast and secure DNS over HTTPS resolution

idoh is a high-performance, async Rust library for DNS over HTTPS (DoH) resolution, designed for speed and reliability through concurrent queries.

Based on idns. See idns for DnsRace, Cache, Parse trait, and more.

Features

  • Concurrent Resolution: Queries multiple DoH providers simultaneously (Tencent, Google, Cloudflare, DNS0, etc.) and returns the fastest response.
  • Simple API: Direct access to DNS answers without complex extraction callbacks.
  • MX Lookup: Specialized support for MX record lookup with automatic priority sorting.
  • Zero-Copy Caching: Optional caching support using expire_cache with GAT-based zero-copy retrieval.
  • Async/Await: Built on tokio for efficient non-blocking I/O.
  • Robust Error Handling: Gracefully handles failures from individual providers.

Usage

Add to your Cargo.toml:

[dependencies]
idoh = "0.1"
idns = "0.1"

Basic Resolution

use idoh::resolve;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Resolve A records for google.com
    let answers = resolve("google.com", "A").await?;
    
    if let Some(answers) = answers {
        for answer in answers {
            println!("IP: {}", answer.data);
        }
    }
    Ok(())
}

TXT/SPF Record Lookup

use idoh::resolve;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Resolve TXT records (e.g., SPF records)
    let answers = resolve("qq.com", "TXT").await?;
    
    if let Some(answers) = answers {
        for answer in answers {
            if answer.data.starts_with("v=spf1") {
                println!("SPF: {}", answer.data);
            }
        }
    }
    Ok(())
}

MX Lookup (Basic)

Enable the mx feature:

[dependencies]
idoh = { version = "0.1", features = ["mx"] }

use idoh::{MxLookup, Resolve};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mx_records = Resolve.mx("gmail.com").await?;
    
    if let Some(records) = mx_records {
        for mx in records.iter() {
            println!("Priority: {}, Server: {}, TTL: {}s", 
                     mx.priority, mx.server, mx.ttl);
        }
    }
    Ok(())
}

DnsRace + Cache (Recommended)

Race multiple DoH servers and cache results using idns:

use idoh::{DOH_LI, doh_li};
use idns::{Cache, DnsRace, Mx, Query};
use std::time::Instant;

#[tokio::main]
async fn main() {
  let race = DnsRace::new(doh_li(DOH_LI));
  let cache: Cache<Mx> = Cache::new(60); // 60s TTL

  // First query (cache miss)
  let t1 = Instant::now();
  let r1 = cache.query(&race, "gmail.com").await;
  let d1 = t1.elapsed();
  println!("First: {}ms", d1.as_millis());
  if let Some(mx_list) = &*r1.unwrap() {
    for mx in mx_list {
      println!("  {} {}", mx.priority, mx.server);
    }
  }

  // Second query (cache hit)
  let t2 = Instant::now();
  let _ = cache.query(&race, "gmail.com").await;
  let d2 = t2.elapsed();
  println!("Cache: {}μs", d2.as_micros());
  println!("✓ {}ms -> {}μs ({}x faster)", d1.as_millis(), d2.as_micros(),
    d1.as_micros() / d2.as_micros().max(1));
}

Output:

First: 744ms
  5 gmail-smtp-in.l.google.com
  10 alt1.gmail-smtp-in.l.google.com
  20 alt2.gmail-smtp-in.l.google.com
  30 alt3.gmail-smtp-in.l.google.com
  40 alt4.gmail-smtp-in.l.google.com
Cache: 1μs
✓ 744ms -> 1μs (744000x faster)

MX Lookup with Caching

Enable both mx and cache features:

[dependencies]
idoh = { version = "0.1", features = ["mx", "cache"] }

use idoh::mx::cache::Cache;
use idoh::MxLookup;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // First call: Network request (cold cache)
    // Time: ~744ms
    let mx_records = Cache.mx("gmail.com").await?;
    
    if let Some(records) = mx_records {
        println!("First call (Network): Found {} records", records.len());
        for mx in records.iter() {
            println!("  Priority: {}, Server: {}", mx.priority, mx.server);
        }
    }
    
    // Second call: Memory lookup (hot cache)
    // Time: ~1.8µs (Zero-copy, >400,000x faster)
    let cached = Cache.mx("gmail.com").await?;
    
    if let Some(records) = cached {
        println!("Second call (Cache): Found {} records", records.len());
    }
    
    Ok(())
}

Performance Comparison

Operation Time Notes
Network Lookup ~744 ms Depends on DNS provider latency
Cache Lookup ~1.8 µs Zero-copy, >400,000x faster

Design Philosophy

idoh prioritizes latency minimization. Instead of querying a single DNS server, it concurrently sends requests to a pre-configured list of high-performance public DoH providers (including Tencent, Google, Cloudflare, AliDNS). The first valid response is returned, effectively racing the providers against each other. This approach mitigates network jitter and single-provider slowness.

Flowchart

graph TD
    A[User calls resolve] --> B{Spawn Manager Task};
    B --> C[Provider 1];
    C -- Wait 500ms --> D[Provider 2];
    D -- Wait 500ms --> E[Provider ...];
    C -- Query --> F[DoH Server 1];
    D -- Query --> G[DoH Server 2];
    E -- Query --> H[DoH Server ...];
    F -- Response --> I{Channel};
    G -- Response --> I;
    H -- Response --> I;
    I -- First Success --> J[Return Result];
    J --> K[Abort Pending Tasks];

Tech Stack

  • Runtime: tokio
  • HTTP Client: ireq (lightweight wrapper)
  • JSON Parsing: sonic-rs (SIMD-accelerated)
  • Caching: expire_cache + dashmap (thread-safe, expiration support)
  • Concurrency: crossfire (efficient channels)

Supported Record Types

The library supports all standard DNS record types. Common ones include:

  • A (1): IPv4 address
  • AAAA (28): IPv6 address
  • MX (15): Mail exchange (with dedicated MxLookup trait)
  • TXT (16): Text records (SPF, DKIM, etc.)
  • CNAME (5): Canonical name
  • NS (2): Name server
  • SRV (33): Service locator
  • PTR (12): Pointer record

See src/record_type.rs for the complete list of constants.

Directory Structure

  • src/lib.rs: Module exports and feature gating
  • src/resolve.rs: Core resolution logic implementing the concurrent "race" mechanism
  • src/resolve_trait.rs: Resolver trait definition
  • src/mx.rs: MX record specific implementation and caching logic
  • src/post.rs: HTTP request handling and JSON response parsing
  • src/record_type.rs: DNS record type constants
  • src/error.rs: Error types and result definitions

Architecture

graph TD
    A[Client] --> B[resolve function]
    B --> C[Manager Task]
    C --> D[Provider 1]
    C --> E[Provider 2]
    C --> F[Provider N]
    D --> G[DoH Server 1]
    E --> H[DoH Server 2]
    F --> I[DoH Server N]
    G --> J[Response Channel]
    H --> J
    I --> J
    J --> K[First Response]
    K --> L[Parse JSON]
    L --> M[Return Answers]
    M --> N[Cancel Pending]

Implementation Details

  • Concurrent Racing: Multiple providers are queried simultaneously with staggered timeouts (500ms intervals)
  • Channel-based Communication: Uses crossfire channels for efficient inter-task communication
  • JSON Parsing: Leverages sonic-rs for SIMD-accelerated JSON parsing
  • Error Resilience: Individual provider failures don't affect the overall operation
  • Resource Management: All pending requests are canceled upon first successful response
  • HTTP/2 Support: Automatically uses HTTP/2 when available for better performance
  • Timeout Handling: Default 5-second timeout per provider, configurable via environment variables

API Reference

Structs

Answer

Represents a DNS answer record.

pub struct Answer {
    pub name: String,
    pub r#type: u16,
    pub ttl: u32,
    pub data: String,
}

Mx

Represents an MX record with priority and server information.

pub struct Mx {
    pub priority: u16,
    pub server: String,
    pub ttl: u32,
}

Functions

resolve

The core function that performs the concurrent DoH lookup.

pub async fn resolve(
  name: impl AsRef<str>,
  record_type: impl AsRef<str>,
) -> Result<Option<Vec<Answer>>>

Returns a vector of DNS answers. Each Answer contains:

  • name: The queried domain name
  • r#type: DNS record type (numeric)
  • ttl: Time to live in seconds
  • data: The record data (IP address, hostname, text, etc.)

Traits

MxLookup

Provides the mx method for fetching MX records.

pub trait MxLookup {
  type VecMx<'a>: Deref<Target = [Mx]> + 'a
  where
    Self: 'a;
  fn mx<'a>(
    &'a self,
    domain: impl AsRef<str> + Send + 'a,
  ) -> impl std::future::Future<Output = Result<Option<Self::VecMx<'a>>>> + Send + 'a;
}

Resolver

Core trait for DNS resolution implementations.

pub trait Resolver {
  fn resolve<'a>(
    &'a self,
    domain: impl AsRef<str> + Send + 'a,
    record_type: impl AsRef<str> + Send + 'a,
  ) -> impl std::future::Future<Output = Result<Option<Vec<Answer>>>> + Send + 'a;
}

Functions

  • doh_li(li: &[&str]) -> Vec<DoH> - Create DoH clients from URL list

Constants

DOH_LI

Pre-configured DoH provider URLs for use with idns:

pub const DOH_LI: &[&str] = &[
    "https://dns.google/dns-query",
    "https://cloudflare-dns.com/dns-query",
    "https://doh.pub/dns-query",
    "https://dns.alidns.com/dns-query",
    "https://zero.dns0.eu/",
];

DOH_PROVIDERS

Pre-configured DoH providers:

Provider URL
Google DNS https://dns.google/dns-query
Cloudflare https://cloudflare-dns.com/dns-query
Tencent DNS https://doh.pub/dns-query
AliDNS https://dns.alidns.com/dns-query
DNS0 https://zero.dns0.eu/

History: The Rise of DoH

The Domain Name System (DNS), the phonebook of the Internet, was designed in the 1980s without encryption. For decades, every website visit leaked your destination to anyone listening on the wire.

In 2018, the IETF standardized DNS over HTTPS (DoH) (RFC 8484) to close this privacy gap. By wrapping DNS queries in encrypted HTTPS traffic, DoH prevents eavesdropping and manipulation. Major browsers like Firefox and Chrome adopted it, sparking a revolution in internet privacy. idoh builds on this legacy, offering a modern, fast, and secure way to resolve names in the Rust ecosystem.

About

This project is an open-source component of js0.site ⋅ Refactoring the Internet Plan.

We are redefining the development paradigm of the Internet in a componentized way. Welcome to follow us:

About

This project is an open-source component of js0.site ⋅ Refactoring the Internet Plan.

We are redefining the development paradigm of the Internet in a componentized way. Welcome to follow us:

idoh : 极速安全的 DoH 解析库

idoh 是一个高性能、异步的 Rust 库，用于通过 HTTPS (DoH) 进行 DNS 解析。它专为速度和可靠性而设计，通过并发查询多个上游服务来确保最快的响应。

基于 idns。DnsRace、Cache、Parse trait 等更多功能请查看 idns。

功能特性

  • 并发解析：同时向多个 DoH 提供商（腾讯、Google、Cloudflare、DNS0 等）发起查询，返回最快的结果。
  • 简洁 API：直接返回 DNS 应答，无需复杂的提取回调。
  • MX 查询：专门优化的 MX 记录查询支持，自动按优先级排序。
  • 零拷贝缓存：可选的缓存支持，基于 expire_cache 和 GAT 技术实现零拷贝获取，性能极致。
  • 异步/Await：基于 tokio 构建，高效非阻塞。
  • 健壮的错误处理：优雅处理单个提供商的失败或超时。

使用指南

在 Cargo.toml 中添加：

[dependencies]
idoh = "0.1"
idns = "0.1"

基础解析

use idoh::resolve;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 解析 google.com 的 A 记录
    let answers = resolve("google.com", "A").await?;
    
    if let Some(answers) = answers {
        for answer in answers {
            println!("IP: {}", answer.data);
        }
    }
    Ok(())
}

TXT/SPF 记录查询

use idoh::resolve;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 解析 TXT 记录（例如 SPF 记录）
    let answers = resolve("qq.com", "TXT").await?;
    
    if let Some(answers) = answers {
        for answer in answers {
            if answer.data.starts_with("v=spf1") {
                println!("SPF: {}", answer.data);
            }
        }
    }
    Ok(())
}

MX 查询（基础）

启用 mx 特性：

[dependencies]
idoh = { version = "0.1", features = ["mx"] }

use idoh::{MxLookup, Resolve};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mx_records = Resolve.mx("gmail.com").await?;
    
    if let Some(records) = mx_records {
        for mx in records.iter() {
            println!("优先级: {}, 服务器: {}, TTL: {}秒", 
                     mx.priority, mx.server, mx.ttl);
        }
    }
    Ok(())
}

DnsRace + Cache（推荐）

使用 idns 竞速查询多个 DoH 服务器并缓存结果：

use idoh::{DOH_LI, doh_li};
use idns::{Cache, DnsRace, Mx, Query};
use std::time::Instant;

#[tokio::main]
async fn main() {
  let race = DnsRace::new(doh_li(DOH_LI));
  let cache: Cache<Mx> = Cache::new(60); // 60 秒 TTL

  // 首次查询（缓存未命中）
  let t1 = Instant::now();
  let r1 = cache.query(&race, "gmail.com").await;
  let d1 = t1.elapsed();
  println!("首次: {}ms", d1.as_millis());
  if let Some(mx_list) = &*r1.unwrap() {
    for mx in mx_list {
      println!("  {} {}", mx.priority, mx.server);
    }
  }

  // 再次查询（缓存命中）
  let t2 = Instant::now();
  let _ = cache.query(&race, "gmail.com").await;
  let d2 = t2.elapsed();
  println!("缓存: {}μs", d2.as_micros());
  println!("✓ {}ms -> {}μs (快 {} 倍)", d1.as_millis(), d2.as_micros(),
    d1.as_micros() / d2.as_micros().max(1));
}

输出：

首次: 744ms
  5 gmail-smtp-in.l.google.com
  10 alt1.gmail-smtp-in.l.google.com
  20 alt2.gmail-smtp-in.l.google.com
  30 alt3.gmail-smtp-in.l.google.com
  40 alt4.gmail-smtp-in.l.google.com
缓存: 1μs
✓ 744ms -> 1μs (快 744000 倍)

MX 查询与缓存

同时启用 mx 和 cache 特性：

[dependencies]
idoh = { version = "0.1", features = ["mx", "cache"] }

use idoh::mx::cache::Cache;
use idoh::MxLookup;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 首次调用：发起网络请求（冷缓存）
    // 耗时：约 744 毫秒
    let mx_records = Cache.mx("gmail.com").await?;
    
    if let Some(records) = mx_records {
        println!("首次调用 (网络): 找到 {} 条记录", records.len());
        for mx in records.iter() {
            println!("  优先级: {}, 服务器: {}", mx.priority, mx.server);
        }
    }
    
    // 第二次调用：内存直接获取（热缓存）
    // 耗时：约 1.8 微秒（零拷贝，快 40 万倍以上）
    let cached = Cache.mx("gmail.com").await?;
    
    if let Some(records) = cached {
        println!("第二次调用 (缓存): 找到 {} 条记录", records.len());
    }
    
    Ok(())
}

性能对比

操作 耗时 说明
网络查询 ~744 毫秒 取决于 DNS 提供商延迟
缓存查询 ~1.8 微秒 零拷贝，快 40 万倍以上

设计思路

idoh 的核心哲学是最小化延迟。它不是依赖单一的 DNS 服务器，而是并发地向预配置的高性能公共 DoH 提供商列表（包括腾讯云、阿里云、Google、Cloudflare 等）发送请求。它采用“赛跑”机制，只取最先返回的有效结果。这种方法有效地规避了网络抖动和单一服务商的偶发性卡顿。

流程图

graph TD
    A[用户调用 resolve] --> B{启动管理任务};
    B --> C[提供商 1];
    C -- 等待 500ms --> D[提供商 2];
    D -- 等待 500ms --> E[提供商 ...];
    C -- 查询 --> F[DoH 服务器 1];
    D -- 查询 --> G[DoH 服务器 2];
    E -- 查询 --> H[DoH 服务器 ...];
    F -- 响应 --> I{通道};
    G -- 响应 --> I;
    H -- 响应 --> I;
    I -- 首个成功 --> J[返回结果];
    J --> K[中止待处理任务];

技术栈

  • 运行时: tokio
  • HTTP 客户端: ireq (轻量级封装)
  • JSON 解析: sonic-rs (SIMD 加速)
  • 缓存: expire_cache + dashmap (线程安全，支持过期)
  • 并发: crossfire (高效通道)

目录结构

  • src/lib.rs: 模块导出和特性门控。
  • src/resolve.rs: 核心解析逻辑，实现了“赛跑”机制。
  • src/resolve_trait.rs: Resolver trait 定义。
  • src/mx.rs: MX 记录的具体实现及缓存逻辑。
  • src/post.rs: HTTP 请求处理和响应解析。
  • src/record_type.rs: DNS 记录类型常量。

架构

graph TD
    A[客户端] --> B[resolve 函数]
    B --> C[管理任务]
    C --> D[提供商 1]
    C --> E[提供商 2]
    C --> F[提供商 N]
    D --> G[DoH 服务器 1]
    E --> H[DoH 服务器 2]
    F --> I[DoH 服务器 N]
    G --> J[响应通道]
    H --> J
    I --> J
    J --> K[首个响应]
    K --> L[解析 JSON]
    L --> M[返回应答]
    M --> N[取消待处理]

实现细节

  • 并发竞速：多个提供商同时查询，采用交错超时（500ms 间隔）
  • 通道通信：使用 crossfire 通道进行高效的任务间通信
  • JSON 解析：利用 sonic-rs 进行 SIMD 加速的 JSON 解析
  • 错误恢复：单个提供商的失败不影响整体操作
  • 资源管理：首次成功响应后取消所有待处理请求
  • HTTP/2 支持：自动使用 HTTP/2 以获得更好性能
  • 超时处理：每个提供商默认 5 秒超时，可通过环境变量配置

API 参考

结构体

Answer

表示 DNS 应答记录。

pub struct Answer {
    pub name: String,
    pub r#type: u16,
    pub ttl: u32,
    pub data: String,
}

Mx

表示 MX 记录，包含优先级和服务器信息。

pub struct Mx {
    pub priority: u16,
    pub server: String,
    pub ttl: u32,
}

函数

resolve

执行并发 DoH 查询的核心函数。

pub async fn resolve(
  name: impl AsRef<str>,
  record_type: impl AsRef<str>,
) -> Result<Option<Vec<Answer>>>

返回 DNS 应答的向量。每个 Answer 包含：

  • name: 查询的域名
  • r#type: DNS 记录类型（数字）
  • ttl: 生存时间（秒）
  • data: 记录数据（IP 地址、主机名、文本等）

Traits

MxLookup

提供 mx 方法用于获取 MX 记录。

pub trait MxLookup {
  type VecMx<'a>: Deref<Target = [Mx]> + 'a
  where
    Self: 'a;
  fn mx<'a>(
    &'a self,
    domain: impl AsRef<str> + Send + 'a,
  ) -> impl std::future::Future<Output = Result<Option<Self::VecMx<'a>>>> + Send + 'a;
}

Resolver

DNS 解析实现的核心 trait。

pub trait Resolver {
  fn resolve<'a>(
    &'a self,
    domain: impl AsRef<str> + Send + 'a,
    record_type: impl AsRef<str> + Send + 'a,
  ) -> impl std::future::Future<Output = Result<Option<Vec<Answer>>>> + Send + 'a;
}

函数

  • doh_li(li: &[&str]) -> Vec<DoH> - 从 URL 列表创建 DoH 客户端

常量

DOH_LI

用于 idns 的预配置 DoH 提供商 URL：

pub const DOH_LI: &[&str] = &[
    "https://dns.google/dns-query",
    "https://cloudflare-dns.com/dns-query",
    "https://doh.pub/dns-query",
    "https://dns.alidns.com/dns-query",
    "https://zero.dns0.eu/",
];

DOH_PROVIDERS

预配置的 DoH 提供商：

提供商 URL
Google DNS https://dns.google/dns-query
Cloudflare https://cloudflare-dns.com/dns-query
腾讯 DNS https://doh.pub/dns-query
阿里 DNS https://dns.alidns.com/dns-query
DNS0 https://zero.dns0.eu/

历史：DoH 的崛起

域名系统 (DNS) 作为互联网的电话簿，设计于 1980 年代，当时并未考虑加密。几十年来，每一次网站访问都会在网络上明文暴露你的目的地。

2018 年，IETF 标准化了 DNS over HTTPS (DoH) (RFC 8484) 以填补这一隐私空白。通过将 DNS 查询封装在加密的 HTTPS 流量中，DoH 防止了窃听和篡改。Firefox 和 Chrome 等主流浏览器迅速采纳，引发了互联网隐私的革命。idoh 建立在这一遗产之上，为 Rust 生态系统提供了一种现代、快速且安全的域名解析方案。

关于

本项目为 js0.site ⋅ 重构互联网计划 的开源组件。

我们正在以组件化的方式重新定义互联网的开发范式，欢迎关注：

关于

本项目为 js0.site ⋅ 重构互联网计划 的开源组件。

我们正在以组件化的方式重新定义互联网的开发范式，欢迎关注：