feat: deliver authenticated task APIs, SDK and P1 regression

2026-09-17 07:41:32 +08:00
parent 4f2935e36f
commit 9701b7a071
37 changed files with 3169 additions and 67 deletions
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -8,17 +8,19 @@
 | --- | --- | --- |
 | `GET /health/live` | 已实现 | [健康检查](health.md) |
 | `GET /health/ready` | 已实现，仅验证数据库与迁移记录 | [健康检查](health.md) |
-| `/v1/tasks` 与任务管理 | 计划 P1–P3，尚未实现 | [任务接口规划](tasks.md) |
+| `/v1/tasks` 提交、查询、分页与待执行取消 | P1 已实现 | [任务接口](tasks.md) |
+| `/v1/queues` 创建与查询 | P1 已实现 | [队列接口](queues.md) |
+| 凭据校验与初始化 CLI | P1 已实现 | [鉴权](authentication.md) |
 | `/v1/worker/connect` | 计划 P2，尚未实现 | [协议草案](../03-http-websocket-protocol.md) |
 | `/v1/schedules` 与计划管理 | 计划 P3，尚未实现 | [协议草案](../03-http-websocket-protocol.md) |
 | `/v1/events/connect` | 计划 P3，尚未实现 | [协议草案](../03-http-websocket-protocol.md) |
 | `/v1/workflows` 与流程管理 | 计划 P4–P5，尚未实现 | [流程接口规划](workflows.md) |

-当前服务对未实现路由返回 404。健康检查就绪不表示任务调度、鉴权或流程引擎已经可用。
+未实现路由返回 404。健康检查就绪不表示任务执行、定时调度或流程引擎已经可用。

 ## 业务接口统一要求

-下述业务契约尚在实现阶段细化，不能用于声称当前已有业务 API：
+P1 业务接口已遵守下述约定，后续接口继续沿用：

 - 生产使用 HTTPS/WSS，凭据通过授权头或受控握手传递，不放入 URL。
 - 应用身份、命名空间和操作权限分别校验；知道资源 ID 不等于拥有权限。
@@ -27,7 +29,7 @@
 - 时间为 UTC RFC 3339，时长字段带单位；查询和批量操作有上限。
 - 错误码、字段、分页游标和限制值在对应阶段实现及回归后冻结。

-健康接口目前直接返回状态对象。业务接口计划使用 `request_id` + `data` / `error` 信封，详见 [通信协议](../03-http-websocket-protocol.md)。
+健康接口直接返回状态对象。已实现的业务接口使用 `request_id` + `data` / `error` 信封；当前实际字段以本目录手册为准，其他尚未实现的接口见 [通信协议草案](../03-http-websocket-protocol.md)。

 ## 每个正式接口的文档模板

