core

import "github.com/afreidah/s3-orchestrator/internal/store/core"

const (
    // LockRebalancer is held by the periodic rebalancer.
    LockRebalancer int64 = 1001
    // LockReplicator is held by the background replicator.
    LockReplicator int64 = 1002
    // LockCleanupQueue is held by the cleanup-queue retry worker.
    LockCleanupQueue int64 = 1003
    // LockMultipartCleanup is held by the stale-multipart sweeper.
    LockMultipartCleanup int64 = 1004
    // LockLifecycle is held by the lifecycle expiration worker.
    LockLifecycle int64 = 1005
    // LockDrain is held by an in-progress backend drain.
    LockDrain int64 = 1006
    // LockUsageFlush is held by the usage-counter flush worker.
    LockUsageFlush int64 = 1007
    // LockOverReplication is held by the excess-replica cleaner.
    LockOverReplication int64 = 1008
    // LockReconcile is held by the reconciler.
    LockReconcile int64 = 1009
    // LockScrubber is held by the integrity scrubber.
    LockScrubber int64 = 1010
    // LockPendingReaper is held by the pending-intent reaper.
    LockPendingReaper int64 = 1011
)

var (
    // ErrNoSpaceAvailable is returned when no backend has sufficient quota.
    ErrNoSpaceAvailable = errors.New("no backend has sufficient quota")

    // ErrDBUnavailable is returned by CircuitBreakerStore when the
    // circuit is open. Manager uses errors.Is to trigger broadcast
    // fallback on reads or 503 rejection on writes.
    ErrDBUnavailable = errors.New("database unavailable")

    // ErrObjectNotFound is returned when an object is not in the
    // location table.
    ErrObjectNotFound = &S3Error{
        StatusCode: 404,
        Code:       "NoSuchKey",
        Message:    "object not found",
    }

    // ErrMultipartUploadNotFound is returned when a multipart upload
    // ID is not found.
    ErrMultipartUploadNotFound = &S3Error{
        StatusCode: 404,
        Code:       "NoSuchUpload",
        Message:    "multipart upload not found",
    }

    // ErrServiceUnavailable is returned to S3 clients when writes are
    // rejected during a database outage.
    ErrServiceUnavailable = &S3Error{
        StatusCode: 503,
        Code:       "ServiceUnavailable",
        Message:    "database unavailable, writes are temporarily rejected",
    }

    // ErrInsufficientStorage is returned when no backend has enough
    // quota at the manager-routing layer.
    ErrInsufficientStorage = &S3Error{
        StatusCode: 507,
        Code:       "InsufficientStorage",
        Message:    "no backend has sufficient quota",
    }

    // ErrUsageLimitExceeded is returned when all backends holding an
    // object have exceeded their monthly usage limits.
    ErrUsageLimitExceeded = &S3Error{
        StatusCode: 429,
        Code:       "SlowDown",
        Message:    "monthly usage limit exceeded for all backends holding this object",
    }

    // ErrCleanupItemNotFound is returned by CleanupTxAdapter.GetCleanupQueueRow
    // when the row no longer exists - typically because another worker
    // already moved it to the DLQ or completed it. Callers treat this as
    // a benign no-op rather than an error.
    ErrCleanupItemNotFound = errors.New("cleanup queue row not found")
)

func DeleteObjectsBatch(ctx context.Context, runner Runner, keys []string) (map[string][]DeletedCopy, error)

func GroupByKey(locations []ObjectLocation) map[string][]ObjectLocation

func ImportObject(ctx context.Context, runner Runner, key, backend string, size int64) (bool, error)

func MoveCleanupToDLQ(ctx context.Context, runner Runner, id int64, lastError string) (bool, error)

func MoveObjectLocation(ctx context.Context, runner Runner, key, fromBackend, toBackend string) (int64, error)

func PromotePending(ctx context.Context, runner Runner, p *PendingObject) (PendingPromoteResult, []DeletedCopy, error)

func RecordReplica(ctx context.Context, runner Runner, key, targetBackend, sourceBackend string) (int64, bool, error)

func RemoveExcessCopy(ctx context.Context, runner Runner, key, backendName string, size int64) error

func SweepStaleCleanupQueueRows(ctx context.Context, runner Runner, objectKey, backend string) (int64, error)

func WithTxVal[T any](ctx context.Context, runner Runner, fn func(ctx context.Context, tx TxAdapter) (T, error)) (T, error)

