orbit/docs/03-http-websocket-protocol.md

Orbit HTTP 与 WebSocket 协议草案

版本 0.2 · 2026-09-17。HTTP + WS 已确认。本文保留首版设计建议；已实现能力以正式接口手册为准，其余路径、消息名、字段和状态码仍待对应阶段实现及验证。

实现更新：HTTP 任务/队列、Worker/Event WSS 以及 Weave 公共接口均已接入；实际帧名、字段、回执与边界见 Worker 契约、事件接口和流程接口。本文保留协议推导和边界说明，生产兼容与拓扑验收仍以持续计划和发布清单为准。

1. 通用契约

• 生产使用 HTTPS / WSS；HTTP 承担任务提交、流程启动与信号、查询、管理，WS 承担 Worker 双向通信与结果订阅。
• 数据采用 JSON；HTTP 契约使用 OpenAPI 描述，WS 消息使用版本化 JSON Schema 与交互时序描述。
• ID 与执行代次等可能超出跨语言整数精度的值使用字符串。时间使用 RFC 3339 UTC 字符串，时长字段注明单位。
• 请求体、消息、批量条数、查询页大小和发送缓冲都必须有限制；具体上限见待定参数表。
• 鉴权后校验应用、环境、队列和操作权限。请求中的命名空间、Worker ID、任务 ID 不能代替授权。
• SDK 与服务端维护兼容矩阵；不兼容的协议或处理器版本明确拒绝，不静默解释为当前版本。

2. HTTP 接口草案

方法与路径	行为
POST /v1/tasks	幂等提交一项任务
POST /v1/tasks:batch	已实现；逐项身份、四类结果与限制见批量手册
GET /v1/tasks/{task_id}	查询权威任务状态与结果摘要
GET /v1/tasks/{task_id}/attempts	分页查询执行尝试
GET /v1/tasks	按有索引的字段分页查询，支持提交幂等键精确查找
POST /v1/tasks/{task_id}:cancel	请求取消，记录原因
POST /v1/tasks/{task_id}:retry	普通任务人工重试；流程关联任务须经 Weave 恢复入口
POST /v1/schedules	创建计划，明确漏跑和重叠策略
PATCH /v1/schedules/{schedule_id}	带预期版本修改计划，冲突时拒绝覆盖
POST /v1/schedules/{schedule_id}:pause	暂停计划的新触发
POST /v1/schedules/{schedule_id}:resume	按漏跑策略恢复计划
GET /v1/schedules/{schedule_id}/occurrences	查询计划触发记录
GET /health/live、GET /health/ready	进程存活与接单就绪状态，二者独立

应用、凭据、队列、配额和审计管理接口沿用同一鉴权、版本与错误规范，其完整路径清单在接口评审时补齐。就绪检查必须反映关键依赖，数据库不可用时不能继续宣称可安全接单。

Weave以下接口已接入公共HTTP与SDK，具体字段和权限以实例接口、恢复接口为准：

