feat: add bounded task priority and fair application dispatch

sdk/go/examples/priority/main.go

@@ -0,0 +1,116 @@
+// priority 演示近同时到期任务的优先级顺序，真实受理与执行由 Orbit 完成。
+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 := "priority." + op
+	created, err := api.CreateQueue(ctx, "queue-"+op, orbit.CreateQueueRequest{Name: name, MaxConcurrency: 1, RatePerSecond: 100, MaxUnfinishedTasks: 3})
+	if err != nil {
+		return err
+	}
+	var tasks []orbit.Task
+	for _, priority := range []int16{0, 9, 4} {
+		in := orbit.SubmitTaskRequest{QueueID: created.Queue.ID, Handler: name, HandlerVersion: "v1", PayloadVersion: "v1", Payload: json.RawMessage(`{"object_ref":"objects/example","n":9007199254740993}`), Priority: priority, TaskTimeoutMS: 20000, Retry: orbit.RetryPolicy{MaxAttempts: 1, AttemptTimeoutMS: 10000}}
+		out, err := api.SubmitTask(ctx, fmt.Sprintf("task-%s-%d", op, priority), in)
+		if err != nil {
+			return err
+		}
+		tasks = append(tasks, out.Task)
+	}
+	order := make(chan int16, 3)
+	w, err := orbit.NewWorker(api, orbit.WorkerOptions{QueueID: created.Queue.ID, Capacity: 1, 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
+		}
+		order <- e.Task.Priority
+		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
+		}
+	}()
+	for _, task := range tasks {
+		for {
+			v, err := api.GetTask(ctx, task.ID)
+			if err != nil {
+				return err
+			}
+			if v.State == orbit.TaskSucceeded {
+				if v.Priority != task.Priority || v.AttemptCount != 1 {
+					return errors.New("frozen priority or execution count changed")
+				}
+				break
+			}
+			if v.State == orbit.TaskFailed || v.State == orbit.TaskNeedsReview || v.State == orbit.TaskCancelled {
+				return fmt.Errorf("unexpected task state: %s", v.State)
+			}
+			select {
+			case <-ctx.Done():
+				return ctx.Err()
+			case <-time.After(80 * time.Millisecond):
+			}
+		}
+	}
+	got := []int16{<-order, <-order, <-order}
+	if got[0] != 9 || got[1] != 4 || got[2] != 0 {
+		return fmt.Errorf("unexpected dispatch order: %v", got)
+	}
+	stop()
+	err = <-done
+	waited = true
+	if err != nil {
+		return err
+	}
+	fmt.Println("submitted_priorities=0,9,4 executed_priorities=9,4,0")
+	fmt.Println("completed=3 attempts_per_task=1 worker_drained=true")
+	return nil
+}

sdk/go/priority_integration_test.go

