asynctask

type CronTask struct {
	Name        string // Use Identifier method to access
	Description string
	Func        TaskFunc
	Total       uint64
	ErrCount    uint64
}

type CronTaskDispatcher interface {
	scene.Named
	// Add will add task with a generated name common uuid
	Add(spec string, cmd TaskFunc) (*CronTask, error)
	// AddWithName will add task with specific name. name should be unique
	AddWithName(spec string, name string, cmd TaskFunc) (*CronTask, error)
	// AddTask is the underlying implementation for Add and AddWithName
	AddTask(spec string, task *CronTask) error
	// Cancel will cancel task have specific identifier
	Cancel(id string) error
	// GetTask will return the underlying task, not copy of the task info.
	// which means user can modify TaskFunc if they need
	GetTask(id string) (*CronTask, error)
}

type HandlerSpec struct {
	// Type is the task type routed by TaskQueueConsumer.
	Type string
	// Handler processes tasks of Type.
	Handler TaskQueueHandler
}

type QueueSpec struct {
	// Queue is the logical queue name registered on TaskQueueConsumer.
	Queue string
	// Config is the queue-level runtime configuration.
	Config TaskQueueConfig
	// Handlers binds task types to handlers in this queue.
	Handlers []HandlerSpec
}

type QueueStats struct {
	Queue    string                    `json:"queue"`
	Total    int64                     `json:"total"`
	ByStatus map[QueueTaskStatus]int64 `json:"by_status"`
}

type QueueTask struct {
	ID string `json:"id"`
	// Queue is the logical queue name.
	// It defines the consumption domain and queue-level runtime config.
	Queue string `json:"queue"`
	// Type is the task type inside a queue.
	// Consumers use it to route the task to a specific handler.
	Type string `json:"type"`
	// Key is an optional business grouping key.
	// It can be used by backends or future schedulers for partitioning,
	// deduplication, or serializing tasks for the same business object.
	Key string `json:"key,omitempty"`
	// Payload is the serialized task body, usually JSON.
	Payload []byte `json:"payload,omitempty"`
	// Headers stores optional metadata for tracing or backend-specific routing.
	Headers map[string]string `json:"headers,omitempty"`
	// Priority orders queued tasks when the backend supports it.
	// Higher values should be consumed before lower values within the same logical queue.
	Priority int `json:"priority,omitempty"`
	// Delay requests delayed execution.
	// The exact behavior depends on the backend implementation.
	Delay time.Duration `json:"delay,omitempty"`
	// Timeout is the handler execution timeout for this task.
	Timeout time.Duration `json:"timeout,omitempty"`
	// MaxRetry overrides the queue-level retry limit when greater than zero.
	MaxRetry    int       `json:"max_retry,omitempty"`
	CreatedAt   time.Time `json:"created_at"`
	AvailableAt time.Time `json:"available_at"`
}

type QueueTaskStatus string

type Task struct {
	Name string
	Func TaskFunc
	Err  error
	// contains filtered or unexported fields
}

type TaskDispatcher interface {
	scene.Named
	// Run run task once, the task should be ended in expected time
	Run(task TaskFunc) *Task
	// RunTask run task once, the task should be ended in expected time
	RunTask(task *Task)
}

type TaskEvent struct {
	TaskID    string          `json:"task_id"`
	Queue     string          `json:"queue"`
	TaskType  string          `json:"task_type"`
	Key       string          `json:"key,omitempty"`
	Status    QueueTaskStatus `json:"status"`
	Attempt   int             `json:"attempt,omitempty"`
	Progress  int             `json:"progress,omitempty"`
	Message   string          `json:"message,omitempty"`
	Error     string          `json:"error,omitempty"`
	UpdatedAt time.Time       `json:"updated_at"`
}

type TaskFunc func() error

type TaskQuery struct {
	Offset      int64             `json:"offset,omitempty"`
	Limit       int64             `json:"limit,omitempty"`
	TaskID      string            `json:"task_id,omitempty"`
	Queue       string            `json:"queue,omitempty"`
	TaskType    string            `json:"task_type,omitempty"`
	Key         string            `json:"key,omitempty"`
	Status      []QueueTaskStatus `json:"status,omitempty"`
	Keyword     string            `json:"keyword,omitempty"`
	UpdatedFrom time.Time         `json:"updated_from,omitempty"`
	UpdatedTo   time.Time         `json:"updated_to,omitempty"`
}

type TaskQueueConfig struct {
	// Concurrency is the number of workers consuming the logical queue.
	Concurrency int
	// MaxRetry is the default retry limit for tasks in the queue.
	MaxRetry int
	// RetryDelay is the default delay before retrying a failed task.
	RetryDelay time.Duration
	// BufferSize is the in-memory queue buffer size.
	// It is only meaningful for in-process backends such as memoryqueue.
	BufferSize int
}

type TaskQueueConsumer interface {
	scene.Named
	// RegisterQueue defines the config of a logical queue.
	// Re-registering the same queue requires an identical config.
	RegisterQueue(queue string, config TaskQueueConfig) error
	// RegisterHandler binds a task type to a logical queue.
	// The queue must be registered before handlers are attached.
	RegisterHandler(queue string, taskType string, handler TaskQueueHandler) error
}

type TaskQueueHandler interface {
	HandleTask(ctx context.Context, task *QueueTask) error
}

type TaskQueueHandlerFunc func(ctx context.Context, task *QueueTask) error

type TaskQueueInspector interface {
	scene.Named
	ListTasks(ctx context.Context, query TaskQuery) (*model.PaginationResult[TaskEvent], error)
	GetTask(ctx context.Context, taskID string) (TaskEvent, error)
	GetQueueStats(ctx context.Context, queue string) (QueueStats, error)
}

type TaskQueuePublisher interface {
	scene.Named
	// Publish enqueues a task to the backend and returns the stored task model.
	// The implementation may populate fields such as ID and CreatedAt.
	Publish(ctx context.Context, task *QueueTask) (*QueueTask, error)
}

type TaskReporter interface {
	scene.Named
	ReportTaskEvent(ctx context.Context, event TaskEvent) error
}

type TaskStatus int32