driver

type BucketConfig struct {
	// Region overrides the default region for the bucket.
	Region string
}

type BucketInfo struct {
	Name      string    `json:"name"`
	CreatedAt time.Time `json:"created_at"`
}

type BucketOption func(*BucketConfig)

type Config struct {
	// Region is the cloud region for the storage backend.
	Region string

	// Endpoint overrides the default service endpoint.
	Endpoint string

	// ForcePathStyle forces path-style addressing for S3-compatible backends.
	ForcePathStyle bool
}

type CopyConfig struct {
	// Metadata overrides the source object's metadata on the copy.
	Metadata map[string]string
}

type CopyOption func(*CopyConfig)

type DSNConfig struct {
	// Scheme is the protocol scheme (e.g., "s3", "gcs", "file", "mem").
	Scheme string

	// User is the username or access key.
	User string

	// Password is the password or secret key.
	Password string

	// Host is the hostname and optional port.
	Host string

	// Path is the path component (e.g., bucket, directory).
	Path string

	// Params holds query string parameters.
	Params url.Values
}

type DeleteConfig struct {
	// VersionID deletes a specific version.
	VersionID string
}

type DeleteOption func(*DeleteConfig)

type Driver interface {
	// Name returns the driver identifier (e.g., "s3", "gcs", "azure", "local", "mem").
	Name() string

	// Open initializes the driver connection with the given DSN and options.
	Open(ctx context.Context, dsn string, opts ...Option) error

	// Close gracefully shuts down the driver, draining active streams.
	Close(ctx context.Context) error

	// Ping verifies backend connectivity.
	Ping(ctx context.Context) error

	// Put stores an object from a reader. Returns the stored object metadata.
	Put(ctx context.Context, bucket, key string, r io.Reader, opts ...PutOption) (*ObjectInfo, error)

	// Get retrieves an object, returning a ReadCloser for the content.
	Get(ctx context.Context, bucket, key string, opts ...GetOption) (*ObjectReader, error)

	// Delete removes an object.
	Delete(ctx context.Context, bucket, key string, opts ...DeleteOption) error

	// Head returns object metadata without content.
	Head(ctx context.Context, bucket, key string) (*ObjectInfo, error)

	// List returns objects matching the given options.
	List(ctx context.Context, bucket string, opts ...ListOption) (*ObjectIterator, error)

	// Copy copies an object within or across buckets.
	Copy(ctx context.Context, srcBucket, srcKey, dstBucket, dstKey string, opts ...CopyOption) (*ObjectInfo, error)

	// CreateBucket creates a new bucket/container.
	CreateBucket(ctx context.Context, name string, opts ...BucketOption) error

	// DeleteBucket removes a bucket.
	DeleteBucket(ctx context.Context, name string) error

	// ListBuckets returns all accessible buckets.
	ListBuckets(ctx context.Context) ([]BucketInfo, error)
}

type Factory func() Driver

type GetConfig struct {
	// Range specifies a byte range to retrieve (e.g., "bytes=0-1023").
	Range string

	// VersionID retrieves a specific version of the object.
	VersionID string
}

type GetOption func(*GetConfig)

type KeyPage struct {
	// Keys are the object keys on this page, in order.
	Keys []string
	// Prefixes are the common prefixes on this page, in order.
	Prefixes []string
	// NextToken is the last item on this page when more items follow,
	// and empty when the listing is complete.
	NextToken string
}

type LifecycleDriver interface {
	Driver
	SetLifecycle(ctx context.Context, bucket string, rules []LifecycleRule) error
	GetLifecycle(ctx context.Context, bucket string) ([]LifecycleRule, error)
}

type LifecycleRule struct {
	ID                string `json:"id"`
	Prefix            string `json:"prefix"`
	ExpirationDays    int    `json:"expiration_days,omitempty"`
	TransitionDays    int    `json:"transition_days,omitempty"`
	TransitionStorage string `json:"transition_storage,omitempty"`
	Enabled           bool   `json:"enabled"`
}

