store

type ClaimStatus string

type ClaimStore interface {
	// Embedding storage.ClaimConsumer guarantees ClaimStore always
	// exposes at least the public surface: any addition to ClaimConsumer
	// propagates here automatically, while purely internal operations
	// live as direct ClaimStore methods. Only claims with
	// Status='uploaded' are eligible for Consume; pending claims behave
	// as if they did not exist and surface ErrClaimNotFound.
	storage.ClaimConsumer

	// Create persists a new pending claim. Returns an error if a row with
	// the same Key already exists.
	Create(ctx context.Context, claim *UploadClaim) error

	// SetUploadID sets the upload_id field on an existing claim row.
	// Used by the upload init flow to attach a backend multipart session
	// ID after the claim row has been persisted (INSERT-first ordering).
	// Returns ErrClaimNotFound when no row matches id.
	SetUploadID(ctx context.Context, id, uploadID string) error

	// MarkUploaded flips claim.status from 'pending' to 'uploaded' inside
	// tx so the business layer can consume the claim. Used by the
	// complete_upload (and synchronous single-shot upload) paths once
	// the underlying object is finalized. Returns ErrClaimNotFound when
	// no row matches id. An expired-but-finalized pending claim may still
	// be recovered by the claim sweeper with this method.
	MarkUploaded(ctx context.Context, tx orm.DB, id string) error

	// MarkUploadedIfPendingExpired conditionally flips claim.status from
	// 'pending' to 'uploaded' for an expired row matching the supplied
	// claim snapshot. It returns true only when this transaction won the
	// race to update the row. Used by the claim sweeper after it verifies
	// the backend object outside the database transaction.
	MarkUploadedIfPendingExpired(ctx context.Context, tx orm.DB, claim UploadClaim, cutoff timex.DateTime) (bool, error)

	// Get returns the claim by ID, or ErrClaimNotFound.
	Get(ctx context.Context, id string) (*UploadClaim, error)

	// CountPendingByOwner returns the number of claims with
	// status='pending' owned by the given principal. Used by init_upload
	// to enforce the per-user in-flight session cap. The cap is
	// best-effort: this count and the follow-up Create are separate
	// statements, so a concurrent burst from one principal may overshoot
	// the limit by the number of in-flight requests (a DoS-hygiene limit,
	// not a hard boundary).
	CountPendingByOwner(ctx context.Context, owner string) (int, error)

	// ListExpired returns up to limit pending claims whose ExpiresAt is
	// before now. Uploaded claims are intentionally excluded: their
	// finalized objects are awaiting business consumption and must not be
	// reaped if Consume happens after the original TTL.
	//
	// Non-transactional: callers that perform follow-up writes later must
	// protect them with conditional predicates such as status='pending'
	// and the original snapshot fields (see DeleteIfPendingExpired).
	ListExpired(ctx context.Context, now timex.DateTime, limit int) ([]UploadClaim, error)

	// Delete removes a single claim row inside tx. Used by the
	// abort_upload flow so the part-row cascade and the claim-row delete
	// commit together; best-effort cleanup callers may wrap a one-shot
	// RunInTx around it.
	Delete(ctx context.Context, tx orm.DB, id string) error

	// DeleteIfPendingExpired conditionally removes one expired pending
	// claim matching the supplied snapshot. It returns true only when
	// this transaction won the race to delete the row.
	DeleteIfPendingExpired(ctx context.Context, tx orm.DB, claim UploadClaim, cutoff timex.DateTime) (bool, error)
}

