DiAL/openspec/specs/udp-checker/spec.md at 22c06820fa8e27eedb43902cb390ea90ac23fb02

Files

lanyuanxiaoyao 7a635a0a9f refactor: 统一 expect 断言体系，引入共享 ValueMatcher/ContentRules/KeyValueExpect 模型

- 引入共享 ValueMatcher（equals/contains/regex/exists/empty/gt/gte/lt/lte）
- 引入共享 ContentRules 数组（direct/json/css/xpath 提取器）
- 引入共享 KeyValueExpect（动态键值断言，字面量等价 equals）
- maxDurationMs → durationMs: ValueMatcher（所有 checker）
- match → regex（固定无 flags）
- Ping max* → packetLossPercent/avgLatencyMs/maxLatencyMs（ValueMatcher）
- LLM finishReason/rawFinishReason → ValueMatcher
- DB 新增 result: ContentRules
- TCP banner → ContentRules 数组
- 删除旧模块：operator.ts、validate-operator.ts、duration.ts、body.ts、text.ts、output.ts
- 更新全部 checker schema/validate/expect/execute
- 更新 probe-config.schema.json、probes.example.yaml
- 更新 README.md、DEVELOPMENT.md（含 expect 字段选择规范）
- 同步 10 个 delta specs 到主 specs，归档 change

2026-05-19 14:24:27 +08:00

12 KiB

Raw Blame History

Purpose

定义 UDP checker 的 target 配置、defaults、执行语义、响应编码、expect 校验、失败结构和状态摘要。

Requirements

Requirement: udp target 配置

系统 SHALL 支持 type: udp 的 target 配置，通过 udp.host 和 udp.port 描述目标 UDP 地址，并通过可选字段控制 payload、编码和响应大小限制。

Scenario: 解析最简 udp target

WHEN YAML 中 target 配置 type: udp、udp.host: "127.0.0.1" 和 udp.port: 9000
THEN 系统 SHALL 将其解析为 udp checker，并填充 payload=""、encoding="text"、responseEncoding="text"、maxResponseBytes=4096、interval、timeout、group 和 expect 配置

Scenario: udp target 缺少 host

WHEN YAML 中 target 配置 type: udp 但缺少 udp.host
THEN 系统 SHALL 以配置错误退出，并提示该 target 缺少 udp.host 字段

Scenario: udp target 缺少 port

WHEN YAML 中 target 配置 type: udp 但缺少 udp.port
THEN 系统 SHALL 以配置错误退出，并提示该 target 缺少 udp.port 字段

Scenario: udp port 范围非法

WHEN YAML 中 udp target 的 udp.port 不是 1 到 65535 之间的整数
THEN 系统 SHALL 以配置错误退出，并提示 udp.port 必须为合法 UDP 端口

Scenario: 省略 payload 发送空 datagram

WHEN YAML 中 udp target 未配置 udp.payload
THEN 系统 SHALL 使用空字符串作为 payload，并在执行时发送零长度 UDP datagram

Scenario: udp defaults 覆盖通用 UDP 参数

WHEN YAML 中配置 defaults.udp.encoding: "hex"、defaults.udp.responseEncoding: "hex" 和 defaults.udp.maxResponseBytes: "8KB"
THEN 未显式配置对应字段的 udp target SHALL 使用 defaults.udp 中的值

Scenario: per-target UDP 参数覆盖 defaults

WHEN defaults.udp 配置了 encoding、responseEncoding 或 maxResponseBytes，且某个 udp target 显式配置对应字段
THEN 该 target SHALL 使用自身 udp 分组中的值

Scenario: udp 分组未知字段失败

WHEN YAML 中 udp target 的 udp 分组包含 dnsQuery、expectResponse 或其他未知字段
THEN 系统 SHALL 以配置错误退出，提示 udp 分组包含未知字段

Scenario: udp 序列化展示摘要

WHEN 系统同步 udp target 到 targets 表
THEN target 展示摘要 SHALL 为 udp <host>:<port>，config JSON SHALL 包含 resolved 后的 host、port、payload、encoding、responseEncoding 和 maxResponseBytes

Requirement: udp payload 编码

系统 SHALL 支持将 udp.payload 按 udp.encoding 解码为发送字节，编码类型限定为 text、hex 和 base64。

Scenario: text payload 编码

WHEN udp target 配置 udp.payload: "PING" 且 udp.encoding 未配置或为 text
THEN 系统 SHALL 以 UTF-8 字节发送 PING

Scenario: hex payload 编码

WHEN udp target 配置 udp.payload: "50494e47" 和 udp.encoding: "hex"
THEN 系统 SHALL 解码 hex 后发送字节内容 PING

Scenario: base64 payload 编码

