DiAL/openspec/specs/probe-engine/spec.md

Purpose

定义拨测调度引擎的行为：按 interval 分组定时、组内并发拨测、expect 结果校验和结果持久化。

Requirements

Requirement: 按 interval 分组调度

系统 SHALL 将拨测目标按 interval 值分组，每组使用独立的定时器进行调度。

Scenario: 相同 interval 的目标共享定时器

• WHEN 多个 target 配置了相同的 interval（如 30s）
• THEN 系统 SHALL 使用同一个 setInterval 定时器，每次 tick 并发拨测所有该组目标

Scenario: 不同 interval 的目标各自调度

• WHEN target A 配置 15s interval，target B 配置 30s interval
• THEN 系统 SHALL 创建两个独立定时器，分别按各自频率调度

Requirement: 组内并发拨测

系统 SHALL 在每次调度 tick 时并发执行同组内目标的检查，但实际同时运行的检查数 MUST 受全局 runtime.maxConcurrentChecks 限制。当某个目标的 checker 执行 rejected（非正常 CheckResult 返回，而是 Promise reject）时，系统 SHALL 将该异常记录为 matched: false 的 check_result，而非仅 console.warn。

Scenario: 同组目标并发执行

• WHEN 调度器触发一次 tick，该组有 3 个目标，且全局并发余量至少为 3
• THEN 系统 SHALL 同时执行 3 个 checker，而非顺序执行

Scenario: 单个目标失败不影响同组其他目标

• WHEN 同组中某个目标的检查请求超时或失败（checker 正常返回 CheckResult）
• THEN 其他目标的检查 SHALL 正常完成并记录结果

Scenario: 同组中某个目标的 checker 执行 rejected

• WHEN 同组中某个目标的 checker 执行抛出未捕获异常（Promise rejected）
• THEN 系统 SHALL 为该目标写入一条 matched: false 的 check_result，failure 为 { kind: "error", phase: "internal", path: "engine", message: <rejected reason> }，其他目标的检查 SHALL 不受影响

Scenario: rejected 结果通过索引关联 targetName

• WHEN checker 执行 rejected
• THEN 系统 SHALL 通过 Promise.allSettled 的索引关联回 target 数组，获取对应的 targetName 用于写入 check_result

Scenario: 全局并发限制生效

• WHEN 调度器同时触发 10 个目标且 runtime.maxConcurrentChecks 为 3
• THEN 系统 MUST 同时最多运行 3 个检查，其余检查等待并发槽位释放

Requirement: HTTP 拨测执行

系统 SHALL 对 type: http 的目标执行 HTTP 请求，支持 GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS 方法，并携带 http.headers 和 http.body。系统 SHALL 支持 http.ignoreSSL 配置跳过 SSL 证书校验，支持 http.maxRedirects 配置控制重定向行为。HTTP response body 读取 SHALL 受 http.maxBodyBytes 流式限制，重定向跟随 SHALL 释放被跟随响应的 body。

Scenario: 执行 GET 请求

• WHEN 目标配置 method 为 GET
• THEN 系统 SHALL 发送 GET 请求到目标 URL

Scenario: 执行 POST 请求带 body

• WHEN 目标配置 method 为 POST 且指定了 body 和 Content-Type header
• THEN 系统 SHALL 发送带指定 body 的 POST 请求

Scenario: 携带自定义 headers

• WHEN 目标配置了 headers（如 Authorization）
• THEN 系统 SHALL 在请求中包含所有配置的 headers

Scenario: HTTP body 读取上限

• WHEN HTTP response body 超过该 target 的 maxBodyBytes
• THEN 系统 MUST 停止继续读取 response body，并记录 matched=false、failure.kind="error"、failure.phase="body" 的结构化输出超限错误

Scenario: HTTP body 大小等于上限

• WHEN HTTP response body 的字节数等于该 target 的 maxBodyBytes
• THEN 系统 SHALL 允许该 body 进入后续解码和 expect 校验

Scenario: HTTP body 上限为 0

• WHEN HTTP target 配置 maxBodyBytes 为 0 且响应体非空
• THEN 系统 SHALL 停止读取并记录 body 超限错误

Scenario: 忽略 SSL 证书校验

• WHEN 目标配置 http.ignoreSSL: true 且目标 URL 为 HTTPS
• THEN 系统 SHALL 跳过 SSL 证书校验，即使证书无效也正常完成请求

Scenario: 不忽略 SSL 证书校验

• WHEN 目标未配置 http.ignoreSSL 或配置为 false，且目标 URL 使用自签名证书
• THEN 系统 SHALL 因 SSL 证书校验失败而记录请求错误

Scenario: 默认不跟随重定向

• WHEN 目标未配置 http.maxRedirects 或配置为 0，且服务端返回 301/302
• THEN 系统 SHALL 不跟随重定向，直接返回 301/302 的响应状态码和响应头

Scenario: 配置跟随重定向

• WHEN 目标配置 http.maxRedirects: 5 且服务端返回重定向
• THEN 系统 SHALL 跟随重定向，最多跟随 5 次，并在跟随前释放当前重定向响应的 body

Scenario: 超过最大重定向次数

