DiAL/openspec/changes/checker-observation/specs/tcp-checker/spec.md

MODIFIED Requirements

Requirement: tcp checker 执行

系统 SHALL 按 tcp target 配置建立 TCP 连接，记录完整执行耗时和 TCP observation，并在连接失败、超时或资源超限时产生结构化失败信息。

Scenario: TCP 连接成功

• WHEN tcp target 指向可连接的 TCP 服务，且未配置 expect 或 expect.connected 为 true
• THEN 系统 SHALL 记录 matched=true、durationMs 和包含 connected、connectTimeMs、banner 的 observation，并关闭 socket

Scenario: TCP 连接失败

• WHEN tcp target 指向不可连接的 host/port，且未配置 expect 或 expect.connected 为 true
• THEN 系统 SHALL 记录 matched=false，observation SHALL 包含 connected=false 和错误信息，failure 的 kind 为 error，phase 为 connect，message 包含可读连接失败原因

Scenario: 期望端口不可达且连接失败

• WHEN tcp target 配置 expect.connected: false，且 TCP 连接失败
• THEN 系统 SHALL 记录 matched=true，observation SHALL 包含 connected=false 和实际连接失败原因，API detail SHALL 展示实际连接失败原因摘要

Scenario: 期望端口不可达但连接成功

• WHEN tcp target 配置 expect.connected: false，但 TCP 连接成功
• THEN 系统 SHALL 记录 matched=false，observation SHALL 包含 connected=true，failure 的 kind 为 mismatch，phase 为 connected

Scenario: TCP 执行超时

• WHEN 引擎注入的 ctx.signal 在 TCP 连接或 banner 读取过程中 abort
• THEN 系统 SHALL best-effort 关闭 socket，记录 matched=false，failure 的 kind 为 error，phase 为 connect 或 banner，message 包含超时信息，并在可收集时记录 observation

Scenario: duration 包含 banner 读取

• WHEN tcp target 开启 readBanner 且服务端延迟发送 banner
• THEN 结果中的 durationMs SHALL 覆盖连接建立、banner 等待、banner 读取和 expect 校验的完整耗时

Requirement: tcp banner 读取

系统 SHALL 仅在 tcp.readBanner: true 时读取服务端主动发送的 banner 数据，并同时受 bannerReadTimeout 和 maxBannerBytes 限制。

Scenario: 默认不读取 banner

• WHEN tcp target 未配置 readBanner 或配置为 false
• THEN 系统 SHALL 在连接建立后立即进入 connected 和 duration 校验，不等待服务端数据

Scenario: 读取服务端 banner

• WHEN tcp target 配置 readBanner: true，且服务端连接后发送 220 smtp.example.com ESMTP
• THEN 系统 SHALL 收集 banner 文本，并允许后续 expect.banner 对该文本执行 operator 断言

Scenario: banner 等待超时无数据

• WHEN tcp target 配置 readBanner: true，但服务端在 bannerReadTimeout 内未发送任何数据
• THEN 系统 SHALL 将 banner 视为空字符串并继续执行 expect 校验，不将无 banner 本身作为连接错误

Scenario: banner 读取超过最大字节数

• WHEN 服务端发送的 banner 数据超过 maxBannerBytes
• THEN 系统 SHALL 停止读取并记录 matched=false、failure.kind=error、failure.phase=banner 的结构化错误

Scenario: banner detail 截断展示

• WHEN tcp target 成功读取到较长 banner
• THEN observation.banner SHALL 保存截断后的 banner 摘要，API detail SHALL 展示截断后的 banner 摘要，避免 UI 展示过长文本