@@ -1,6 +1,6 @@
# 队列接口 v1
状态：P1 已实现创建与 查询。更新、暂停、实际派发并发与速率控制随 P2– 。
状态：已实现创建、 查询、配置替换、暂停/恢复、共享并发、开始速率与未终结任务背压。MySQL 是跨节点额度的权威存储；没有额外缓存或消息队列依赖 。
## POST /v1/queues
@@ -11,6 +11,7 @@
| name | string | 1– `_ . : -` ；命名空间内唯一 |
| max_concurrency | uint32 | 必填， –
| rate_per_second | uint32 | 必填， –
| max_unfinished_tasks | uint32 | 可选，省略/零为 100000； – ，
``` sh
" $ORBIT_URL /v1/queues " \
@@ -30,7 +31,8 @@ curl "$ORBIT_URL/v1/queues" \
"queue" : {
"id" : "11111111111111111111111111111111" ,
"namespace_id" : "33333333333333333333333333333333" ,
"name" : "images" , "paused" : false , "max_concurrency" : 8 , "rate_per_second" : 100 , "revision" : "1"
"name" : "images" , "paused" : false , "max_concurrency" : 8 , "rate_per_second" : 100 ,
"max_unfinished_tasks" : 100000 , "unfinished_tasks" : "0" , "revision" : "1"
}
}
}
@@ -49,3 +51,97 @@ curl "$ORBIT_URL/v1/queues/$ORBIT_QUEUE_ID" -H "Authorization: Bearer $ORBIT_TOK
```
SDK： `Client.GetQueue(ctx, queueID)` 。范围限制、重复创建和同名冲突已纳入 [P1 回归 ](../reports/phase-1.md )。这些配置上限不是生产容量承诺。
unfinished_tasks 为 uint64 的十进制字符串，表示当前 WAITING、LEASED、RUNNING、NEEDS_REVIEW 的总数。它是运行计数，变化不增加队列配置 revision。创建/配置回执保存操作时的快照，获取实时积压需要再次 GetQueue。
## POST /v1/queues/{queue_id}:configure
需要 queues:manage 及对应队列范围。完整替换控制参数，不改变名称、队列身份、已受理任务的冻结策略或历史结果。
| 字段 | 类型 | 要求 |
| --- | --- | --- |
| expected_revision | string | 必填，非零 uint64 的十进制字符串 |
| reason | string | 必填，非空白，最多 1024 个 Unicode 字符，写入审计 |
| paused | bool | 必须显式提供；省略/null 都拒绝 |
| max_concurrency | uint32 | 必填， –
| rate_per_second | uint32 | 必填， –
| max_unfinished_tasks | uint32 | 必填， – ；
``` sh
" $ORBIT_URL /v1/queues/ $ORBIT_QUEUE_ID :configure " \
" Authorization: Bearer $ORBIT_TOKEN " \
'Content-Type: application/json' \
'Idempotency-Key: queue-control-001' \
'{"expected_revision":"1","reason":"limit background traffic","paused":false,"max_concurrency":2,"rate_per_second":1,"max_unfinished_tasks":100}'
```
成功 200 的 data 形状与创建一致，队列配置 revision 加一。配置、并发限制同步、审计、事件和幂等回执在一个事务提交。原键、原 expected_revision 和原内容重报返回原快照， ； ，
SDK： `Client.ConfigureQueue(ctx, queueID, key, orbit.ConfigureQueueRequest{...})` 返回 CreateQueueResult。先 GetQueue 读取版本，网络结果不明时保留原命令核对；只有确认版本冲突并重新评估后，才建立新的配置操作。
## 并发、限速与背压的区别
| 控制 | 实际行为 |
| --- | --- |
| paused=true | 阻止新的领取和 Start；
| max_concurrency | 限制队列有效执行许可，包括 LEASED 和 RUNNING；
| rate_per_second | 每个数据库一秒计数窗口内最多提交的 Start 授权数；续租和原回执重报不计数 |
| max_unfinished_tasks | 限制新任务进入队列；等待、退避、预占、运行、待核查都占一个名额 |
速率窗口由第一次成功 Start 建立，保存到 MySQL；
领取还预留尚未开始尝试所需的窗口空间，额度不足时保持 WAITING， ， ；
降并发不撤销已有许可，超出新上限时等待在途工作收尾再领取；降速率保留当前窗口已用次数；降积压上限保留已有任务，禁止新受理直到低于新上限。调整参数、暂停/恢复、断开连接和节点重启都不能清零使用量。
任务第一次进入 SUCCEEDED、FAILED 或 CANCELLED 时，积压额度同事务减一；重试和待核查不释放、不重复增加。运行中取消只保存意图，仍占名额。迟到证据及重复确认不改变计数。人工核查解除入口仍待 P5，
### HTTP 429 QUEUE_FULL
满额时新的 Submit 返回 429， `Retry-After: 1` ，错误信封为：
``` json
{ "request_id" : "44444444444444444444444444444444" , "error" : { "code" : "QUEUE_FULL" , "message" : "queue unfinished task limit reached; retry later using the original identity" } }
```
该请求没有受理任务，新增占位幂等记录也回滚。已受理请求的同身份重报优先返回原回执，不被当前满额拒绝。释放空间后使用被拒请求的原键、原内容有限重试；建议至少等待 Retry-After 并加入抖动/总截止。若绝对 available_at/start_deadline_at 已过期，原请求会被参数规则拒绝，不能无限重试。
SDK 返回 `*orbit.APIError` ， ；
计划触发也使用相同名额。部分补跑已生成的任务正常提交；满额的原触发点保留为下一游标，不创建假任务或跳过记录。下一批继续使用冻结的漏跑策略，因此等待期间超过补偿窗口的点仍可能按策略记录 SKIPPED。队列暂停仅控制执行，
## 完整 SDK 场景
源码：[resources/main.go ](../../sdk/go/examples/resources/main.go )。先完成当前迁移并启动服务，初始化带 Worker 权限且 queues:manage 范围为全部队列的专用开发凭据：
``` sh
chmod 700 .local
go run ./cmd/orbit-admin bootstrap \
\
cd sdk/go
ORBIT_URL = http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE = ../../.local/resources.credentials.json \
```
示例创建独立队列（积压 2、并发 2、每秒 1 次开始），暂停后提交两个任务；第三个被拒，重复第一个仍得到原回执；取消第一个释放空间，用第三个原身份重新提交，然后恢复并执行两个纯数据回显任务。
``` text
duplicate=true rejected_request_retried=true
task=<第二个任务ID> state=SUCCEEDED attempts=1
task=<第三个任务ID> state=SUCCEEDED attempts=1
unfinished=0 rate_per_second=1 worker_drained=true
```
每次运行创建独立队列和任务，历史保留，不硬删除。无外部业务副作用；任务自带 20 秒总截止，失败非零退出并有界收尾。示例遇到未知网络结果会退出，不自动换键重建资源。
## 升级与未完成范围
000009 增加四个带中文说明的队列字段，回填所有既有未终结任务；旧配置版本及任务内容保持不变。先停止旧服务和写入，运行迁移，再启动新版。只读检查不能代替升级维护窗口；大表回填及混合版本升级待生产环境验证。
创建命令省略新字段时， ， ； ，
本阶段验证见 [资源控制报告 ](../reports/phase-3-queue-resources.md )。仍需应用级跨命名空间配额、同业务键许可、可配置优先级及应用间公平性、可靠事件积压限制和容量验收；不能用单队列控制替代这些要求。