--- a/docs/api/authentication.md
+++ b/docs/api/authentication.md
@@ -0,0 +1,53 @@
+# 凭据、权限与初始化
+
+状态：P1 已实现。业务接口每次在数据库事务内校验凭据摘要、撤销/到期、应用与命名空间启停，以及动作和队列范围。授权与写入使用同一事务；管理变更与已经获得授权锁的请求按事务先后次序生效。
+
+## 初始化一个新的接入应用
+
+前置：专用 MySQL 数据库已经执行 orbit-migrate up，使用持有初始化权限的数据库管理连接。此命令创建新应用、命名空间、队列和凭据，不会覆盖现有同名应用。
+
+```sh
+mkdir -p .local
+chmod 700 .local
+go run ./cmd/orbit-admin bootstrap \
+  --application sample-app \
+  --namespace default \
+  --environment development \
+  --queue files \
+  --output .local/development.credentials.json
+```
+
+ORBIT_MYSQL_DSN 通过环境注入，命令不读取 .env。所有名称必填，以字母/数字开头，后续允许字母、数字、`_ . : -`；environment 最长 32，其余最长 128。输出文件必须不存在，以 0600 创建；原始凭据不会打印到 stdout/stderr。`.local/` 和 `*.credentials.json` 已被 Git 忽略。
+
+输出 JSON 包含 application_id / namespace_id / queue_id / credential_id / token / expires_at。初始凭据有效期为 30 天，权限包括当前命名空间内的五个 P1 动作和全部队列。初始队列 max_concurrency=4、rate_per_second=10；这是开发初始配置，执行限流随 P2–P3 落地。
+
+资源、凭据摘要和初始化审计在一个事务中提交。交付文件先写入并同步到磁盘，成功后再提交事务。如果文件写入失败则回滚并移除文件；如果已经交付后提交无法确认，保留文件并报错，应使用其中凭据核对结果，不能直接覆盖或重复创建。
+
+初始文件包含真实秘密，应保管在受限目录或导入秘密管理系统。运行账户与迁移/初始化账户分开；生产只通过 HTTPS 使用凭据。凭据管理 HTTP API、轮换与细粒度运维命令在后续阶段实现，当前 bootstrap 主要用于完成独立接入与开发验证。
+
+## 凭据格式与作用域
+
+```text
+orb1.<namespace_id>.<credential_id>.<32-byte-base64url-secret>
+```
+
+服务端仅保存 SHA-256 秘密摘要。ID 不是授权证明，秘密不进入 URL。客户端请求：
+
+```text
+Authorization: Bearer <token>
+```
+
+权限存储格式如下，当前由受控初始化及管理侧写入，不能通过普通任务请求修改：
+
+```json
+{
+  "actions":["tasks:submit","tasks:read","tasks:cancel","queues:read","queues:manage"],
+  "queues":["*"]
+}
+```
+
+actions 不支持通配符；queues 可列出队列 ID，星号仅表示当前命名空间内全部队列。创建队列必须具有 queues:manage 和全部队列范围。请求不接受自定义 namespace_id 来跨越隔离边界。
+
+原始秘密错误、凭据撤销/过期、应用或命名空间停用统一返回 401。合法身份缺少动作权限返回 403。读取不在范围内的单个资源返回 404，避免披露资源内容。
+
+SDK 使用 `orbit.Options{Token: token}`。健康查询不发送凭据。当前不启用业务权限缓存，撤销校验不依赖缓存过期。
--- a/docs/api/health.md
+++ b/docs/api/health.md
@@ -42,4 +42,4 @@ curl -i http://127.0.0.1:8080/health/ready

 对应 `Client.Liveness(ctx)` 和 `Client.Readiness(ctx)`，见 [SDK 接入](../sdk/README.md)。HTTP 503 返回 `*orbit.HTTPError`。

-此阶段的 ready 只表示数据库与迁移基础可用；尚无任务、Worker、流程或业务鉴权服务。SDK 默认请求超时为 10 秒，调用方可通过 context 设置更短期限。
+ready 只表示数据库与迁移基础可用；不检查 Worker、任务积压、流程执行或业务效果。P1 启动时先校验迁移，缺失或 dirty 会拒绝启动；运行后数据库不可用时 ready 返回 503。SDK 默认请求超时为 10 秒，调用方可通过 context 设置更短期限。
--- a/docs/api/queues.md
+++ b/docs/api/queues.md
@@ -0,0 +1,51 @@
+# 队列接口 v1
+
+状态：P1 已实现创建与查询。更新、暂停、实际派发并发与速率控制随 P2–P3 实现；当前参数是后续执行所需的持久化配置。
+
+## POST /v1/queues
+
+需要 queues:manage 和当前命名空间内全部队列范围。鉴权、请求体、幂等键及错误信封与 [任务接口](tasks.md) 一致。
+
+| 字段 | 类型 | 要求 |
+| --- | --- | --- |
+| name | string | 1–128 字符，以 ASCII 字母/数字开头，其后允许字母、数字、`_ . : -`；命名空间内唯一 |
+| max_concurrency | uint32 | 必填，1–100000 |
+| rate_per_second | uint32 | 必填，1–1000000 |
+
+```sh
+curl "$ORBIT_URL/v1/queues" \
+  -H "Authorization: Bearer $ORBIT_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: queue-images-v1' \
+  --data '{"name":"images","max_concurrency":8,"rate_per_second":100}'
+```
+
+首次 201：
+
+```json
+{
+  "request_id":"44444444444444444444444444444444",
+  "data":{
+    "deduplicated":false,
+    "queue":{
+      "id":"11111111111111111111111111111111",
+      "namespace_id":"33333333333333333333333333333333",
+      "name":"images","paused":false,"max_concurrency":8,"rate_per_second":100,"revision":"1"
+    }
+  }
+}
+```
+
+同键同内容返回 200、deduplicated=true。同键不同内容返回 409 IDEMPOTENCY_CONFLICT；换键创建同名队列返回 409 STATE_CONFLICT。创建、幂等记录和管理审计同事务提交。
+
+SDK：`Client.CreateQueue(ctx, key, orbit.CreateQueueRequest{...})`。
+
+## GET /v1/queues/{queue_id}
+
+权限：queues:read 和对应队列范围。200 的 data 直接为上方 queue 对象；资源不存在或单资源范围不匹配返回 404。
+
+```sh
+curl "$ORBIT_URL/v1/queues/$ORBIT_QUEUE_ID" -H "Authorization: Bearer $ORBIT_TOKEN"
+```
+
+SDK：`Client.GetQueue(ctx, queueID)`。范围限制、重复创建和同名冲突已纳入 [P1 回归](../reports/phase-1.md)。这些配置上限不是生产容量承诺。
--- a/docs/api/tasks.md
+++ b/docs/api/tasks.md
@@ -1,16 +1,187 @@
-# 任务接口规划
+# 任务接口 v1

