feat: support durable task cancellation without foreign keys

2026-09-17 17:03:23 +08:00
parent 6805506450
commit 3ce7d2c104
48 changed files with 1642 additions and 164 deletions
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -7,7 +7,7 @@
 | 接口 | 状态 | 手册 |
 | --- | --- | --- |
 | `GET /health/live` | 已实现 | [健康检查](health.md) |
-| `GET /health/ready` | 已实现，仅验证数据库与迁移记录 | [健康检查](health.md) |
+| `GET /health/ready` | 已实现，验证数据库、迁移记录及零外键要求 | [健康检查](health.md) |
 | `/v1/tasks` 提交、查询、分页与待执行取消 | P1 已实现 | [任务接口](tasks.md) |
 | `/v1/tasks/{task_id}/attempts` 与尝试详情 | P2 已实现 | [执行历史](execution-history.md) |
 | `/v1/tasks/{task_id}/attempts/{attempt_id}/evidence` 与证据详情 | P2 已实现 | [执行历史](execution-history.md) |
@@ -15,6 +15,7 @@
 | 凭据校验与初始化 CLI | P1 已实现 | [鉴权](authentication.md) |
 | `/v1/worker/connect` | P2 已实现并通过阶段验收 | [Worker 契约](worker.md)、[Schema](worker-schema.md) |
 | 任务冻结策略与 Worker `retryable` | P3 安全重试已实现 | [安全重试](retries.md) |
+| `/v1/tasks/{task_id}:cancel` 与 `task.cancel` 通知 | P3 运行中取消已实现 | [取消及 SDK 场景](cancellation.md) |
 | `/v1/schedules`、不可变版本、暂停/恢复及触发查询 | P3 已实现 | [计划接口与 SDK 场景](schedules.md) |
 | `/v1/events/connect` | 计划 P3，尚未实现 | [协议草案](../03-http-websocket-protocol.md) |
 | `/v1/workflows` 与流程管理 | 计划 P4–P5，尚未实现 | [流程接口规划](workflows.md) |
