cache

type Cache interface {
	// Put writes data to the cache under the given bucket/key and returns
	// the resulting metadata (path, size, etag, checksum).
	// The data is fsync'd before returning to guarantee durability.
	// size is the most bytes r may supply; the write holds that much capacity
	// before reading r and returns ErrCacheFull without reading when the cache
	// cannot hold it, or ErrSizeExceeded when r supplies more.
	// Returns ErrInvalidPath if bucket/key would escape the cache root.
	Put(ctx context.Context, bucket, key string, r io.Reader, size int64) (*ObjectInfo, error)

	// PutStaged writes data to a temp file (fsync'd) without replacing the
	// existing cache entry. Returns a StagedObject whose Commit method
	// atomically renames the temp file to the final path. If Commit is not
	// called, Rollback removes the temp file. The capacity held for size, as
	// in Put, lasts until Commit or Rollback.
	// Callers choose whether to commit before or after their DB transaction.
	PutStaged(ctx context.Context, bucket, key string, r io.Reader, size int64) (*StagedObject, error)

	// Get opens a cached object for reading. Returns os.ErrNotExist if the
	// object is not in the cache.
	// Returns ErrInvalidPath if bucket/key would escape the cache root.
	Get(ctx context.Context, bucket, key string) (io.ReadCloser, *ObjectInfo, error)

	// Delete removes an object from the cache.
	// Returns ErrInvalidPath if bucket/key would escape the cache root.
	Delete(ctx context.Context, bucket, key string) error

	// Exists reports whether an object is present in the cache.
	Exists(ctx context.Context, bucket, key string) bool

	// UsedBytes returns the total bytes consumed by committed cached objects.
	UsedBytes() int64

	CapacitySnapshot() CapacitySnapshot

	// ConsumeRefusedWriteBytes returns the largest capacity reservation refused
	// since the previous call and clears the record. The capacity task owns it.
	ConsumeRefusedWriteBytes() int64

	// CreateBucketDir ensures the directory for a bucket exists.
	// Returns ErrInvalidPath if bucket would escape the cache root.
	CreateBucketDir(ctx context.Context, bucket string) error

	// DeleteBucketDir removes the cache directory for a bucket.
	// Returns ErrInvalidPath if bucket would escape the cache root.
	DeleteBucketDir(ctx context.Context, bucket string) error

	// PutPart writes a multipart upload part to the cache.
	// Parts are stored under .multipart/<uploadID>/<partNumber>.
	// size bounds and reserves the part as in Put.
	// Returns ObjectInfo with the part's Size, ETag (MD5), and Checksum (SHA-256).
	PutPart(ctx context.Context, uploadID string, partNumber int, r io.Reader, size int64) (*ObjectInfo, error)

	// AssemblePartsStaged concatenates the specified parts in order into a
	// staged file next to bucket/key, plus the ordered list of individual part
	// MD5 hex digests (for S3 ETag computation). The caller names the final
	// destination through Commit or CommitAs once the assembled checksum has
	// resolved a content row. The part files are NOT deleted; call DeleteUpload.
	// Capacity for the assembled size is held before assembly starts.
	AssemblePartsStaged(ctx context.Context, bucket, key, uploadID string, partNumbers []int) (*StagedObject, []string, error)

	// DeleteUpload removes all part files for the given upload ID.
	DeleteUpload(ctx context.Context, uploadID string) error
}

type CapacitySnapshot struct {
	UsedBytes     int64
	ReservedBytes int64
	MaxBytes      int64
}

type EvictionPolicy string

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

type ObjectInfo struct {
	Path     string
	Size     int64
	ETag     string
	Checksum string // SHA-256 hex digest
}

type StagedObject struct {
	Info *ObjectInfo
	// contains filtered or unexported fields
}