store

type Attempt struct {
	ID             int64
	TaskPK         int64
	QueueID        int64
	Number         int
	DispatchTime   time.Time
	ResponseTime   *time.Time
	ResponseStatus int // 0 = no response
	ErrorKind      string
	ErrorSnippet   string
	Duration       time.Duration
}

type ClaimBudget struct {
	QueueID  int64
	N        int
	PurgedAt *time.Time
}

type Event struct {
	Kind         EventKind
	QueueID      int64
	Queue        string
	ScheduleTime time.Time // EventTaskReady
	TaskPK       int64     // EventRunTask
}

type EventKind int

type HTTPTarget struct {
	BaseURL         string            // resolves relative task paths; "" = tasks must use absolute URLs
	Method          string            // "" = no override
	HeaderOverrides map[string]string // merged over task headers; queue wins
	SigningSecret   string            // Standard Webhooks secret ("whsec_..."); "" = unsigned
}

type ListQueuesOpts struct {
	NamePrefix string
	PageSize   int
	PageToken  string
}

type ListTasksOpts struct {
	Queue     string
	State     TaskState // "" = all non-deleted
	IDPrefix  string
	View      View
	PageSize  int
	PageToken string
}

type NewTask struct {
	Queue            string
	ID               string // "" = server-generated
	URL              string
	Method           string
	Headers          map[string]string
	Body             []byte
	DispatchDeadline time.Duration
	RetryOverride    *RetryOverride
	ScheduleTime     time.Time
}

type Outcome int

type Queue struct {
	ID              int64
	Name            string
	State           QueueState
	RateLimits      RateLimits
	Retry           RetryConfig
	Target          HTTPTarget
	DeadLetterQueue string
	PurgedAt        *time.Time
	ConfigVersion   int64
	CreatedAt       time.Time
	UpdatedAt       time.Time
}

type QueuePatch struct {
	State                   *QueueState
	MaxDispatchesPerSecond  *float64
	MaxBurstSize            *int
	MaxConcurrentDispatches *int
	RetryMaxAttempts        *int
	RetryMaxRetryDuration   *time.Duration
	RetryMinBackoff         *time.Duration
	RetryMaxBackoff         *time.Duration
	RetryMaxDoublings       *int
	TargetBaseURL           *string
	TargetMethod            *string
	TargetHeaderOverrides   *map[string]string
	SigningSecret           *string
	DeadLetterQueue         *string
}

type QueueSeed struct {
	QueueID      int64
	Pending      int64
	Leased       int64
	NextSchedule *time.Time
}

type QueueState string

type QueueStats struct {
	Pending         int64 // due now or overdue
	Running         int64
	Succeeded       int64
	Failed          int64
	ScheduledFuture int64 // pending with schedule_time in the future
	OldestDueAt     *time.Time
	Dispatched1m    int64
	Errors1m        int64
	Dispatched1h    int64
	Errors1h        int64
}

type QueueUpsert struct {
	Name            string
	RateLimits      RateLimits
	Retry           RetryConfig
	Target          HTTPTarget
	KeepSecret      bool // true = leave stored signing secret untouched (secret omitted from request)
	DeadLetterQueue string
}

type RateLimits struct {
	MaxDispatchesPerSecond  float64
	MaxBurstSize            int // 0 = auto: clamp(ceil(rate), 1, 500)
	MaxConcurrentDispatches int
}

type RetryConfig struct {
	MaxAttempts      int           // includes the first attempt; -1 = unlimited
	MaxRetryDuration time.Duration // measured from the first attempt; 0 = unlimited
	MinBackoff       time.Duration
	MaxBackoff       time.Duration
	MaxDoublings     int
}

type RetryOverride struct {
	MaxAttempts      *int           `json:"max_attempts,omitempty"`
	MaxRetryDuration *time.Duration `json:"max_retry_duration_ms,omitempty"`
	MinBackoff       *time.Duration `json:"min_backoff_ms,omitempty"`
	MaxBackoff       *time.Duration `json:"max_backoff_ms,omitempty"`
	MaxDoublings     *int           `json:"max_doublings,omitempty"`
}