type AdvisoryLocker interface {
    WithAdvisoryLock(ctx context.Context, lockID int64, fn func(ctx context.Context) error) (bool, error)
}

type BackendLifecycleStore interface {
    BackendObjectStats(ctx context.Context, backendName string) (int64, int64, error)
    DeleteBackendData(ctx context.Context, backendName string) error
}

type CleanupItem struct {
    ID          int64
    BackendName string
    ObjectKey   string
    Reason      string
    Attempts    int32
    SizeBytes   int64
    ClaimedAt   *time.Time
    ClaimedBy   *string
    Reclaimed   bool `json:"-"`
}

type CleanupQueueRow struct {
    ID          int64
    BackendName string
    ObjectKey   string
    Reason      string
    SizeBytes   int64
    Attempts    int32
    CreatedAt   time.Time
    LastError   string
}

type CleanupStore interface {
    EnqueueCleanup(ctx context.Context, backendName, objectKey, reason string, sizeBytes int64) error

    // GetPendingCleanups returns a read-only snapshot of pending rows for
    // admin / dashboard display. It does not stamp claim columns; the
    // cleanup worker uses ClaimPendingCleanups instead.
    GetPendingCleanups(ctx context.Context, limit int) ([]CleanupItem, error)

    // ClaimPendingCleanups atomically reserves a batch of cleanup rows
    // for the calling instance. Postgres uses FOR UPDATE SKIP LOCKED so
    // concurrent claim transactions across instances return disjoint row
    // sets; SQLite serialises writes intrinsically. A row is eligible
    // when claimed_at IS NULL or older than graceCutoff (a stale claim
    // from a worker that died mid-process). Returned rows have Reclaimed
    // set true when their previous claim was reclaimed by this call.
    ClaimPendingCleanups(ctx context.Context, limit int, instanceID string, graceCutoff time.Time) ([]CleanupItem, error)

    // CompleteCleanupItem atomically deletes a successfully-processed row
    // and decrements the backing backend's orphan_bytes by the row's
    // size_bytes. Idempotent against re-claim retries: if the row was
    // already deleted by a previous worker, orphan_bytes is not
    // double-decremented.
    CompleteCleanupItem(ctx context.Context, id int64) error

    // RetryCleanupItem advances next_retry, records the error, and
    // clears the claim so the row is immediately re-eligible for the
    // next worker tick.
    RetryCleanupItem(ctx context.Context, id int64, backoff time.Duration, lastError string) error
    CleanupQueueDepth(ctx context.Context) (int64, error)
    IncrementOrphanBytes(ctx context.Context, backendName string, amount int64) error
    DecrementOrphanBytes(ctx context.Context, backendName string, amount int64) error
    SweepStaleCleanupQueueRows(ctx context.Context, key, backend string) (int64, error)

    // MoveCleanupToDLQ atomically graduates an exhausted cleanup_queue
    // row to cleanup_dlq. orphan_bytes is intentionally left untouched
    // because the underlying backend object is still on disk; the DLQ
    // entry exists so an operator can investigate, retry, or write off
    // each unrecoverable orphan deliberately. Returns true if a row was
    // moved, false if no row existed (benign concurrent-finaliser race).
    MoveCleanupToDLQ(ctx context.Context, id int64, lastError string) (bool, error)

    // CleanupDLQDepth returns the number of rows currently in
    // cleanup_dlq. Updates the cleanup_dlq_depth gauge so dashboards can
    // surface the count of unrecoverable orphans needing attention.
    CleanupDLQDepth(ctx context.Context) (int64, error)
}

type CleanupTxAdapter interface {
    // SumAndDeleteCleanupQueueRows deletes every cleanup_queue row for
    // the given (objectKey, backend) pair and returns the count and
    // total size of the deleted rows.
    SumAndDeleteCleanupQueueRows(ctx context.Context, objectKey, backend string) (deleted int64, totalBytes int64, err error)

    // GetCleanupQueueRow returns the full payload of a single
    // cleanup_queue row by id. Used inside MoveCleanupToDLQ so the row
    // contents (key, backend, size, attempts, created_at, last_error)
    // can be copied into the DLQ insert without a separate round trip.
    GetCleanupQueueRow(ctx context.Context, id int64) (CleanupQueueRow, error)

    // InsertCleanupDLQ inserts the supplied row into cleanup_dlq. The
    // original_id retains the queue row's id for forensic correlation;
    // first_enqueued_at carries the original created_at so the DLQ
    // entry remembers how long the cleanup was outstanding. Takes a
    // pointer so the 112-byte row payload travels by reference.
    InsertCleanupDLQ(ctx context.Context, row *CleanupQueueRow) error

    // DeleteCleanupItem removes a cleanup_queue row by id. Used inside
    // MoveCleanupToDLQ so the queue->DLQ move is atomic.
    DeleteCleanupItem(ctx context.Context, id int64) error
}

