provider

type AzureConfig struct {
	// AccountName is the Azure storage account name.
	//   env_var: AZURE_ACCOUNT_NAME
	AccountName CredentialSource `koanf:"account_name"`

	// AccountKey credential source.
	//   env_var: AZURE_STORAGE_KEY
	//   secret_manager: env:AZURE_STORAGE_KEY
	AccountKey CredentialSource `koanf:"account_key"`

	// Container is the default (private) container name.
	Container string `koanf:"container"`

	// PublicContainer is the container for public objects.
	PublicContainer string `koanf:"public_container"`
}

type CircuitBreakerConfig struct {
	// Enabled turns on circuit-breaker wrapping for the returned Store.
	Enabled bool `koanf:"enabled"`

	// FailureThreshold is the number of consecutive failures required
	// to trip the breaker open. Non-positive falls back to pkg/circuit's
	// default (1).
	FailureThreshold int `koanf:"failure_threshold"`

	// Cooldown is the duration the breaker stays open before admitting
	// half-open probes. Non-positive falls back to pkg/circuit's
	// default (30s).
	Cooldown time.Duration `koanf:"cooldown"`

	// HalfOpenMaxConcurrent caps in-flight probes in the half-open
	// state. Non-positive falls back to pkg/circuit's default (1).
	HalfOpenMaxConcurrent int `koanf:"half_open_max_concurrent"`
}

type CleanupConfig struct {
	// Enabled turns on background cleanup.
	Enabled bool `koanf:"enabled"`

	// Interval is how often to run cleanup (e.g. "1h").
	Interval string `koanf:"interval"`

	// Prefix is the key prefix for temporary objects (default: "_tmp/").
	Prefix string `koanf:"prefix"`

	// MaxAge is the maximum age before an object is deleted (e.g. "24h").
	MaxAge string `koanf:"max_age"`
}

type Config struct {

	// ProviderConfig carries the `storage.<provider>.*` subtree for a
	// provider this package does not know about. The framework fills it;
	// a third-party factory reads it with BindProvider.
	//
	// It is a decoded map rather than a typed field because the framework
	// cannot know the shape of a backend it has never seen — which is the
	// whole point of the registry. The provider owns the shape and
	// declares it in its own struct.
	ProviderConfig map[string]any `koanf:"-" json:"-" yaml:"-"`
	// Default visibility for new objects (private|public).
	DefaultVisibility Visibility `koanf:"default"`

	// Provider selects the storage backend (s3|gcs|azure|local).
	Provider ProviderType `koanf:"provider"`

	// PublicPaths maps public URL paths to storage key prefixes.
	// Example: "/media" -> "storage/public/media/"
	// Requests to /media/* are served from keys with that prefix.
	PublicPaths map[string]string `koanf:"public_paths"`

	// PublicURLBase is the base URL for public objects (CDN or direct provider).
	// Example: "https://cdn.example.com"
	PublicURLBase string `koanf:"public_url_base"`

	// S3 configuration
	S3 S3Config `koanf:"s3"`

	// GCS Configuration
	GCS GCSConfig `koanf:"gcs"`

	// Azure configuration
	Azure AzureConfig `koanf:"azure"`

	// Local configuration (development only)
	Local LocalConfig `koanf:"local"`

	// Cleanup config for temporary objects
	Cleanup CleanupConfig `koanf:"cleanup"`

	// CircuitBreaker, when Enabled, wraps remote provider operations
	// (Put/Get/Delete/Exists/List/SignedURL/Copy) with a pkg/circuit
	// breaker. The local provider is never wrapped — filesystem failures
	// are not the kind of outage circuit breakers are designed to
	// short-circuit. PublicURL is also not wrapped (pure string
	// composition).
	CircuitBreaker CircuitBreakerConfig `koanf:"circuit_breaker"`
}

type CredentialSource struct {
	// Value is the literal credential value (for testing or non-sensitive configs).
	Value string `koanf:"value"`

	// EnvVar reads the credential from an environment variable.
	// This is the primary method for production: orchestrators inject
	// secrets from Secret Manager into env vars before starting the container.
	// Example: "AWS_SECRET_ACCESS_KEY"
	EnvVar string `koanf:"env_var"`

	// File reads the credential from a file path.
	// Used for:
	// - GCS service account JSON key mounted as volume
	// - Kubernetes secrets mounted as files
	// - Azure managed identity token file
	// Example: "/etc/secrets/gcs-sa.json"
	File string `koanf:"file"`

	// SecretManager currently supports only env: references, for example
	// "env:MY_SECRET_KEY". Cloud Secret Manager SDK lookups are deliberately
	// not implemented yet; inject cloud-managed secrets into env vars or files.
	// Resolution happens at startup. The secret value is read once and cached.
	SecretManager string `koanf:"secret_manager"`
}

type ErrInvalidKey string

type ErrNotFound string

type Factory func(cfg Config) (Store, error)

type GCSConfig struct {
	// Bucket is the default (private) bucket name.
	Bucket string `koanf:"bucket"`

	// CredentialsSource for the GCS service account.
	// When empty, uses Application Default Credentials (ADC).
	//
	// Examples for Cloud Run / GKE:
	//   env_var: GOOGLE_APPLICATION_CREDENTIALS  # Path injected by Secret Manager
	//   file: /etc/secrets/gcs-sa.json           # Volume-mounted secret
	//
	// Examples for workload identity (no credentials needed):
	//   (leave empty — ADC uses the GKE service account)
	CredentialsSource CredentialSource `koanf:"credentials"`

	// PublicBucket is an optional separate bucket for public objects.
	PublicBucket string `koanf:"public_bucket"`
}

