queue

type Arg struct {
	Value any    `json:"value"`
	Type  string `json:"type"`
}

type Args struct {
	// Specify connection
	Connection string
	// Queue specifies queue names as a comma-separated priority list,
	// consumed from left to right.
	Queue string
	// Concurrent num
	Concurrent int
	// Tries maximum attempts
	Tries int
}

type ChainJob struct {
	Delay time.Time `json:"delay"`
	Job   Job       `json:"job"`
	Args  []Arg     `json:"args"`
}

type Config interface {
	config.Config
	Debug() bool
	DefaultConnection() string
	// DefaultQueue returns the first valid queue name configured for the default connection.
	// This is the queue used when dispatching a job without an explicit queue.
	DefaultQueue() string
	DefaultConcurrent() int
	Driver(connection string) string
	FailedDatabase() string
	FailedTable() string
	Via(connection string) any
	// Timeout returns the blocking receive timeout for the given connection,
	// resolved from `queue.connections.<connection>.timeout` (a number of
	// seconds, integer or fractional, or a duration string like "5s"), falling
	// back to DefaultReceiveTimeout when missing, non-positive or unparsable.
	Timeout(connection string) time.Duration
}

type Driver interface {
	// Driver returns the driver name for the driver.
	Driver() string
	// Pop pops the next job off of the queue.
	Pop(queue string) (ReservedJob, error)
	// Push pushes the job onto the queue.
	Push(task Task, queue string) error
}

type DriverCreator interface {
	Create(connection string) (Driver, error)
}

type DriverWithReceive interface {
	// Receive retrieves up to count messages from the queue.
	// It may block until at least one message is available or ctx expires.
	// Returns empty slice and nil error if no messages available within deadline.
	Receive(ctx context.Context, queue string, count int) ([]ReservedJob, error)
}

type FailedJob interface {
	Connection() string
	Queue() string
	FailedAt() *carbon.DateTime
	Retry() error
	Signature() string
	UUID() string
}

type Failer interface {
	All() ([]FailedJob, error)
	Get(connection, queue string, uuids []string) ([]FailedJob, error)
}

type Job interface {
	// Signature set the unique signature of the job.
	Signature() string
	// Handle executes the job.
	Handle(args ...any) error
}

type JobStorer interface {
	All() []Job
	Call(signature string, args []any) error
	Get(signature string) (Job, error)
	Register(jobs []Job)
}

type JobWithShouldRetry interface {
	// ShouldRetry determines if the job should be retried based on the error.
	// maxTries is the queue worker's configured tries: queue.Args.Tries for
	// Worker(args), or 1 for the no-argument Worker() (which hardcodes it).
	// Note that leaving Args.Tries unset passes the zero value 0; both 0 and 1
	// yield a single-shot fallback for jobs without their own retry policy.
	// Implementations without their own retry policy fall back to maxTries.
	ShouldRetry(err error, attempt, maxTries int) (retryable bool, delay time.Duration)
}

type PendingJob interface {
	// Delay dispatches the task after the given delay.
	Delay(time time.Time) PendingJob
	// Dispatch dispatches the task.
	Dispatch() error
	// DispatchSync dispatches the task synchronously.
	DispatchSync() error
	// OnConnection sets the connection of the task.
	OnConnection(connection string) PendingJob
	// OnQueue sets the single queue to which the task is dispatched.
	OnQueue(queue string) PendingJob
}

type Queue interface {
	// Connection gets a driver instance by connection name
	Connection(name string) (Driver, error)
	// Chain creates a chain of jobs to be processed one by one, passing
	Chain(jobs []ChainJob) PendingJob
	// Failer gets failed jobs
	Failer() Failer
	// GetJob gets job by signature
	GetJob(signature string) (Job, error)
	// GetJobs gets all jobs
	GetJobs() []Job
	// JobStorer gets job storer
	JobStorer() JobStorer
	// Job add a job to queue
	Job(job Job, args ...[]Arg) PendingJob
	// Register register jobs
	Register(jobs []Job)
	// Worker create a queue worker
	Worker(payloads ...Args) Worker
}

type ReservedJob interface {
	// Attempts returns the number of times the job has been attempted so far.
	Attempts() int
	// Delete removes the job from the queue.
	Delete() error
	// Release makes the job available again after the given delay so it can
	// be retried, incrementing attempts on the next pop.
	Release(delay time.Duration) error
	// Task returns the task to execute.
	Task() Task
}

type Task struct {
	ChainJob
	UUID  string     `json:"uuid"`
	Chain []ChainJob `json:"chain"`
}

type Worker interface {
	Run() error
	Shutdown() error
}