lanyuanxiaoyao/DiAL
1
0
Fork 0
Code Activity
Files
393e8da5fd24448ea49c9f934608e64964fb45bf
DiAL/openspec/changes/add-icmp-checker/specs/probe-config/spec.md
lanyuanxiaoyao 393e8da5fd feat: 新增 ICMP/Ping checker 设计提案 
- 定义 ping target 配置：host、count、packetSize
- 定义 ping expect 断言：alive、maxPacketLoss、maxAvgLatencyMs、maxMaxLatencyMs
- 设计跨平台 ping 输出解析器（Linux/macOS/Windows 含多语言支持）
- 双重超时保障：ping 命令自身超时 + AbortSignal 兜底
- 扩展 checker-runner-abstraction spec 支持 ping checker 子进程控制
- 更新 probe-config spec 支持 ping type 配置
2026-05-18 00:33:11 +08:00

4.6 KiB
Raw Blame History

MODIFIED Requirements

Requirement: YAML 配置文件格式

系统 SHALL 支持通过 YAML 配置文件定义全部运行参数，包括 server 配置、runtime 配置、可选的 variables 段、checker 默认值和 typed target 列表（含可选 group 字段）。target MUST 使用 id 字段作为唯一标识符，MUST 使用 type 字段声明 checker 类型，SHALL 支持可选的 name 字段作为展示名称元信息，SHALL 支持可选的 description 字段作为目标说明。name 和 description 均 SHALL 允许省略或显式配置为 null；省略或显式 null 时解析结果 SHALL 保留为 null。HTTP 领域字段 MUST 放在 http 分组，cmd 领域字段 MUST 放在 cmd 分组，db 领域字段 MUST 放在 db 分组，tcp 领域字段 MUST 放在 tcp 分组，ping 领域字段 MUST 放在 ping 分组。HTTP target 的 http 分组 SHALL 支持可选的 ignoreSSL（布尔值）和 maxRedirects（非负整数）字段。Db target 的 db 分组 SHALL 支持 url（必填）和 query（可选）字段。Tcp target 的 tcp 分组 SHALL 支持 host（必填）、port（必填）、readBanner（可选）、bannerReadTimeout（可选）和 maxBannerBytes（可选）字段。Ping target 的 ping 分组 SHALL 支持 host（必填）、count（可选，默认 3）和 packetSize（可选，默认 56）字段。

defaults.http 分组 SHALL 仅支持 headers（可选）和 maxBodyBytes（可选）字段。defaults.http 分组 MUST NOT 支持 method 字段。defaults.tcp 分组 SHALL 仅支持 bannerReadTimeout（可选）和 maxBannerBytes（可选）字段。

Scenario: 最简 ping 配置文件解析

  • WHEN 系统读取只包含一个 type: ping target（含 id 和 ping.host）的 YAML 配置文件
  • THEN 系统 SHALL 使用内置默认值填充未指定的字段（interval=30s, timeout=10s, group="default", ping.count=3, ping.packetSize=56），并保留 name=null、description=null

Requirement: 配置校验

系统 SHALL 在启动时对 YAML 配置进行完整校验，校验失败时以非零状态退出并输出清晰的错误信息。系统 SHALL 使用 TypeBox 定义配置契约和 raw config TypeScript 类型，由 Ajv 校验 TypeBox 生成的 JSON Schema，再执行启动期语义 validator。配置加载流程 SHALL 明确区分 RawProbeConfig、ValidatedProbeConfig、ResolvedConfig 三段生命周期，并在 YAML 解析之后、AJV 校验之前执行变量替换阶段。JSON Schema 契约 SHALL 覆盖业务无关的结构规则，包括字段类型、必填字段、枚举、数组与对象形状、数值范围和未知字段。语义 validator SHALL 覆盖契约不适合表达的业务规则，包括 target id 唯一性、id 命名规则校验、checker type 注册状态、时长和大小解析、HTTP URL、正则可编译、JSONPath 子集和 XPath 可编译。

契约校验和语义 validator SHALL 统一产出 ConfigValidationIssue，最终由配置加载流程统一渲染为中文错误信息。

系统 SHALL 导出完整 probe-config.schema.json，该文件 SHALL 与运行期 TypeBox fragments 生成的 JSON Schema 保持一致，用于用户配置引用和编辑器提示。

除 headers、env、variables 等明确声明为动态键值表的对象外，配置中的未知字段 SHALL 导致启动期配置错误。系统 MUST NOT 静默忽略未知字段。

Scenario: ping target 缺少 host

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

Scenario: ping expect 未知字段

  • WHEN YAML 中 ping target 的 expect 包含非 ping expect 字段
  • THEN 系统 SHALL 以配置错误退出，提示 expect 包含未知字段

Requirement: expect 配置增强

系统 SHALL 支持 typed target 的领域专用 expect 配置，包括 HTTP 的 status（支持精确数字和范围模式）、headers、body，cmd 的 exitCode、stdout、stderr，tcp 的 connected、banner，以及 ping 的 alive、maxPacketLoss、maxAvgLatencyMs、maxMaxLatencyMs。内容类 expect MUST 使用数组表达配置顺序。

Scenario: 解析 ping expect 配置

  • WHEN YAML 配置文件中 ping target 的 expect 包含 alive、maxPacketLoss、maxAvgLatencyMs、maxMaxLatencyMs 和 maxDurationMs
  • THEN 系统 SHALL 正确解析并存储为 ping target 的 expect 字段

Scenario: 不配置 ping expect

  • WHEN ping target 未配置任何 expect 规则
  • THEN 系统 SHALL 正常处理，expect 字段为 undefined，执行时使用默认 alive=true 语义
View Git Blame Copy Permalink