--- a/docs/api/cancellation.md
+++ b/docs/api/cancellation.md
@@ -0,0 +1,108 @@
+# 任务取消与结果确认
+
+状态：已实现 HTTP 取消意图、开始前取消、WSS 通知、重连核对及 Go Worker 自动停止。取消记录、审计、事件和回执使用 MySQL 事务；运行结果仍以有效尝试的确认或到期核查为准。
+
+## 1. HTTP 接口
+
+`POST /v1/tasks/{task_id}:cancel`。需要当前 `tasks:cancel` 动作和目标队列权限；Bearer、JSON 和 Idempotency-Key 规则同 [任务接口](tasks.md)。适用于普通任务和计划生成任务；流程拥有的任务由流程控制管理，此入口返回 409。
+
+```json
+{"expected_revision":"3","reason":"用户终止本次处理"}
+```
+
+| 当前状态 | 提交后行为 | HTTP 状态 |
+| --- | --- | --- |
+| WAITING | 阻止后续尝试，通常成为 CANCELLED | 200 |
+| LEASED | 与开始事务竞争；尚未授权时结束尝试并释放许可 | 200 |
+| RUNNING | 保持 RUNNING，记录 cancel_requested_at；许可暂不释放 | 202 |
+| NEEDS_REVIEW | 保持核查状态，保存取消意图，不清除未知效果 | 200 |
+| 已有取消意图或终态 | 新操作身份返回 STATE_CONFLICT；原键仍返回首次回执 | 409 或原回执状态 |
+
+成功的 data 为 `{"task":<操作提交时的完整任务快照>,"deduplicated":false}`，与 CancelTaskResult 一致。202 只表示取消意图已经可靠保存，不能解释为处理器已经停止。
+
+WAITING/LEASED 若承接先前未知效果，取消后进入 NEEDS_REVIEW，保留 effect_uncertain=true 和空 completed_at。本次未开始不能证明此前尝试没有产生效果。
+
+请求结果不明时，保留原键、原 expected_revision 和原 reason 重报。只有明确收到 STATE_CONFLICT 后，才读取新状态并创建新的管理操作；任务的续租也会更新 revision。已保存的 RUNNING 取消回执即使任务后来结束，重报仍是原快照和 202，当前状态用 GET 查询。
+
+取消与开始竞争有两种有效结果：取消先提交则 Start 不获授权；Start 先提交则旧 expected_revision 冲突，重新查询后可记录运行中取消。权限、名称空间、幂等回执、版本和审计都在事务内核对。
+
+## 2. Worker 协议
+
+Hello 可选 `cancellation_notifications:true` 表示接收异步通知。低层 SDK 的 WorkerRegistration 默认为 false，自动 NewWorker 显式开启。未开启的连接不会收到新通知类型。
+
+服务端通知示例，session_id 是当前连接，消息没有 reply_to：
+
+```json
+{
+  "protocol_version":"1",
+  "type":"task.cancel",
+  "message_id":"11111111111111111111111111111111",
+  "session_id":"22222222222222222222222222222222",
+  "body":{
+    "task_id":"33333333333333333333333333333333",
+    "attempt_id":"44444444444444444444444444444444",
+    "epoch":"1",
+    "requested_at":"2026-09-17T08:00:00.123456Z"
+  }
+}
+```
+
+每次连接按数据库事实扫描当前拥有的运行尝试，通常约一秒发现取消，实际延迟受数据库和网络影响。通知允许重复、迟到、断线丢失，只作用于 TaskID/AttemptID/Epoch 全部匹配的尝试。单次读取最多 256 条，连接发送与 SDK 接收缓冲有界；慢消费者断开后重新核对。
+
+Start/Renew/Resume 返回的当前 Lease 也包含可选 `cancel_requested_at`；即使原 Start 回执是已批准执行，当前 Lease 中的取消意图也不能忽略。Active=true 表示原尝试仍可在有效期内提交权威结果，**有取消意图时不得继续业务处理**。SDK 的 ExecutionDeadline 在此情况下返回 false。
+
+取消后 Renew 不延长任何执行期限。处理器应尽快停止并提交已知结果；原租约或尝试截止到期后，未确认效果转 UNKNOWN/NEEDS_REVIEW，禁止因任务幂等声明自动再试。服务停止、通知丢失或 Worker 不配合，都不会自动成为 CANCELLED。
+
+结果继续使用 `task.finish`，新增 outcome=CANCELLED；error_code 必填稳定分类，retryable 不得为 true，result 是非 null JSON 或核查证据引用。不存在已保存取消意图时，此结果被拒绝。
+
+| 有效尝试上报 | 任务结果 |
+| --- | --- |
+| SUCCEEDED | SUCCEEDED，成功不被取消意图覆盖 |
+| FAILED | FAILED，停止后续自动重试；先前效果未知则仍需核查 |
+| UNKNOWN | NEEDS_REVIEW，不能把 context 错误当作撤销证明 |
+| CANCELLED | 本次确认停止且无遗留效果；若此前存在未知效果，仍为 NEEDS_REVIEW |
+| 租约已失效或结果冲突 | 追加 EVIDENCE_ONLY，不覆盖权威状态 |
+
+新版要求先停用旧服务、应用全部迁移（000007 扩展取消证据，000008 移除外键），再启动新版服务，最后升级自动 Worker。旧服务会拒绝新增 Hello 字段或 CANCELLED 结果；不能将带新能力的连接随机路由至旧节点。旧低层客户端可以继续原协议，但必须升级后才能依赖自动取消通知；取消后的续租不延长期限，同样适用于旧客户端。数据库升级细节见 [数据模型](../07-data-model.md)。
+
+## 3. Go SDK 接入
+
+自动 Worker 将业务 context 的 cause 设置为 `orbit.ErrTaskCancellationRequested`。仅当接入方能确认本次已停止且无未结清效果时返回 `*orbit.WorkerCancellationConfirmed`：
+
+```go
+<-ctx.Done()
+if !errors.Is(context.Cause(ctx), orbit.ErrTaskCancellationRequested) {
+    return nil, ctx.Err()
+}
+// 先完成本次外部操作核实；此处的类型是业务声明，不替代核实。
+return nil, &orbit.WorkerCancellationConfirmed{
+    Details: json.RawMessage(`{"evidence_ref":"objects/stopped"}`),
+}
+```
+
+普通 ctx.Err()、panic、网络错误和无效结果仍属于 UNKNOWN。处理器已经成功时返回真实结果，即使此时 context 也被取消，平台仍按有效结果确认。开始批准已提交但 ACK 丢失时，SDK 重连先检查取消意图；如果处理器尚未被调用，可以明确报告本次没有副作用，禁止重启处理器。
+
+低层接口设置 WorkerRegistration.CancellationNotifications 后，使用 NextCancellation 持续读取，并同时检查每次 Start/Renew/Resume 的 Lease。NextCancellation 的等待 context 取消只停止等待，不关闭连接。取消响应丢失后的 Finish 重报必须保留相同消息身份和结果。
+
+任务取消不等同于取消 Run context：前者停止指定业务处理器，后者要求整个 Worker 排空。无法强杀不配合 context 的 goroutine；它仍占本地物理槽，ShutdownTimeout 到期会报告未收尾数量。
+
+## 4. 可运行场景
+
+源码：[cancellation/main.go](../../sdk/go/examples/cancellation/main.go)。使用 [Worker 初始化](../sdk/worker-runtime.md) 的私有凭据文件，需 tasks:submit/read/cancel、workers:connect/consume 和队列范围。此示例只等待停止提示，没有外部业务副作用。
+
+```sh
+cd sdk/go
+ORBIT_URL=http://127.0.0.1:8080 \
+ORBIT_CREDENTIALS_FILE=/private/path/worker.credentials.json \
+go run ./examples/cancellation
+```
+
+预期输出：
+
+```text
+task=<任务ID> cancel_requested=true accepted_state=RUNNING
+final_state=CANCELLED attempts=1
+worker_drained=true running=0
+```
+
+每次运行使用新任务/处理器身份；正常执行保留任务、尝试和审计记录，不删除历史。错误时非零退出并尝试有界收尾。网络结果不明时示例停止，真实集成应保存原幂等身份以便核对。
--- a/docs/api/health.md
+++ b/docs/api/health.md
@@ -18,7 +18,7 @@ HTTP 200，`Content-Type: application/json`：

 ## GET /health/ready

