sdq

type Config struct {
	// DefaultTTR 默认 TTR
	DefaultTTR time.Duration
	// MaxJobSize 最大任务大小（字节）
	MaxJobSize int

	// Ticker 自定义 Ticker 实例（优先级高于 NewTickerFunc）
	Ticker Ticker
	// NewTickerFunc Ticker 构造函数（当 Ticker 为 nil 时使用）
	NewTickerFunc NewTickerFunc

	// MaxTouches 最大 Touch 次数
	MaxTouches int
	// MaxTouchDuration 最大延长时间
	MaxTouchDuration time.Duration
	// MinTouchInterval 最小 Touch 间隔
	MinTouchInterval time.Duration

	// MaxTopics 最大 topic 数（0 表示无限制）
	MaxTopics int
	// MaxJobsPerTopic 每个 topic 最大任务数（0 表示无限制）
	MaxJobsPerTopic int
	// EnableTopicCleanup 启用 Topic 惰性清理（定期清理空 Topic）
	EnableTopicCleanup bool
	// TopicCleanupInterval Topic 清理间隔（默认 1 小时）
	TopicCleanupInterval time.Duration

	// Storage 存储后端实例（优先级高于 NewStorageFunc）
	Storage Storage
	// NewStorageFunc Storage 构造函数（当 Storage 为 nil 时使用）
	NewStorageFunc NewStorageFunc

	// Logger 日志记录器（可选）
	// 如果为 nil，将使用 slog.Default()
	Logger *slog.Logger
}

type Inspector struct {
	// contains filtered or unexported fields
}

type Job struct {
	Meta *JobMeta // 元数据
	// contains filtered or unexported fields
}

type JobMeta struct {
	// === 基本信息 ===
	ID       uint64 // 任务 ID
	Topic    string // 所属 topic
	Priority uint32 // 优先级（数字越小优先级越高）
	State    State  // 当前状态

	// === 时间参数 ===
	Delay time.Duration // 延迟时间（创建时指定）
	TTR   time.Duration // Time To Run - 执行超时时间

	// === 时间戳 ===
	CreatedAt   time.Time // 创建时间
	ReadyAt     time.Time // 就绪时间（延迟任务的到期时间）
	ReservedAt  time.Time // 被保留时间
	LastTouchAt time.Time // 最后一次 Touch 的时间
	BuriedAt    time.Time // 被埋葬时间
	DeletedAt   time.Time // 删除时间（软删除时使用）

	// === 统计信息 ===
	Reserves       int           // 被保留次数
	Timeouts       int           // 超时次数
	Releases       int           // 被释放次数
	Buries         int           // 被埋葬次数
	Kicks          int           // 被踢出次数
	Touches        int           // Touch 次数（TTR 延长）
	TotalTouchTime time.Duration // 累计延长的总时间（用于 MaxTouchDuration 检查）
}

type JobMetaFilter struct {
	Topic  string // 按 topic 过滤，空表示不过滤
	State  *State // 按状态过滤，nil 表示不过滤
	Limit  int    // 返回数量限制，0 表示无限制
	Offset int    // 偏移量，用于分页
	Cursor uint64 // 游标（任务 ID），用于游标分页，0 表示从头开始
}

type JobMetaList struct {
	Metas      []*JobMeta // 任务元数据列表
	Total      int        // 总数（可选，某些实现可能不支持）
	HasMore    bool       // 是否还有更多数据
	NextCursor uint64     // 下一页游标（最后一个任务的 ID）
}

type NewStorageFunc func(ctx context.Context, config *Config) (Storage, error)

type NewTickerFunc func(ctx context.Context, config *Config) (Ticker, error)

type Queue struct {
	// contains filtered or unexported fields
}

type RecoveryCallback func(progress *RecoveryProgress)

type RecoveryPhase int

type RecoveryProgress struct {
	Phase      RecoveryPhase   // 当前阶段
	Result     *RecoveryResult // 恢复结果（仅在 Complete 阶段有值）
	TotalJobs  int             // 总任务数
	LoadedJobs int             // 已加载任务数
	FailedJobs int             // 失败任务数
	Error      error           // 错误信息（仅在 Error 阶段有值）
}

type RecoveryResult struct {
	MaxID      uint64                // 最大任务 ID
	TopicJobs  map[string][]*JobMeta // topic -> jobs
	TotalJobs  int                   // 总任务数
	FailedJobs int                   // 失败的任务数
}

type SortOrder int

type StartOptions struct {
	// RecoveryCallback 恢复进度回调
	// 如果提供了回调，会在恢复过程中调用它报告进度（Start, Recovering 阶段）
	RecoveryCallback RecoveryCallback
}

type State int

