docs: consolidate runnable examples and publish v0.1.1 guides

2026-09-24 21:27:25 +08:00
parent e29dec717f
commit 81e56bd633
124 changed files with 1430 additions and 281 deletions
--- a/examples/subscriptions/main.go
+++ b/examples/subscriptions/main.go
@@ -0,0 +1,109 @@
+// subscriptions 演示订阅管理和幂等回执；事件消费及Inbox完整示例随后独立提供。
+package main
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"time"
+
+	orbit "git.yuntuo.hk/k2safe/orbit/sdk/go"
+)
+
+func main() {
+	if err := run(); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+func run() error {
+	token, queue := os.Getenv("ORBIT_TOKEN"), os.Getenv("ORBIT_QUEUE_ID")
+	if path := os.Getenv("ORBIT_CREDENTIALS_FILE"); path != "" {
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return err
+		}
+		var credential struct {
+			Token   string `json:"token"`
+			QueueID string `json:"queue_id"`
+		}
+		if err = json.Unmarshal(raw, &credential); err != nil {
+			return err
+		}
+		if token == "" {
+			token = credential.Token
+		}
+		if queue == "" {
+			queue = credential.QueueID
+		}
+	}
+	if token == "" || queue == "" {
+		return errors.New("provide an event-enabled credential and queue via ORBIT_CREDENTIALS_FILE or environment")
+	}
+	client, err := orbit.NewClient(os.Getenv("ORBIT_URL"), orbit.Options{Token: token})
+	if err != nil {
+		return err
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+	var random [16]byte
+	if _, err = rand.Read(random[:]); err != nil {
+		return err
+	}
+	operation := hex.EncodeToString(random[:])
+	input := orbit.CreateSubscriptionRequest{Name: "results-" + operation, QueueID: queue, Types: []string{"task.succeeded", "task.failed", "task.cancelled", "task.needs_review"}, MaxPending: 100, MaxAttempts: 20}
+	created, err := client.CreateSubscription(ctx, "create-"+operation, input)
+	if err != nil {
+		return err
+	}
+	duplicate, err := client.CreateSubscription(ctx, "create-"+operation, input)
+	if err != nil {
+		return err
+	}
+	if !duplicate.Deduplicated || duplicate.Subscription.ID != created.Subscription.ID {
+		return errors.New("subscription identity was not preserved")
+	}
+	sub := created.Subscription
+	configure := func(enabled bool, key string) error {
+		out, err := client.ConfigureSubscription(ctx, sub.ID, key, orbit.ConfigureSubscriptionRequest{ExpectedRevision: sub.Revision, Enabled: enabled, Reason: "subscription management example"})
+		if err == nil {
+			sub = out.Subscription
+		}
+		return err
+	}
+	if err = configure(false, "pause-"+operation); err != nil {
+		return err
+	}
+	if err = configure(true, "resume-"+operation); err != nil {
+		return err
+	}
+	current, err := client.GetSubscription(ctx, sub.ID)
+	if err != nil {
+		return err
+	}
+	if !current.Enabled || current.Revision != 3 {
+		return errors.New("subscription control state mismatch")
+	}
+	page, err := client.ListSubscriptions(ctx, queue, orbit.SubscriptionPageRequest{Limit: 100})
+	if err != nil {
+		return err
+	}
+	found := false
+	for _, item := range page.Items {
+		found = found || item.ID == sub.ID
+	}
+	if !found {
+		return errors.New("subscription absent from scoped listing")
+	}
+	// 示例不启动消费者。结束时暂停本次订阅，保留配置和审计以便核查。
+	if err = configure(false, "finish-"+operation); err != nil {
+		return err
+	}
+	fmt.Printf("subscription=%s duplicate=true resumed_revision=3\n", sub.ID)
+	fmt.Printf("final_enabled=%t revision=%d pending=%d\n", sub.Enabled, sub.Revision, sub.PendingCount)
+	return nil
+}