-状态：计划 P1–P3，尚未实现。以下为后续落地清单；实际字段与可运行请求将在相应阶段补齐。
+状态：P1 已实现并通过真实 MySQL 与 SDK 回归。当前提供受理、查询、分页和待执行取消；Worker 执行与自动重试在 P2–P3 实现。

-| 操作 | 候选接口 | 关键行为 |
-| --- | --- | --- |
-| 提交 | `POST /v1/tasks` | 携带稳定 `Idempotency-Key`，受理提交完成后响应 |
-| 批量提交 | `POST /v1/tasks:batchSubmit` | 每项独立幂等与结果；顶层成功不代表全部成功 |
-| 查询 | `GET /v1/tasks/{task_id}` | 校验命名空间和权限，返回当前状态与结果 |
-| 执行历史 | `GET /v1/tasks/{task_id}/attempts` | 分页返回历史尝试，不展示执行秘密凭据 |
-| 取消 | `POST /v1/tasks/{task_id}:cancel` | 待执行时取消生效；在途工作先记录取消意图 |
-| 人工重试 | `POST /v1/tasks/{task_id}:retry` | 带原因与权限；流程关联任务通过 Weave 恢复 |
+## 公共约定

-提交契约需要队列、处理器/参数版本、业务输入或引用、执行时间、时限、恢复安全等级和重试策略。业务参数内容由接入方解释。
+业务接口需要 `Authorization: Bearer <token>`；写入需要 `Content-Type: application/json` 和稳定的 `Idempotency-Key`。凭据决定命名空间，请求体不能覆盖它。详见 [鉴权与初始化](authentication.md)。

