zstash

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.
	// Higher values indicate better compression (e.g., 3.0 means 3:1 compression).
	CompressionRatio float64

	// Sha256Sum is the SHA-256 hash of the archive file.
	// Only populated for save operations, empty for restore.
	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 Cache struct {
	// contains filtered or unexported fields
}

type Config struct {
	// Client is the Buildkite API client (required).
	// Create with api.NewClient(ctx, version, endpoint, token).
	Client api.CacheClient

	// BucketURL is the storage backend URL (required for most store types).
	// Examples: "s3://bucket-name", "gs://bucket-name", "file:///path/to/dir"
	BucketURL string

	// Format is the archive format. Defaults to "zip" if not specified.
	Format string

	// Branch is the git branch name, used for cache scoping in the Buildkite API.
	Branch string

	// Pipeline is the pipeline slug, used for cache scoping in the Buildkite API.
	Pipeline string

	// Organization is the organization slug, used for cache scoping in the Buildkite API.
	Organization string

	// Platform is the OS/arch string (e.g., "linux/amd64", "darwin/arm64").
	// If empty, defaults to runtime.GOOS/runtime.GOARCH.
	Platform string

	// Registry is the default cache registry to use for all cache operations.
	// If empty, defaults to "~" (the default registry).
	// Individual cache configurations can override this by setting their own Registry field.
	Registry string

	// Env is an optional environment variable map used for cache template expansion.
	// If nil, OS environment variables are used instead via os.Getenv.
	// Cache keys and paths can use templates like "{{ env \"NODE_VERSION\" }}".
	Env map[string]string

	// Caches is the list of cache configurations to manage.
	// Cache keys and paths will be expanded using template variables.
	Caches []cache.Cache

	// OnProgress is an optional callback for progress updates during operations.
	// If nil, no progress callbacks are made. The callback must be thread-safe
	// as it may be called from multiple goroutines.
	OnProgress ProgressCallback
}

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

type RestoreResult struct {
	// CacheHit indicates whether the exact cache key was found.
	// false means either no cache found, or a fallback key was used.
	// When false, check CacheRestored to distinguish between cache miss
	// and fallback hit.
	CacheHit bool

	// CacheRestored indicates whether any cache was restored (including fallbacks).
	// false means complete cache miss (no matching key or fallback keys).
	CacheRestored bool

	// Key is the actual cache key that was restored.
	// May differ from the requested key if FallbackUsed is true.
	Key string

	// FallbackUsed indicates whether a fallback key was used.
	// true means the exact key wasn't found, but a fallback key matched.
	FallbackUsed bool

	// Archive contains information about the archive that was extracted,
	// including size, compression ratio, and file counts.
	Archive ArchiveMetrics

	// Transfer contains information about the download operation,
	// including bytes transferred and transfer speed.
	Transfer TransferMetrics

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

	// TotalDuration is the end-to-end duration of the restore operation,
	// from validation through extraction.
	TotalDuration time.Duration
}

type SaveResult struct {
	// CacheCreated 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.
	CacheCreated 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 CacheCreated is false.
	UploadID string

	// Archive contains information about the archive that was built,
	// including size, compression ratio, and file counts.
	Archive ArchiveMetrics

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

	// TotalDuration is the end-to-end duration of the save operation,
	// from validation through commit (if created) or early exit (if exists).
	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.
	// Format depends on the storage backend (e.g., S3 request ID).
	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
}