feat: add generic queue and subscription retirement
This commit is contained in:
16
sdk/go/examples/resource-lifecycle/README.md
Normal file
16
sdk/go/examples/resource-lifecycle/README.md
Normal file
@@ -0,0 +1,16 @@
|
||||
# 队列和订阅的通用退役示例
|
||||
|
||||
用途：为一次独立回归创建专属空队列和订阅，然后退役订阅、重报原操作验证幂等、退役队列。不会提交任务，也不会修改现有队列或任何业务凭据。名称随机生成，没有行业或接入方约定。
|
||||
|
||||
需要已部署迁移 000034 的 Orbit、`queues:manage/queues:read/events:manage` 权限及允许创建新队列的范围。配置 `ORBIT_URL` 和 `ORBIT_TOKEN`，或使用 `ORBIT_CREDENTIALS_FILE` 引用自己的 SDK 凭据文件。
|
||||
|
||||
```sh
|
||||
cd sdk/go
|
||||
export ORBIT_URL=http://127.0.0.1:18080
|
||||
export ORBIT_CREDENTIALS_FILE=/absolute/path/to/sdk.credentials.json
|
||||
go run ./examples/resource-lifecycle
|
||||
```
|
||||
|
||||
预期输出只有本次资源 ID，以及 `retired=true history_preserved=true subscription_replay=true`。控制台仍能查询历史，订阅不再占活动名额。
|
||||
|
||||
若中途失败，示例以非零状态退出；保留已经打印的 ID，按[退役规则](../../../../docs/api/resource-retirement.md)核查并收尾。生产部署应持久保存每条退役命令的幂等键、目标及原请求，网络不明确时重报同一条命令。
|
||||
77
sdk/go/examples/resource-lifecycle/main.go
Normal file
77
sdk/go/examples/resource-lifecycle/main.go
Normal file
@@ -0,0 +1,77 @@
|
||||
// resource-lifecycle 创建并退役本次独占的空队列与订阅，不处理任何现有资源。
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"crypto/rand"
|
||||
"encoding/hex"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
orbit "git.yuntuo.hk/k2safe/orbit/sdk/go"
|
||||
"os"
|
||||
"time"
|
||||
)
|
||||
|
||||
func main() {
|
||||
if err := run(); err != nil {
|
||||
fmt.Fprintln(os.Stderr, err)
|
||||
os.Exit(1)
|
||||
}
|
||||
}
|
||||
func run() error {
|
||||
token := os.Getenv("ORBIT_TOKEN")
|
||||
if path := os.Getenv("ORBIT_CREDENTIALS_FILE"); token == "" && path != "" {
|
||||
raw, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
var c struct {
|
||||
Token string `json:"token"`
|
||||
}
|
||||
if err = json.Unmarshal(raw, &c); err != nil {
|
||||
return err
|
||||
}
|
||||
token = c.Token
|
||||
}
|
||||
client, err := orbit.NewClient(os.Getenv("ORBIT_URL"), orbit.Options{Token: token})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
|
||||
defer cancel()
|
||||
var random [16]byte
|
||||
if _, err = rand.Read(random[:]); err != nil {
|
||||
return err
|
||||
}
|
||||
runID := hex.EncodeToString(random[:])
|
||||
q, err := client.CreateQueue(ctx, runID+"-queue", orbit.CreateQueueRequest{Name: "lifecycle-" + runID, MaxConcurrency: 1, RatePerSecond: 10})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
fmt.Printf("queue=%s\n", q.Queue.ID)
|
||||
sub, err := client.CreateSubscription(ctx, runID+"-sub", orbit.CreateSubscriptionRequest{Name: "lifecycle-" + runID, QueueID: q.Queue.ID})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
fmt.Printf("subscription=%s\n", sub.Subscription.ID)
|
||||
in := orbit.RetireResourceRequest{ExpectedRevision: sub.Subscription.Revision, Reason: "isolated lifecycle example completed"}
|
||||
if _, err = client.RetireSubscription(ctx, sub.Subscription.ID, runID+"-retire-sub", in); err != nil {
|
||||
return err
|
||||
}
|
||||
replay, err := client.RetireSubscription(ctx, sub.Subscription.ID, runID+"-retire-sub", in)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if !replay.Deduplicated {
|
||||
return fmt.Errorf("retirement did not preserve operation identity")
|
||||
}
|
||||
retired, err := client.RetireQueue(ctx, q.Queue.ID, runID+"-retire-queue", orbit.RetireResourceRequest{ExpectedRevision: q.Queue.Revision, Reason: "isolated lifecycle example completed"})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if retired.Queue.RetiredAt == nil {
|
||||
return fmt.Errorf("queue retirement missing")
|
||||
}
|
||||
fmt.Println("retired=true history_preserved=true subscription_replay=true")
|
||||
return nil
|
||||
}
|
||||
32
sdk/go/retirement.go
Normal file
32
sdk/go/retirement.go
Normal file
@@ -0,0 +1,32 @@
|
||||
package orbit
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
)
|
||||
|
||||
// RetireResourceRequest 永久退役已结清的资源；保留原键/版本用于未知回执重报。
|
||||
type RetireResourceRequest struct {
|
||||
ExpectedRevision uint64 `json:"expected_revision,string"` // ExpectedRevision 当前配置版本。
|
||||
Reason string `json:"reason"` // Reason 管理原因，写入服务端审计。
|
||||
}
|
||||
|
||||
// RetireQueue 拒绝新工作并保留历史；未结清资源返回 RESOURCE_BUSY。
|
||||
func (c *Client) RetireQueue(ctx context.Context, id, key string, in RetireResourceRequest) (CreateQueueResult, error) {
|
||||
var out CreateQueueResult
|
||||
if !validID(id) {
|
||||
return out, errors.New("invalid queue id")
|
||||
}
|
||||
err := c.call(ctx, "POST", "/v1/queues/"+id+":retire", key, in, &out)
|
||||
return out, err
|
||||
}
|
||||
|
||||
// RetireSubscription 只在结果全部确认后退役，释放活动名额；不可重新启用。
|
||||
func (c *Client) RetireSubscription(ctx context.Context, id, key string, in RetireResourceRequest) (SubscriptionResult, error) {
|
||||
var out SubscriptionResult
|
||||
if !validID(id) {
|
||||
return out, errors.New("invalid subscription id")
|
||||
}
|
||||
err := c.call(ctx, "POST", "/v1/subscriptions/"+id+":retire", key, in, &out)
|
||||
return out, err
|
||||
}
|
||||
@@ -17,19 +17,23 @@ type CreateSubscriptionRequest struct {
|
||||
|
||||
// Subscription 仅包含订阅配置和窗口进度，不包含任何凭据原文。
|
||||
type Subscription struct {
|
||||
ID string `json:"id"`
|
||||
QueueID string `json:"queue_id"`
|
||||
CredentialID string `json:"credential_id"`
|
||||
Name string `json:"name"`
|
||||
Revision uint64 `json:"revision,string"` // Revision 配置版本，不随领取和ACK计数变化。
|
||||
Enabled bool `json:"enabled"` // Enabled 为false时停止新领取，已有证明仍可确认。
|
||||
Types []string `json:"types"`
|
||||
CursorSequence uint64 `json:"cursor_sequence,string"` // CursorSequence 已扫描并建立交付的位置，不等于确认位置。
|
||||
PendingCount uint32 `json:"pending_count"` // PendingCount 包括PENDING、LEASED和EXPIRED。
|
||||
MaxPending uint32 `json:"max_pending"`
|
||||
MaxAttempts uint32 `json:"max_attempts"`
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
UpdatedAt time.Time `json:"updated_at"`
|
||||
// RetiredAt 永久退役时间；退役后不可重新启用且不占活动订阅名额。
|
||||
RetiredAt *time.Time `json:"retired_at,omitempty"`
|
||||
// RetiredSequence 退役时的结果流截止水位，十进制字符串；之后的结果不再订阅。
|
||||
RetiredSequence *uint64 `json:"retired_sequence,string,omitempty"`
|
||||
ID string `json:"id"`
|
||||
QueueID string `json:"queue_id"`
|
||||
CredentialID string `json:"credential_id"`
|
||||
Name string `json:"name"`
|
||||
Revision uint64 `json:"revision,string"` // Revision 配置版本，不随领取和ACK计数变化。
|
||||
Enabled bool `json:"enabled"` // Enabled 为false时停止新领取，已有证明仍可确认。
|
||||
Types []string `json:"types"`
|
||||
CursorSequence uint64 `json:"cursor_sequence,string"` // CursorSequence 已扫描并建立交付的位置，不等于确认位置。
|
||||
PendingCount uint32 `json:"pending_count"` // PendingCount 包括PENDING、LEASED和EXPIRED。
|
||||
MaxPending uint32 `json:"max_pending"`
|
||||
MaxAttempts uint32 `json:"max_attempts"`
|
||||
CreatedAt time.Time `json:"created_at"`
|
||||
UpdatedAt time.Time `json:"updated_at"`
|
||||
}
|
||||
type SubscriptionResult struct {
|
||||
Subscription Subscription `json:"subscription"`
|
||||
|
||||
@@ -177,5 +177,22 @@ func TestIntegrationSubscriptionManagementSDK(t *testing.T) {
|
||||
if err != nil || current.PendingCount != 0 || current.Revision != resumed.Subscription.Revision {
|
||||
t.Fatal("SDK pending count or config version", err)
|
||||
}
|
||||
retireKey := workerTestID(t)
|
||||
retireInput := RetireResourceRequest{ExpectedRevision: current.Revision, Reason: "completed SDK subscription regression"}
|
||||
retired, err := api.RetireSubscription(ctx, sub.ID, retireKey, retireInput)
|
||||
if err != nil || retired.Subscription.RetiredAt == nil {
|
||||
t.Fatal("SDK retire subscription", err)
|
||||
}
|
||||
repeated, err := api.RetireSubscription(ctx, sub.ID, retireKey, retireInput)
|
||||
if err != nil || !repeated.Deduplicated {
|
||||
t.Fatal("SDK retire replay", err)
|
||||
}
|
||||
if _, err = api.GetEventDelivery(ctx, sub.ID, expired.ID); err != nil {
|
||||
t.Fatal("retired delivery history", err)
|
||||
}
|
||||
queueRetired, err := api.RetireQueue(ctx, queue.Queue.ID, workerTestID(t), RetireResourceRequest{ExpectedRevision: queue.Queue.Revision, Reason: "completed SDK queue regression"})
|
||||
if err != nil || queueRetired.Queue.RetiredAt == nil {
|
||||
t.Fatal("SDK retire queue", err)
|
||||
}
|
||||
t.Log("management SDK exercised create/get/list/control/detail/expired retry with a real 30-second delivery lease")
|
||||
}
|
||||
|
||||
@@ -176,6 +176,8 @@ type CreateQueueRequest struct {
|
||||
RatePerSecond uint32 `json:"rate_per_second"`
|
||||
}
|
||||
type Queue struct {
|
||||
// RetiredAt 永久退役时间；为空表示仍可使用，历史查询保持可用。
|
||||
RetiredAt *time.Time `json:"retired_at,omitempty"`
|
||||
// MaxUnfinishedTasks 未终结任务上限，只限制新的受理。
|
||||
MaxUnfinishedTasks uint32 `json:"max_unfinished_tasks"`
|
||||
// UnfinishedTasks 未终结任务数，线上为十进制字符串；变化不增加配置版本。
|
||||
|
||||
Reference in New Issue
Block a user