type Stats struct {
	// 队列状态
	TotalJobs    int // 总任务数
	ReadyJobs    int // 就绪任务数
	DelayedJobs  int // 延迟任务数
	ReservedJobs int // 保留任务数
	BuriedJobs   int // 埋葬任务数
	Topics       int // topic 数量

	// 操作计数
	Puts     uint64 // Put 操作次数
	Reserves uint64 // Reserve 操作次数
	Deletes  uint64 // Delete 操作次数
	Releases uint64 // Release 操作次数
	Buries   uint64 // Bury 操作次数
	Kicks    uint64 // Kick 操作次数
	Timeouts uint64 // 超时次数
	Touches  uint64 // Touch 操作次数
}

type Storage interface {
	// Name 返回存储名称
	Name() string

	// SaveJob 保存完整任务（元数据 + Body）
	// 只在 Put 时调用，同时保存 meta 和 body
	// Body 不可变，一旦保存就不会修改
	// 如果任务已存在则返回 ErrJobExists
	SaveJob(ctx context.Context, meta *JobMeta, body []byte) error

	// UpdateJobMeta 更新任务元数据
	// 只更新元数据（状态、统计等），不涉及 Body
	// 如果任务不存在则返回 ErrNotFound
	UpdateJobMeta(ctx context.Context, meta *JobMeta) error

	// GetJobMeta 获取任务元数据
	// 如果任务不存在则返回 ErrNotFound
	GetJobMeta(ctx context.Context, id uint64) (*JobMeta, error)

	// ScanJobMeta 扫描任务元数据
	// 支持过滤、分页和游标
	// filter 为 nil 时返回所有任务元数据（用于启动恢复）
	// 启动恢复时：ScanJobMeta(ctx, nil) 加载所有元数据，不加载 Body
	// 性能关键：100 万任务时只需 200MB 内存而不是 10GB
	ScanJobMeta(ctx context.Context, filter *JobMetaFilter) (*JobMetaList, error)

	// GetJobBody 获取任务 Body
	// 如果任务不存在则返回 ErrNotFound
	// Reserve 时才调用，按需加载
	GetJobBody(ctx context.Context, id uint64) ([]byte, error)

	// DeleteJob 删除任务（元数据 + Body）
	// 如果任务不存在则返回 ErrNotFound
	DeleteJob(ctx context.Context, id uint64) error

	// CountJobs 统计任务数量
	// filter 为 nil 时统计所有任务
	CountJobs(ctx context.Context, filter *JobMetaFilter) (int, error)

	// GetMaxJobID 获取最大任务 ID
	// 用于快速启动时初始化 ID 生成器，避免扫描所有任务
	// 如果没有任务则返回 0
	GetMaxJobID(ctx context.Context) (uint64, error)

	// Stats 返回存储统计信息
	Stats(ctx context.Context) (*StorageStats, error)

	// Close 关闭存储
	Close() error
}

type StorageStats struct {
	Name           string // 存储名称
	TotalJobs      int64  // 总任务数
	TotalTopics    int    // 总 topic 数
	MetaSize       int64  // 元数据存储大小（字节）
	BodySize       int64  // Body 存储大小（字节）
	TotalSize      int64  // 总存储大小（字节）
	LastSaveTime   int64  // 最后保存时间（Unix 时间戳）
	LastLoadTime   int64  // 最后加载时间（Unix 时间戳）
	AvgMetaSize    int64  // 平均元数据大小（字节）
	AvgBodySize    int64  // 平均 Body 大小（字节）
	LoadedMetaSize int64  // 已加载元数据大小（字节）
	LoadedBodySize int64  // 已加载 Body 大小（字节）
}

type Tickable interface {
	// ProcessTick 处理 tick 通知
	ProcessTick(now time.Time)

	// NextTickTime 返回下一个需要 tick 的时间
	// 返回 zero time 表示不需要 tick
	NextTickTime() time.Time

	// NeedsTick 是否需要 tick
	NeedsTick() bool
}

type Ticker interface {
	// Name 返回定时器名称
	Name() string

	// Start 启动定时器
	Start()

	// Stop 停止定时器
	Stop()

	// Register 注册需要 tick 的对象
	Register(name string, tickable Tickable)

	// Unregister 取消注册
	Unregister(name string)

	// Wakeup 唤醒定时器（新任务加入时）
	Wakeup()

	// Stats 返回统计信息
	Stats() *TickerStats
}

type TickerStats struct {
	Name            string        // 定时器名称
	RegisteredCount int           // 注册的对象数量
	NextTickTime    time.Time     // 下一个 tick 时间
	TimeUntilTick   time.Duration // 距离下一个 tick 的时间
}

type TopicStats struct {
	Name         string
	ReadyJobs    int
	DelayedJobs  int
	ReservedJobs int
	BuriedJobs   int
	TotalJobs    int
}

type WaitingStats struct {
	Topic          string // Topic 名称
	WaitingWorkers int    // 等待的 worker 数量
}