WHEN udp target 配置 udp.payload: "UElORw==" 和 udp.encoding: "base64"
THEN 系统 SHALL 解码 base64 后发送字节内容 PING

Scenario: 非法 encoding 失败

WHEN YAML 中 udp target 配置 udp.encoding: "json"
THEN 系统 SHALL 以配置错误退出，提示 udp.encoding 必须为 text、hex 或 base64

Scenario: 非法 responseEncoding 失败

WHEN YAML 中 udp target 配置 udp.responseEncoding: "json"
THEN 系统 SHALL 以配置错误退出，提示 udp.responseEncoding 必须为 text、hex 或 base64

Scenario: 非法 hex payload 失败

WHEN YAML 中 udp target 配置 udp.encoding: "hex" 但 udp.payload 不是合法 hex 字符串
THEN 系统 SHALL 以配置错误退出，提示 udp.payload 与 udp.encoding 不匹配

Scenario: 非法 base64 payload 失败

WHEN YAML 中 udp target 配置 udp.encoding: "base64" 但 udp.payload 不是合法 base64 字符串
THEN 系统 SHALL 以配置错误退出，提示 udp.payload 与 udp.encoding 不匹配

Requirement: udp checker 执行

系统 SHALL 使用 Bun connected UDP socket 向目标发送单个 datagram，等待第一个 UDP 响应 datagram，记录完整执行耗时，并在发送失败、超时、资源超限或底层 socket 错误时产生结构化失败信息。

Scenario: UDP 请求响应成功

WHEN udp target 指向会返回 PONG 的 UDP 服务，且未配置 expect 或 expect.responded 为 true
THEN 系统 SHALL 记录 matched=true、durationMs 和包含响应大小的 statusDetail，并关闭 socket

Scenario: 使用 hostname 执行 UDP 探测

WHEN udp target 的 udp.host 为可解析域名或 localhost
THEN 系统 SHALL 使用 Bun connected UDP socket 完成发送和接收，不要求配置 IP 地址

Scenario: 只处理第一个响应 datagram

WHEN UDP 服务对一次请求返回多个 datagram
THEN 系统 SHALL 仅使用第一个收到的 UDP datagram 执行 expect 校验，并关闭 socket

Scenario: UDP 无响应且默认期望响应

WHEN udp target 指向在 timeout 内不返回 UDP datagram 的服务，且未配置 expect 或 expect.responded 为 true
THEN 系统 SHALL 在 ctx.signal abort 后记录 matched=false，failure 的 kind 为 error，phase 为 response，message 包含超时或未响应信息

Scenario: 期望无响应且实际无响应

WHEN udp target 配置 expect.responded: false，且 timeout 内未收到 UDP datagram
THEN 系统 SHALL 记录 matched=true，statusDetail SHALL 表示未收到响应

Scenario: 期望无响应但实际收到响应

WHEN udp target 配置 expect.responded: false，但收到了 UDP datagram
THEN 系统 SHALL 记录 matched=false，failure 的 kind 为 mismatch，phase 为 responded

Scenario: UDP socket 底层错误

WHEN Bun UDP socket 在发送或接收过程中触发 error 事件
THEN 系统 SHALL best-effort 关闭 socket，并记录 matched=false、failure.kind=error 和可读错误信息

Scenario: ICMP unreachable 不作为 UDP 响应

WHEN 底层系统因目标端口不可达产生 ICMP unreachable
THEN 系统 SHALL NOT 将其视为 responded=true 的 UDP datagram 响应

Scenario: UDP 执行超时关闭 socket

WHEN 引擎注入的 ctx.signal 在 UDP 发送或等待响应过程中 abort
THEN 系统 SHALL best-effort 关闭 UDP socket，并记录结构化超时或未响应结果

Requirement: udp 响应大小限制

系统 SHALL 使用 udp.maxResponseBytes 限制单个 UDP 响应 datagram 的可处理字节数，默认值为 4096，支持数字或 size string。

Scenario: 响应大小未超过限制

WHEN udp target 配置 udp.maxResponseBytes: 4096，且实际响应为 16 字节
THEN 系统 SHALL 允许后续 expect 校验继续执行

Scenario: 响应大小超过限制

WHEN udp target 配置 udp.maxResponseBytes: 4，且实际响应为 16 字节
THEN 系统 SHALL 返回 matched=false，failure 的 kind 为 error，phase 为 response，message 包含响应超过大小限制的信息

Scenario: Bun 标记 datagram 被截断

WHEN Bun UDP data 回调中的 flags.truncated 为 true
THEN 系统 SHALL 返回 matched=false，failure 的 kind 为 error，phase 为 response，message 包含响应被截断的信息

Scenario: maxResponseBytes 格式非法

