idoh 0.2.3

[English](#en) | [中文](#zh)

---

<a id="en"></a>

# 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](https://crates.io/crates/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`:

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

### Basic Resolution

```rust
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

```rust
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:
```toml
[dependencies]
idoh = { version = "0.1", features = ["mx"] }
```

```rust
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:

```rust
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:
```toml
[dependencies]
idoh = { version = "0.1", features = ["mx", "cache"] }
```

```rust
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

```mermaid
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

```mermaid
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.

```rust
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.

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

### Functions

#### `resolve`

The core function that performs the concurrent DoH lookup.

```rust
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.

```rust
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.

```rust
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:

```rust
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](https://js0.site).

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

* [Google Group](https://groups.google.com/g/js0-site)
* [js0site.bsky.social](https://bsky.app/profile/js0site.bsky.social)

---

## About

This project is an open-source component of [js0.site ⋅ Refactoring the Internet Plan](https://js0.site).

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

* [Google Group](https://groups.google.com/g/js0-site)
* [js0site.bsky.social](https://bsky.app/profile/js0site.bsky.social)

---

<a id="zh"></a>

# idoh : 极速安全的 DoH 解析库

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

基于 [idns](https://crates.io/crates/idns)。`DnsRace`、`Cache`、`Parse` trait 等更多功能请查看 idns。

## 功能特性

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

## 使用指南

在 `Cargo.toml` 中添加：

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

### 基础解析

```rust
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 记录查询

```rust
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` 特性：
```toml
[dependencies]
idoh = { version = "0.1", features = ["mx"] }
```

```rust
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 服务器并缓存结果：

```rust
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` 特性：
```toml
[dependencies]
idoh = { version = "0.1", features = ["mx", "cache"] }
```

```rust
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 等）发送请求。它采用“赛跑”机制，只取最先返回的有效结果。这种方法有效地规避了网络抖动和单一服务商的偶发性卡顿。

### 流程图

```mermaid
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 记录类型常量。

## 架构

```mermaid
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 应答记录。

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

#### `Mx`

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

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

### 函数

#### `resolve`

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

```rust
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 记录。

```rust
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。

```rust
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：

```rust
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 ⋅ 重构互联网计划](https://js0.site) 的开源组件。

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

* [谷歌邮件列表](https://groups.google.com/g/js0-site)
* [js0site.bsky.social](https://bsky.app/profile/js0site.bsky.social)

---

## 关于

本项目为 [js0.site ⋅ 重构互联网计划](https://js0.site) 的开源组件。

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

* [谷歌邮件列表](https://groups.google.com/g/js0-site)
* [js0site.bsky.social](https://bsky.app/profile/js0site.bsky.social)