56 lines
4.5 KiB
Markdown
56 lines
4.5 KiB
Markdown
# P2 Worker SDK 协议阶段回归
|
||
|
||
日期：2026-09-17。此历史阶段记录覆盖独立 SDK 的底层连接和一次性执行闭环，**不代表 P2 完成，也不覆盖自动 Worker 运行器**。后续运行器的实现与验证见 [独立报告](phase-2-worker-runtime.md)。
|
||
|
||
## 实现范围
|
||
|
||
- 独立 module 内实现 WS/WSS 注册、容量/心跳、派发读取、Start、Renew、Finish、Resume；不引用服务端模型/存储。
|
||
- 固定子协议、授权头、受信任 TLS、禁用重定向/压缩、握手/控制/读取时限及缓冲上限。
|
||
- 并发 ACK 关联、稳定消息身份、公开错误分类；秘密和业务结果在默认格式化输出中隐藏。
|
||
- 当前租约与原回执分离，保守单调时钟期限；精确 JSON 数字及字符串 uint64 版本。
|
||
- 可运行的纯文本规范化示例，有限手动重连核对控制操作，不重复调用处理器。
|
||
- 新增字段均有中文契约注释；无持久化模型或迁移变更。
|
||
|
||
## 验证环境与命令
|
||
|
||
macOS arm64，Go 1.27.1，Docker 隔离 MySQL 8.4.10。连接依赖锁定 `github.com/coder/websocket v1.8.15`。
|
||
|
||
```sh
|
||
make test
|
||
make vet
|
||
make build
|
||
make integration
|
||
cd sdk/go
|
||
GOWORK=off go test -race ./...
|
||
GOWORK=off go vet ./...
|
||
GOWORK=off go test -run '^$' -fuzz FuzzWorkerJSON -fuzztime=15s .
|
||
```
|
||
|
||
测试脚本在一次性数据库先执行原服务端迁移、任务、执行、WSS 回归，再启动真实 orbit 命令及独立凭据，用 SDK 接入该服务；随后执行真实示例。测试不连接已有业务库，凭据不放入 URL、命令参数或输出。WSS 故障网关使用 `httptest.NewTLSServer` 及受信任测试证书，没有跳过证书校验。
|
||
|
||
## 通过的场景
|
||
|
||
| 测试层 | 场景与断言 |
|
||
| --- | --- |
|
||
| SDK 单元/WSS | 派发与 ACK 交错，多个请求逆序响应仍正确关联；业务整数/高精度小数和 uint64 版本不转为 float64 |
|
||
| SDK 授权判断 | 数据库墙钟偏差 24 小时不改变本地有效窗口；扣除全请求耗时和 250 毫秒余量；历史 RUNNING 回执和自行解码的 Lease 均不能授权 |
|
||
| SDK 有界传输 | 32 个未确认控制请求后拒绝新增；同 ID 同时在途拒绝；取消让所有等待者退出；派发缓冲耗尽关闭；关闭后不返回缓存任务 |
|
||
| SDK 协议防护 | 重定向不转交凭据；非法/未知回复、错误会话控制、失效凭据错误关闭；拒绝重复键、非法 Unicode、过深 JSON；默认格式化隐藏秘密 |
|
||
| 真实服务 + MySQL + WSS 故障网关 | 服务端完成 start 后丢 ACK；新连接 Resume 并重报原 start ID 得到原回执，原尝试保持不变 |
|
||
| 真实服务 + MySQL + WSS 故障网关 | 服务端完成 finish 后丢 ACK；新连接核对原结果，保持 SUCCEEDED、一次尝试及原始精确数值；旧 start ACK 不能再次授权 |
|
||
| 真实服务 + MySQL | 同消息续租返回原版本/期限；冲突结果只保存 EVIDENCE_ONLY；持久化排空跨重连，尝试清除被拒绝 |
|
||
| 真实服务 + MySQL | 短尝试时限驱动本地 context 到期；过期后旧回执不授权、迟到报告仅证据；服务端恢复为 NEEDS_REVIEW，不生成第二次尝试 |
|
||
| 真实命令行示例 | 提交文本 → 开始授权 → 实际规范化 → 上报 → 查询 → 排空；输出 SUCCEEDED、attempts=1、HELLO ORBIT |
|
||
|
||
15 秒 JSON 模糊测试本次执行 738,707 个输入，通过。实际执行数只描述本次运行，不是稳定吞吐或性能基准。完整隔离回归中原服务端测试通过，SDK 故障测试通过，三类 SDK 示例通过。
|
||
|
||
首次新增集成测试把“已排空后发送 Drain=false”误写为可成功但保持排空；实际服务端按既定契约返回 STATE_CONFLICT。已修正测试为确认拒绝，再以 Drain=true 心跳验证，重新执行完整隔离回归通过。没有为通过测试放宽服务端排空语义。
|
||
|
||
## 尚未覆盖与下一步
|
||
|
||
本轮故障恢复由测试驱动器/示例显式调用底层 SDK，不应描述为自动重连。业务函数调用一次的断言限定在示例驱动流程，不能推导任意外部系统的 exactly-once 效果。
|
||
|
||
下一步实现自动 Worker 运行器：处理器注册与并发限制、自动心跳/续租、单调期限取消、同进程断线恢复、稳定结果重报、处理器 panic/未知效果分类、非协作处理器与有界排空退出。之后继续补齐尝试/证据查询、完整 WS Schema 和 P2 阶段验收。
|
||
|
||
进程崩溃、宿主故障、数据库故障转移、生产 TLS 终止及高并发容量验证仍在后续范围。本地受控 WSS 中断不等同于跨故障域高可用验收。
|