metadata

type EntryScope string

type File struct {
	ID             string
	StorageKey     string
	Filename       string
	ContentType    string
	SizeBytes      int64
	ChecksumSHA256 string         // hex sha-256
	Metadata       map[string]any // JSONB tags
	CreatedAt      time.Time
	UpdatedAt      *time.Time // nil until the first metadata update — a pristine, unmodified file has none
	DeletedAt      *time.Time // soft delete; nil while live
}

type IdempotencyRecord struct {
	Status string  // IdempotencyPending | IdempotencyCompleted
	FileID *string // the produced file id; nil while pending
}

type Job struct {
	ID        string
	ArchiveID string
	Status    JobStatus
	// Selection is the caller's entry indexes. nil means every selectable
	// entry; an empty, non-nil slice selects nothing. The distinction is
	// preserved through storage (null vs []).
	Selection       []int
	CancelRequested bool
	// Attempt counts claims. It is the fencing token on every worker write.
	Attempt int
	// Progress of the current run: Done entries processed of Total intended.
	// A job resumed after an interruption counts only what remained.
	ProgressDone  int
	ProgressTotal int
	// Summary is the extraction summary as JSON, once terminal. nil when the
	// run never produced one (cancelled before it started, or failed before
	// the archive could be opened).
	Summary json.RawMessage
	// Error is the reason when Status is JobFailed.
	Error       string
	HeartbeatAt *time.Time // set while running; nil otherwise
	CreatedAt   time.Time
	UpdatedAt   time.Time
	FinishedAt  *time.Time // set once terminal
}

type JobRepository interface {
	// CreateJob inserts job as pending. created=false with activeID set means
	// another job for the same archive is still pending or running — the
	// unique index refused the insert. activeID may be empty if that job
	// finished between the conflict and the lookup; the caller simply retries.
	// ErrNotFound when the archive row no longer exists.
	CreateJob(ctx context.Context, job *Job) (created bool, activeID string, err error)

	// GetJob returns the job by id, or ErrJobNotFound.
	GetJob(ctx context.Context, id string) (*Job, error)

	// RequestCancel asks a job to stop. A pending job becomes cancelled at
	// once; a running one has its flag set for the worker to honour after
	// the current entry; a terminal one is left as it is. Returns the job's
	// state after the request, or ErrJobNotFound.
	RequestCancel(ctx context.Context, id string) (*Job, error)

	// ClaimJob moves the oldest pending job to running for this caller,
	// bumping Attempt, and returns it — or nil, nil when nothing is pending.
	// Safe across replicas: concurrent callers never claim the same row.
	ClaimJob(ctx context.Context) (*Job, error)

	// HeartbeatJob records progress and liveness for a running job in one
	// round trip and reports whether cancellation has been requested.
	// ErrJobNotFound when the row is not running under this attempt — the
	// caller has lost ownership and must stop.
	HeartbeatJob(ctx context.Context, id string, attempt, done, total int) (cancelRequested bool, err error)

	// FinishJob records a terminal result for a running job. ErrJobNotFound
	// when the row is not running under this attempt.
	FinishJob(ctx context.Context, id string, attempt int, result JobResult) error

	// ParkJob returns a running job to pending — a worker shutting down —
	// keeping its progress. ErrJobNotFound when the row is not running under
	// this attempt.
	ParkJob(ctx context.Context, id string, attempt, done, total int) error

	// ReapJobs returns running jobs that have gone longer than ttl without a
	// heartbeat to pending, so the next pickup resumes them, and reports how
	// many. Judged on the repository's own clock, which also stamps the
	// heartbeat: this is the one comparison where a skew between processes
	// would hand a live run to a second worker.
	ReapJobs(ctx context.Context, ttl time.Duration) (int, error)

	// CountPendingJobs is the queue depth.
	CountPendingJobs(ctx context.Context) (int, error)

	// PurgeFinishedJobs deletes terminal jobs that finished before the cutoff
	// (retention), returning how many. Called by GC.
	PurgeFinishedJobs(ctx context.Context, before time.Time) (int, error)
}

type JobResult struct {
	Status  JobStatus       // JobSucceeded, JobFailed or JobCancelled
	Done    int             // entries processed
	Total   int             // entries the run intended to write
	Summary json.RawMessage // nil when there is none
	Error   string          // the reason, for JobFailed
}

type JobStatus string

type ListFilter struct {
	ContentType string
	Tags        map[string]any // matched against the JSONB metadata column
	Limit       int
	Cursor      string     // exclusive upper-bound file id; empty means first page
	Entries     EntryScope // "" behaves as EntriesInclude

	// IncludeDeleted also returns soft-deleted rows. Every read path stays
	// live-only except extraction's resume logic, which must see the tombstone
	// of an entry the user deleted so that it does not recreate it.
	IncludeDeleted bool
}

type Repository interface {
	// Create inserts a new record. The caller supplies the ID and StorageKey.
	Create(ctx context.Context, f *File) error

	// Get returns the record by ID, or ErrNotFound.
	Get(ctx context.Context, id string) (*File, error)

	// List returns records matching the filter, newest first.
	List(ctx context.Context, filter ListFilter) ([]*File, error)

	// UpdateMetadata writes tags into the record's JSONB metadata: merged into
	// the existing object when merge is true, replacing it wholesale otherwise.
	// A replace preserves keys under ReservedTagPrefix.
	UpdateMetadata(ctx context.Context, id string, tags map[string]any, merge bool) (*File, error)

	// Delete soft-deletes the record by ID (sets deleted_at). The object is
	// purged asynchronously by GC. Returns ErrNotFound if no live row matched.
	Delete(ctx context.Context, id string) error

	// ListDeleted returns up to limit soft-deleted records, oldest first, so GC
	// can purge their objects and then Purge the rows.
	ListDeleted(ctx context.Context, limit int) ([]*File, error)

	// Purge hard-deletes a soft-deleted record by ID, after its object is gone.
	Purge(ctx context.Context, id string) error

	// StorageKeys returns the set of every storage key referenced by the table
	// (any state), so GC can tell which stored objects are orphans.
	StorageKeys(ctx context.Context) (map[string]struct{}, error)

	// ClaimIdempotencyKey atomically claims key as pending. It returns
	// claimed=true if this caller now owns the key; otherwise claimed=false and
	// existing describes the row already present (which may be nil if it raced
	// away). Implemented as INSERT ... ON CONFLICT DO NOTHING.
	ClaimIdempotencyKey(ctx context.Context, key string) (claimed bool, existing *IdempotencyRecord, err error)

	// CreateForKey inserts the file row and marks the (already-claimed) key
	// completed in one transaction, so the two can never disagree after a crash.
	CreateForKey(ctx context.Context, f *File, key string) error

	// ReleaseIdempotencyKey deletes a still-pending claim so a failed upload can
	// be retried under the same key.
	ReleaseIdempotencyKey(ctx context.Context, key string) error

	// PurgeIdempotencyKeys deletes keys created before the cutoff (TTL), returning
	// how many were removed. Called by GC.
	PurgeIdempotencyKeys(ctx context.Context, before time.Time) (int, error)
}