type CreateMultipartUploadParams struct {
    UploadID      string
    ObjectKey     string
    BackendName   string
    ContentType   string
    Metadata      map[string]string
    EncryptionKey []byte // empty for unencrypted uploads
    KeyID         string // empty for unencrypted uploads
}

type DashboardStore interface {
    GetQuotaStats(ctx context.Context) (map[string]QuotaStat, error)
    GetObjectCounts(ctx context.Context) (map[string]int64, error)
    GetUnverifiedObjectCounts(ctx context.Context) (map[string]int64, error)
    GetActiveMultipartCounts(ctx context.Context) (map[string]int64, error)
    GetUsageForPeriod(ctx context.Context, period string) (map[string]UsageStat, error)
    ListDirectoryChildren(ctx context.Context, prefix, startAfter string, maxKeys int) (*DirectoryListResult, error)
}

type DecryptableLocation struct {
    ObjectKey     string
    BackendName   string
    SizeBytes     int64
    EncryptionKey []byte
    KeyID         string
    PlaintextSize int64
}

type DeletedCopy struct {
    BackendName string
    SizeBytes   int64
}

func DeleteObject(ctx context.Context, runner Runner, key string) ([]DeletedCopy, error)

func RecordObject(ctx context.Context, runner Runner, key, backend string, size int64, enc *EncryptionMeta) ([]DeletedCopy, error)

func RecordObjectAndClearPending(ctx context.Context, runner Runner, key, backend string, size int64, enc *EncryptionMeta, intentID string) ([]DeletedCopy, error)

type DirEntry struct {
    Name      string   `json:"name"`
    IsDir     bool     `json:"isDir"`
    FileCount int64    `json:"fileCount"`
    TotalSize int64    `json:"totalSize"`
    Backends  []string `json:"backends"`
    CreatedAt string   `json:"createdAt"`
}

type DirectoryListResult struct {
    Entries    []DirEntry `json:"entries"`
    HasMore    bool       `json:"hasMore"`
    NextCursor string     `json:"nextCursor"`
}

type EncryptedLocation struct {
    ObjectKey     string
    BackendName   string
    EncryptionKey []byte
    KeyID         string
}

type EncryptionAdmin interface {
    ListEncryptedLocations(ctx context.Context, keyID string, limit, offset int) ([]EncryptedLocation, error)
    UpdateEncryptionKey(ctx context.Context, objectKey, backendName string, newEncryptionKey []byte, newKeyID string) error
    ListUnencryptedLocations(ctx context.Context, limit, offset int) ([]UnencryptedLocation, error)
    MarkObjectEncrypted(ctx context.Context, objectKey, backendName string, encryptionKey []byte, keyID string, plaintextSize, ciphertextSize int64) error
    ListAllEncryptedLocations(ctx context.Context, limit, offset int) ([]DecryptableLocation, error)
    MarkObjectDecrypted(ctx context.Context, objectKey, backendName string, plaintextSize int64) error
}

type EncryptionMeta struct {
    Encrypted     bool
    EncryptionKey []byte
    KeyID         string
    PlaintextSize int64
    ContentHash   string
}

type ExistingCopy struct {
    BackendName string
    SizeBytes   int64
    CreatedAt   time.Time
}

type ExpiredObjectsLister interface {
    ListExpiredObjects(ctx context.Context, prefix string, cutoff time.Time, limit int) ([]ObjectLocation, error)
}

type IntegrityStore interface {
    GetRandomHashedObjects(ctx context.Context, limit int) ([]ObjectLocation, error)
    GetObjectsWithoutHash(ctx context.Context, limit, offset int) ([]ObjectLocation, error)
    UpdateContentHash(ctx context.Context, key, backendName, hash string) error
}

type KeyedExistingCopy struct {
    ObjectKey   string
    BackendName string
    SizeBytes   int64
}

type LifecycleAdmin interface {
    RunMigrations(ctx context.Context) error
    VerifySchemaVersion(ctx context.Context) error
    SyncQuotaLimits(ctx context.Context, backends []config.BackendConfig) error
    Close()
}

