objectstorex

type Client interface {

	// Bucket returns the default bucket name.
	Bucket() string

	// BucketExists checks if the configured bucket exists.
	BucketExists(ctx context.Context) (bool, error)

	// EnsureBucket creates the bucket if it doesn't exist. Idempotent.
	EnsureBucket(ctx context.Context) error

	// PutObject uploads an object. body is the reader; size is the content
	// length (use -1 if unknown). Returns ObjectInfo on success.
	PutObject(ctx context.Context, key string, body ReadSeeker, size int64, opts PutOptions) (ObjectInfo, error)

	// GetObject downloads an object. Returns a ReadCloser (caller must close)
	// and ObjectInfo. Returns ErrNotFound if the key doesn't exist.
	GetObject(ctx context.Context, key string, opts GetOptions) (ReadCloser, ObjectInfo, error)

	// DeleteObject removes an object. No-op if the key doesn't exist.
	DeleteObject(ctx context.Context, key string) error

	// StatObject returns metadata about an object without downloading it.
	StatObject(ctx context.Context, key string) (ObjectInfo, error)

	// ListObjects lists objects in the bucket matching the prefix.
	ListObjects(ctx context.Context, opts ListOptions) ([]ObjectInfo, error)

	// CopyObject copies an object from srcKey to dstKey.
	CopyObject(ctx context.Context, srcKey, dstKey string, opts PutOptions) (ObjectInfo, error)

	// PresignPut generates a presigned URL for uploading an object directly
	// from the browser. The URL expires after expiry.
	PresignPut(ctx context.Context, key string, expiry time.Duration) (string, error)

	// PresignGet generates a presigned URL for downloading an object directly
	// from the browser. The URL expires after expiry.
	PresignGet(ctx context.Context, key string, expiry time.Duration) (string, error)

	// InitMultipartUpload starts a multipart upload session.
	// Returns an upload ID that must be passed to UploadPart and CompleteMultipartUpload.
	InitMultipartUpload(ctx context.Context, key string, opts PutOptions) (uploadID string, err error)

	// UploadPart uploads a single part of a multipart upload.
	// partNumber is 1-indexed. Returns the ETag of the part.
	UploadPart(ctx context.Context, key, uploadID string, partNumber int, body ReadSeeker, size int64) (etag string, err error)

	// CompleteMultipartUpload finalizes a multipart upload by assembling
	// all uploaded parts into the final object.
	CompleteMultipartUpload(ctx context.Context, key, uploadID string, parts []CompletedPart) (ObjectInfo, error)

	// AbortMultipartUpload cancels a multipart upload and discards uploaded parts.
	AbortMultipartUpload(ctx context.Context, key, uploadID string) error

	// Close closes the underlying client. Idempotent.
	Close() error

	// DriverName returns the registered driver name.
	DriverName() string
}

type CompletedPart struct {
	PartNumber int
	ETag       string
}

type Config struct {
	// Driver selects the registered driver: "minio".
	Driver string `json:"driver"`

	// Endpoint is the S3-compatible endpoint URL.
	// Minio: "localhost:9000"
	// AWS S3: "s3.us-east-1.amazonaws.com"
	Endpoint string `json:"endpoint"`

	// UseSSL enables HTTPS.
	UseSSL bool `json:"use_ssl"`

	// AccessKey is the access key ID.
	AccessKey string `json:"access_key"`

	// SecretKey is the secret access key.
	SecretKey string `json:"secret_key"`

	// Bucket is the default bucket name.
	Bucket string `json:"bucket"`

	// Region is the S3 region (leave empty for Minio).
	Region string `json:"region"`

	// EnsureBucket, if true, creates the bucket on startup if it doesn't exist.
	EnsureBucket bool `json:"ensure_bucket"`

	// PresignExpiry is the default expiry for presigned URLs.
	// Zero means 15 minutes.
	PresignExpiry time.Duration `json:"presign_expiry_ns"`

	// Logger is the component logger. If nil, objectstorex uses logx.DefaultLogger().
	Logger logx.Logger `json:"-" yaml:"-"`

	// Metrics is the optional metrics manager for object store operations.
	Metrics metricsx.Manager `json:"-" yaml:"-"`

	// MetricsEnabled controls whether object store operations record metrics.
	MetricsEnabled bool `json:"metrics_enabled" yaml:"metrics_enabled"`
}

type DriverOpener func(cfg Config) (Client, error)

type GetOptions struct {
	// Range requests a byte range (e.g., "bytes=0-1023"). Empty = full object.
	Range string
}

type ListOptions struct {
	// Prefix filters objects by key prefix.
	Prefix string
	// MaxKeys limits the number of results. 0 = use server default (1000).
	MaxKeys int
	// Recursive lists all objects (not just "folders").
	Recursive bool
}

type ObjectInfo struct {
	Bucket       string
	Key          string
	Size         int64
	ContentType  string
	ETag         string
	LastModified time.Time
	Metadata     map[string]string
}

type PutOptions struct {
	ContentType string
	Metadata    map[string]string
	// CacheControl sets the Cache-Control header.
	CacheControl string
}

type ReadCloser interface {
	Read(p []byte) (n int, err error)
	Close() error
}

type ReadSeeker interface {
	Read(p []byte) (n int, err error)
	Seek(offset int64, whence int) (int64, error)
}