-检查数据库连接和迁移记录是否与当前二进制的版本、校验和一致且没有 dirty 标记。内部检查最多 2 秒。
+检查数据库连接和迁移记录是否与当前二进制的版本、校验和一致且没有 dirty 标记，并检查 Orbit 表的数据库外键为 0。内部检查最多 2 秒。

 ```sh
 curl -i http://127.0.0.1:8080/health/ready
@@ -30,7 +30,7 @@ curl -i http://127.0.0.1:8080/health/ready
 {"status":"ready","scope":"database_and_schema"}
 ```

-数据库不可用、迁移缺失、记录被修改或存在 dirty 标记时 HTTP 503：
+数据库不可用、迁移缺失、记录被修改、存在 dirty 标记或 Orbit 表被添加外键时 HTTP 503：

 ```json
 {"status":"not_ready"}
--- a/docs/api/retries.md
+++ b/docs/api/retries.md
@@ -1,6 +1,6 @@
 # 安全重试 v1

-状态：P3 的安全重试已实现。使用现有任务提交与 Worker 结果接口，无独立的自动重试路由；[Cron/固定间隔计划](schedules.md) 已接入；运行中取消、人工恢复与可靠结果订阅继续按 [计划](../08-development-plan.md) 开发。验证证据见 [本阶段报告](../reports/phase-3-safe-retry.md)。
+状态：P3 的安全重试已实现。使用现有任务提交与 Worker 结果接口，无独立的自动重试路由；[Cron/固定间隔计划](schedules.md) 和 [运行中取消](cancellation.md) 已接入；人工恢复与可靠结果订阅继续按 [计划](../08-development-plan.md) 开发。验证证据见 [本阶段报告](../reports/phase-3-safe-retry.md)。

 ## 1. 三种不同的重报

@@ -54,7 +54,7 @@ available_at = 本次结束事务中的数据库时间 + delay_ms

 `task.requeued` 等持久化事件记录 decision、delay_ms、next_available_at、attempt_count、max_attempts、effect_uncertain。decision 包括 RETRYABLE_FAILURE、IDEMPOTENT_UNKNOWN、UNSTARTED_LEASE_EXPIRED、ATTEMPT_LIMIT、DEADLINE_EXCEEDED、RECONCILIATION_REQUIRED 等。当前可靠事件订阅尚未开放。

-当前取消接口仅支持不归属流程的 WAITING 任务。若等待的是历史效果不明后的重试，取消会记录意图、停止后续尝试并进入 NEEDS_REVIEW，不能宣称此前业务已撤销；其他 WAITING 任务可进入 CANCELLED。运行中取消仍未开放。
+取消接口支持独立任务和计划任务的 WAITING、LEASED、RUNNING 与 NEEDS_REVIEW。取消意图阻止后续尝试；运行中继续收集结果，普通取消错误或失联保持 UNKNOWN，不因 IDEMPOTENT 声明再次执行。此前未核实的效果不会被本次确认取消清除，详见 [取消状态与结果表](cancellation.md)。

 ## 4. SDK 接入

--- a/docs/api/tasks.md
+++ b/docs/api/tasks.md
@@ -152,7 +152,7 @@ curl "$ORBIT_URL/v1/tasks?queue_id=$ORBIT_QUEUE_ID&state=WAITING&limit=20" \

 ## POST /v1/tasks/{task_id}:cancel

-权限：tasks:cancel 和队列范围。当前只允许取消 WAITING 状态且不归属流程的任务。LEASED/RUNNING 或流程任务暂时返回 409，后续由执行与流程控制实现安全取消。
+权限：tasks:cancel 和队列范围。支持独立任务和计划生成任务的 WAITING、LEASED、RUNNING、NEEDS_REVIEW；流程所属任务仍由后续流程控制管理。运行中只记录取消意图，返回 202，最终状态等待有效结果或超时核查。完整规则及 SDK 示例见 [取消契约](cancellation.md)。

 ```sh
 curl "$ORBIT_URL/v1/tasks/$TASK_ID:cancel" \