@@ -0,0 +1,114 @@
+package orbit
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"reflect"
+	"testing"
+	"time"
+)
+
+func TestIntegrationWorkerRuntimePriority(t *testing.T) {
+	api, _, _ := integrationWorkerClient(t)
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	defer cancel()
+	name := "priority." + workerTestID(t)
+	q, err := api.CreateQueue(ctx, name, CreateQueueRequest{Name: name, MaxConcurrency: 1, RatePerSecond: 100})
+	if err != nil {
+		t.Fatal(err)
+	}
+	base := map[string]any{"queue_id": q.Queue.ID, "handler": name, "handler_version": "v1", "payload_version": "v1", "payload": map[string]any{}}
+	for _, invalid := range []any{-1, 10, 1.5, nil, "9", true} {
+		base["priority"] = invalid
+		var ignored SubmitTaskResult
+		err := api.call(ctx, "POST", "/v1/tasks", workerTestID(t), base, &ignored)
+		var rejected *APIError
+		if !errors.As(err, &rejected) || rejected.StatusCode != 400 {
+			t.Fatalf("invalid priority %v accepted: %v", invalid, err)
+		}
+	}
+	var tasks []Task
+	for _, priority := range []int16{0, 9, 4} {
+		out, err := api.SubmitTask(ctx, workerTestID(t), SubmitTaskRequest{QueueID: q.Queue.ID, Handler: name, HandlerVersion: "v1", PayloadVersion: "v1", Payload: json.RawMessage(`{"n":9007199254740993}`), Priority: priority})
+		if err != nil || out.Task.Priority != priority {
+			t.Fatal("priority not accepted", err)
+		}
+		tasks = append(tasks, out.Task)
+	}
+	observed := make(chan int16, 3)
+	w, err := NewWorker(api, WorkerOptions{QueueID: q.Queue.ID, Capacity: 1, Handlers: []WorkerHandler{runtimeHandler(name, func(ctx context.Context, e WorkerExecution) (json.RawMessage, error) {
+		observed <- e.Task.Priority
+		return e.Task.Payload, nil
+	})}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	run, stop := context.WithCancel(ctx)
+	done := make(chan error, 1)
+	go func() { done <- w.Run(run) }()
+	defer func() {
+		stop()
+		if err := <-done; err != nil {
+			t.Error(err)
+		}
+	}()
+	for _, task := range tasks {
+		v := waitRuntimeState(t, ctx, api, task.ID, TaskSucceeded)
+		if v.Priority != task.Priority {
+			t.Fatal("priority changed")
+		}
+	}
+	got := []int16{<-observed, <-observed, <-observed}
+	if !reflect.DeepEqual(got, []int16{9, 4, 0}) {
+		t.Fatalf("dispatch priorities %v", got)
+	}
+}
+
+func TestIntegrationWorkerProcessPriorityRecovery(t *testing.T) {
+	a := startOrbitProcess(t)
+	_, _, token := integrationWorkerClient(t)
+	api := processClient(t, a, token)
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	defer cancel()
+	name := "priority-crash." + workerTestID(t)
+	q, err := api.CreateQueue(ctx, name, CreateQueueRequest{Name: name, MaxConcurrency: 1, RatePerSecond: 100})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, p := range []int16{0, 9, 4} {
+		if _, err := api.SubmitTask(ctx, workerTestID(t), SubmitTaskRequest{QueueID: q.Queue.ID, Handler: name, HandlerVersion: "v1", PayloadVersion: "v1", Payload: json.RawMessage(`{}`), Priority: p}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	a.kill(t)
+	b := startOrbitProcess(t)
+	if a.nodeID == b.nodeID {
+		t.Fatal("node id reused")
+	}
+	api = processClient(t, b, token)
+	r, err := NewWorkerRegistration(q.Queue.ID, 1, []WorkerCapability{{Handler: name, HandlerVersion: "v1", PayloadVersion: "v1"}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	w, err := api.DialWorker(ctx, r)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer w.Close()
+	if _, err = w.Capacity(ctx, workerTestID(t), WorkerCapacity{Sequence: 1, Capacity: 1}); err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []int16{9, 4, 0} {
+		a, err := w.NextAssignment(ctx)
+		if err != nil || a.Task.Priority != want {
+			t.Fatal("restart lost frozen dispatch order", err)
+		}
+		if _, err = w.Start(ctx, workerTestID(t), a.Attempt()); err != nil {
+			t.Fatal(err)
+		}
+		if _, err = w.Finish(ctx, workerTestID(t), WorkerFinish{Ref: a.Attempt(), Outcome: WorkerSucceeded, Result: json.RawMessage(`{}`)}); err != nil {
+			t.Fatal(err)
+		}
+	}
+}

sdk/go/types.go

@@ -22,6 +22,8 @@ type SubmitTaskRequest struct {
 	BusinessKey string `json:"business_key,omitempty"`
 	// ConcurrencyKey 显式互斥资源键，同命名空间跨队列最多一个有效尝试；不代替业务幂等。
 	ConcurrencyKey string `json:"concurrency_key,omitempty"`
+	// Priority 冻结优先级，0至9，每级30秒排序优势，不改变最早执行时间。
+	Priority int16 `json:"priority,omitempty"`
 	// AvailableAt 最早执行时间；为空表示受理后即可进入派发范围。
 	AvailableAt *time.Time `json:"available_at,omitempty"`
 	// StartDeadlineAt 最晚开始时间；为空表示使用任务总截止时间。
@@ -62,6 +64,8 @@ type Task struct {
 	BusinessKey string `json:"business_key,omitempty"`
 	// ConcurrencyKey 显式互斥资源键，同命名空间跨队列最多一个有效尝试；不代替业务幂等。
 	ConcurrencyKey string `json:"concurrency_key,omitempty"`
+	// Priority 冻结优先级，0至9，每级30秒排序优势，不改变最早执行时间。
+	Priority int16 `json:"priority,omitempty"`
 	// AvailableAt 最早可执行时间，UTC。
 	AvailableAt time.Time `json:"available_at"`
 	// StartDeadlineAt 最晚开始时间；为空时使用任务总截止时间。
@@ -132,6 +136,8 @@ type TaskSummary struct {
 	BusinessKey string `json:"business_key,omitempty"`
 	// ConcurrencyKey 显式互斥资源键，同命名空间跨队列最多一个有效尝试；不代替业务幂等。
 	ConcurrencyKey string `json:"concurrency_key,omitempty"`
+	// Priority 冻结优先级，0至9，每级30秒排序优势，不改变最早执行时间。
+	Priority int16 `json:"priority,omitempty"`
 	// AvailableAt 最早可执行时间，UTC。
 	AvailableAt time.Time `json:"available_at"`
 	// DeadlineAt 任务总截止时间，UTC。

sdk/go/worker_connection.go

@@ -399,6 +399,9 @@ func (w *WorkerConnection) command(ctx context.Context, op, id string, ref Worke
 }
 
 func (w *WorkerConnection) validAssignment(a WorkerAssignment) bool {
+	if a.Task.Priority < 0 || a.Task.Priority > 9 {
+		return false
+	}
 	if (a.Task.ConcurrencyKey == "") != (a.ConcurrencyToken == 0) || (a.Task.ConcurrencyKey != "" && (!w.registration.ConcurrencyKeys || !validConcurrencyKey(a.Task.ConcurrencyKey))) {
 		return false
 	}