type Store interface {
	Migrate(ctx context.Context) error
	Ping(ctx context.Context) error
	Close() error
	Dialect() string

	// Events streams dispatcher wakeup hints (task ready, queue config
	// changed, force-run). Best-effort: events may be dropped under load;
	// the dispatcher reconcile loop is the correctness backstop.
	Events() <-chan Event

	// Queues
	UpsertQueue(ctx context.Context, u QueueUpsert, now time.Time) (Queue, UpsertOutcome, error)
	CreateQueue(ctx context.Context, u QueueUpsert, now time.Time) (Queue, error)
	PatchQueue(ctx context.Context, name string, p QueuePatch, now time.Time) (Queue, error)
	GetQueue(ctx context.Context, name string) (Queue, error)
	GetQueuesByID(ctx context.Context, ids []int64) ([]Queue, error)
	ListQueues(ctx context.Context, opts ListQueuesOpts) ([]Queue, string, error)
	DeleteQueue(ctx context.Context, name string) error
	// SetQueueState is used by pause/resume; disabled is set via PatchQueue.
	SetQueueState(ctx context.Context, name string, state QueueState, now time.Time) (Queue, error)
	PurgeQueue(ctx context.Context, name string, now time.Time) (Queue, error)
	QueueStats(ctx context.Context, name, idPrefix string, now time.Time) (QueueStats, error)

	// Tasks
	CreateTask(ctx context.Context, t NewTask, now time.Time) (Task, error)
	CreateTasks(ctx context.Context, ts []NewTask, now time.Time) ([]TaskResult, error)
	GetTask(ctx context.Context, queue, taskID string, view View) (Task, error)
	ListTasks(ctx context.Context, opts ListTasksOpts) ([]Task, string, error)
	// DeleteTask tombstones the row (state=deleted) for the dedup window.
	DeleteTask(ctx context.Context, queue, taskID string, now time.Time) error
	// ForceRun moves a pending task's schedule_time to now and emits
	// EventRunTask. The dispatcher dispatches it immediately, bypassing
	// rate limits and PAUSED state (GCP parity).
	ForceRun(ctx context.Context, queue, taskID string, now time.Time) (Task, error)
	ListAttempts(ctx context.Context, queue, taskID string) ([]Attempt, error)

	// Dispatcher
	SeedDispatch(ctx context.Context) ([]QueueSeed, error)
	// ClaimTasks atomically leases up to budget.N due pending tasks per
	// queue, incrementing dispatch_count and stamping first_attempt_at.
	ClaimTasks(ctx context.Context, now time.Time, leaseToken string, leaseGrace time.Duration, budgets []ClaimBudget) ([]Task, error)
	// ClaimTaskForRun leases one specific task regardless of schedule_time
	// or queue pause state (still refuses disabled queues).
	ClaimTaskForRun(ctx context.Context, now time.Time, leaseToken string, leaseGrace time.Duration, taskPK int64) (Task, bool, error)
	// NextPending returns the min schedule_time among pending tasks.
	NextPending(ctx context.Context, queueID int64, now time.Time) (*time.Time, error)
	// FinishAttempt records the attempt and applies the outcome, fenced on
	// (taskPK, leaseToken, state=leased). Returns false when the fence
	// fails (lease expired/stolen or task deleted/purged) — the result is
	// then discarded.
	FinishAttempt(ctx context.Context, now time.Time, taskPK int64, leaseToken string, att Attempt, outcome Outcome, nextSchedule time.Time) (bool, error)
	ListExpiredLeases(ctx context.Context, now time.Time, limit int) ([]Task, error)
	// CleanupTerminal hard-deletes terminal rows older than their TTL
	// (floored by the dedup window). Returns rows deleted.
	CleanupTerminal(ctx context.Context, now time.Time, succeededTTL, failedTTL, dedupWindow time.Duration, limit int) (int64, error)
	// HardDeletePurged removes pending tasks superseded by a purge watermark.
	HardDeletePurged(ctx context.Context, limit int) (int64, error)
}

type Task struct {
	PK               int64
	QueueID          int64
	Queue            string // queue name (joined for convenience)
	ID               string
	State            TaskState
	URL              string // absolute URL or path starting with "/" (resolved at dispatch)
	Method           string
	Headers          map[string]string
	Body             []byte
	DispatchDeadline time.Duration
	RetryOverride    *RetryOverride
	ScheduleTime     time.Time
	CreatedAt        time.Time
	FirstAttemptAt   *time.Time
	FinishedAt       *time.Time
	DispatchCount    int
	ResponseCount    int
	LeaseToken       string
	LeaseExpiresAt   *time.Time
	LastAttemptAt    *time.Time
	LastStatus       int // 0 = none
	LastError        string
}

type TaskResult struct {
	Task Task
	Err  error // ErrAlreadyExists etc.; nil on success
}

type TaskState string

type UpsertOutcome int

type View string