@@ -164,7 +164,7 @@ curl "$ORBIT_URL/v1/tasks/$TASK_ID:cancel" \

 expected_revision 必填，为非零 uint64 的十进制字符串；reason 必填且不能全为空白，最多 1024 个 Unicode 字符。服务端以版本和状态条件更新，只有一个竞争请求能成功。

-200 的 data 为 `{"task":<完整最新任务>,"deduplicated":false}`。示例任务会变为 state=CANCELLED、revision="2"，写入 cancel_requested_at/completed_at，并同事务追加取消事件及审计。首次取消之后使用相同键、原因和**原 expected_revision**重报，返回原取消回执且 deduplicated=true。换键重报已取消任务返回 409。若 WAITING 来自未知效果后的自动重试，取消会保存 cancel_requested_at 并转 NEEDS_REVIEW，保留 effect_uncertain=true、completed_at 为空，停止后续尝试但不宣称此前效果已经撤销。
+200/202 的 data 为 `{"task":<本次取消的任务快照>,"deduplicated":false}`。上方等待态示例会变为 state=CANCELLED、revision="2"，写入 cancel_requested_at/completed_at，并同事务追加取消事件及审计。首次取消之后使用相同键、原因和**原 expected_revision**重报，返回原取消回执且 deduplicated=true；原回执为 RUNNING 时仍返回 202，最新状态另行 GetTask。换键重报已有取消意图或终态任务返回 409。WAITING/LEASED 若承接历史未知效果，取消转 NEEDS_REVIEW，保留 effect_uncertain=true、completed_at 为空；已在核查的任务保持核查。

 SDK：`Client.CancelTask(ctx, taskID, key, request)`。此操作不承诺回滚任何已发生的外部业务效果。

