provider

type ConditionalCapabilityReporter interface {
	ConditionalWriteCapabilities() ConditionalWriteCapabilities
}

type ConditionalMultipartCompleter interface {
	CompleteMultipartUploadConditional(ctx context.Context, key, uploadID string, parts []PartETag, precond PutPrecondition) (PutResult, error)
}

type ConditionalPutter interface {
	PutObjectConditional(ctx context.Context, key string, body io.Reader, contentLength int64, precond PutPrecondition) (PutResult, error)
}

type ConditionalWriteCapabilities struct {
	// IfAbsent reports that PutObjectConditional honors an IfAbsent precondition.
	IfAbsent bool
	// IfMatchETag reports that PutObjectConditional honors an IfMatchETag
	// precondition (atomic compare-and-swap against the destination ETag).
	IfMatchETag bool
	// ConditionalMultipartCompletion reports that CompleteMultipartUploadConditional
	// honors its precondition, so a large conditional overwrite completes
	// atomically instead of uploading parts and discovering the predicate is
	// unsupported only at completion time.
	ConditionalMultipartCompletion bool
}

type ConnectionPoolPolicy struct {
	// MaxIdleConnsPerHost is idle retention capacity per host. Zero leaves
	// SDK / transport defaults.
	MaxIdleConnsPerHost int
	// MaxConnsPerHost is the hard cap across active, dialing, and idle
	// connections per host. Zero leaves SDK / transport defaults.
	MaxConnsPerHost int
}

type DelimiterLister interface {
	ListWithDelimiter(ctx context.Context, opts ListWithDelimiterOptions) (*ListWithDelimiterResult, error)
}

type ListCommonPrefixesOptions struct {
	Prefix            string
	Delimiter         string
	ContinuationToken string
	MaxKeys           int
}

type ListCommonPrefixesResult struct {
	Prefixes          []string
	ContinuationToken string
	IsTruncated       bool
}

type ListOptions struct {
	// Prefix filters results to keys starting with this value.
	// Empty string lists all objects.
	Prefix string

	// ContinuationToken resumes listing from a previous ListResult.
	// Empty string starts from the beginning.
	ContinuationToken string

	// MaxKeys limits the number of objects returned per page.
	// Zero uses provider default (typically 1000).
	MaxKeys int
}

type ListResult struct {
	// Objects contains the object summaries for this page.
	Objects []ObjectSummary

	// ContinuationToken is used to retrieve the next page.
	// Empty string indicates no more pages.
	ContinuationToken string

	// IsTruncated indicates whether more results are available.
	IsTruncated bool
}

type ListWithDelimiterOptions struct {
	// Prefix filters results to keys starting with this value.
	Prefix string

	// Delimiter groups keys (e.g., "/").
	Delimiter string

	// ContinuationToken resumes listing from a previous ListWithDelimiterResult.
	ContinuationToken string

	// MaxKeys limits the number of keys returned per page.
	MaxKeys int
}

type ListWithDelimiterResult struct {
	// Objects are object summaries directly under the requested Prefix.
	Objects []ObjectSummary

	// CommonPrefixes are the immediate child prefixes.
	CommonPrefixes []string

	// ContinuationToken is used to retrieve the next page.
	ContinuationToken string

	// IsTruncated indicates whether more results are available.
	IsTruncated bool
}

type MetadataAwareMultipartUploader interface {
	CreateMultipartUploadWithOptions(ctx context.Context, key string, opts PutOptions) (uploadID string, err error)
}

type MetadataAwarePutter interface {
	PutObjectWithOptions(ctx context.Context, key string, body io.Reader, contentLength int64, opts PutOptions) error
	PutObjectConditionalWithOptions(ctx context.Context, key string, body io.Reader, contentLength int64, precond PutPrecondition, opts PutOptions) (PutResult, error)
}

type MetadataAwareResultPutter interface {
	PutObjectResultWithOptions(ctx context.Context, key string, body io.Reader, contentLength int64, opts PutOptions) (PutResult, error)
}

type MultipartUploader interface {
	CreateMultipartUpload(ctx context.Context, key string) (uploadID string, err error)
	UploadPart(ctx context.Context, key, uploadID string, partNumber int32, body io.Reader, size int64) (PartETag, error)
	CompleteMultipartUpload(ctx context.Context, key, uploadID string, parts []PartETag) (PutResult, error)
	AbortMultipartUpload(ctx context.Context, key, uploadID string) error
}