• WHEN 目标配置 http.maxRedirects: 1 且服务端连续返回两次重定向
• THEN 系统 SHALL 只跟随第一次重定向，并返回第二次重定向响应的状态码和响应头

Scenario: POST 重定向改 GET

• WHEN POST 请求遇到 301/302 或任意方法请求遇到 303，且系统决定按 GET 跟随重定向
• THEN 系统 SHALL 移除请求 body，并清理 content-type、content-length 等 body 相关 headers 后发起后续 GET 请求

Scenario: 跨 origin 重定向敏感 header

• WHEN HTTP 请求跟随重定向到不同 origin
• THEN 系统 SHALL NOT 将 authorization、cookie 等敏感 headers 转发到新的 origin

Scenario: 响应体编码自动检测

• WHEN HTTP 响应的 Content-Type header 包含 charset=gbk 或 charset="gbk"
• THEN 系统 SHALL 使用 GBK 编码解码响应体，而非硬编码 UTF-8

Scenario: 响应体编码回退 UTF-8

• WHEN HTTP 响应的 Content-Type header 未指定 charset
• THEN 系统 SHALL 使用 UTF-8 编码解码响应体

Scenario: 响应体编码不支持

• WHEN HTTP 响应的 Content-Type header 指定了当前运行时不支持的 charset
• THEN 系统 SHALL 记录 matched=false、failure.kind="error"、failure.phase="body" 的解码失败结果

Requirement: 请求超时控制

系统 SHALL 对每次 checker 执行实施超时控制，超时时间使用目标配置的 timeout 值。

Scenario: HTTP 请求超时

• WHEN HTTP 请求在 timeout 时间内未收到响应
• THEN 系统 SHALL 中止该请求，记录为失败并标注超时错误

Scenario: cmd 执行超时

• WHEN cmd 进程在 timeout 时间内未退出
• THEN 系统 MUST 终止该子进程，记录为失败并标注超时错误

Scenario: 请求在超时前完成

• WHEN checker 在超时前完成执行
• THEN 系统 SHALL 正常记录执行结果并进入 expect 校验

Requirement: expect 校验

系统 SHALL 在 checker 执行完成后根据目标类型的 expect 配置校验观测结果，校验结果和首个失败原因记入 check result。HTTP checker 的 durationMs SHALL 表示完整 checker 执行耗时，包括重定向、响应体读取、响应体解码和 expect 校验。

Scenario: HTTP 默认状态码

• WHEN HTTP target 未配置 expect.status
• THEN 系统 SHALL 按默认 status: [200] 校验响应状态码

Scenario: 校验 HTTP 状态码精确值

• WHEN HTTP target 配置了 expect.status: [200, 201]
• THEN 系统 SHALL 检查响应状态码是否在列表中，将匹配结果记录到 matched 字段

Scenario: 校验 HTTP 状态码范围模式

• WHEN HTTP target 配置了 expect.status: ["2xx"]
• THEN 系统 SHALL 检查响应状态码是否在 200-299 范围内

Scenario: 校验 HTTP 状态码混合模式

• WHEN HTTP target 配置了 expect.status: ["2xx", 301]，且响应状态码为 204
• THEN 系统 SHALL 判定状态码匹配（204 属于 2xx 范围）

Scenario: 校验 HTTP 响应头

• WHEN HTTP target 配置了 expect.headers: {"Content-Type": {contains: "application/json"}}
• THEN 系统 SHALL 检查响应头是否符合指定规则，全部匹配时继续后续阶段

Scenario: 校验 HTTP 响应体

• WHEN HTTP target 配置了有序 expect.body 规则数组
• THEN 系统 SHALL 按数组顺序执行 body 规则，任一失败立即记录 failure 并停止后续规则

Scenario: 校验 HTTP 完整耗时阈值

• WHEN 目标配置了 expect.maxDurationMs，且 HTTP checker 完整执行（含重定向、body 读取、解码和 expect）后的 durationMs 超过阈值
• THEN 系统 SHALL 判定 duration 不匹配，记录完整 durationMs 和 duration failure

Scenario: HTTP body 前耗时已超阈值

• WHEN HTTP target 配置了 body 校验和 expect.maxDurationMs，且进入 body 读取前的已耗时已超过阈值
• THEN 系统 SHALL 直接返回 duration failure，且 MUST NOT 读取 response body

Scenario: HTTP body 失败优先于后续 duration 检查

• WHEN HTTP target 配置了 body 校验和 expect.maxDurationMs，body 阶段存在失败，且完整执行后 duration 也超过阈值
• THEN 系统 SHALL 返回 body 阶段的失败（首个失败为准），durationMs SHALL 记录完整耗时

Scenario: HTTP 慢响应体计入耗时

• WHEN HTTP target 配置了 body 校验和 expect.maxDurationMs，且响应头很快返回但响应体读取导致完整执行耗时超过阈值
• THEN 系统 SHALL 判定 duration 不匹配并记录完整 durationMs

Scenario: 多条 expect 规则

• WHEN 目标同时配置状态、duration、元数据和内容规则
• THEN 系统 SHALL 所有规则全部通过时 matched 为 true，任一不通过则为 false 并记录首个失败原因