type ListObjectsResult struct {
    Objects               []ObjectLocation
    IsTruncated           bool
    NextContinuationToken string
}

type MetadataStore interface {
    ObjectStore
    QuotaStore
    MultipartStore
    ReplicationStore
    CleanupStore
    PendingStore
    IntegrityStore
    ExpiredObjectsLister
    BackendLifecycleStore
    UsageFlusher
    AdvisoryLocker
    DashboardStore
    LifecycleAdmin
    EncryptionAdmin
    NotificationOutbox
}

type MultipartPart struct {
    PartNumber    int
    ETag          string
    SizeBytes     int64
    CreatedAt     time.Time
    Encrypted     bool
    EncryptionKey []byte
    KeyID         string
    PlaintextSize int64
}

type MultipartStore interface {
    CreateMultipartUpload(ctx context.Context, params *CreateMultipartUploadParams) error
    GetMultipartUpload(ctx context.Context, uploadID string) (*MultipartUpload, error)
    RecordPart(ctx context.Context, uploadID string, partNumber int, etag string, size int64, enc *EncryptionMeta) error
    GetParts(ctx context.Context, uploadID string) ([]MultipartPart, error)
    DeleteMultipartUpload(ctx context.Context, uploadID string) error
    ListMultipartUploads(ctx context.Context, prefix string, maxUploads int) ([]MultipartUpload, error)
    CountActiveMultipartUploads(ctx context.Context, bucketPrefix string) (int64, error)
    GetStaleMultipartUploads(ctx context.Context, olderThan time.Duration) ([]MultipartUpload, error)
    GetMultipartUploadsByBackend(ctx context.Context, backendName string) ([]MultipartUpload, error)
}

type MultipartUpload struct {
    UploadID      string
    ObjectKey     string
    BackendName   string
    ContentType   string
    Metadata      map[string]string
    Encrypted     bool
    EncryptionKey []byte
    KeyID         string
    CreatedAt     time.Time
}

type NotificationOutbox interface {
    InsertNotification(ctx context.Context, eventType, payload, endpointURL string) error
    GetPendingNotifications(ctx context.Context, limit int) ([]NotificationRow, error)
    CompleteNotification(ctx context.Context, id int64) error
    RetryNotification(ctx context.Context, id int64, backoff time.Duration, lastError string) error
}

type NotificationRow struct {
    ID          int64
    EventType   string
    Payload     []byte
    EndpointURL string
    Attempts    int32
}

type ObjectLocation struct {
    ObjectKey     string
    BackendName   string
    SizeBytes     int64
    CreatedAt     time.Time
    Encrypted     bool
    EncryptionKey []byte
    KeyID         string
    PlaintextSize int64
    ContentHash   string
}

type ObjectStore interface {
    GetAllObjectLocations(ctx context.Context, key string) ([]ObjectLocation, error)
    GetObjectBackendsForKeys(ctx context.Context, keys []string) (map[string][]string, error)
    RecordObject(ctx context.Context, key, backend string, size int64, enc *EncryptionMeta) ([]DeletedCopy, error)
    RecordObjectAndClearPending(ctx context.Context, key, backend string, size int64, enc *EncryptionMeta, intentID string) ([]DeletedCopy, error)
    DeleteObject(ctx context.Context, key string) ([]DeletedCopy, error)
    DeleteObjectsBatch(ctx context.Context, keys []string) (map[string][]DeletedCopy, error)
    ListObjects(ctx context.Context, prefix, startAfter string, maxKeys int) (*ListObjectsResult, error)
    ListObjectsByBackend(ctx context.Context, backendName string, limit int) ([]ObjectLocation, error)
    ListObjectsByBackendKeyAsc(ctx context.Context, backendName, afterKey string, limit int) ([]ObjectLocation, error)
    MoveObjectLocation(ctx context.Context, key, fromBackend, toBackend string) (int64, error)
    ImportObject(ctx context.Context, key, backend string, size int64) (bool, error)
    DeleteObjectLocation(ctx context.Context, key, backendName string) error
}

