feat: publish immutable workflow definitions with typed SDK

2026-09-18 00:28:00 +08:00
parent a664ec9370
commit 520e98d9d1
33 changed files with 2603 additions and 11 deletions
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -1,6 +1,6 @@
 # Orbit HTTP / WebSocket 接口手册

-更新：2026-09-17。接口实现状态随 [开发计划](../08-development-plan.md) 更新。
+更新：2026-09-18。接口实现状态随 [开发计划](../08-development-plan.md) 更新。

 ## 当前接口状态

@@ -26,6 +26,7 @@
 | `/v1/schedules`、不可变版本、暂停/恢复及触发查询 | P3 已实现 | [计划接口与 SDK 场景](schedules.md) |
 | `/v1/subscriptions` 及管理、交付查询与重试 | 已实现 HTTP、管理 SDK 和完整管理示例 | [订阅手册](subscriptions.md) |
 | `/v1/events/connect` | 已实现 WSS、消息 Schema、连接 SDK 和自动消费器 | [消息协议](subscriptions.md#5-websocket-建连与边界) / [消费 SDK](../sdk/event-consumer.md) |
+| `/v1/workflow-definitions` 创建、发布与固定版本读取 | P4定义子项已实现，实例执行尚未实现 | [定义接口](workflow-definitions.md)、[格式规范](workflow-definition-format.md) |
 | `/v1/workflows` 与流程管理 | 计划 P4–P5，尚未实现 | [流程接口规划](workflows.md) |

 未实现路由返回 404。健康检查就绪不表示任务执行、定时调度或流程引擎已经可用。
--- a/docs/api/authentication.md
+++ b/docs/api/authentication.md
@@ -61,3 +61,5 @@ P3 应用额度管理新增 `application:resources:read` 和 `application:resour
 P3 独立任务核查、人工重试和操作审计分别增加 `tasks:review`、`tasks:retry`、`tasks:audit:read`，bootstrap显式 `--recovery-access` 才授予三项；默认凭据和 `--worker-access` 都不自动获得。核查/重试记录真实认证凭据及证据，读取任务详情仍需tasks:read，见[人工恢复](task-recovery.md)。

 P3 结果订阅核心新增 `events:read`、`events:manage` 和 `events:consume`，bootstrap 仅显式 `--event-access` 时授予。订阅绑定创建凭据与单个队列，不能用同命名空间的另一张凭据消费或管理。当前 HTTP/WSS、管理及消费 SDK 已接入；凭据重绑继续开发，详见 [订阅接口](subscriptions.md)。
+
+P4定义发布新增`workflows:definitions:read`与`workflows:definitions:publish`，仅显式`--workflow-access`授予。创建/读取元数据作用于命名空间，发布及读取完整版本额外校验全部引用队列；默认提交/Worker凭据不获此权限。发布不创建任务，不要求tasks:submit，详见[定义API](workflow-definitions.md)。
--- a/docs/api/workflow-definition-format.md
+++ b/docs/api/workflow-definition-format.md
@@ -0,0 +1,102 @@
+# 流程定义结构版本1
+
+本页冻结已实现的发布格式与静态校验。TASK、BRANCH、PARALLEL、SIGNAL、TIMER、POLL均可描述并发布；对应实例执行器仍按P4–P5开发，发布成功不能当作流程执行成功。API见[定义发布](workflow-definitions.md)。
+
+## 1. 顶层、顺序块与类型
+
+顶层`schema_version`必须为1；`input_type`声明实例输入；`timeout_ms`为1毫秒至30天的总时限；`failure_policy`必填`REVIEW`或`FAIL_AFTER_SETTLED`；`body`为顺序块。未来实例总时限包含等待和暂停，不能因恢复重新计时；未知外部效果始终需要核查，不能由失败策略覆盖。
+
+一个块包含`steps`（可省略为空，不能为null）、必填`output_type`和`output`。步骤顺序固定，输出表达式在全部步骤完成后解析。空块可以直接映射输入或常量。组合节点只把该块输出暴露给外部，禁止从外部读取内部步骤。
+
+类型对象使用`kind`：
+
+| kind | 附加字段 | 契约 |
+| --- | --- | --- |
+| STRING | 可选`enum: string[]` | 非空枚举最多32项，值互异且每项最多128字节；无enum表示任意有效JSON字符串 |
+| NUMBER | 无 | 精确JSON数字；数字token最长256字节，指数范围等沿用平台JSON边界，不以float64比较 |
+| BOOLEAN / NULL | 无 | 必须精确匹配布尔或null，不做隐式转换 |
+| OBJECT | `fields: map<string,Type>` | 0–64个字段，所有声明字段必填，额外字段不允许；空映射可省略 |
+| ARRAY | 必填`items: Type` | 所有元素同型；运行数据校验最多4096项 |
+| JSON | 无 | 任意合法JSON整体值；不允许根据未知字段或下标做引用 |
+
+类型嵌套最多8层。字段名1–64 ASCII字符，首位字母或数字，其余可含`.`、`_`、`-`；每个path元素按完整字段名匹配，点号不自动展开。类型不支持可选字段、隐式null、联合类型或脚本。
+
+输入/结果校验同时受256 KiB及平台JSON深度和数字边界限制。NUMBER和STRING不互相转换；字符串枚举来源必须是目标枚举子集。OBJECT字段集合必须相同且递归兼容。目标JSON可以接收任意合法类型，JSON来源不能窄化为未验证的具体类型。
+
+## 2. 数据表达式与条件
+
+| Value.kind | 配置 | 说明 |
+| --- | --- | --- |
+| LITERAL | 必填`literal` | 任意合法常量，显式null仅用于允许NULL/JSON的目标；保留原数字文本 |
+| REFERENCE | 必填`reference:{source,path?}` | source为`input`、`workflow`或当前词法作用域已完成步骤key；path最多8个已声明OBJECT字段 |
+| OBJECT | `fields: map<string,Value>` | 构造对象，最多64个字段；输出契约为OBJECT时必须覆盖全部字段 |
+| ARRAY | `items: Value[]` | 构造数组，最多256项；更大业务数组可整体引用 |
+
+表达式最多8层；禁止前向、自引用、跨兄弟分支引用和越过组合节点引用内部步骤。空path引用整个值，不支持数组索引、动态路径、字符串插值、当前时间、随机数或任意代码。`workflow`内置类型为`{id: STRING, business_key: STRING}`。
+
+条件为`Predicate`：比较操作`EQ/NE/LT/LE/GT/GE`必须有`left`和`right`，且类型相同；有序比较只支持STRING、NUMBER，布尔和NULL只支持相等/不等。`AND/OR`使用2–16项`arguments`，`NOT`恰好1项，不能同时携带比较操作数；条件最多8层。STRING按精确文本比较，NUMBER后续执行必须保留十进制精度。
+
+不属于当前kind的非空配置会拒绝；可省略集合与空集合使用统一编码。任何未识别字段仍直接拒绝。
+
+## 3. 步骤
+
+每步必填`key`和`kind`。key在整个定义中唯一，1–64 ASCII字符，名称规则同字段名，保留`input`、`workflow`。必须且只能携带对应的一种配置。
+
+### TASK：普通业务任务
+
+`task`字段：
+
+| 字段 | 类型 / 规则 |
+| --- | --- |
+| queue_id | 必填32位ID；发布时核对当前命名空间、队列存在和权限 |
+| handler / handler_version / payload_version | 必填，沿用Pulse命名与版本规则，Worker承载对应实现 |
+| input_type / input | 必填，处理器参数契约及构造表达式 |
+| result_type | 必填，权威成功结果契约；未来不匹配不能推进后续步骤 |
+| timeout_ms | 必填正值，不超过流程总时限；执行时还受实例剩余时间约束 |
+| retry | 必填显式策略：max_attempts包含首次，1–100；attempt_timeout_ms等按[Pulse规则](retries.md)校验；多次尝试须提供合法退避区间 |
+| recovery_safety | 必填RECONCILE_ONLY或IDEMPOTENT，不接受隐式默认策略 |
+| priority | 可省略为0，0–9 |
+| business_key / concurrency_key | 可选STRING表达式；业务键只用于追踪，资源键按Pulse许可语义使用 |
+
+输入和结果类型不能声明为NULL，任务输入不能是字面null。JSON来源仍可能在运行时产生null，实例引擎必须再次检查实际输入/结果、键长度和Pulse限制，不能把静态通过当作运行数据有效。处理器名/版本是否有在线Worker不在发布时检查，发布不要求Worker正在运行。
+
+### BRANCH：条件分支
+
+`branch.cases`为1–16项`{when: Predicate, body: Block}`，按顺序取第一个匹配路径；`branch.default`必须给出Block。所有路径的output_type必须等价。对外结果是选中路径输出，不允许绕过默认分支或引用仅部分路径存在的内部节点。
+
+### PARALLEL：有限并行与汇合
+
+`parallel.branches`为2–8项`{name,body}`，name在本节点内唯一，规则同字段名。分支分别使用进入该节点前的作用域；全部成功后汇合。节点结果为以分支name命名的OBJECT，例如`outputs.preview`通过source=`outputs`、path=`["preview"]`读取。没有任意交叉边、动态分支或任意JOIN节点。
+
+### SIGNAL：等待输入
+
+`signal`必填`name`（最多128）、`payload_version`（最多32）、`correlation`（STRING表达式）、`payload_type`和`timeout_ms`。名称规则同字段名；等待时限为正值且不超过流程总时限。correlation字面值必须非空且最多512字节，动态值在激活时再检查并冻结。节点输出为经payload_type验证的信号内容。
+
+信号的提前到达、重复、激活关联、授权和竞态处理属于后续实例引擎；本次只验证并保存等待契约。
+
+### TIMER：等待时间
+
+`timer.delay_ms`为正值且不超过流程总时限；输出类型为NULL。等待不占业务Worker并发槽，实际持久化计时和恢复随后实现。
+
+### POLL：有界重复查询
+
+| 字段 | 规则 |
+| --- | --- |
+| task | 完整TASK配置，固定查询处理器与输入；只能查询既有作业，不能重复发起原业务提交 |
+| max_rounds | 1–1000，包含首次查询；每轮单独Pulse任务，单轮重试不增加查询轮次 |
+| timeout_ms | 正值，不超过流程时限；task.timeout_ms不得超过此值 |
+| interval_ms | 至少1000，必须小于查询总时限；从“仍在处理”结果受理后起算，不补发错过轮次 |
+| status_path | 可省略为空，引用task.result_type中的STRING枚举；空表示整个结果就是枚举 |
+| pending / succeeded | 各至少1个枚举值 |
+| failed / review | 可省略为空，与前两组互斥；四组必须无重复、完整覆盖状态枚举 |
+| final_signal | 可选SIGNAL；类型必须等价于查询结果，timeout_ms必须等于查询总时限 |
+
+查询成功且PENDING意味着继续等待；网络或执行错误才按该轮Pulse策略重试。两种预算独立，节点总时限不延长。最终信号不得是PENDING；轮次/时限耗尽、信号与查询同时到达的处理仍由后续运行器实现。发布格式中的配置不提供任意循环能力。
+
+## 4. 整体预算与兼容
+
+最多128个静态步骤（组合节点也计数），顶层块深度0，嵌套块深度不超过4；嵌套并行计算出的业务任务同时运行上界不超过32。SIGNAL/TIMER不占此业务任务并发。所有静态TASK的max_attempts加所有POLL的`max_rounds × max_attempts`不超过10000；条件各路径也全部计入保守预算，不依据当前输入缩减。
+
+定义大小、JSON总深度、类型深度和块深度同时适用，任何一项超限都拒绝；不能仅满足步骤数就忽略深度。完整定义在调用方编码后才有最终字节大小。
+
+结构版本1的既有定义解释必须兼容；将来若改变语义或冻结内容格式，应增加schema_version和独立校验/执行分支，不能原地修改旧版本。业务版本名由研发显式推进；运行实例固定版本及后续恢复兼容是P4–P7待验收项。
--- a/docs/api/workflow-definitions.md
+++ b/docs/api/workflow-definitions.md
@@ -0,0 +1,159 @@
+# 流程定义与不可变版本
+
+状态：P4 定义校验、持久化发布及独立 Go SDK 已实现；实例启动、推进、等待和恢复尚未实现。规则格式见[结构版本1](workflow-definition-format.md)，可运行源码及命令见[研发发布场景](../examples/workflow-definition.md)。
+
+## 1. 权限、传输与范围
+
+使用 HTTPS、`Authorization: Bearer <token>`、统一 `request_id` 信封。POST 必须有唯一 `Idempotency-Key` 头及 `Content-Type: application/json`。请求体最多512 KiB，完整定义编码最多256 KiB，JSON总深度最多32；拒绝未知字段、大小写别名、重复字段、非法Unicode、无效数字和不符合类型的null。
+
+| 接口 | 权限 | 范围 |
+| --- | --- | --- |
+| `POST /v1/workflow-definitions` | `workflows:definitions:publish` | 当前凭据命名空间 |
+| `GET /v1/workflow-definitions/{definition_id}` | `workflows:definitions:read` | 当前命名空间元数据，不返回规则 |
+| `POST /v1/workflow-definitions/{definition_id}/versions` | `workflows:definitions:publish` | 定义及其引用的全部队列 |
+| `GET /v1/workflow-definitions/{definition_id}/versions/{version}` | `workflows:definitions:read` | 定义及其引用的全部队列 |
+
+发布与完整版本读取均在事务中核对队列存在、命名空间归属及当前凭据队列范围。发布不要求`tasks:submit`，不创建任务；发布者可以与运行方分权。默认Bootstrap凭据没有流程权限，显式`--workflow-access`才增加上述两个动作。读取元数据只受命名空间级定义权限限制。
+
+GET不接受查询参数。当前没有定义列表、修改、删除或latest接口；调用方保存创建回执中的定义ID，并显式使用版本名。
+
+## 2. 创建定义
+
+`POST /v1/workflow-definitions`
+
+| 字段 | 类型 | 规则 |
+| --- | --- | --- |
+| name | string | 必填，1–128 ASCII字符；首位字母或数字，其余可含`.`、`_`、`-`；同命名空间唯一且区分大小写 |
+| description | string | 可省略为空，最多1024个Unicode字符，不允许NUL |
+
+```json
+{"name":"object.pipeline","description":"通用对象作业"}
+```
+
+首次创建201，原键重报200。回执示意（实际ID、时间由服务端生成）：
+
+```json
+{
+  "request_id":"0123456789abcdef0123456789abcdef",
+  "data":{
+    "definition":{
+      "id":"1123456789abcdef0123456789abcdef",
+      "namespace_id":"2123456789abcdef0123456789abcdef",
+      "name":"object.pipeline",
+      "description":"通用对象作业",
+      "revision":"1",
+      "created_at":"2026-09-18T00:00:00Z",
+      "updated_at":"2026-09-18T00:00:00Z"
+    },
+    "deduplicated":false
+  }
+}
+```
+
+`GET /v1/workflow-definitions/{definition_id}`的`data`直接返回上述`definition`对象。`revision`为字符串编码的uint64，初始1，每个新版本发布增加1。名称和说明在本阶段没有修改入口。原创建回执保留创建时的revision，当前值通过GET查询。
+
+每个命名空间最多100个定义。不同键重用同一名称返回409；恢复创建结果必须使用原键，不能用名称猜测操作是否成功。
+
+## 3. 发布版本
+
+`POST /v1/workflow-definitions/{definition_id}/versions`
+
+| 字段 | 类型 | 规则 |
+| --- | --- | --- |
+| version | string | 必填，1–64 ASCII字符，名称规则同上；研发指定的业务版本名，不与schema_version混用 |
+| specification | object | 必填，完整结构版本1定义；所有生效任务策略显式冻结 |
+| reason | string | 必填非空白，最多1024个Unicode字符，不允许NUL，写入发布审计 |
+
+最小定义直接返回输入，可用于验证发布链路：
+
+```json
+{
+  "version":"v1",
+  "reason":"initial developer release",
+  "specification":{
+    "schema_version":1,
+    "input_type":{"kind":"STRING"},
+    "timeout_ms":60000,
+    "failure_policy":"REVIEW",
+    "body":{
+      "output_type":{"kind":"STRING"},
+      "output":{"kind":"REFERENCE","reference":{"source":"input"}}
+    }
+  }
+}
+```
+
+首次发布201；原键重报或不同键的同版本同内容发布200。信封`data`为：
+
+```json
+{
+  "version":{
+    "id":"3123456789abcdef0123456789abcdef",
+    "namespace_id":"2123456789abcdef0123456789abcdef",
+    "definition_id":"1123456789abcdef0123456789abcdef",
+    "version":"v1",
+    "specification":{
+      "schema_version":1,
+      "input_type":{"kind":"STRING"},
+      "timeout_ms":60000,
+      "failure_policy":"REVIEW",
+      "body":{
+        "output_type":{"kind":"STRING"},
+        "output":{"kind":"REFERENCE","reference":{"source":"input"}}
+      }
+    },
+    "content_digest":"0000000000000000000000000000000000000000000000000000000000000000",
+    "published_by":"4123456789abcdef0123456789abcdef",
+    "published_at":"2026-09-18T00:00:00Z",
+    "analysis":{"steps":0,"max_concurrency":0,"max_task_attempts":0,"queues":[]}
+  },
+  "deduplicated":false
+}
+```
+
+示意中的全零摘要不是上述请求的实际摘要。实际`content_digest`为64位小写十六进制SHA-256：对已校验结构的规范JSON加域前缀`orbit.weave.spec.v1\0`后计算。对象键顺序、数字的等值十进制表示不影响内容比较；数组顺序属于内容，包括枚举/状态分组数组。数字全程保留精度，不使用float64生成内容摘要。
+
+`published_by`是最初发布凭据ID，`published_at`是原始数据库UTC时间；重复发布不改写。`analysis`按全部静态路径保守计算节点、并发与任务尝试上界，队列排序去重且始终为数组。它不是运行用量或已授予配额。
+
+每个定义最多100个版本。达到上限仍可原键核对和同版本同内容确认。发布v2不改写v1。数据库不可变触发器拒绝UPDATE，关联关系由事务校验，无外键、无级联删除。
+
+## 4. 幂等、并发及未知结果
+
+- 创建操作按命名空间和`workflow.definition.create`隔离；发布按命名空间、`workflow.version.publish`及定义ID隔离。幂等键格式和90天保留窗口沿用[公共规则](tasks.md)。
+- 原键绑定整个命令，包括`reason`。原键不同内容为`IDEMPOTENCY_CONFLICT`；换键不允许覆盖已存在版本，不同规则为`STATE_CONFLICT`。
+- 不同键、相同版本及相同规则返回第一次的版本。后续请求的原因不替换原审计，不增加父定义revision，不重复产生发布审计。
+- 并发控制顺序为认证共享锁→应用额度行→操作身份→定义行→排序后的引用队列。定义、版本、父定义revision、审计和幂等回执同事务提交，审计失败全部回滚。
+- 任何超时、连接中断或503都可能发生在提交前后。保留原ID、版本、内容、原因和键核对，禁止生成新身份或盲目修改规则重发。
+- 每次重报仍核对当前权限和引用队列；权限被收回、队列缺失时不得用旧回执绕过。版本读取还验证存储原文、结构版本和内容摘要，损坏或不兼容数据返回503，不能默默忽略后继续使用。
+
+## 5. 读取与错误
+
+`GET /v1/workflow-definitions/{definition_id}/versions/{version}`的`data`直接返回上述`version`对象，200。输入版本名被严格限制，不能携带路径片段。
+
+| 状态 / code | 处理 |
+| --- | --- |
+| 400 / INVALID_ARGUMENT | 修正结构、引用、类型、预算或字段；此校验拒绝不发布版本 |
+| 401 / UNAUTHENTICATED | 核对凭据与有效期 |
+| 403 / PERMISSION_DENIED | 缺少定义动作权限 |
+| 404 / NOT_FOUND | 定义/版本/队列不存在、不同命名空间或队列范围不允许；不据此猜测他人资源 |
+| 409 / IDEMPOTENCY_CONFLICT | 原键绑定不同命令；回查原操作，不直接换键 |
+| 409 / STATE_CONFLICT | 名称冲突或同版本不同规则；有意更新需显式发布新版本 |
+| 409 / WORKFLOW_DEFINITION_LIMIT | 命名空间达到100个定义，原创建回执仍可恢复 |
+| 409 / WORKFLOW_VERSION_LIMIT | 定义达到100个版本，旧版本确认与读取不受此上限影响 |
+| 413 / BODY_TOO_LARGE | 整个HTTP请求超过512 KiB |
+| 415 / UNSUPPORTED_MEDIA_TYPE | 必须使用application/json |
+| 503 / UNAVAILABLE | 服务/事务/存储完整性异常，原身份核对；持续异常需要运维核查 |
+
+## 6. SDK
+
+独立module为`git.yuntuo.hk/k2safe/orbit/sdk/go`，无服务端模型、数据库或ORM依赖。
+
+| 方法 | 输入 → 返回 |
+| --- | --- |
+| `CreateWorkflowDefinition(ctx,key,in)` | CreateWorkflowDefinitionRequest → WorkflowDefinitionResult |
+| `GetWorkflowDefinition(ctx,id)` | 定义ID → WorkflowDefinition |
+| `PublishWorkflowVersion(ctx,id,key,in)` | PublishWorkflowVersionRequest → WorkflowVersionResult |
+| `GetWorkflowVersion(ctx,id,version)` | 定义ID及固定版本 → WorkflowVersion |
+| `WorkflowRef(source,path...)` | 构造有类型校验的引用表达式；发布时校验作用域 |
+
+规则通过`WorkflowSpecification`、`WorkflowStep`等强类型结构构建，常量使用`json.RawMessage`，避免把大整数先转float64。SDK不复制服务端完整校验器；发布返回权威校验结果。网络错误不会自动重试发布，也不自动变更版本。完整示例见[发布场景](../examples/workflow-definition.md)。
--- a/docs/api/workflows.md
+++ b/docs/api/workflows.md
@@ -1,10 +1,9 @@
-# 流程接口规划
+# 流程接口状态

-状态：计划 P4–P5，尚未实现。研发通过 Go SDK 描述流程并显式发布，服务端保存不可变定义版本。
+状态：定义格式校验、创建与不可变版本发布已实现，详见[定义接口](workflow-definitions.md)、[格式规范](workflow-definition-format.md)和[可运行SDK例子](../examples/workflow-definition.md)。实例执行与管理仍按P4–P5开发。下表仅列后续实例接口。

 | 操作 | 候选接口 | 完成要求 |
 | --- | --- | --- |
-| 发布版本 | `POST /v1/workflow-definitions/{definition_id}/versions` | 图结构、类型、预算校验；同版本同内容幂等，不同内容冲突 |
 | 启动实例 | `POST /v1/workflows` | 固定版本并幂等启动，首批任务与实例原子创建 |
 | 查询实例 | `GET /v1/workflows/{workflow_id}` | 状态、暂停标记、版本、等待原因、预算摘要 |
 | 查询步骤 | `GET /v1/workflows/{workflow_id}/steps` | 步骤、激活、查询轮次、输入/结果引用与任务关联 |