-P1 回归完成前，此页不提供看似可调用的 SDK 方法或 HTTP 请求体。接口实现后同步增加完整请求/响应、错误码及文件转换场景。
+请求体上限 512 KiB。拒绝未知字段、大小写别名、重复 JSON 键、无效 UTF-8、孤立 Unicode 代理项和超过 32 层的嵌套。除可空时间外，字段不能显式传 null。请求追踪 ID 由服务端生成，与幂等键分开。
+
+响应使用 `{"request_id":"…","data":…}`；X-Request-ID 与正文一致。revision 是十进制字符串；ID 是 32 位小写十六进制字符串。时间使用 RFC 3339，返回 UTC，最多微秒精度。
+
+## POST /v1/tasks
+
+权限：tasks:submit，并有目标队列的访问范围。首次提交返回 201，同键相同内容返回 200。两者均只表示**数据库已受理**，不表示业务处理完成。
+
+| 字段 | 类型 | 必填 / 默认 | 含义与限制 |
+| --- | --- | --- | --- |
+| queue_id | string | 必填 | 同一命名空间内的队列 ID |
+| handler | string | 必填 | 处理器名称，1–128 字符 |
+| handler_version | string | 必填 | 固定处理器版本，1–64 字符 |
+| payload_version | string | 必填 | 输入契约版本，1–32 字符 |
+| payload | JSON | 必填 | 非 null JSON，最大 256 KiB；平台不解释业务字段 |
+| business_key | string | 可选 | 最多 191 个 Unicode 字符，无 NUL/换行；用于关联，不提供业务幂等 |
+| available_at | time / null | 受理时数据库时间 | 最早可执行时间；必须早于总截止时间，仅允许最多 1 秒的过去时间容差 |
+| start_deadline_at | time / null | 无独立限制 | 必须晚于当前时间，不早于 available_at，不晚于总截止时间 |
+| task_timeout_ms | uint64 | 0 或省略为 86400000 | 从受理时计算的总时限，最大 30 天（2592000000 毫秒） |
+| recovery_safety | string | RECONCILE_ONLY | 也可为 IDEMPOTENT；必须基于处理器真实的幂等能力声明 |
+| retry | object | 见下表 | 受理时冻结的执行策略；当前阶段仅保存 |
+
+处理器及版本名称以 ASCII 字母或数字开头，后续只能包含字母、数字、`_ . : -`。时间年份为 2000–9998。
+
+| retry 字段 | 默认与限制 |
+| --- | --- |
+| max_attempts | 0 或省略为 1；范围 1–100，包含首次尝试 |
+| attempt_timeout_ms | 0 或省略为 30000；必须不超过任务总时限 |
+| initial_delay_ms | 多次尝试时 0 或省略为 1000；必须为正且不超过 max_delay_ms；单次尝试默认 0 |
+| max_delay_ms | 多次尝试时 0 或省略为 30000；单次尝试默认 0；最大 9223372036854，整体仍受总截止时间限制 |
+
+这些值是当前接口保护边界，不代表已经验证相应吞吐或并发容量。
+
+业务 JSON 以经过校验的文本持久化，保留大整数和小数的精确数字内容。不要在接入方先转成 float64；Go 使用 json.RawMessage、结构体中的精确类型或业务约定的字符串。单个数字最长 256 字符，显式指数和去除尾零后的指数均需在 -308 至 308 内，数值不能超出有限 double 的幅度；这只是可接受范围检查，摘要不使用浮点近似值。
+
+请求示例，队列 ID 替换为初始化结果：
+
+```sh
+curl -i "$ORBIT_URL/v1/tasks" \
+  -H "Authorization: Bearer $ORBIT_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: conversion-operation-001' \
+  --data '{
+    "queue_id":"11111111111111111111111111111111",
+    "handler":"file.convert",
+    "handler_version":"v1",
+    "payload_version":"v1",
+    "payload":{"source_ref":"objects/input.txt","format":"pdf","sequence":9007199254740993},
+    "business_key":"conversion-001"
+  }'
+```
+
+首次受理的完整响应示例，ID 和时间为示意值：
+
+```json
+{
+  "request_id":"44444444444444444444444444444444",
+  "data":{
+    "deduplicated":false,
+    "task":{
+      "id":"22222222222222222222222222222222",
+      "namespace_id":"33333333333333333333333333333333",
+      "queue_id":"11111111111111111111111111111111",
+      "state":"WAITING",
+      "revision":"1",
+      "handler":"file.convert",
+      "handler_version":"v1",
+      "payload_version":"v1",
+      "payload":{"source_ref":"objects/input.txt","format":"pdf","sequence":9007199254740993},
+      "business_key":"conversion-001",
+      "available_at":"2026-09-17T00:00:00Z",
+      "deadline_at":"2026-09-18T00:00:00Z",
+      "recovery_safety":"RECONCILE_ONLY",
+      "retry":{"max_attempts":1,"initial_delay_ms":0,"max_delay_ms":0,"attempt_timeout_ms":30000},
+      "attempt_count":0,
+      "created_at":"2026-09-17T00:00:00Z",
+      "updated_at":"2026-09-17T00:00:00Z"
+    }
+  }
+}
+```
+
+可选响应字段：start_deadline_at、result、cancel_requested_at、completed_at、business_key，未设置时省略。终态有 completed_at。状态集合为 WAITING / LEASED / RUNNING / NEEDS_REVIEW / SUCCEEDED / FAILED / CANCELLED；P1 仅主动产生 WAITING 和 CANCELLED。
+
+### 幂等与失败处理
+
+- 键为 1–128 个可打印 ASCII 字符，不含空格；作用域为命名空间 + 操作类型，取消额外包含任务 ID。不同凭据在同一命名空间共享该身份，重复请求仍需通过当前权限校验。
+- 固定默认值、规范化 UTC 时间、排序 JSON 对象键、精确规范化十进制数字，再计算版本化 SHA-256 摘要。1 与 1.0 等价；数组顺序有意义。内部算法名 orbit-json-v1，不宣称采用 RFC 8785。
+- 同键不同内容返回 409 IDEMPOTENCY_CONFLICT；不同键即使 business_key 相同，也可以产生两个任务。
+- 同一事务保存任务、受理事件、提交者审计、幂等身份与原始回执；验证或写入失败整体回滚。提交审计记录凭据与处理器/队列，不复制业务参数。
+- 同键重报返回**首次操作的回执快照**；任务之后取消也不会改写该回执。获取最新状态调用 GET。
+- 网络中断、客户端超时或 503 时，不能认定提交未发生；保持原键和原内容查询或重报。SDK 不自动换键或自动重试写操作。
+- 幂等记录设置 90 天保留截止时间；当前尚无清理任务，存在的记录持续生效。后续清理不得缩短已承诺窗口。
+
+SDK：`Client.SubmitTask(ctx, key, request)`。
+
+## GET /v1/tasks/{task_id}
+
+权限：tasks:read 和任务所在队列范围。200 的 data 直接为上方 task 对象，返回当前状态和完整参数/已保存结果。不存在、跨命名空间或不在该凭据队列范围时返回 404。
+
+```sh
+curl "$ORBIT_URL/v1/tasks/$TASK_ID" -H "Authorization: Bearer $ORBIT_TOKEN"
+```
+
+SDK：`Client.GetTask(ctx, taskID)`。
+
+## GET /v1/tasks
+
+权限：tasks:read。查询参数均只能出现一次：
+
+| 参数 | 要求 |
+| --- | --- |
+| queue_id | 必填，有权限的队列 ID |
+| state | 可选，取上述状态之一 |
+| limit | 可选，默认 20；1–100 |
+| cursor | 可选，上一页返回值；必须保持 queue_id/state 不变，最长 1024 字符 |
+
+按 (created_at DESC, id DESC) 游标分页，不使用大 offset。不承诺跨页快照：读取过程中状态可能变化。列表省略 payload/result/retry 等大字段，返回摘要。
+
+```sh
+curl "$ORBIT_URL/v1/tasks?queue_id=$ORBIT_QUEUE_ID&state=WAITING&limit=20" \
+  -H "Authorization: Bearer $ORBIT_TOKEN"
+```
+
+```json
+{
+  "request_id":"44444444444444444444444444444444",
+  "data":{
+    "items":[{
+      "id":"22222222222222222222222222222222",
+      "queue_id":"11111111111111111111111111111111",
+      "state":"WAITING","revision":"1",
+      "handler":"file.convert","handler_version":"v1","business_key":"conversion-001",
+      "available_at":"2026-09-17T00:00:00Z","deadline_at":"2026-09-18T00:00:00Z",
+      "attempt_count":0,"created_at":"2026-09-17T00:00:00Z","updated_at":"2026-09-17T00:00:00Z"
+    }]
+  }
+}
+```
+
+还有下一页时返回 data.next_cursor。空结果为 items: []。SDK：`Client.ListTasks(ctx, request)`。
+
+## POST /v1/tasks/{task_id}:cancel
+
+权限：tasks:cancel 和队列范围。当前只允许取消 WAITING 状态且不归属流程的任务。LEASED/RUNNING 或流程任务暂时返回 409，后续由执行与流程控制实现安全取消。
+
+```sh
+curl "$ORBIT_URL/v1/tasks/$TASK_ID:cancel" \
+  -H "Authorization: Bearer $ORBIT_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -H 'Idempotency-Key: conversion-operation-001-cancel' \
+  --data '{"expected_revision":"1","reason":"source object was replaced"}'
+```
+
+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。
+
+SDK：`Client.CancelTask(ctx, taskID, key, request)`。此操作不承诺回滚任何已发生的外部业务效果。
+
+## 错误与回归
+
+| HTTP / code | 处理 |
+| --- | --- |
+| 400 INVALID_ARGUMENT | 修正字段、时间、游标或幂等键 |
+| 401 UNAUTHENTICATED | 检查凭据、到期/撤销和应用/命名空间状态 |
+| 403 PERMISSION_DENIED | 检查动作或提交/列表所需队列范围 |
+| 404 NOT_FOUND | 资源不存在或单资源读取范围不匹配 |
+| 409 IDEMPOTENCY_CONFLICT | 原键已对应其他内容，不应盲目换键重试 |
+| 409 STATE_CONFLICT | 当前状态或版本不允许操作，先查询 |
+| 413 BODY_TOO_LARGE | 减小请求或改为传递业务对象引用 |
+| 415 UNSUPPORTED_MEDIA_TYPE | 使用 application/json |
+| 503 UNAVAILABLE | 结果可能未知；保留原幂等身份，有限退避后核对 |
+
+```json
+{"request_id":"44444444444444444444444444444444","error":{"code":"IDEMPOTENCY_CONFLICT","message":"idempotency key was used with different content"}}
+```
+
+批量受理、执行历史、人工重试和运行中取消尚未实现。完整可运行程序见 [SDK 任务示例](../../sdk/go/examples/tasks/main.go)，已验证异常场景见 [P1 回归报告](../reports/phase-1.md)。SDK 忽略未知响应字段；更改已有字段语义需升级契约和回归。