type ObjectsTxAdapter interface {
    GetExistingCopiesForUpdate(ctx context.Context, objectKey string) ([]ExistingCopy, error)
    InsertObjectLocation(ctx context.Context, loc *ObjectLocation) error
    DeleteObjectCopies(ctx context.Context, objectKey string) error

    // GetCopiesForKeysForUpdate returns every (key, backend, size) row
    // matching any key in the supplied list, locked FOR UPDATE so the
    // same transaction can delete the rows and decrement quotas
    // atomically. Used by the batch-delete path.
    GetCopiesForKeysForUpdate(ctx context.Context, keys []string) ([]KeyedExistingCopy, error)

    // DeleteObjectsByKeys removes every object_locations row whose key
    // is in the supplied list. Caller must have already locked the
    // rows via GetCopiesForKeysForUpdate.
    DeleteObjectsByKeys(ctx context.Context, keys []string) error

    // CheckObjectExistsOnBackend reports whether the object_locations
    // table holds a row for (key, backend).
    CheckObjectExistsOnBackend(ctx context.Context, objectKey, backend string) (bool, error)

    // LockObjectOnBackend takes a FOR UPDATE lock on the
    // (key, backend) row and returns its full payload. Returns
    // (nil, false, nil) when the row is gone - benign race the caller
    // treats as nothing to act on.
    LockObjectOnBackend(ctx context.Context, objectKey, backend string) (loc *ObjectLocation, ok bool, err error)

    // DeleteObjectFromBackend removes the single (key, backend)
    // object_locations row.
    DeleteObjectFromBackend(ctx context.Context, objectKey, backend string) error

    // InsertObjectLocationIfNotExists is the import-side INSERT that
    // preserves an existing row. Returns true if a row was inserted.
    InsertObjectLocationIfNotExists(ctx context.Context, loc *ObjectLocation) (inserted bool, err error)

    // InsertReplicaConditional inserts a replica row only if the
    // source copy still exists. Returns the size_bytes the row was
    // inserted with (read from the source row inside the same
    // statement) and inserted=true on success, or (0, false, nil)
    // when the source copy is gone or the target already has a copy.
    // Callers use the returned size for IncrementBackendQuota so
    // object_locations.size_bytes and backend_quotas.bytes_used always
    // agree.
    InsertReplicaConditional(ctx context.Context, objectKey, targetBackend, sourceBackend string) (size int64, inserted bool, err error)
}

type PendingObject struct {
    IntentID      string
    ObjectKey     string
    BackendName   string
    SizeBytes     int64
    Encrypted     bool
    EncryptionKey []byte
    KeyID         string
    PlaintextSize int64
    ContentHash   string
    CreatedAt     time.Time
}

type PendingPromoteResult int

const (
    // PendingPromoteCommitted means the pending row was promoted into
    // object_locations and removed in the same transaction.
    PendingPromoteCommitted PendingPromoteResult = iota

    // PendingPromoteAmbiguous is reserved for pathological cases the
    // resolver cannot decide between promotion and dropping. The current
    // resolver does not produce this result; the timestamp comparison
    // covers every previously-ambiguous case as Superseded instead. Kept
    // so the metric label and constant stay stable across releases.
    PendingPromoteAmbiguous

    // PendingPromoteAlreadyResolved means the pending row was gone by
    // the time the transaction acquired its lock - another reaper
    // instance already resolved it. Benign no-op.
    PendingPromoteAlreadyResolved

    // PendingPromoteSuperseded means a successful write for the same
    // key committed after this intent was inserted. The intent is
    // provably stale, so the resolver deletes the pending row.
    PendingPromoteSuperseded
)

type PendingStore interface {
    InsertPending(ctx context.Context, p *PendingObject) error
    DeletePending(ctx context.Context, intentID string) error
    GetStalePending(ctx context.Context, olderThan time.Time, limit int) ([]PendingObject, error)
    PromotePending(ctx context.Context, p *PendingObject) (PendingPromoteResult, []DeletedCopy, error)
    PendingDepth(ctx context.Context) (int64, error)
    DeletePendingByBackend(ctx context.Context, backendName string) error
}

type PendingTxAdapter interface {
    // ClaimPending returns true if the pending row was successfully
    // claimed for promotion, false if it has already been resolved by
    // another worker. Postgres uses SELECT FOR UPDATE; SQLite uses an
    // existence probe inside the writer-serialized txn - same
    // guarantee.
    ClaimPending(ctx context.Context, intentID string) (claimed bool, err error)

    InsertPending(ctx context.Context, p *PendingObject) error
    DeletePending(ctx context.Context, intentID string) error
    DeletePendingByBackend(ctx context.Context, backendName string) error
}

type QuotaStat struct {
    BackendName string
    BytesUsed   int64
    BytesLimit  int64
    OrphanBytes int64
    UpdatedAt   time.Time
}