type ObjectDeleter interface {
	DeleteObject(ctx context.Context, key string) error
}

type ObjectGetter interface {
	GetObject(ctx context.Context, key string) (body io.ReadCloser, contentLength int64, err error)
}

type ObjectMeta struct {
	ObjectSummary

	// Version is the provider-specific version handle, when available.
	// For S3 this is the VersionId. Providers without native object versions
	// may leave it empty.
	Version string

	// ContentType is the MIME type of the object.
	ContentType string

	// Metadata contains user-defined metadata key-value pairs.
	Metadata map[string]string

	// StorageClass is the provider-native object storage class. Providers may
	// leave it empty when the concept is unsupported or unknown.
	StorageClass string

	// ArchiveStatus is the provider-native archive access status observed via
	// HEAD, when supplied. For S3 this is typically ARCHIVE_ACCESS or
	// DEEP_ARCHIVE_ACCESS.
	ArchiveStatus string

	// RestoreState is the normalized restore state observed via HEAD. Supported
	// values are ongoing, completed, expired, and unknown.
	RestoreState string

	// RestoreExpiry is the provider-reported restore expiry timestamp, when
	// available.
	RestoreExpiry *time.Time
}

type ObjectPutter interface {
	PutObject(ctx context.Context, key string, body io.Reader, contentLength int64) error
}

type ObjectRanger interface {
	GetRange(ctx context.Context, key string, start, endInclusive int64) (body io.ReadCloser, contentLength int64, err error)
}

type ObjectSummary struct {
	// Key is the full object key (path) in the bucket.
	Key string

	// Size is the object size in bytes.
	Size int64

	// ETag is the entity tag, typically an MD5 hash of the object.
	ETag string

	// Revision is a provider-native immutable version or generation returned by
	// LIST, when available. It is opaque outside the provider adapter.
	Revision string

	// LastModified is when the object was last modified.
	LastModified time.Time

	// StorageClass is the provider-native storage class returned by LIST, when
	// available. Providers may leave it empty when unsupported or omitted.
	StorageClass string
}

type PartETag struct {
	PartNumber int32
	ETag       string
}

type PrefixLister interface {
	ListCommonPrefixes(ctx context.Context, opts ListCommonPrefixesOptions) (*ListCommonPrefixesResult, error)
}

type Provider interface {
	// List returns a page of objects with the given prefix.
	// Use ContinuationToken from ListResult for subsequent pages.
	List(ctx context.Context, opts ListOptions) (*ListResult, error)

	// Head returns metadata for a single object.
	// Returns ErrNotFound if the object does not exist.
	Head(ctx context.Context, key string) (*ObjectMeta, error)

	// Close releases any resources held by the provider.
	Close() error
}

type ProviderError struct {
	// Op is the operation that failed (e.g., "List", "Head").
	Op string

	// Provider is the provider type (e.g., "s3").
	Provider ProviderType

	// Bucket is the bucket name, if applicable.
	Bucket string

	// Key is the object key, if applicable.
	Key string

	// Err is the underlying error.
	Err error
}

type ProviderType string

type PutOptions struct {
	// UserMetadata contains user-defined object metadata keys without provider
	// wire prefixes such as x-amz-meta-. Keys should already be canonicalized by
	// callers that expose user input.
	UserMetadata map[string]string

	// ContentType is the destination object's content type. Empty means provider
	// default.
	ContentType string

	// StorageClass is the destination object's provider-native storage class.
	// Empty means provider default.
	StorageClass string
}

type PutPrecondition struct {
	IfAbsent    bool
	IfMatchETag *string
}

type PutResult struct {
	ETag    string
	Version string
}

type ResultPutter interface {
	PutObjectResult(ctx context.Context, key string, body io.Reader, contentLength int64) (PutResult, error)
}

type RevisionGetter interface {
	GetObjectRevision(ctx context.Context, key string, revision SourceRevision) (body io.ReadCloser, meta ObjectMeta, err error)
}

type RevisionKind string

type SourceRevision struct {
	Kind  RevisionKind
	Value string
}

type VersionedGetter interface {
	GetObjectVersioned(ctx context.Context, key string) (body io.ReadCloser, meta ObjectMeta, err error)
}