# DNS Checker

`type: dns` 支持两种解析模式：本机解析器检查和指定 DNS server 协议级检查。

## resolver 模式

| 模式     | 说明                                                                          |
| -------- | ----------------------------------------------------------------------------- |
| `system` | 使用本机 DNS 解析器检查域名是否能解析到预期地址                               |
| `server` | 直接向指定 DNS server 发起 UDP/TCP 深度拨测，检查 RCODE、TTL、flags、记录值等 |

## `dns.resolver: system` 配置项

| 字段           | 说明                          | 必填 | 默认值   |
| -------------- | ----------------------------- | ---- | -------- |
| `dns.resolver` | 解析模式                      | 是   | `system` |
| `dns.name`     | 待解析域名                    | 是   | 无       |
| `dns.family`   | 地址族：`any`、`ipv4`、`ipv6` | 否   | `any`    |

### system 模式 expect

| 字段         | 说明                 | 断言模型                          |
| ------------ | -------------------- | --------------------------------- |
| `values`     | 解析结果地址集合断言 | DNS 集合（include/exclude/exact） |
| `valueCount` | 解析结果数量         | ValueMatcher                      |
| `durationMs` | 解析耗时             | ValueMatcher                      |

```yaml
- id: "dns-system-api"
  name: "本机 DNS 解析"
  type: dns
  dns:
    resolver: system
    name: "api.example.com"
    family: any
  expect:
    values:
      exact:
        - "203.0.113.10"
    durationMs:
      lte: 500
```

## `dns.resolver: server` 配置项

| 字段                   | 说明                              | 必填 | 默认值   |
| ---------------------- | --------------------------------- | ---- | -------- |
| `dns.resolver`         | 解析模式                          | 是   | `server` |
| `dns.server`           | DNS server 地址                   | 是   | 无       |
| `dns.name`             | 查询域名                          | 是   | 无       |
| `dns.port`             | DNS server 端口                   | 否   | `53`     |
| `dns.protocol`         | 传输协议：`udp`、`tcp`            | 否   | `udp`    |
| `dns.recordType`       | DNS 记录类型                      | 否   | `A`      |
| `dns.recursionDesired` | 是否设置 RD flag                  | 否   | `true`   |
| `dns.tcpFallback`      | UDP 响应 TC=1 时是否 TCP fallback | 否   | `true`   |
| `dns.maxResponseBytes` | 响应最大字节数                    | 否   | `4KB`    |

`recordType` 可选值：`A`、`AAAA`、`CNAME`、`NS`、`MX`、`TXT`、`SOA`、`SRV`、`CAA`、`PTR`。

### server 模式 expect

| 字段                 | 说明                               | 断言模型                          |
| -------------------- | ---------------------------------- | --------------------------------- |
| `responded`          | 是否收到 DNS response              | boolean                           |
| `rcode`              | 期望 RCODE 列表，如 `NOERROR`      | string[]                          |
| `values`             | 目标类型记录值集合断言             | DNS 集合（include/exclude/exact） |
| `valueCount`         | 目标类型记录数量                   | ValueMatcher                      |
| `answerCount`        | answer section 总记录数            | ValueMatcher                      |
| `ttlMin`             | answer 中最小 TTL                  | ValueMatcher                      |
| `ttlMax`             | answer 中最大 TTL                  | ValueMatcher                      |
| `authoritative`      | AA flag                            | boolean                           |
| `recursionAvailable` | RA flag                            | boolean                           |
| `truncated`          | TC flag                            | boolean                           |
| `authenticatedData`  | AD flag                            | boolean                           |
| `result`             | 完整结构化响应的 JSONPath 兜底断言 | ContentExpectations               |
| `durationMs`         | 完整查询耗时                       | ValueMatcher                      |

```yaml
- id: "dns-server-api"
  name: "Cloudflare DNS A 记录"
  type: dns
  dns:
    resolver: server
    server: "1.1.1.1"
    name: "api.example.com"
    recordType: A
  expect:
    rcode: ["NOERROR"]
    values:
      include:
        - "203.0.113.10"
    ttlMin:
      gte: 60
    durationMs:
      lte: 200
```

## 注意事项

- 未配置 expect 时，`system` 模式默认要求解析成功且 `valueCount > 0`，`server` 模式默认要求 `NOERROR + valueCount > 0`。
- 显式配置非 `NOERROR` rcode（如 `NXDOMAIN`）时，不自动要求 `valueCount > 0`。
- `values.exact` 忽略返回顺序。
- 对 A/AAAA 查询，CNAME 链不计入 `values`，单独放入 `cnameChain`。
- `values` 按记录类型规范化为字符串，例如 MX 为 `"10 mail.example.com"`，SRV 为 `"10 60 443 server.example.com"`。