type QuotaStore interface {
    GetBackendWithSpace(ctx context.Context, size int64, backendOrder []string) (string, error)
    GetLeastUtilizedBackend(ctx context.Context, size int64, eligible []string) (string, error)
    GetQuotaStats(ctx context.Context) (map[string]QuotaStat, error)
}

type QuotaTxAdapter interface {
    // IncrementBackendQuota credits delta bytes to the backend's
    // quota and returns ErrNoSpaceAvailable when the row reports zero
    // rows updated (quota would be exceeded).
    IncrementBackendQuota(ctx context.Context, backendName string, delta int64) error

    // DecrementBackendQuota debits delta bytes from the backend's
    // quota.
    DecrementBackendQuota(ctx context.Context, backendName string, delta int64) error

    // DecrementOrphanBytes debits delta bytes from the backend's
    // orphan_bytes counter, clamped at zero.
    DecrementOrphanBytes(ctx context.Context, backendName string, delta int64) error
}

type Reader interface {
    // Pending reads
    GetStalePending(ctx context.Context, olderThan time.Time, limit int) ([]PendingObject, error)
    CountPending(ctx context.Context) (int64, error)

    // Object listing reads
    GetAllObjectLocations(ctx context.Context, key string) ([]ObjectLocation, error)
    ListObjectsByBackend(ctx context.Context, backendName string, limit int) ([]ObjectLocation, error)
    ListObjectsByBackendKeyAsc(ctx context.Context, backendName, afterKey string, limit int) ([]ObjectLocation, error)
    ListObjectsByPrefix(ctx context.Context, prefix, startAfter string, maxKeys int) ([]ObjectLocation, error)
    ListExpiredObjects(ctx context.Context, prefix string, cutoff time.Time, limit int) ([]ObjectLocation, error)

    // Cleanup queue reads
    GetPendingCleanups(ctx context.Context, limit int) ([]CleanupItem, error)
    CleanupQueueDepth(ctx context.Context) (int64, error)

    // CleanupDLQDepth returns the number of rows in cleanup_dlq. Used
    // by the cleanup_dlq_depth gauge so dashboards surface the count
    // of unrecoverable orphans needing operator attention.
    CleanupDLQDepth(ctx context.Context) (int64, error)
}

type ReplicationStore interface {
    GetUnderReplicatedObjects(ctx context.Context, factor, limit int) ([]ObjectLocation, error)
    GetUnderReplicatedObjectsExcluding(ctx context.Context, factor, limit int, excludedBackends []string) ([]ObjectLocation, error)
    RecordReplica(ctx context.Context, key, targetBackend, sourceBackend string) (size int64, inserted bool, err error)
    GetOverReplicatedObjects(ctx context.Context, factor, limit int) ([]ObjectLocation, error)
    CountOverReplicatedObjects(ctx context.Context, factor int) (int64, error)
    RemoveExcessCopy(ctx context.Context, key, backendName string, size int64) error
}

type Runner interface {
    // WithTx is method-form here for Go interface satisfaction; the
    // generic helper below is the calling convention used by core
    // operations. A type that implements WithTx with the unwrapped
    // signature satisfies this interface; the WithTxVal helper wraps
    // it.
    WithTx(ctx context.Context, fn func(ctx context.Context, tx TxAdapter) error) error
}

type S3Error struct {
    StatusCode int
    Code       string
    Message    string
}

func (e *S3Error) Error() string

type TxAdapter interface {
    PendingTxAdapter
    ObjectsTxAdapter
    CleanupTxAdapter
    QuotaTxAdapter

    // AcquireKeyLock takes a transaction-scoped lock keyed by the
    // object key. Postgres uses pg_advisory_xact_lock derived from a
    // hash of the key; SQLite no-ops because the engine serializes
    // writers and the in-tx existence probe provides the same
    // guarantee.
    AcquireKeyLock(ctx context.Context, objectKey string) error
}

type UnencryptedLocation struct {
    ObjectKey   string
    BackendName string
    SizeBytes   int64
}

type UsageFlusher interface {
    FlushUsageDeltas(ctx context.Context, backendName, period string, apiRequests, egressBytes, ingressBytes int64) error
}

type UsageLimits struct {
    APIRequestLimit  int64
    EgressByteLimit  int64
    IngressByteLimit int64
}

type UsageStat struct {
    APIRequests  int64
    EgressBytes  int64
    IngressBytes int64
}