@@ -186,4 +186,4 @@ SDK：`Client.CancelTask(ctx, taskID, key, request)`。此操作不承诺回滚
 {"request_id":"44444444444444444444444444444444","error":{"code":"IDEMPOTENCY_CONFLICT","message":"idempotency key was used with different content"}}
 ```

-有限自动重试已实现，具体分类、退避、回执和升级边界见 [安全重试](retries.md)。批量受理、人工重试和运行中取消尚未实现。[执行历史](execution-history.md) 已提供尝试与证据的列表和详情。完整可运行程序见 [SDK 任务示例](../../sdk/go/examples/tasks/main.go)，已验证异常场景见 [P1 回归报告](../reports/phase-1.md)。SDK 忽略未知响应字段；更改已有字段语义需升级契约和回归。
+有限自动重试已实现，具体分类、退避、回执和升级边界见 [安全重试](retries.md)。[运行中取消](cancellation.md) 已实现；批量受理和人工重试尚未实现。[执行历史](execution-history.md) 已提供尝试与证据的列表和详情。完整可运行程序见 [SDK 任务示例](../../sdk/go/examples/tasks/main.go)，已验证异常场景见 [P1 回归报告](../reports/phase-1.md) 及 [取消回归](../reports/phase-3-cancellation.md)。SDK 忽略未知响应字段；更改已有字段语义需升级契约和回归。
--- a/docs/api/worker-schema.md
+++ b/docs/api/worker-schema.md
@@ -17,6 +17,7 @@ Schema 根接受双向消息，调用方应根据方向选择更严格的定义
 | `#/$defs/resumeFrame` | 尝试归属恢复请求 |
 | `#/$defs/startFrame`、`renewFrame`、`finishFrame` | 开始、续租、结果报告 |
 | `#/$defs/welcomeFrame`、`assignmentFrame` | 注册确认与主动派发 |
+| `#/$defs/cancellationFrame` | 已选择通知的连接接收 task.cancel，无 reply_to |
 | `#/$defs/ackFrame`、`errorFrame` | 操作确认与公开错误 |

 除首条 hello 外，请求必须提供当前 session_id。请求不得包含响应专用字段，包括 `reply_to:""` 或 `error:null`。主动派发没有 reply_to；操作响应通过 reply_to 关联原消息。error 在注册失败时不带 session_id；会话内错误带 session_id，主动致命错误不带 reply_to。
@@ -29,7 +30,8 @@ ACK 的 body 根据原请求选择：worker.capacity → welcome，worker.resume
 - 结构体必填字段必须显式提供，包括 capacity=0、drain=false；缺少字段不能被解释为调用者明确选择零值。
 - epoch、sequence、revision 为规范十进制字符串：范围 1–18446744073709551615，无前导零和正号。SDK 使用 uint64，线上使用字符串。
 - instance_secret/lease_secret 必须是 32 字节秘密的严格无填充 base64url，长度 43；知道资源 ID 无法替代秘密。
- 结果为非 null JSON；FAILED/UNKNOWN 必须携带稳定 error_code；SUCCEEDED 省略或使用空 error_code。
+- 结果为非 null JSON；FAILED/UNKNOWN/CANCELLED 必须携带稳定 error_code；SUCCEEDED 省略或使用空 error_code。
+- hello.cancellation_notifications 可选且默认 false；Lease 可返回 cancel_requested_at。CANCELLED 需要事务核验已保存意图；通知、取消后执行边界与升级顺序见 [取消契约](cancellation.md)。
 - finish.retryable 为可选布尔值，默认 false；true 仅允许 FAILED，Schema 与服务端都校验。派发任务可带 effect_uncertain=true，表示此前授权执行的效果尚未核实。业务重试条件见 [安全重试](retries.md)。
 - 返回时间使用 UTC RFC 3339，最多微秒精度。验证器应开启 format 断言以校验实际日历日期。

--- a/docs/api/worker.md
+++ b/docs/api/worker.md
@@ -65,6 +65,7 @@ go run ./cmd/orbit-admin bootstrap \
 | queue_id | 当前进程绑定队列 |
 | capabilities | 1–32 个 handler / handler_version / payload_version 精确版本组合，不可重复 |
 | capacity | 总执行槽数量，1–256，不是可用槽的累加值 |
+| cancellation_notifications | 可选 bool，默认 false；true 接收 task.cancel 通知，自动 Worker 默认开启 |

 重连必须保持凭据、队列、处理器集合和进程秘密，处理器集合的排列顺序不影响身份。新连接递增会话代次并使旧会话失效。知道 instance_id 或 task_id 不能接管执行。