type ListOptions struct {
	// Prefix filters objects by key prefix (directory-like listing).
	Prefix string

	// Delimiter causes keys containing the delimiter after the prefix
	// to be rolled up into "common prefixes" (simulating directories).
	Delimiter string

	// Limit caps the number of results. 0 = provider default (usually 1000).
	Limit int

	// Marker starts listing after this key (for pagination).
	Marker string
}

type ListResult struct {
	Objects        []ObjectInfo `json:"objects"`
	CommonPrefixes []string     `json:"common_prefixes,omitempty"`
	NextMarker     string       `json:"next_marker,omitempty"`
	Truncated      bool         `json:"truncated"`
}

type LocalConfig struct {
	// Path is the root directory for all stored files.
	Path string `koanf:"path"`
}

type ObjectInfo struct {
	Key         string            `json:"key"`
	Size        int64             `json:"size"`
	ContentType string            `json:"content_type"`
	Visibility  Visibility        `json:"visibility"`
	Metadata    map[string]string `json:"metadata,omitempty"`
	UpdatedAt   time.Time         `json:"updated_at"`
}

type ProviderType string

type PutOptions struct {
	// Visibility controls public access. Defaults to Private.
	Visibility Visibility

	// ContentType is the MIME type (e.g. "image/png", "application/pdf").
	// Auto-detected from key extension when empty.
	ContentType string

	// Metadata stores custom key-value pairs on the provider.
	Metadata map[string]string

	// TenantPrefix overrides the automatic tenant prefix.
	// Empty means auto-detect from context. Set to "" explicitly to disable prefixing.
	TenantPrefix string
}

type S3Config struct {
	// Endpoint is the S3 API endpoint. Empty = AWS S3.
	// For MinIO: "http://minio:9000"
	// For Cloudflare R2: "https://<account>.r2.cloudflarestorage.com"
	Endpoint string `koanf:"endpoint"`

	// Bucket is the default (private) bucket name.
	Bucket string `koanf:"bucket"`

	// Region is the AWS region.
	Region string `koanf:"region"`

	// AccessKeyID credential source.
	// Examples:
	//   env_var: AWS_ACCESS_KEY_ID          # From environment variable
	//   file: /etc/secrets/aws-access-key   # From mounted secret file
	//   value: AKIA...                       # Direct (not recommended for production)
	AccessKeyID CredentialSource `koanf:"access_key_id"`

	// SecretAccessKey credential source.
	// Examples:
	//   env_var: AWS_SECRET_ACCESS_KEY
	//   file: /etc/secrets/aws-secret-key
	SecretAccessKey CredentialSource `koanf:"secret_access_key"`

	// SessionToken credential source (for temporary STS credentials).
	//   env_var: AWS_SESSION_TOKEN
	SessionToken CredentialSource `koanf:"session_token"`

	// UsePathStyle forces path-style URLs instead of virtual-hosted style.
	// Required for MinIO and some other S3-compatible providers.
	UsePathStyle bool `koanf:"use_path_style"`

	// PublicBucket is an optional separate bucket for public objects.
	// When set, public objects are stored here instead of Bucket.
	PublicBucket string `koanf:"public_bucket"`

	// CreateBucketIfMissing provisions Bucket (and PublicBucket, when set)
	// at construction time if they do not exist yet, using Region for the
	// bucket location. Opt-in (QCD-FW-2): the default refuses to create
	// infrastructure against a production object store — but note that a
	// missing bucket now fails the constructor LOUDLY either way, instead
	// of booting green and failing on the first Put.
	CreateBucketIfMissing bool `koanf:"create_bucket_if_missing"`
}

type Store interface {
	// Put uploads a file from an io.Reader. The reader is consumed entirely.
	// Key is the logical path (e.g. "tenant_a/uploads/image.png").
	// Returns the final storage key (with tenant prefix applied) and object info.
	Put(ctx context.Context, key string, reader io.Reader, opts PutOptions) (ObjectInfo, error)

	// Get retrieves a file by key. Returns an io.ReadCloser that MUST be closed.
	// Returns ErrNotFound if the key does not exist.
	Get(ctx context.Context, key string) (io.ReadCloser, ObjectInfo, error)

	// Delete removes an object by key. Idempotent: no error if key doesn't exist.
	Delete(ctx context.Context, key string) error

	// Exists checks if a key exists.
	Exists(ctx context.Context, key string) (bool, error)

	// List returns objects with the given prefix.
	List(ctx context.Context, opts ListOptions) (ListResult, error)

	// PublicURL returns a publicly accessible URL for a key.
	// Returns empty string if the object is private or the provider
	// doesn't support public URLs.
	PublicURL(ctx context.Context, key string, opts URLConfig) (string, error)

	// SignedURL returns a time-limited URL for accessing a private object.
	// The URL grants direct access to the object without authentication.
	SignedURL(ctx context.Context, key string, expires time.Duration, opts URLConfig) (string, error)

	// Copy copies an object from srcKey to dstKey (within the same bucket/container).
	Copy(ctx context.Context, srcKey, dstKey string) (ObjectInfo, error)

	// Close releases any resources held by the store (connections, background goroutines).
	Close() error
}

type URLConfig struct {
	// Expires sets the URL validity duration. Only meaningful for SignedURL.
	Expires time.Duration

	// ContentType overrides the Content-Type header for the URL response.
	ContentType string

	// Disposition sets Content-Disposition header ("inline" or "attachment").
	Disposition string
}

type Visibility string