cache

type Backend interface {
	// Name returns the backend type name (e.g., "github/actions").
	Name() string

	// Save uploads a single data stream (a tar.gz archive) under the exact key.
	// Implementations return errUtils.ErrCacheAlreadyExists when the key exists.
	Save(ctx context.Context, key string, data io.Reader, size int64) error

	// Restore downloads the entry for the exact key, or the first restore-key
	// prefix match when the exact key is absent. It returns the key that was
	// actually matched and a reader the caller must close. When nothing
	// matches it returns errUtils.ErrCacheNotFound.
	Restore(ctx context.Context, key string, restoreKeys []string) (matchedKey string, rc io.ReadCloser, err error)

	// List returns cache entries, optionally filtered by key prefix.
	List(ctx context.Context, opts ListOptions) ([]Entry, error)

	// Delete removes a cache entry by exact key. Deleting a missing key is a
	// no-op (returns nil) so callers can treat delete as idempotent.
	Delete(ctx context.Context, key string) error
}

type BackendFactory func(opts Options) (Backend, error)

type Config struct {
	// Enabled is the master switch (ci.cache.enabled).
	Enabled bool

	// Auto is the automatic mode: off | restore | save | both.
	Auto string

	// Root is the absolute well-known cache directory that is archived.
	Root string

	// Includes are root-relative subpaths to include; empty means the whole root.
	Includes []string

	// Key is the resolved exact cache key.
	Key string

	// RestoreKeys are prefix fallbacks tried (in order) when Key is absent.
	RestoreKeys []string

	// Compression is the archive compression (currently always gzip).
	Compression string
}

type Entry struct {
	// Key is the cache key.
	Key string

	// Size is the entry size in bytes (0 if unknown).
	Size int64

	// CreatedAt is when the entry was created (zero if unknown).
	CreatedAt time.Time

	// ID is the provider-specific identifier for the entry (may be empty).
	ID string
}

type ListOptions struct {
	// KeyPrefix restricts results to entries whose key starts with this value.
	// Empty matches all entries.
	KeyPrefix string
}

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

type Options struct {
	// AtmosConfig is the active Atmos configuration (may be nil).
	AtmosConfig *schema.AtmosConfiguration

	// Options carries backend-specific configuration (owner, repo, etc.).
	Options map[string]any
}

type RestoreResult struct {
	// Hit is true when an entry was restored (exact or prefix match).
	Hit bool
	// MatchedKey is the key that was actually restored.
	MatchedKey string
	// Exact is true when the exact key matched (vs a restore-key prefix).
	Exact bool
	// Skipped is true when restore was a no-op because this key was already
	// restored in this lifecycle.
	Skipped bool
}

type SaveResult struct {
	// Saved is true when an entry was uploaded (or already present remotely).
	Saved bool
	// Skipped is true when save was a no-op.
	Skipped bool
	// Reason explains a skip (e.g. "exact cache hit", "already saved").
	Reason string
}