lanyuanxiaoyao
393e8da5fd
- 定义 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 配置
39 lines
4.6 KiB
Markdown
39 lines
4.6 KiB
Markdown
## 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 语义
|