type ListConfig struct {
	// Prefix filters objects by key prefix.
	Prefix string

	// Delimiter groups keys by a delimiter character (e.g., "/"). Keys that
	// contain the delimiter after Prefix are folded into a common prefix and
	// come back in ObjectIterator.CommonPrefixes() instead of as objects.
	Delimiter string

	// MaxKeys is the maximum number of objects and common prefixes returned
	// together in one page.
	MaxKeys int

	// Cursor is the NextToken from a previous List call, passed back
	// unchanged. It is opaque: drivers may use a key, a backend
	// continuation token or anything else, so never construct one.
	Cursor string
}

type ListOption func(*ListConfig)

type MultipartDriver interface {
	Driver
	InitiateMultipart(ctx context.Context, bucket, key string, opts ...PutOption) (uploadID string, err error)
	UploadPart(ctx context.Context, bucket, key, uploadID string, partNum int, r io.Reader) (*PartInfo, error)
	CompleteMultipart(ctx context.Context, bucket, key, uploadID string, parts []PartInfo) (*ObjectInfo, error)
	AbortMultipart(ctx context.Context, bucket, key, uploadID string) error
}

type NotificationDriver interface {
	Driver
	Watch(ctx context.Context, bucket string, opts ...WatchOption) (<-chan ObjectEvent, error)
}

type ObjectEvent struct {
	Type   ObjectEventType `json:"type"`
	Bucket string          `json:"bucket"`
	Key    string          `json:"key"`
	Info   *ObjectInfo     `json:"info,omitempty"`
}

type ObjectEventType string

type ObjectInfo struct {
	Key          string            `json:"key"`
	Size         int64             `json:"size"`
	ContentType  string            `json:"content_type"`
	ETag         string            `json:"etag"`
	LastModified time.Time         `json:"last_modified"`
	Metadata     map[string]string `json:"metadata,omitempty"`
	VersionID    string            `json:"version_id,omitempty"`
	StorageClass string            `json:"storage_class,omitempty"`
}

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

type ObjectReader struct {
	io.ReadCloser
	Info *ObjectInfo
}

type ObjectRef struct {
	Bucket string `json:"bucket"`
	Key    string `json:"key"`
}

type Option func(*Config)

type PartInfo struct {
	PartNumber int    `json:"part_number"`
	ETag       string `json:"etag"`
	Size       int64  `json:"size"`
}

type PresignDriver interface {
	Driver
	PresignGet(ctx context.Context, bucket, key string, expires time.Duration) (string, error)
	PresignPut(ctx context.Context, bucket, key string, expires time.Duration) (string, error)
}

type PutConfig struct {
	ContentType  string
	Metadata     map[string]string
	Tags         map[string]string
	StorageClass string
}

type PutOption func(*PutConfig)

type RangeDriver interface {
	Driver
	// GetRange retrieves a byte range of an object. The offset is the
	// starting byte position and length is the number of bytes to read.
	// A length of -1 reads from offset to end.
	GetRange(ctx context.Context, bucket, key string, offset, length int64) (*ObjectReader, error)
}

type ServerCopyDriver interface {
	Driver
	ServerCopy(ctx context.Context, src, dst ObjectRef) (*ObjectInfo, error)
}

type VersionInfo struct {
	VersionID    string    `json:"version_id"`
	Key          string    `json:"key"`
	Size         int64     `json:"size"`
	LastModified time.Time `json:"last_modified"`
	IsLatest     bool      `json:"is_latest"`
}

type VersioningDriver interface {
	Driver
	ListVersions(ctx context.Context, bucket, key string) ([]VersionInfo, error)
	GetVersion(ctx context.Context, bucket, key, versionID string) (*ObjectReader, error)
	DeleteVersion(ctx context.Context, bucket, key, versionID string) error
	RestoreVersion(ctx context.Context, bucket, key, versionID string) (*ObjectInfo, error)
}

type WatchConfig struct {
	Prefix     string
	EventTypes []ObjectEventType
}

type WatchOption func(*WatchConfig)