WHEN YAML 中 udp target 或 defaults.udp 的 maxResponseBytes 不是非负整数或合法 size string
THEN 系统 SHALL 以配置错误退出，提示 maxResponseBytes 格式错误

Requirement: udp expect 校验

系统 SHALL 支持 udp 专属 expect，包括 responded、response、responseSize、sourceHost、sourcePort 和 durationMs，并按 responded、responseSize、response、sourceHost、sourcePort、durationMs 的阶段顺序快速失败。responded SHALL 保持布尔状态语义，未配置时默认 true。response MUST 使用共享 ContentRules 数组，并作用于按 udp.responseEncoding 转换后的响应文本。responseSize、sourceHost、sourcePort 和 durationMs SHALL 使用共享 ValueMatcher。

Scenario: 默认 responded 成功语义

WHEN udp target 未显式配置 expect.responded
THEN 系统 SHALL 使用默认 expect.responded: true 进行校验

Scenario: response ContentRules 校验通过

WHEN udp target 配置 expect.response: [{ contains: "PONG" }]，且按 responseEncoding 转换后的响应文本包含 PONG
THEN 系统 SHALL 判定 response 阶段通过

Scenario: response JSON 校验通过

WHEN udp target 收到文本响应 {"status":"ok"} 且配置 expect.response: [{json: {path: "$.status", equals: "ok"}}]
THEN 系统 SHALL 判定 response 阶段通过

Scenario: response ContentRules 校验失败

WHEN udp target 配置 expect.response: [{ contains: "PONG" }]，但按 responseEncoding 转换后的响应文本不包含 PONG
THEN 系统 SHALL 返回 matched=false，failure 的 kind 为 mismatch，phase 为 response，path 指向失败的 response 规则

Scenario: responseEncoding 为 hex

WHEN udp target 配置 udp.responseEncoding: "hex" 且收到字节内容 PONG
THEN 系统 SHALL 将响应转换为小写 hex 字符串 504f4e47 后执行 expect.response 规则

Scenario: responseSize matcher 校验通过

WHEN udp target 配置 expect.responseSize: { gte: 4 }，且实际响应为 4 字节
THEN 系统 SHALL 判定 responseSize 阶段通过

Scenario: responseSize matcher 校验失败

WHEN udp target 配置 expect.responseSize: { gte: 4 }，但实际响应为 2 字节
THEN 系统 SHALL 返回 matched=false，failure 的 kind 为 mismatch，phase 为 responseSize

Scenario: sourceHost matcher 校验

WHEN udp target 配置 expect.sourceHost: { equals: "127.0.0.1" }，且 Bun 回调中的来源地址为 127.0.0.1
THEN 系统 SHALL 判定 sourceHost 阶段通过

Scenario: sourcePort matcher 校验

WHEN udp target 配置 expect.sourcePort: { equals: 9000 }，且 Bun 回调中的来源端口为 9000
THEN 系统 SHALL 判定 sourcePort 阶段通过

Scenario: durationMs 校验

WHEN udp target 配置 expect.durationMs: {lte: 100}，且完整执行耗时超过 100ms
THEN 系统 SHALL 返回 matched=false，failure 的 phase 为 duration

Scenario: response 断言要求实际有响应

WHEN udp target 配置了 expect.response 或 expect.responseSize，但同时配置 expect.responded: false
THEN 系统 SHALL 在启动期配置校验失败，提示响应内容或大小断言需要 expect.responded 为 true

Scenario: source 断言要求实际有响应

WHEN udp target 配置了 expect.sourceHost 或 expect.sourcePort，但同时配置 expect.responded: false
THEN 系统 SHALL 在启动期配置校验失败，提示响应来源断言需要 expect.responded 为 true

Scenario: udp expect 未知字段失败

WHEN YAML 中 udp target 的 expect 包含 status: [200]、maxDurationMs: 1000 或其他非 udp expect 字段
THEN 系统 SHALL 以配置错误退出，提示 expect 包含未知字段

Requirement: udp statusDetail 摘要

系统 SHALL 在 udp 执行后生成简短 statusDetail 摘要，展示关键结果并避免写入过长响应内容。

Scenario: 收到响应的摘要

WHEN udp target 收到 4 字节响应且完整执行耗时为 12ms
THEN statusDetail SHALL 包含 responded in 12ms 和 4 bytes

Scenario: 未收到响应的摘要

WHEN udp target 配置 expect.responded: false 且 timeout 内未收到 UDP datagram
THEN statusDetail SHALL 包含 no response 和执行耗时

Scenario: 响应内容摘要截断

WHEN udp target 收到较长响应内容
THEN statusDetail SHALL 只展示按 responseEncoding 转换并截断后的响应摘要

12 KiB Raw Blame History Unescape Escape