83 lines
4.5 KiB
Markdown
83 lines
4.5 KiB
Markdown
## Purpose
|
||
|
||
定义 Command 类型拨测目标：通过 `type: command` 配置执行本地命令（如进程检查、脚本健康检测），捕获 exit code、stdout、stderr，按 expect 规则校验并生成 matched 判定。
|
||
|
||
## Requirements
|
||
|
||
### Requirement: command target 配置
|
||
系统 SHALL 支持 `type: command` 的 target 配置，通过 `command.exec` 和 `command.args` 描述本地命令，并使用 command 专用字段配置工作目录、环境变量和输出限制。
|
||
|
||
#### Scenario: 解析 command target
|
||
- **WHEN** YAML 中 target 配置 `type: command`、`command.exec: "pgrep"` 和 `command.args: ["nginx"]`
|
||
- **THEN** 系统 SHALL 将其解析为 command checker，并保留 exec、args、cwd、env、maxOutputBytes、interval、timeout 和 expect 配置
|
||
|
||
#### Scenario: command target 缺少 exec
|
||
- **WHEN** YAML 中 target 配置 `type: command` 但缺少 `command.exec`
|
||
- **THEN** 系统 SHALL 以配置错误退出，并提示该 target 缺少 command.exec 字段
|
||
|
||
#### Scenario: cwd 相对配置文件目录解析
|
||
- **WHEN** command target 配置 `command.cwd: "scripts"` 且配置文件位于 `/opt/checker/probes.yaml`
|
||
- **THEN** 系统 SHALL 将 cwd 解析为 `/opt/checker/scripts`
|
||
|
||
#### Scenario: command 不使用 shell
|
||
- **WHEN** command target 配置 `exec` 和 `args`
|
||
- **THEN** 系统 MUST 直接执行该程序和参数，不通过 shell 解释整段命令字符串
|
||
|
||
#### Scenario: env 默认继承并允许覆盖
|
||
- **WHEN** command target 配置 `command.env: {LANG: "C"}` 且当前进程环境包含 `PATH`
|
||
- **THEN** 系统 SHALL 继承当前进程的全部环境变量，并将 `LANG` 覆盖为 `"C"`
|
||
|
||
#### Scenario: 不支持 stdin
|
||
- **WHEN** command target 配置并执行命令
|
||
- **THEN** 系统 MUST NOT 向子进程 stdin 写入数据，避免命令因等待输入而阻塞
|
||
|
||
### Requirement: command checker 执行
|
||
系统 SHALL 按 command target 配置执行本地命令，记录执行耗时、退出码、stdout 和 stderr，并在执行失败时产生结构化错误信息。
|
||
|
||
#### Scenario: 命令正常退出
|
||
- **WHEN** command target 执行的进程正常退出且 exit code 为 0
|
||
- **THEN** 系统 SHALL 记录 `durationMs`、`statusDetail="exitCode=0"`，并进入 expect 校验
|
||
|
||
#### Scenario: 命令非零退出
|
||
- **WHEN** command target 执行的进程正常退出但 exit code 为 1
|
||
- **THEN** 系统 SHALL 记录 `statusDetail="exitCode=1"`，并由 expect.exitCode 决定 matched 结果
|
||
|
||
#### Scenario: 命令启动失败
|
||
- **WHEN** command target 的 exec 不存在或无法启动
|
||
- **THEN** 系统 SHALL 记录 `matched=false`，并在 failure 中写入 kind=`error` 和可读错误信息
|
||
|
||
#### Scenario: 命令超时
|
||
- **WHEN** command target 在 timeout 时间内未结束
|
||
- **THEN** 系统 MUST 终止该子进程，记录 `matched=false`，并在 failure 中写入命令超时信息
|
||
|
||
#### Scenario: 命令输出超限
|
||
- **WHEN** command target 的 stdout 和 stderr 合计输出超过 `maxOutputBytes`
|
||
- **THEN** 系统 MUST 停止收集输出并终止该检查，记录 `matched=false`，并在 failure 中写入输出超限信息
|
||
|
||
### Requirement: command expect 校验
|
||
系统 SHALL 支持 command 专用 expect，包括 `exitCode`、`stdout` 和 `stderr`，并按 exitCode、duration、stdout、stderr 的阶段顺序快速失败。
|
||
|
||
#### Scenario: 默认 exitCode 成功语义
|
||
- **WHEN** command target 未显式配置 `expect.exitCode`
|
||
- **THEN** 系统 SHALL 使用默认 `expect.exitCode: [0]` 进行校验
|
||
|
||
#### Scenario: 显式 exitCode 校验
|
||
- **WHEN** command target 配置 `expect.exitCode: [0, 2]` 且实际 exit code 为 2
|
||
- **THEN** 系统 SHALL 判定 exitCode 阶段通过，并继续后续 expect 阶段
|
||
|
||
#### Scenario: exitCode 不匹配快速失败
|
||
- **WHEN** command target 配置 `expect.exitCode: [0]` 且实际 exit code 为 1
|
||
- **THEN** 系统 SHALL 立即返回 `matched=false`，并在 failure 中写入 phase=`exitCode`、path=`expect.exitCode`、expected 和 actual
|
||
|
||
#### Scenario: stdout 按配置顺序校验
|
||
- **WHEN** command target 配置 `expect.stdout` 为两个规则，第一条通过且第二条失败
|
||
- **THEN** 系统 SHALL 先执行第一条 stdout 规则，再执行第二条，并将 failure.path 指向失败的 `expect.stdout[1]`
|
||
|
||
#### Scenario: stderr 校验为空
|
||
- **WHEN** command target 配置 `expect.stderr: [{empty: true}]` 且实际 stderr 为空字符串
|
||
- **THEN** 系统 SHALL 判定 stderr 阶段通过
|
||
|
||
#### Scenario: stdout 失败后不检查 stderr
|
||
- **WHEN** command target 同时配置 stdout 和 stderr 规则，且 stdout 规则失败
|
||
- **THEN** 系统 SHALL 快速失败并 MUST NOT 继续执行 stderr 规则
|