Scenario: cmd 默认 exitCode

• WHEN cmd target 未配置 expect.exitCode
• THEN 系统 SHALL 按默认 exitCode: [0] 校验命令退出码

Scenario: 校验 cmd stdout

• WHEN cmd target 配置了有序 expect.stdout 规则数组
• THEN 系统 SHALL 按数组顺序执行 stdout 规则，任一失败立即记录 failure 并停止后续规则

Requirement: Body 校验按需解析

系统 SHALL 仅在 HTTP target 配置了 body 校验，且 status、headers 阶段均通过，并且进入 body 前未确定 duration 已失败时才读取并解析响应体，避免不必要的读取和解析开销。HTTP target 未配置 body 校验时，系统 SHALL NOT 读取 response body。

Scenario: status 失败时不读取 body

• WHEN HTTP target 的 status 阶段不匹配
• THEN 系统 SHALL 立即返回 matched=false，且 MUST NOT 读取 response body

Scenario: headers 失败时不读取 body

• WHEN HTTP target 的 status 阶段匹配但 headers 阶段不匹配
• THEN 系统 SHALL 立即返回 matched=false，且 MUST NOT 读取 response body

Scenario: 进入 body 前 duration 已失败时不读取 body

• WHEN HTTP target 已配置 expect.maxDurationMs，且进入 body 读取前的已耗时已经超过阈值
• THEN 系统 SHALL 返回 duration failure，且 MUST NOT 读取 response body

Scenario: 仅配置 contains 时不解析 JSON

• WHEN HTTP target 仅配置 body contains 规则而未配置 json/css/xpath 规则
• THEN 系统 SHALL 不执行 JSON.parse 或 HTML/XML 解析

Scenario: 配置 json 时解析 JSON 失败

• WHEN HTTP target 配置了 body json 规则但响应体不是合法 JSON
• THEN 系统 SHALL 判定 matched 为 false，并记录 json 规则对应的 failure.path

Requirement: HTTP 运行期错误归属

HTTP checker SHALL 将运行期失败归属到实际失败阶段。请求、网络、TLS 和 timeout 错误 SHALL 记录为 request 阶段错误；body 超限、响应体解码失败、响应内容解析失败 SHALL 记录为 body 阶段错误；expect 不匹配 SHALL 记录为对应 mismatch 阶段。

Scenario: 请求错误归属 request

• WHEN HTTP 请求因为网络、TLS 或 timeout 失败
• THEN 系统 SHALL 记录 matched=false、failure.kind="error"、failure.phase="request"

Scenario: body 超限归属 body

• WHEN HTTP response body 超过 maxBodyBytes
• THEN 系统 SHALL 记录 failure.kind="error"、failure.phase="body"、failure.path="body"

Scenario: body 解析错误归属 body

• WHEN HTTP response body 已读取，但解码、JSON 解析、CSS 解析或 XPath 解析失败
• THEN 系统 SHALL 记录 failure.phase="body"，且 SHALL NOT 将该失败记录为 request 错误

Requirement: 拨测结果记录

系统 SHALL 在每次 checker 完成后，将结果写入 SQLite 数据存储，包含 target_id、timestamp、matched、duration_ms、observation、failure 字段。detail SHALL 为 API 层派生字段，不写入存储层；系统 SHALL NOT 写入 status_detail 字段。

Scenario: 成功检查结果记录

• WHEN checker 成功执行且 expect 全部匹配
• THEN 系统 SHALL 记录 matched=true、duration_ms、observation，failure 为 null

Scenario: 执行失败结果记录

• WHEN checker 执行失败（网络错误、超时、命令启动失败、输出超限等）
• THEN 系统 SHALL 记录 matched=false、failure.kind="error" 和具体错误信息，并在可收集领域观测数据时记录 observation

Scenario: expect 不匹配结果记录

• WHEN checker 执行成功但 expect 不匹配
• THEN 系统 SHALL 记录 matched=false、observation、failure.kind="mismatch" 和具体不匹配信息

Requirement: runner 选择

系统 SHALL 根据 target.type 选择对应 runner 执行检查。

Scenario: 选择 HTTP runner

• WHEN target.type 为 http
• THEN 系统 SHALL 使用 HTTP runner 执行该目标

Scenario: 选择 cmd runner

• WHEN target.type 为 cmd
• THEN 系统 SHALL 使用 cmd runner 执行该目标

Requirement: 定期数据清理

ProbeEngine SHALL 在启动时注册数据清理定时器，定期调用 ProbeStore.prune() 清理过期数据。

Scenario: 引擎启动注册清理

• WHEN ProbeEngine.start() 被调用且 retentionMs > 0
• THEN 系统 SHALL 立即执行一次 prune，然后每隔 1 小时再次执行

Scenario: 引擎停止清除定时器

• WHEN ProbeEngine.stop() 被调用
• THEN 系统 SHALL 清除清理定时器，不再执行后续清理

Scenario: retentionMs 为 0 不注册清理

• WHEN ProbeEngine 构造时 retentionMs 为 0
• THEN 系统 SHALL 不注册清理定时器