k2safe/orbit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: consolidate runnable examples and publish v0.1.1 guides

Browse Source
This commit is contained in:
k2safe
2026-09-24 21:27:25 +08:00
parent e29dec717f
commit 81e56bd633
124 changed files with 1430 additions and 281 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/api/application-resources.md
View File

@@ -121,7 +121,7 @@ curl -X POST "$ORBIT_URL/v1/application/resources:configure" \
## 6. SDK 与可运行场景
SDK 方法：`GetApplicationResources(ctx)` 和 `ConfigureApplicationResources(ctx, key, request)`。完整双命名空间场景源码：[application-resources](../../sdk/go/examples/application-resources/main.go)。
SDK 方法：`GetApplicationResources(ctx)` 和 `ConfigureApplicationResources(ctx, key, request)`。完整双命名空间场景源码：[application-resources](../../examples/application-resources/main.go)。
在仓库根目录，先用已迁移数据库启动服务，并初始化一个独立、空闲的示例应用：
@@ -135,11 +135,11 @@ ORBIT_EXAMPLE_APP_ID=$(sed -n 's/.*"application_id":"\([^"]*\)".*/\1/p' .local/a
go run ./cmd/orbit-admin bootstrap \
--application-id "$ORBIT_EXAMPLE_APP_ID" --namespace second --environment development \
--queue second --resource-access --output .local/app-second.credentials.json
cd sdk/go
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=../../.local/app-first.credentials.json \
ORBIT_SECOND_CREDENTIALS_FILE=../../.local/app-second.credentials.json \
go run ./examples/application-resources
ORBIT_CREDENTIALS_FILE=../.local/app-first.credentials.json \
ORBIT_SECOND_CREDENTIALS_FILE=../.local/app-second.credentials.json \
go run ./application-resources
```
预期：

2
docs/api/batch-tasks.md
View File

@@ -157,4 +157,4 @@ for _, item := range result.Items {
SDK验证输入数量/身份/整体体积及返回数量、顺序、状态和回执归属；不自动重试、拆批或创建新键。`err == nil` 只表示取得可解释的逐项响应。局部错误为 `BatchItemError`，不是顶层APIError；整批HTTP错误仍为APIError，网络错误沿用标准库。独立SDK无数据库依赖。
完整运行命令、输入输出和收尾见 [批量场景](../examples/batch.md)，源码见 [SDK示例](../../sdk/go/examples/batch/main.go)，覆盖范围和实际证据见 [回归报告](../reports/phase-3-batch-tasks.md)。旧客户端继续使用单项接口；新SDK调用旧服务该路由会返回404，不会静默退化为其他语义。
完整运行命令、输入输出和收尾见 [批量场景](../examples/batch.md)，源码见 [SDK示例](../../examples/batch/main.go)，覆盖范围和实际证据见 [回归报告](../reports/phase-3-batch-tasks.md)。旧客户端继续使用单项接口；新SDK调用旧服务该路由会返回404，不会静默退化为其他语义。

6
docs/api/cancellation.md
View File

@@ -88,13 +88,13 @@ return nil, &orbit.WorkerCancellationConfirmed{
## 4. 可运行场景
源码：[cancellation/main.go](../../sdk/go/examples/cancellation/main.go)。使用 [Worker 初始化](../sdk/worker-runtime.md) 的私有凭据文件，需 tasks:submit/read/cancel、workers:connect/consume 和队列范围。此示例只等待停止提示，没有外部业务副作用。
源码：[cancellation/main.go](../../examples/cancellation/main.go)。使用 [Worker 初始化](../sdk/worker-runtime.md) 的私有凭据文件，需 tasks:submit/read/cancel、workers:connect/consume 和队列范围。此示例只等待停止提示，没有外部业务副作用。
```sh
cd sdk/go
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=/private/path/worker.credentials.json \
go run ./examples/cancellation
go run ./cancellation
```
预期输出：

2
docs/api/execution-history.md
View File

@@ -1,6 +1,6 @@
# 执行尝试与证据查询 v1
更新：2026-09-17。四个只读接口及独立 Go SDK 已实现；对应 [可运行示例](../../sdk/go/examples/history/main.go) 和 [回归记录](../reports/phase-2-execution-history.md)。
更新：2026-09-17。四个只读接口及独立 Go SDK 已实现；对应 [可运行示例](../../examples/history/main.go) 和 [回归记录](../reports/phase-2-execution-history.md)。
## 1. 用途与权限

6
docs/api/keyed-concurrency.md
View File

@@ -80,7 +80,7 @@ accepted, err := api.SubmitTask(ctx, "update-object-42-operation-001", orbit.Sub
## 5. 完整可运行场景
源码：[keyed-concurrency/main.go](../../sdk/go/examples/keyed-concurrency/main.go)。示例创建两个专用队列，每条队列提交一个相同资源键的任务；两个自动 Worker 各自容量为 4。处理器调用一个受控内存资源模型，查询尝试确认序号增长，最后模拟旧请求验证它被拒绝。
源码：[keyed-concurrency/main.go](../../examples/keyed-concurrency/main.go)。示例创建两个专用队列，每条队列提交一个相同资源键的任务；两个自动 Worker 各自容量为 4。处理器调用一个受控内存资源模型，查询尝试确认序号增长，最后模拟旧请求验证它被拒绝。
从仓库根目录，在专用开发数据库完成迁移并启动服务：
@@ -94,9 +94,9 @@ go run ./cmd/orbit
上述命令使用预先设置的 `ORBIT_MYSQL_DSN`，服务使用 `ORBIT_HTTP_ADDR=127.0.0.1:8080`。示例凭据需具有全部队列范围的 queues:manage、tasks:submit/read 和 workers:connect/consume。另一个终端执行：
```sh
cd sdk/go
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=/tmp/orbit-keyed.credentials.json go run ./examples/keyed-concurrency
ORBIT_CREDENTIALS_FILE=/tmp/orbit-keyed.credentials.json go run ./keyed-concurrency
```
正常输出：

2
docs/api/operations.md
View File

@@ -3,7 +3,7 @@
`orbit-admin release manifest` 不连接数据库，输出当前二进制内置的构建身份、协议版本和完整迁移名称/校验和。它用于在构建阶段冻结发布证据；输出不含 DSN、凭据、迁移 SQL 或业务数据。
```sh
docker run --rm --entrypoint /usr/local/bin/orbit-admin registry.example/orbit:1.0.0 release manifest > orbit-release-manifest.json
docker run --rm --entrypoint /usr/local/bin/orbit-admin registry.example/orbit:v0.1.1 release manifest > orbit-release-manifest.json
# 本地工作区也可执行：
make release-manifest > orbit-release-manifest.json
```

6
docs/api/priority-and-fairness.md
View File

@@ -69,7 +69,7 @@ Worker 连接不再各自直接并发发起一批数据库领取。节点采用
## 4. SDK 完整场景
源码：[priority/main.go](../../sdk/go/examples/priority/main.go)。创建专用队列，先按 0、9、4 的顺序提交三条任务，再启动容量为 1 的自动 Worker；三条任务在近同时到期的条件下按 9、4、0 执行，每条只有一次尝试。
源码：[priority/main.go](../../examples/priority/main.go)。创建专用队列，先按 0、9、4 的顺序提交三条任务，再启动容量为 1 的自动 Worker；三条任务在近同时到期的条件下按 9、4、0 执行，每条只有一次尝试。
从仓库根目录准备专用开发数据库，设置 ORBIT_MYSQL_DSN 和 `ORBIT_HTTP_ADDR=127.0.0.1:8080` 后：
@@ -83,9 +83,9 @@ go run ./cmd/orbit
凭据需要全部队列范围的 queues:manage、tasks:submit/read、workers:connect/consume。另一个终端执行：
```sh
cd sdk/go
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=/tmp/orbit-priority.credentials.json go run ./examples/priority
ORBIT_CREDENTIALS_FILE=/tmp/orbit-priority.credentials.json go run ./priority
```
预期输出：

8
docs/api/queues.md
View File

@@ -112,7 +112,7 @@ SDK 返回 `*orbit.APIError`，Code=QUEUE_FULL、StatusCode=429、RetryAfter=tim
## 完整 SDK 场景
源码：[resources/main.go](../../sdk/go/examples/resources/main.go)。先完成当前迁移并启动服务，初始化带 Worker 权限且 queues:manage 范围为全部队列的专用开发凭据：
源码：[resources/main.go](../../examples/resources/main.go)。先完成当前迁移并启动服务，初始化带 Worker 权限且 queues:manage 范围为全部队列的专用开发凭据：
```sh
mkdir -p .local
@@ -120,10 +120,10 @@ chmod 700 .local
go run ./cmd/orbit-admin bootstrap \
--application resources-demo --namespace default --environment development \
--queue bootstrap --worker-access --output .local/resources.credentials.json
cd sdk/go
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=../../.local/resources.credentials.json \
go run ./examples/resources
ORBIT_CREDENTIALS_FILE=../.local/resources.credentials.json \
go run ./resources
```
示例创建独立队列（积压 2、并发 2、每秒 1 次开始），暂停后提交两个任务；第三个被拒，重复第一个仍得到原回执；取消第一个释放空间，用第三个原身份重新提交，然后恢复并执行两个纯数据回显任务。

8
docs/api/retries.md
View File

@@ -92,13 +92,13 @@ WorkerFailure 默认 Retryable=false；普通 error、panic、runtime.Goexit 和
## 5. 运行完整示例
源码：[examples/retry/main.go](../../sdk/go/examples/retry/main.go)。先运行当前迁移、服务，并按 [Worker 初始化步骤](../sdk/worker.md#1-可运行的文本规范化示例) 准备具有提交、读取、消费权限的专用凭据。从仓库根目录执行：
源码：[examples/retry/main.go](../../examples/retry/main.go)。先运行当前迁移、服务，并按 [Worker 初始化步骤](../sdk/worker.md#1-可运行的文本规范化示例) 准备具有提交、读取、消费权限的专用凭据。从仓库根目录执行：
```sh
cd sdk/go
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=../../.local/worker.credentials.json \
go run ./examples/retry
ORBIT_CREDENTIALS_FILE=../.local/worker.credentials.json \
go run ./retry
```
输入为 `{"text":" safe retry "}`。第一次处理在产生效果前模拟明确拒绝，第二次执行真正的文本规范化；重试等待由平台持久化安排。

8
docs/api/schedules.md
View File

@@ -178,13 +178,13 @@ go run ./cmd/orbit-admin bootstrap \
--application schedule-demo --namespace default --environment development \
--queue snapshots --worker-access --schedule-access \
--output .local/schedule.credentials.json
cd sdk/go
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=../../.local/schedule.credentials.json \
go run ./examples/schedules
ORBIT_CREDENTIALS_FILE=../.local/schedule.credentials.json \
go run ./schedules
```
前置数据库与目录步骤见 [SDK 接入](../sdk/README.md)。源码：[完整调度示例](../../sdk/go/examples/schedules/main.go)。示例创建暂停的每秒计划，恢复后让自动 Worker 返回对象输入快照，查询两次完成，再暂停并排空。计划本身有十秒结束边界，任务与历史保留；重复运行生成独立身份，不调用外部业务系统。
前置数据库与目录步骤见 [SDK 接入](../sdk/README.md)。源码：[完整调度示例](../../examples/schedules/main.go)。示例创建暂停的每秒计划，恢复后让自动 Worker 返回对象输入快照，查询两次完成，再暂停并排空。计划本身有十秒结束边界，任务与历史保留；重复运行生成独立身份，不调用外部业务系统。
```text
source_kind=SCHEDULE fixed_version=1

2
docs/api/subscriptions.md
View File

@@ -322,6 +322,6 @@ _, err = client.ConfigureSubscription(ctx, current.ID, pauseKey, orbit.Configure
return err
```
[完整管理示例](../../sdk/go/examples/subscriptions/main.go) 的启动、输入输出、失败和保留规则见 [场景文档](../examples/subscriptions.md)。它演示管理与幂等，不启动结果消费者。正式 [事件连接 SDK 与自动消费器](../sdk/event-consumer.md) 已提供接收、ACK、心跳、重连与有界收尾；[完整协议示例](../examples/event-protocol.md) 验证跨连接重报原确认。[独立 MySQL Inbox 示例](../examples/result-inbox.md) 已实现并验证消费者进程退出后的去重。
[完整管理示例](../../examples/subscriptions/main.go) 的启动、输入输出、失败和保留规则见 [场景文档](../examples/subscriptions.md)。它演示管理与幂等，不启动结果消费者。正式 [事件连接 SDK 与自动消费器](../sdk/event-consumer.md) 已提供接收、ACK、心跳、重连与有界收尾；[完整协议示例](../examples/event-protocol.md) 验证跨连接重报原确认。[独立 MySQL Inbox 示例](../examples/result-inbox.md) 已实现并验证消费者进程退出后的去重。
机器可读消息契约见 [events.schema.json](../../protocol/eventsv1/events.schema.json)，使用 Draft 2020-12，clientFrame/serverFrame 分方向约束。运行时额外拒绝重复 JSON 键、超范围 uint64 及非规范 base64url。Schema 不代替授权、状态机、租约及事务校验。

2
docs/api/task-queries.md
View File

@@ -95,7 +95,7 @@ for {
}
```
片段假设已有客户端及time.Time类型from/before；完整可运行源码见[示例](../../sdk/go/examples/task-query/main.go)。SDK校验ID、范围、状态、键长度/UTF-8及时间精度，并用url.Values编码，时间转UTC，不修改调用方时间对象。超时只影响读取，可保持条件重新请求；没有自动重试或自动翻页。
片段假设已有客户端及time.Time类型from/before；完整可运行源码见[示例](../../examples/task-query/main.go)。SDK校验ID、范围、状态、键长度/UTF-8及时间精度，并用url.Values编码，时间转UTC，不修改调用方时间对象。超时只影响读取，可保持条件重新请求；没有自动重试或自动翻页。
## 5. 存储、升级与边界

8
docs/api/task-source.md
View File

@@ -132,10 +132,10 @@ SDK的ScheduleVersion为uint64，JSON仍为字符串；时间使用time.Time。S
| 场景 | 完整源码 | 运行说明与新增输出 |
| --- | --- | --- |
| 单项受理、取消后读取来源 | [tasks](../../sdk/go/examples/tasks/main.go) | [SDK初始化](../sdk/README.md)，source_kind=DIRECT |
| 按计划找到触发任务，再反查来源 | [schedules](../../sdk/go/examples/schedules/main.go) | [计划场景](schedules.md#6-sdk-与完整示例)，source_kind=SCHEDULE、fixed_version=1 |
| 人工核查后创建关联新任务 | [recovery](../../sdk/go/examples/recovery/main.go) | [恢复场景](../examples/recovery.md)，source_kind=MANUAL_RETRY、parent=原任务ID |
| 并行流程完成后核对每项任务来源 | [workflow](../../sdk/go/examples/workflow/main.go) | [流程场景](../examples/workflow.md)，workflow_sources_verified=3、fixed_version=v1 |
| 单项受理、取消后读取来源 | [tasks](../../examples/tasks/main.go) | [SDK初始化](../sdk/README.md)，source_kind=DIRECT |
| 按计划找到触发任务，再反查来源 | [schedules](../../examples/schedules/main.go) | [计划场景](schedules.md#6-sdk-与完整示例)，source_kind=SCHEDULE、fixed_version=1 |
| 人工核查后创建关联新任务 | [recovery](../../examples/recovery/main.go) | [恢复场景](../examples/recovery.md)，source_kind=MANUAL_RETRY、parent=原任务ID |
| 并行流程完成后核对每项任务来源 | [workflow](../../examples/workflow/main.go) | [流程场景](../examples/workflow.md)，workflow_sources_verified=3、fixed_version=v1 |
上述示例均运行在隔离回归中；新发布计划/流程版本后老任务仍指向原版本，人工恢复后旧激活仍可追溯。WORKFLOW是新增来源种类，旧SDK可能按未知种类返回错误；应升级SDK，不能降级为DIRECT。不更改Task/TaskSummary或Worker消息结构，不增加权限配置；新客户端调用旧节点的404/503同样不能理解为DIRECT。

2
docs/api/tasks.md
View File

@@ -203,4 +203,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)。[运行中取消](cancellation.md) 已实现；[批量受理](batch-tasks.md) 已实现逐项结果与原身份补交；[独立任务核查与关联新任务重试](task-recovery.md) 已实现。[执行历史](execution-history.md) 已提供尝试与证据的列表和详情。完整可运行程序见 [SDK 任务示例](../../sdk/go/examples/tasks/main.go)，已验证异常场景见 [P1 回归报告](../reports/phase-1.md) 及 [取消回归](../reports/phase-3-cancellation.md)。SDK 忽略未知响应字段；更改已有字段语义需升级契约和回归。
有限自动重试已实现，具体分类、退避、回执和升级边界见 [安全重试](retries.md)。[运行中取消](cancellation.md) 已实现；[批量受理](batch-tasks.md) 已实现逐项结果与原身份补交；[独立任务核查与关联新任务重试](task-recovery.md) 已实现。[执行历史](execution-history.md) 已提供尝试与证据的列表和详情。完整可运行程序见 [SDK 任务示例](../../examples/tasks/main.go)，已验证异常场景见 [P1 回归报告](../reports/phase-1.md) 及 [取消回归](../reports/phase-3-cancellation.md)。SDK 忽略未知响应字段；更改已有字段语义需升级契约和回归。