queue

type AVNodeStore interface {
	GetNode(ctx context.Context, id int64) (*model.Node, error)
	SoftDeleteAndRetag(ctx context.Context, id int64, trashPath, trashHash, origPath string) error
}

type AVScanner interface {
	Supports() bool
	Scan(ctx context.Context, r io.Reader) (infected bool, signature string, err error)
}

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

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

type Driver interface {
	// Init wires the driver to its backing store. Called once at boot.
	Init(ctx context.Context, cfg map[string]any) error

	// Name returns the registered driver name (e.g. "sqlite").
	Name() string

	// Enqueue persists op and returns its assigned id. Op.ID is ignored.
	//
	// When op.DedupKey is non-empty and a pending op already holds that
	// key, implementations MUST return ErrDuplicate and persist nothing.
	// Two concurrent Enqueues with the same key must resolve to exactly
	// one stored op — never zero.
	Enqueue(ctx context.Context, op Op) (id string, err error)

	// Dequeue atomically picks and marks-running the next eligible op.
	// types limits the candidate set — empty slice means any type.
	// Returns ErrEmpty when nothing is ready (callers sleep + retry).
	Dequeue(ctx context.Context, types []string) (Op, error)

	// Ack marks the op completed. Done24h counters bump.
	Ack(ctx context.Context, id string) error

	// Fail records a failure. If retry is true, the op goes back to
	// pending with attempts++; otherwise it terminates as failed.
	Fail(ctx context.Context, id string, errMsg string, retry bool) error

	// List returns ops filtered by status (or empty for any). Pagination
	// via limit/offset; total returns the unpaginated count.
	List(ctx context.Context, status string, limit, offset int) (ops []Op, total int64, err error)

	// Get returns a single op by id. Returns ErrNotFound when missing.
	Get(ctx context.Context, id string) (Op, error)

	// Stats returns aggregated counters for the admin dashboard.
	Stats(ctx context.Context) (Stats, error)

	// Cancel transitions a pending op to cancelled. Running ops cannot
	// be cancelled in v0.1 — the worker checks ctx.Err() but cooperative
	// shutdown is on the caller's handler.
	Cancel(ctx context.Context, id string) error

	// Retry transitions a failed op back to pending (resetting attempts
	// to attempts ≥ 0 — drivers may bump this if they wish). Used by
	// admin UI's "retry" button.
	Retry(ctx context.Context, id string) error

	// RecoverOrphans flips long-running rows back to pending. Called on
	// boot to handle ungraceful shutdowns. olderThan is the threshold
	// (running rows whose started_at < now - olderThan re-queued).
	RecoverOrphans(ctx context.Context, olderThan time.Duration) (int64, error)

	// Close releases resources. Pool calls this on Stop.
	Close() error
}

type Factory func() Driver

type Handler func(ctx context.Context, op Op) error

type NodeGetter interface {
	GetNode(ctx context.Context, id int64) (*model.Node, error)
}

type Op struct {
	ID          string         `json:"id"`
	Type        string         `json:"type"`
	Payload     map[string]any `json:"payload"`
	Status      string         `json:"status"`
	Priority    int            `json:"priority"`
	Attempts    int            `json:"attempts"`
	MaxAttempts int            `json:"max_attempts"`
	LastError   string         `json:"last_error,omitempty"`
	EnqueuedAt  time.Time      `json:"enqueued_at"`
	StartedAt   *time.Time     `json:"started_at,omitempty"`
	FinishedAt  *time.Time     `json:"finished_at,omitempty"`
	NotBefore   *time.Time     `json:"not_before,omitempty"`

	// DedupKey coalesces ops: while a PENDING op holds this key, another
	// Enqueue with the same key is refused with ErrDuplicate instead of
	// creating a second op. Empty (the default) opts out entirely, so every
	// existing caller keeps its behaviour byte for byte.
	//
	// Scoped to `pending` on purpose. The key is released the moment the op
	// is dequeued, so a request that arrives while the op is RUNNING queues
	// a fresh one — the running scan may already have read the old bytes.
	// The failure this ordering avoids is the dangerous one: dropping a
	// request whose content nothing will ever look at. Queueing one scan too
	// many wastes a scan; queueing none is the bug.
	//
	// ⚠ Write-only on the wire: drivers persist and enforce it, but Dequeue,
	// Get and List do NOT populate it back. Assert on the ErrDuplicate
	// behaviour, which is the actual contract, not on the field round-tripping.
	DedupKey string `json:"-"`
}

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

type PoolOption func(*Pool)

type Stats struct {
	Pending   int64 `json:"pending"`
	Running   int64 `json:"running"`
	Failed    int64 `json:"failed"`
	Done24h   int64 `json:"done_24h"`
	Cancelled int64 `json:"cancelled"`
}