Files
MonkeyCode/backend/pkg/tasker/tasker.go

555 lines
13 KiB
Go

package tasker
import (
"context"
"encoding/json"
"errors"
"fmt"
"log/slog"
"strconv"
"strings"
"time"
"github.com/redis/go-redis/v9"
)
// Opt 配置选项
type Opt[T any] func(t *Tasker[T])
// WithPrefix 设置 Redis key 前缀
func WithPrefix[T any](prefix string) Opt[T] {
return func(t *Tasker[T]) {
t.keyPrefix = prefix
}
}
// WithLogger 设置日志
func WithLogger[T any](logger *slog.Logger) Opt[T] {
return func(t *Tasker[T]) {
t.logger = logger
}
}
// WithStreamTrimEnabled 设置是否启用 stream 裁剪
func WithStreamTrimEnabled[T any](enabled bool) Opt[T] {
return func(t *Tasker[T]) {
t.streamTrimEnabled = enabled
}
}
// WithStreamTrimInterval 设置 stream 裁剪间隔
func WithStreamTrimInterval[T any](interval time.Duration) Opt[T] {
return func(t *Tasker[T]) {
if interval > 0 {
t.streamTrimInterval = interval
}
}
}
// WithStreamTrimWindow 设置 stream 裁剪窗口
func WithStreamTrimWindow[T any](window time.Duration) Opt[T] {
return func(t *Tasker[T]) {
if window > 0 {
t.streamTrimWindow = window
}
}
}
// Phase 任务阶段
type Phase string
const (
PhaseCreated Phase = "created"
PhaseStarted Phase = "started"
PhaseRunning Phase = "running"
PhaseFailed Phase = "failed"
PhaseFinished Phase = "finished"
)
var (
ErrTaskExists = errors.New("task already exists")
ErrTaskNotFound = errors.New("task not found")
ErrInvalidTransition = errors.New("invalid state transition")
)
var allowedTransitions = map[Phase]map[Phase]bool{
PhaseCreated: {PhaseStarted: true, PhaseFailed: true},
PhaseStarted: {PhaseRunning: true, PhaseFailed: true},
PhaseRunning: {PhaseFailed: true, PhaseFinished: true},
PhaseFailed: {PhaseRunning: true},
PhaseFinished: {},
}
// Task 泛型任务
type Task[T any] struct {
ID string `json:"id"`
Phase Phase `json:"phase"`
Payload T `json:"payload,omitempty"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
type taskEvent struct {
ID string `json:"id"`
Phase Phase `json:"phase"`
UpdatedAt int64 `json:"updated_at"`
}
// EventHandler 事件处理器
type EventHandler[T any] func(ctx context.Context, task Task[T])
// TaskUpdateFunc 任务更新函数
type TaskUpdateFunc[T any] func(task *Task[T]) error
// Tasker 泛型 Redis 任务状态机
type Tasker[T any] struct {
redis *redis.Client
handlers map[Phase][]EventHandler[T]
keyPrefix string
logger *slog.Logger
streamMax int64
streamTrimEnabled bool
streamTrimInterval time.Duration
streamTrimWindow time.Duration
}
// NewTasker 创建任务状态机
func NewTasker[T any](redis *redis.Client, opts ...Opt[T]) *Tasker[T] {
t := &Tasker[T]{
redis: redis,
handlers: make(map[Phase][]EventHandler[T]),
keyPrefix: "tasker",
logger: slog.Default(),
streamMax: 0,
streamTrimEnabled: true,
streamTrimInterval: 5 * time.Minute,
streamTrimWindow: 72 * time.Hour,
}
for _, opt := range opts {
opt(t)
}
if t.streamTrimEnabled {
go t.startStreamTrim(context.Background())
}
return t
}
// On 注册阶段事件处理器
func (t *Tasker[T]) On(phase Phase, handler EventHandler[T]) {
if handler == nil {
return
}
t.handlers[phase] = append(t.handlers[phase], handler)
}
// CreateTask 创建任务并触发 created 事件
func (t *Tasker[T]) CreateTask(ctx context.Context, id string, payload T) error {
key := t.taskKey(id)
exists, err := t.redis.Exists(ctx, key).Result()
if err != nil {
return err
}
if exists > 0 {
return ErrTaskExists
}
payloadJSON, err := json.Marshal(payload)
if err != nil {
return err
}
now := time.Now()
if err := t.redis.HSet(ctx, key, map[string]any{
"id": id,
"phase": string(PhaseCreated),
"payload": string(payloadJSON),
"created_at": now.UnixMilli(),
"updated_at": now.UnixMilli(),
}).Err(); err != nil {
return err
}
if err := t.redis.SAdd(ctx, t.phaseSetKey(PhaseCreated), id).Err(); err != nil {
return err
}
task := Task[T]{
ID: id,
Phase: PhaseCreated,
Payload: payload,
CreatedAt: now,
UpdatedAt: now,
}
if err := t.publishEvent(ctx, PhaseCreated, task); err != nil {
return err
}
t.triggerLocalHandlers(ctx, PhaseCreated, task)
return nil
}
// SetTaskTTL 设置任务过期时间
func (t *Tasker[T]) SetTaskTTL(ctx context.Context, id string, ttl time.Duration) error {
if ttl <= 0 {
return nil
}
return t.redis.Expire(ctx, t.taskKey(id), ttl).Err()
}
// CleanupTask 清理任务
func (t *Tasker[T]) CleanupTask(ctx context.Context, id string, _ Phase) error {
phases := []Phase{PhaseCreated, PhaseStarted, PhaseRunning, PhaseFailed, PhaseFinished}
for _, p := range phases {
if err := t.redis.SRem(ctx, t.phaseSetKey(p), id).Err(); err != nil {
return err
}
}
return t.redis.Del(ctx, t.taskKey(id)).Err()
}
// GetTask 获取任务
func (t *Tasker[T]) GetTask(ctx context.Context, id string) (Task[T], error) {
key := t.taskKey(id)
data, err := t.redis.HGetAll(ctx, key).Result()
if err != nil {
return Task[T]{}, err
}
if len(data) == 0 {
return Task[T]{}, ErrTaskNotFound
}
var payload T
if p := data["payload"]; p != "" {
_ = json.Unmarshal([]byte(p), &payload)
}
createdMs, _ := strconv.ParseInt(data["created_at"], 10, 64)
updatedMs, _ := strconv.ParseInt(data["updated_at"], 10, 64)
return Task[T]{
ID: data["id"],
Phase: Phase(data["phase"]),
Payload: payload,
CreatedAt: time.UnixMilli(createdMs),
UpdatedAt: time.UnixMilli(updatedMs),
}, nil
}
// Transition 阶段转换
func (t *Tasker[T]) Transition(ctx context.Context, id string, to Phase) error {
return t.TransitionWithUpdate(ctx, id, to, nil)
}
// TransitionWithUpdate 阶段转换并更新任务数据
func (t *Tasker[T]) TransitionWithUpdate(ctx context.Context, id string, to Phase, update TaskUpdateFunc[T]) error {
key := t.taskKey(id)
task, err := t.GetTask(ctx, id)
if err != nil {
return err
}
from := task.Phase
if !t.canTransition(from, to) {
return ErrInvalidTransition
}
if update != nil {
if err := update(&task); err != nil {
return err
}
}
now := time.Now()
task.Phase = to
task.UpdatedAt = now
payloadJSON, err := json.Marshal(task.Payload)
if err != nil {
return err
}
if err := t.redis.HSet(ctx, key, map[string]any{
"phase": string(task.Phase),
"payload": string(payloadJSON),
"updated_at": task.UpdatedAt.UnixMilli(),
}).Err(); err != nil {
return err
}
if err := t.redis.SRem(ctx, t.phaseSetKey(from), id).Err(); err != nil {
return err
}
if err := t.redis.SAdd(ctx, t.phaseSetKey(to), id).Err(); err != nil {
return err
}
if err := t.publishEvent(ctx, to, task); err != nil {
return err
}
t.triggerLocalHandlers(ctx, to, task)
return nil
}
// EnsureStreamsAndGroup 确保各阶段事件流与消费组存在
func (t *Tasker[T]) EnsureStreamsAndGroup(ctx context.Context, group string) error {
phases := []Phase{PhaseStarted, PhaseRunning, PhaseFailed, PhaseFinished}
for _, p := range phases {
if err := t.redis.XGroupCreateMkStream(ctx, t.streamKey(p), group, "0").Err(); err != nil {
if err.Error() != "BUSYGROUP Consumer Group name already exists" {
return err
}
}
}
return nil
}
// StartGroupConsumers 启动消费者组阻塞消费
func (t *Tasker[T]) StartGroupConsumers(ctx context.Context, group, consumer string, block time.Duration, count int64) error {
if count <= 0 {
count = 10
}
if block <= 0 {
block = time.Second
}
streams := []string{
t.streamKey(PhaseStarted), ">",
t.streamKey(PhaseRunning), ">",
t.streamKey(PhaseFailed), ">",
t.streamKey(PhaseFinished), ">",
}
for {
res, err := t.redis.XReadGroup(ctx, &redis.XReadGroupArgs{
Group: group,
Consumer: consumer,
Streams: streams,
Count: count,
Block: block,
}).Result()
if err != nil {
if errors.Is(err, context.Canceled) {
return nil
}
time.Sleep(time.Second)
continue
}
for _, strm := range res {
phase := t.phaseFromStreamKey(strm.Stream)
for _, msg := range strm.Messages {
raw, _ := t.extractTaskJSON(msg)
if len(raw) == 0 {
_ = t.redis.XAck(ctx, strm.Stream, group, msg.ID).Err()
continue
}
var evt taskEvent
if err := json.Unmarshal(raw, &evt); err != nil {
_ = t.redis.XAck(ctx, strm.Stream, group, msg.ID).Err()
continue
}
task, err := t.GetTask(ctx, evt.ID)
if err != nil {
_ = t.redis.XAck(ctx, strm.Stream, group, msg.ID).Err()
continue
}
t.triggerLocalHandlers(ctx, phase, task)
_ = t.redis.XAck(ctx, strm.Stream, group, msg.ID).Err()
}
}
}
}
// ClaimStalePending 认领陈旧的待处理消息
func (t *Tasker[T]) ClaimStalePending(ctx context.Context, phase Phase, group, consumer string, minIdle time.Duration, count int64) error {
if count <= 0 {
count = 100
}
stream := t.streamKey(phase)
start := "0-0"
for {
msgs, next, err := t.redis.XAutoClaim(ctx, &redis.XAutoClaimArgs{
Stream: stream,
Group: group,
Consumer: consumer,
MinIdle: minIdle,
Start: start,
Count: count,
}).Result()
if err != nil {
if errors.Is(err, context.Canceled) {
return nil
}
return err
}
for _, msg := range msgs {
raw, _ := t.extractTaskJSON(msg)
var evt taskEvent
if len(raw) > 0 && json.Unmarshal(raw, &evt) == nil {
task, err := t.GetTask(ctx, evt.ID)
if err == nil {
t.triggerLocalHandlers(ctx, phase, task)
}
}
_ = t.redis.XAck(ctx, stream, group, msg.ID).Err()
}
if next == start {
break
}
start = next
}
return nil
}
// ReconcileStartup 启动期对账扫描
func (t *Tasker[T]) ReconcileStartup(ctx context.Context) error {
phases := []Phase{PhaseStarted, PhaseRunning, PhaseFailed, PhaseFinished}
for _, p := range phases {
visited := make(map[string]struct{})
if err := t.scanSetAndTrigger(ctx, t.phaseSetKey(p), p, visited); err != nil {
return err
}
}
return nil
}
func (t *Tasker[T]) scanSetAndTrigger(ctx context.Context, setKey string, phase Phase, visited map[string]struct{}) error {
cursor := uint64(0)
for {
members, next, err := t.redis.SScan(ctx, setKey, cursor, "", 100).Result()
if err != nil {
return err
}
for _, id := range members {
if _, ok := visited[id]; ok {
continue
}
visited[id] = struct{}{}
task, err := t.GetTask(ctx, id)
if err != nil {
continue
}
t.triggerLocalHandlers(ctx, phase, task)
}
if next == 0 {
break
}
cursor = next
}
return nil
}
func (t *Tasker[T]) publishEvent(ctx context.Context, phase Phase, task Task[T]) error {
evt := taskEvent{
ID: task.ID,
Phase: phase,
UpdatedAt: task.UpdatedAt.UnixMilli(),
}
data, err := json.Marshal(evt)
if err != nil {
return err
}
args := &redis.XAddArgs{
Stream: t.streamKey(phase),
ID: "*",
Values: map[string]any{"data": data},
}
if t.streamMax > 0 {
args.MaxLen = t.streamMax
args.Approx = false
}
return t.redis.XAdd(ctx, args).Err()
}
func (t *Tasker[T]) startStreamTrim(ctx context.Context) {
ticker := time.NewTicker(t.streamTrimInterval)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return
case <-ticker.C:
t.trimStreams(ctx)
}
}
}
func (t *Tasker[T]) trimStreams(ctx context.Context) {
if !t.streamTrimEnabled {
return
}
phases := []Phase{PhaseStarted, PhaseRunning, PhaseFailed, PhaseFinished}
for _, phase := range phases {
if err := t.trimStream(ctx, t.streamKey(phase)); err != nil {
t.logger.With("error", err, "key", t.streamKey(phase)).ErrorContext(ctx, "failed to trim task stream")
}
}
}
func (t *Tasker[T]) trimStream(ctx context.Context, stream string) error {
windowMinID := fmt.Sprintf("%d-0", time.Now().Add(-t.streamTrimWindow).UnixMilli())
err := t.redis.XTrimMinID(ctx, stream, windowMinID).Err()
if err != nil && isNoSuchStreamErr(err) {
return nil
}
return err
}
func isNoSuchStreamErr(err error) bool {
if errors.Is(err, redis.Nil) {
return true
}
return strings.Contains(err.Error(), "no such key")
}
func (t *Tasker[T]) triggerLocalHandlers(ctx context.Context, phase Phase, task Task[T]) {
if handlers := t.handlers[phase]; len(handlers) > 0 {
for _, h := range handlers {
h(ctx, task)
}
}
}
func (t *Tasker[T]) extractTaskJSON(msg redis.XMessage) ([]byte, bool) {
if v, ok := msg.Values["data"]; ok {
switch vv := v.(type) {
case string:
return []byte(vv), true
case []byte:
return vv, true
default:
bs, _ := json.Marshal(v)
return bs, true
}
}
return nil, false
}
func (t *Tasker[T]) canTransition(from, to Phase) bool {
nexts := allowedTransitions[from]
return nexts != nil && nexts[to]
}
func (t *Tasker[T]) taskKey(id string) string {
return fmt.Sprintf("%s:task:%s", t.keyPrefix, id)
}
func (t *Tasker[T]) phaseSetKey(phase Phase) string {
return fmt.Sprintf("%s:phase:%s", t.keyPrefix, phase)
}
func (t *Tasker[T]) streamKey(phase Phase) string {
return fmt.Sprintf("%s:stream:%s", t.keyPrefix, phase)
}
func (t *Tasker[T]) phaseFromStreamKey(stream string) Phase {
for i := len(stream) - 1; i >= 0; i-- {
if stream[i] == ':' {
return Phase(stream[i+1:])
}
}
return PhaseStarted
}