@@ -90,7 +91,7 @@ capacity 使用单调递增序号和覆盖值。同序号同内容可重复，
 | task.renew | AttemptRef | 只续期当前 RUNNING；新消息可续租，重复原消息只取回原回执 |
 | task.finish | ref: AttemptRef、outcome、result、error_code、可选 retryable | 保存明确结果或未知效果；返回操作回执和当前授权 |

-outcome 为 SUCCEEDED / FAILED / UNKNOWN。result 为非 null JSON 或证据引用。FAILED/UNKNOWN 必须带 1–64 字符的稳定 error_code；SUCCEEDED 不带错误分类。retryable 省略为 false，只有 FAILED 可设 true，表示此次明确失败可安全重试。FAILED/true 受次数与时限限制进入退避；UNKNOWN 仅在冻结策略为 IDEMPOTENT 且预算允许时自动恢复，其他情况转 NEEDS_REVIEW。历史不确定效果不会被后续失败覆盖；完整规则见 [安全重试](retries.md)。
+outcome 为 SUCCEEDED / FAILED / UNKNOWN / CANCELLED。result 为非 null JSON 或证据引用。非成功结果必须带 1–64 字符的稳定 error_code；SUCCEEDED 不带错误分类。retryable 省略为 false，只有 FAILED 可设 true。CANCELLED 要求已保存取消意图且确认本次停止，不能用普通 context 错误推断；协议与升级顺序见 [取消契约](cancellation.md)。FAILED/true 受次数与时限限制进入退避；UNKNOWN 仅在冻结策略为 IDEMPOTENT、未取消且预算允许时自动恢复，其他情况转 NEEDS_REVIEW。历史不确定效果不会被后续失败或取消覆盖；完整规则见 [安全重试](retries.md)。

 开始、续租和结束返回 CommandResult：

@@ -116,7 +117,7 @@ outcome 为 SUCCEEDED / FAILED / UNKNOWN。result 为非 null JSON 或证据引

 receipt 是原操作的不可变确认；lease 是本次重新核验的执行权，两者不能混用：

- 只有 lease.active=true、lease.state=RUNNING，且仍在保守的本地有效期内，才允许处理器推进。LEASED 的 active 只表示预占有效。
+- 只有 lease.active=true、lease.state=RUNNING、没有 cancel_requested_at，且仍在保守的本地有效期内，才允许处理器推进。LEASED 的 active 只表示预占有效。取消后的 active 可为 true，用于确认当前结果；不允许继续业务执行或延长期限。
 - 原 start 回执可能仍表示 RUNNING，但当前 lease.active=false；旧 ACK 不能让已过期、已结束或已被替换的尝试复活。
 - 有效期不超过租约窗口、会话期限、任务总截止和从 authorized_at 起计算的单次尝试时限。
 - 客户端需要扣除请求总耗时及安全余量，用本地单调时钟停止执行，不能假定本地墙上时钟与数据库一致。
@@ -145,4 +146,4 @@ receipt 是原操作的不可变确认；lease 是本次重新核验的执行权

 这些是有界的开发基线，不代表经过容量压测的生产参数。当前同队列操作使用较粗的行锁协调，吞吐与公平性需要 P6 按负载验证。服务退出会显式关闭被 HTTP Upgrade 接管的连接；断开不会直接撤销外部已发出的请求。

-协议 Schema 和真实进程强杀恢复已通过回归，见 [P2 阶段验收](../reports/phase-2.md)。运行中取消属于 P3；凭据轮换、数据库故障切换、跨主机演练与容量验收属于后续生产验证。自动运行器对非协作处理器提供有界退出与状态报告，不能强制停止其外部副作用。
+协议 Schema 和真实进程强杀恢复已通过回归，见 [P2 阶段验收](../reports/phase-2.md)。[运行中取消](cancellation.md) 已实现并通过回归；凭据轮换、数据库故障切换、跨主机演练与容量验收属于后续生产验证。自动运行器对非协作处理器提供有界退出与状态报告，不能强制停止其外部副作用。