type DeleteQueue interface {
	// Enqueue is the only method business code reaches through the
	// public storage.DeleteEnqueuer interface. Embedding keeps the two
	// surfaces in lock-step at compile time.
	storage.DeleteEnqueuer

	// Insert writes fully-formed rows inside tx. Used by the claim
	// sweeper to forward UploadID + claim_expired reason on a per-row
	// basis. items may be empty (no-op).
	//
	// Unlike Enqueue, Insert does NOT deduplicate items before issuing
	// the INSERT — the public Enqueue path dedupes the (key, reason)
	// pair, while Insert callers must either supply already-unique rows
	// or rely on the (object_key, reason) UNIQUE constraint's
	// ON CONFLICT DO NOTHING for idempotency.
	Insert(ctx context.Context, tx orm.DB, items []PendingDelete) error

	// Lease atomically claims up to limit rows whose NextAttemptAt <= now,
	// pushing each claimed row's NextAttemptAt to now+leaseDuration.
	// Returned rows are the worker's responsibility until Done or Defer is
	// called or the lease expires. leaseDuration should comfortably exceed
	// expected per-item processing time (e.g. 5 minutes for object delete).
	Lease(ctx context.Context, now timex.DateTime, limit int, leaseDuration time.Duration) ([]PendingDelete, error)

	// Done removes the rows identified by ids in a single batch (DELETE)
	// inside tx, so the caller can commit the delete alongside any
	// follow-up bookkeeping (typically an outbox event publish). ids
	// may be empty (no-op).
	Done(ctx context.Context, tx orm.DB, ids []string) error

	// Defer atomically increments Attempts and sets NextAttemptAt = nextAt
	// for the row identified by id, inside tx. The worker uses this on
	// transient failure with an exponential-backoff timestamp, or on
	// dead-letter park together with a co-committed dead-letter event.
	//
	// Returns result.ErrRecordNotFound when the row no longer exists —
	// typically because another worker instance (or a later tick of
	// this one) already finalized it after the lease expired. Callers
	// MUST treat this as a benign cross-instance race rather than a
	// failure.
	Defer(ctx context.Context, tx orm.DB, id string, nextAt timex.DateTime) error
}

type PendingDelete struct {
	orm.BaseModel `json:"-" bun:"table:sys_storage_pending_delete,alias:spd"`

	ID            string               `json:"id"            bun:"id,pk"`
	Key           string               `json:"key"           bun:"object_key"`
	UploadID      string               `json:"uploadId"      bun:"upload_id"`
	Reason        storage.DeleteReason `json:"reason"        bun:"reason"`
	Attempts      int                  `json:"attempts"      bun:"attempts"`
	NextAttemptAt timex.DateTime       `json:"nextAttemptAt" bun:"next_attempt_at"`
	CreatedAt     timex.DateTime       `json:"createdAt"     bun:"created_at,skipupdate"`
}

type UploadClaim struct {
	orm.BaseModel `json:"-" bun:"table:sys_storage_upload_claim,alias:suc"`

	ID               string         `json:"id"               bun:"id,pk"`
	CreatedAt        timex.DateTime `json:"createdAt"        bun:"created_at,skipupdate"`
	CreatedBy        string         `json:"createdBy"        bun:"created_by,skipupdate"`
	Key              string         `json:"key"              bun:"object_key"`
	UploadID         string         `json:"uploadId"         bun:"upload_id"`
	Size             int64          `json:"size"             bun:"size"`
	ContentType      string         `json:"contentType"      bun:"content_type"`
	OriginalFilename string         `json:"originalFilename" bun:"original_filename"`
	Status           ClaimStatus    `json:"status"           bun:"status"`
	Public           bool           `json:"public"           bun:"public"`
	PartSize         int64          `json:"partSize"         bun:"part_size"`
	PartCount        int            `json:"partCount"        bun:"part_count"`
	ExpiresAt        timex.DateTime `json:"expiresAt"        bun:"expires_at"`
}

type UploadPart struct {
	orm.BaseModel `json:"-" bun:"table:sys_storage_upload_part,alias:sup"`

	ID         string         `json:"id"         bun:"id,pk"`
	ClaimID    string         `json:"claimId"    bun:"claim_id"`
	PartNumber int            `json:"partNumber" bun:"part_number"`
	ETag       string         `json:"eTag"       bun:"etag"`
	Size       int64          `json:"size"       bun:"size"`
	CreatedAt  timex.DateTime `json:"createdAt"  bun:"created_at,skipupdate"`
}

type UploadPartStore interface {
	// Upsert inserts a new part row or overwrites the ETag / Size of an
	// existing (claim_id, part_number) row. Used by upload_part to make
	// part re-upload safe (the backend returns a fresh ETag and the
	// caller persists it without caring about previous attempts).
	Upsert(ctx context.Context, tx orm.DB, part *UploadPart) error

	// ListByClaim returns every part of the given claim, sorted ascending
	// by PartNumber. complete_upload uses the result to assemble the
	// CompletedPart list it hands to the backend.
	ListByClaim(ctx context.Context, claimID string) ([]UploadPart, error)

	// DeleteByClaim removes every part of the given claim inside tx.
	// Used by complete_upload (after the backend assembles the final
	// object) and abort_upload (cleanup). The schema also cascades on
	// claim deletion; this method is the explicit path for the success
	// case where the claim row remains in 'uploaded' state.
	DeleteByClaim(ctx context.Context, tx orm.DB, claimID string) error
}