方法与路径	行为
POST /v1/workflow-definitions/{definition_id}/versions	研发通过 SDK 发布不可变定义；同版本同内容幂等，不同内容冲突
POST /v1/workflows	幂等启动流程，固定定义版本
GET /v1/workflows/{workflow_id}	查询实例、定义版本、执行状态、暂停标记与等待摘要
GET /v1/workflows/{workflow_id}/steps	按键返回最多128项步骤元数据；单个步骤详情另用/steps/{key}读取输入/输出、等待和查询预算
POST /v1/workflows/{workflow_id}/signals	幂等受理信号，不等于信号已经被消费
GET /v1/workflows/{workflow_id}/signals/{signal_id}	查询信号受理、匹配与消费结果
POST /v1/workflows/{workflow_id}/control	PAUSE/RESUME/CANCEL；按control_revision保存门控与意图
POST /v1/workflows/{workflow_id}/recovery/*	六类有证据恢复，按当前实例/步骤/任务版本核对
GET /v1/workflows/{workflow_id}/operations	有界分页读取流程操作审计摘要，正文另用单条查询

流程列表、实例筛选、激活/轮次/信号历史和状态事件时间线已交付；字段、权限和有界分页以实例查询、流程历史和事件时间线为准。恢复必须带预期状态版本、稳定操作身份、原因与证据，不提供任意修改状态的通用入口。

暂停和继续使用独立管理权限、预期控制版本、幂等操作身份与原因；同一操作重报返回原确认，过期控制版本不能覆盖后来的操作。建议 200 确认门控已提交，后续执行进度通过查询观察；门控失效条件和终态操作错误在协议评审时固定。

2.1 受理、幂等与错误

• 首次创建任务、流程或信号记录的建议响应为 201 Created，表示资源及幂等记录已可靠提交，不表示业务执行或信号消费完成。
• 相同幂等请求返回 200 和原资源 ID，标记 deduplicated: true；相同键不同语义请求返回 409。
• 单项提交使用 Idempotency-Key；已实现的批量每项使用 idempotency_key，与单项共用受理身份；不接受整批幂等头，见批量接口。
• 普通任务提交幂等作用域为命名空间内的任务提交操作；流程启动使用独立操作作用域，信号按命名空间、实例与信号 ID 去重。其他管理写操作按命名空间、操作和资源界定作用域，避免同一个键在不同 API 间意外冲突。
• HTTP request_id 仅用于追踪，与业务幂等键分开。
• 请求超时后，使用原幂等键查询或重试；不能通过换一个键来猜测原请求是否失败。
• 语义哈希排除请求追踪、连接身份等传输字段，明确 JSON 规范化、缺省值和数组顺序；不能依赖普通 map 的序列化顺序。算法在协议冻结时确定。

建议统一响应结构：成功包含 request_id 和 data；失败包含 request_id 和 error，其中 error 含稳定的 code、可读 message 和受控的 details。

HTTP 状态	用途
200 / 201	查询或已确认的操作结果 / 新资源可靠创建
202	取消等操作已记录意图，最终行为仍在推进
400 / 422	协议格式错误 / 语义校验失败
401 / 403	未认证 / 无操作权限
404	不存在或按访问策略隐藏的资源
409	幂等内容冲突、资源版本冲突或操作状态冲突
429 / 503	容量限制 / 服务暂不可用，可提供 Retry-After

批量请求顶层校验通过后可返回 200，但每项必须给出索引、任务 ID 或错误。顶层成功不表示每项均被受理。限流或断线后的补交仍使用原逐项幂等键。

3. Worker 连接

建议入口：GET /v1/worker/connect，使用 WebSocket Upgrade，协商子协议 pulse.worker.v1。SDK 在握手中携带应用凭据，不把长期密钥放在 URL 查询参数中。

连接生命周期：鉴权 → 协议协商 → 能力登记 → 恢复核对 → 可接单 → 排空 / 断线。

• worker_instance_id 标识一个进程实例，重连保留，重启建议新建；可另设可读名称。
• session_id 标识本次连接。新连接需有新的会话身份，旧连接消息不得继续修改新会话的执行权。
• 恢复执行必须校验认证身份、执行凭据和数据库中的当前归属，不能仅凭相同 Worker 名称认领。
• Worker 声明队列、处理器兼容版本及容量。平台授权与配额优先于客户端声明。

4. 消息信封

以下为示意，时间与数值不是生产默认参数：

{
  "protocol_version": "1",
  "type": "task.assign",
  "message_id": "msg_example",
  "session_id": "session_example",
  "task_id": "task_example",
  "attempt_id": "attempt_example",
  "body": {
    "handler": "report.generate",
    "handler_version": "1",
    "payload_version": "1",
    "payload": {"report_ref": "report_example"},
    "lease_token": "example-only-not-a-real-secret",
    "lease_expires_at": "2026-09-17T08:00:30Z"
  }
}

响应通过 reply_to 关联原消息。需要可靠确认的操作使用稳定消息 ID；跨重连重报时保留操作身份，但使用当前会话认证。传输会话变化不改变操作的语义哈希。

执行凭据属于敏感信息，不进入普通日志、管理查询或指标标签。Task / Attempt / Message / Session 四种 ID 分别表达业务工作、执行尝试、通信操作和连接。

5. 消息类型与确认

消息	方向	语义
worker.hello / worker.welcome	双向	协商能力、版本、会话与协议限制
worker.resume / worker.resume.result	双向	核对断线前的执行尝试，逐项给出续接、停止或核查结果
worker.capacity	Worker → 平台	更新容量声明；带会话内序号，重复上报不得重复增加额度
task.assign	平台 → Worker	派发已持久化授权的任务与执行凭据
task.start	Worker → 平台	确认接单并申请开始；建议获平台确认后再调用处理器
task.renew	Worker → 平台	续期有效执行租约，可批量但逐项确认
task.complete	Worker → 平台	提交结果或结果引用，等待持久化确认
task.fail	Worker → 平台	提交错误分类及已知业务结果，平台按冻结策略决定后续行为
task.cancel	平台 → Worker	传递已保存的取消意图，不代表副作用被撤销
task.finish 的 outcome=CANCELLED	Worker → 平台	已实现的取消确认；需已保存取消意图且本次停止可确认，详见 取消契约；不使用单独的 task.cancelled 消息
worker.drain	双向	停止接收新任务，受控完成已有任务
ack / error	双向	关联明确操作的确认或错误，不能用连接 Pong 替代

建议采用两步派发：平台先保存 LEASED 并发送任务；Worker 发 task.start，平台原子确认有效租约和未被取消后保存 RUNNING，再确认执行。消息丢失时按同一尝试重报或核对，不能未经重新授权自行执行。

如关联执行门控已暂停，尚未获开始授权的 task.start 不能被确认可执行；已确认开始的操作重报只补取原确认，不授予第二次执行。具体暂挂、释放预占容量和恢复派发的消息细节在协议冻结时补齐。

RUNNING 表示平台已授权开始，不足以证明业务侧已经发生某项效果。租约前后派发与取消的竞争见 可靠性模型。

5.1 完成确认丢失

1. 平台在同一事务内保存任务终态、尝试结果与待交付事件。
2. 提交成功后回复 ack。
3. SDK 未收到确认时，重报相同结果或查询任务。
4. 已确认的同一尝试、同一结果再次上报，返回原确认，即使此时原租约已经到期。
5. 不同结果冲突或过期尝试试图写入新结果时拒绝修改，保留可诊断记录。

先验证权限，再识别已完成操作的幂等重报，最后对新操作校验租约，避免将合法的确认补取误判为任务失败。

SDK 可以在进程存活期间缓存未确认消息；不得宣称内存缓存能跨进程崩溃恢复。业务效果已发生但结果尚未回报的情况，依赖业务幂等、业务侧操作记录或结果查询恢复。

6. 心跳、重连与背压

• Ping/Pong 用于连接活性；具体任务的续租必须单独经过授权与持久化确认。WebSocket 标准
• 任务续租失败后，SDK 不能仅因连接仍在线就继续假定执行权有效。
• SDK 根据服务端确认的租约期限，结合请求耗时、安全余量及本地单调时钟管理停止边界；不直接信任客户端墙上时钟与服务器完全一致。
• 重连使用有上限的指数退避与抖动；支持凭据刷新、重新鉴权和恢复核对。
• 断线后允许在最后确认的有效租约内按策略推进；无法及时恢复有效执行权时，停止推进并尽力取消可取消操作。外部已发请求仍需核查。
• 重连可进入任一平台节点；有效旧尝试经原子校验迁移到新会话，失效尝试不得因重连复活。
• 平台为已派发未确认的任务预占容量。容量消息采用序号和明确的覆盖/计算规则，重复消息不能释放或重复发放额度。
• 单连接读写由独立循环管理；设置消息上限、读写期限和有界发送队列，处理器运行不占网络循环。
• 慢消费者停止追加派发；非关键进度更新可合并，关键状态与结果必须保留恢复路径。
• 负载均衡器支持 Upgrade、长连接超时和排空；网络断开不能触发无条件的业务重试。

7. 可靠结果订阅

当前已实现独立 WSS 入口 /v1/events/connect 与子协议 orbit.events.v1，区分 Worker 消费权和结果订阅权。当前请求、响应、限制与机器可读 Schema 以 订阅接口 为准；下述涉及流程事件的描述仍为规划。

事件包含 event_id、资源类型、资源 ID、状态版本、事件类型及结果引用，可表达任务与流程事件。平台先持久化事件与交付状态，再发送 event.deliver；接收方完成自身的可靠处理后发送 event.ack。

未确认事件可重新发送，订阅方按事件 ID 去重；同一资源按状态版本处理迟到信息，不承诺跨资源全局顺序。事件保留到期、订阅失效与补偿查询行为必须公开。

实时控制台展示可使用合并后的进度通知，但业务流程推进不能依赖只有在线时才能收到的消息。

Weave 消费 Pulse 的内部持久化事件，不经此对外订阅入口；其事务与去重要求见 流程协作。

8. 版本与协议验证

HTTP /v1 与 WS 子协议分别标识兼容边界，业务处理器版本独立。新增可选字段应兼容旧客户端；未知关键消息、状态或枚举不能被当作成功。

协议测试应覆盖断线、重复、迟到、会话切换、局部批量失败与凭据撤销。OpenAPI 与 WS Schema 要进入版本控制和兼容性检查，禁止服务端与 SDK 各自维护不同的状态解释。