feat: enforce durable queue resource limits and backpressure

sdk/go/examples/resources/main.go

@@ -0,0 +1,150 @@
+// resources 演示队列暂停、积压背压、幂等核对、释放空间与限速执行。
+package main
+
+import (
+	"context"
+	"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 := os.Getenv("ORBIT_TOKEN")
+	if path := os.Getenv("ORBIT_CREDENTIALS_FILE"); path != "" && token == "" {
+		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
+	}
+	api, err := orbit.NewClient(os.Getenv("ORBIT_URL"), orbit.Options{Token: token})
+	if err != nil {
+		return err
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 25*time.Second)
+	defer cancel()
+	op, err := orbit.NewWorkerMessageID()
+	if err != nil {
+		return err
+	}
+	name := "resources." + op
+	created, err := api.CreateQueue(ctx, "queue-"+op, orbit.CreateQueueRequest{Name: name, MaxConcurrency: 2, RatePerSecond: 1, MaxUnfinishedTasks: 2})
+	if err != nil {
+		return err
+	}
+	q := created.Queue
+	configure := func(paused bool) error {
+		out, err := api.ConfigureQueue(ctx, q.ID, fmt.Sprintf("configure-%s-%t", op, paused), orbit.ConfigureQueueRequest{ExpectedRevision: q.Revision, Reason: "resource control example", Paused: paused, MaxConcurrency: 2, RatePerSecond: 1, MaxUnfinishedTasks: 2})
+		if err == nil {
+			q = out.Queue
+		}
+		return err
+	}
+	if err := configure(true); err != nil {
+		return err
+	}
+	in := orbit.SubmitTaskRequest{QueueID: q.ID, Handler: name, HandlerVersion: "v1", PayloadVersion: "v1", Payload: json.RawMessage(`{"object_ref":"objects/example","n":9007199254740993}`), TaskTimeoutMS: 20000, Retry: orbit.RetryPolicy{MaxAttempts: 1, AttemptTimeoutMS: 10000}}
+	first, err := api.SubmitTask(ctx, "first-"+op, in)
+	if err != nil {
+		return err
+	}
+	second, err := api.SubmitTask(ctx, "second-"+op, in)
+	if err != nil {
+		return err
+	}
+	_, err = api.SubmitTask(ctx, "third-"+op, in)
+	var rejected *orbit.APIError
+	if !errors.As(err, &rejected) || rejected.Code != "QUEUE_FULL" {
+		return fmt.Errorf("expected QUEUE_FULL, got %v", err)
+	}
+	fmt.Printf("backpressure=%s http=%d\n", rejected.Code, rejected.StatusCode)
+	duplicate, err := api.SubmitTask(ctx, "first-"+op, in)
+	if err != nil {
+		return err
+	}
+	if !duplicate.Deduplicated || duplicate.Task.ID != first.Task.ID {
+		return errors.New("original receipt was not preserved")
+	}
+	if _, err := api.CancelTask(ctx, first.Task.ID, "cancel-"+op, orbit.CancelTaskRequest{ExpectedRevision: first.Task.Revision, Reason: "free one unfinished slot"}); err != nil {
+		return err
+	}
+	// 明确 429 表示未受理；释放空间后仍使用第三个任务的原幂等键与原内容。
+	third, err := api.SubmitTask(ctx, "third-"+op, in)
+	if err != nil {
+		return err
+	}
+	fmt.Println("duplicate=true rejected_request_retried=true")
+	w, err := orbit.NewWorker(api, orbit.WorkerOptions{QueueID: q.ID, Capacity: 2, ShutdownTimeout: 5 * time.Second, Handlers: []orbit.WorkerHandler{{Capability: orbit.WorkerCapability{Handler: name, HandlerVersion: "v1", PayloadVersion: "v1"}, Handle: func(ctx context.Context, e orbit.WorkerExecution) (json.RawMessage, error) {
+		if err := ctx.Err(); err != nil {
+			return nil, err
+		}
+		return e.Task.Payload, nil
+	}}}})
+	if err != nil {
+		return err
+	}
+	run, stop := context.WithCancel(ctx)
+	done := make(chan error, 1)
+	go func() { done <- w.Run(run) }()
+	waited := false
+	defer func() {
+		stop()
+		if !waited {
+			<-done
+		}
+	}()
+	if err := configure(false); err != nil {
+		return err
+	}
+	for _, id := range []string{second.Task.ID, third.Task.ID} {
+		for {
+			task, err := api.GetTask(ctx, id)
+			if err != nil {
+				return err
+			}
+			if task.State == orbit.TaskSucceeded {
+				fmt.Printf("task=%s state=%s attempts=%d\n", id, task.State, task.AttemptCount)
+				break
+			}
+			if task.State == orbit.TaskFailed || task.State == orbit.TaskNeedsReview || task.State == orbit.TaskCancelled {
+				return fmt.Errorf("unexpected task state: %s", task.State)
+			}
+			select {
+			case <-ctx.Done():
+				return ctx.Err()
+			case <-time.After(80 * time.Millisecond):
+			}
+		}
+	}
+	q, err = api.GetQueue(ctx, q.ID)
+	if err != nil {
+		return err
+	}
+	if q.UnfinishedTasks != 0 {
+		return errors.New("queue still has unfinished work")
+	}
+	stop()
+	err = <-done
+	waited = true
+	if err != nil {
+		return err
+	}
+	fmt.Printf("unfinished=%d rate_per_second=%d worker_drained=true\n", q.UnfinishedTasks, q.RatePerSecond)
+	return nil
+}