cache

type ArchiveMetrics struct {
	// Size is the total size of the archive file in bytes (compressed).
	Size int64

	// WrittenBytes is the uncompressed size of all files in bytes.
	WrittenBytes int64

	// WrittenEntries is the number of files/directories in the archive.
	WrittenEntries int64

	// CompressionRatio is WrittenBytes / Size.
	CompressionRatio float64

	// Sha256Sum is the SHA-256 hash of the archive file (save only).
	Sha256Sum string

	// Duration is how long the archive build or extraction took.
	Duration time.Duration

	// Paths are the filesystem paths that were archived or extracted.
	Paths []string
}

type Config struct {
	// BucketURL is the URL of the bucket (e.g., s3://bucket-name)
	BucketURL string
	// Branch is the branch associated with the cache
	Branch string
	// Pipeline is the pipeline slug for this cache
	Pipeline string
	// Organization is the organization slug for this cache
	Organization string
	// CacheConfigFile is the path to the cache configuration YAML file
	CacheConfigFile string
	// Ids is a list of cache IDs (if empty, processes all caches)
	Ids []string
	// Concurrency is the number of concurrent cache operations
	Concurrency int
}

type ProgressCallback func(cacheID, stage, message string, current, total int)

type RestoreResult struct {
	// CacheHit indicates whether the exact cache key was found.
	CacheHit bool

	// CacheRestored indicates whether any cache was restored (including fallbacks).
	CacheRestored bool

	// Key is the actual cache key that was restored.
	Key string

	// FallbackUsed indicates whether a fallback key was used.
	FallbackUsed bool

	// Archive contains information about the archive that was extracted.
	Archive ArchiveMetrics

	// Transfer contains information about the download operation.
	Transfer TransferMetrics

	// ExpiresAt indicates when this cache entry will expire.
	ExpiresAt time.Time

	// TotalDuration is the end-to-end duration of the restore operation.
	TotalDuration time.Duration
}

type SaveResult struct {
	// CacheEntryCreated indicates whether a new cache entry was created.
	// false means the cache already existed and no upload occurred.
	// When false, Transfer will be nil since no upload was performed.
	CacheEntryCreated bool

	// Key is the actual cache key that was used (after template expansion).
	Key string

	// UploadID is the unique identifier for this upload (if created).
	// Empty if CacheEntryCreated is false.
	UploadID string

	// Archive contains information about the archive that was built.
	Archive ArchiveMetrics

	// Transfer contains information about the upload (if performed).
	// Nil if CacheEntryCreated is false (cache already existed).
	Transfer *TransferMetrics

	// TotalDuration is the end-to-end duration of the save operation.
	TotalDuration time.Duration
}

type TransferMetrics struct {
	// BytesTransferred is the number of bytes uploaded or downloaded.
	BytesTransferred int64

	// TransferSpeed is the transfer rate in MB/s.
	TransferSpeed float64

	// Duration is how long the transfer took.
	Duration time.Duration

	// RequestID is the provider-specific request identifier for debugging.
	RequestID string

	// PartCount is the number of parts used in multipart transfer (0 if not multipart).
	PartCount int

	// Concurrency is the number of concurrent uploads/downloads used.
	Concurrency int
}