// Package imgcache provides interfaces and types for the image caching proxy.
package imgcache

import (
	"context"
	"io"
	"time"

	"sneak.berlin/go/pixa/internal/imagerequest"
)

// ImageResponse represents a processed image ready to serve
type ImageResponse struct {
	// Content is the image data reader
	Content io.ReadCloser
	// ContentLength is the size in bytes (-1 if unknown)
	ContentLength int64
	// ContentType is the MIME type of the response
	ContentType string
	// ETag is the entity tag for caching
	ETag string
	// LastModified is when the content was last modified
	LastModified time.Time
	// CacheStatus indicates HIT, MISS, or STALE
	CacheStatus CacheStatus
	// FetchedBytes is the number of bytes fetched from upstream (0 if cache hit)
	FetchedBytes int64
}

// CacheStatus indicates whether the response was served from cache.
type CacheStatus string

// Cache status values for response headers.
const (
	CacheHit   CacheStatus = "HIT"
	CacheMiss  CacheStatus = "MISS"
	CacheStale CacheStatus = "STALE"
)

// ImageCache is the main interface for the image caching proxy
type ImageCache interface {
	// Get retrieves a processed image, fetching and processing if necessary
	Get(ctx context.Context, req *imagerequest.Request) (*ImageResponse, error)

	// Warm pre-fetches and caches an image without returning it
	Warm(ctx context.Context, req *imagerequest.Request) error

	// Stats returns cache statistics
	Stats(ctx context.Context) (*CacheStats, error)
}

// CacheStats contains cache statistics
type CacheStats struct {
	// TotalItems is the number of cached source images plus processed
	// variants
	TotalItems int64
	// TotalSizeBytes is the total size of cached source images and
	// processed variants
	TotalSizeBytes int64
	// HitCount is the number of cache hits
	HitCount int64
	// MissCount is the number of cache misses
	MissCount int64
	// HitRate is HitCount / (HitCount + MissCount)
	HitRate float64
}