object

type ByteRange struct {
	Start  uint64
	End    uint64 // Inclusive
	Length uint64
}

type CRRHook interface {
	AfterPutObject(ctx context.Context, bucketInfo interface{}, key, etag string, size int64)
	AfterDeleteObject(ctx context.Context, bucketInfo interface{}, key string)
}

type ConditionalResult struct {
	ShouldProceed bool
	StatusCode    int  // HTTP status code if ShouldProceed is false
	NotModified   bool // true for 304 Not Modified
}

type Config struct {
	DB             db.DB
	Storage        *storage.Coordinator
	Encryption     *encryption.Handler
	BucketStore    *cache.BucketStore
	DefaultProfile string
	Profiles       *types.ProfileSet
	CRRHook        CRRHook          // Optional, enterprise feature
	Emitter        *events.Emitter  // Optional, for S3 event notifications
	BackendManager *backend.Manager // Optional, for reading transitioned objects
	TaskQueue      taskqueue.Queue  // Optional, for intelligent tiering promotions
}

type CopyObjectRequest struct {
	SourceBucket string
	SourceKey    string
	DestBucket   string
	DestKey      string

	// Directives
	MetadataDirective string // "COPY" or "REPLACE"
	TaggingDirective  string // "COPY" or "REPLACE"

	// Content-Type for destination object (used when MetadataDirective is REPLACE)
	// If empty with REPLACE, defaults to application/octet-stream
	ContentType string

	// Metadata for destination object (used when MetadataDirective is REPLACE)
	// Keys are lowercase header names without the x-amz-meta- prefix
	// If nil with REPLACE, destination gets no user metadata
	Metadata map[string]string

	// Tags for destination object (used when TaggingDirective is REPLACE)
	// If nil with REPLACE, destination gets no tags
	Tags []Tag

	// Storage class for destination object (optional)
	// If not specified, inherits from source object
	StorageClass string

	// Conditional headers for source
	CopySourceIfMatch           string
	CopySourceIfNoneMatch       string
	CopySourceIfModifiedSince   *time.Time
	CopySourceIfUnmodifiedSince *time.Time

	// SSE-KMS encryption for destination (optional)
	// If not specified and source is encrypted, copy the encryption
	// If not specified and bucket has default encryption, use that
	SSEKMS *SSEKMSParams
}

type CopyObjectResult struct {
	ETag         string
	LastModified time.Time
	VersionID    string

	// SSE response info (if encryption was applied)
	SSEAlgorithm      string
	SSEKMSKeyID       string
	SSEKMSContext     string
	SSECustomerKeyMD5 string
}

type DeleteError struct {
	Key       string
	VersionID string
	Code      string
	Message   string
}

type DeleteObjectEntry struct {
	Key       string
	VersionID string
}

type DeleteObjectResult struct {
	VersionID      string
	DeleteMarker   bool
	DeleteMarkerID string
}

type DeleteObjectsRequest struct {
	Bucket  string
	Objects []DeleteObjectEntry
	Quiet   bool
}

type DeleteObjectsResult struct {
	Deleted []DeletedObject
	Errors  []DeleteError
}

type DeletedObject struct {
	Key                   string
	VersionID             string
	DeleteMarker          bool
	DeleteMarkerVersionID string
}

type Error struct {
	Code    ErrorCode
	Message string
	Err     error
}

type ErrorCode int

type GetObjectRequest struct {
	Bucket    string
	Key       string
	VersionID string     // Specific version to retrieve (empty for latest)
	Range     *ByteRange // nil for full object

	// For SSE-C encrypted objects
	SSEC *SSECParams

	// For SSE-KMS key validation (optional)
	SSEKMSKeyID string

	// Conditional headers
	IfMatch           string
	IfNoneMatch       string
	IfModifiedSince   *time.Time
	IfUnmodifiedSince *time.Time
}

type GetObjectResult struct {
	Object   *types.ObjectRef
	Body     io.ReadCloser // Caller must close
	Metadata *ObjectMetadata

	// Range info (populated if range request)
	Range        *ByteRange
	IsPartial    bool
	AcceptRanges string
}

type HeadObjectResult struct {
	Object   *types.ObjectRef
	Metadata *ObjectMetadata
}

type ListObjectsRequest struct {
	Bucket    string
	Prefix    string
	Delimiter string
	Marker    string
	MaxKeys   int
}

type ListObjectsResult struct {
	Name           string
	Prefix         string
	Marker         string
	NextMarker     string
	Delimiter      string
	MaxKeys        int
	IsTruncated    bool
	Contents       []ObjectEntry
	CommonPrefixes []string
}

type ListObjectsV2Request struct {
	Bucket            string
	Prefix            string
	Delimiter         string
	ContinuationToken string
	StartAfter        string
	MaxKeys           int
	FetchOwner        bool
}

type ListObjectsV2Result struct {
	Name                  string
	Prefix                string
	Delimiter             string
	MaxKeys               int
	KeyCount              int
	IsTruncated           bool
	ContinuationToken     string
	NextContinuationToken string
	StartAfter            string
	Contents              []ObjectEntry
	CommonPrefixes        []string
}

type ObjectEntry struct {
	Key          string
	LastModified time.Time
	ETag         string
	Size         uint64
	StorageClass string
	Owner        *ObjectOwner
}

type ObjectMetadata struct {
	ETag         string
	LastModified time.Time
	Size         uint64
	ContentType  string
	StorageClass string

	// Encryption metadata
	SSEAlgorithm      string
	SSECustomerKeyMD5 string
	SSEKMSKeyID       string
	SSEKMSContext     string

	// User-defined metadata (x-amz-meta-* headers)
	Metadata map[string]string
}

type ObjectOwner struct {
	ID          string
	DisplayName string
}

type PutObjectRequest struct {
	Bucket        string
	Key           string
	Body          io.Reader
	ContentLength int64  // -1 if unknown (chunked encoding)
	ContentType   string // MIME type (defaults to application/octet-stream)
	StorageClass  string
	Owner         string

	// ACL for the object (nil uses default private ACL)
	ACL *s3types.AccessControlList

	// User-defined metadata (x-amz-meta-* headers)
	// Keys are lowercase header names without the x-amz-meta- prefix
	Metadata map[string]string

	// Encryption options (mutually exclusive)
	SSEC   *SSECParams
	SSEKMS *SSEKMSParams
}

type PutObjectResult struct {
	ETag      string
	VersionID string

	// Encryption metadata for response headers
	SSEAlgorithm      string
	SSECustomerKeyMD5 string
	SSEKMSKeyID       string
	SSEKMSContext     string
}

type SSECParams struct {
	Algorithm string // "AES256"
	Key       []byte // 32 bytes for AES-256
	KeyMD5    string // Base64-encoded MD5 of key
}

type SSEKMSParams struct {
	KeyID   string
	Context string // JSON encryption context
}

type Service interface {
	// PutObject stores an object and returns the result.
	// For SSE-C/SSE-KMS, the body is encrypted before storage.
	PutObject(ctx context.Context, req *PutObjectRequest) (*PutObjectResult, error)

	// GetObject retrieves an object for reading.
	// Returns a ReadCloser that the caller must close.
	// For SSE-C/SSE-KMS encrypted objects, decryption is handled transparently.
	GetObject(ctx context.Context, req *GetObjectRequest) (*GetObjectResult, error)

	// HeadObject retrieves object metadata without the body.
	HeadObject(ctx context.Context, bucket, key string) (*HeadObjectResult, error)

	// DeleteObject soft-deletes an object.
	// Returns nil if the object doesn't exist (S3 compatibility).
	DeleteObject(ctx context.Context, bucket, key string) (*DeleteObjectResult, error)

	// DeleteObjectWithVersion handles versioned delete operations.
	// If versionID is empty and versioning is enabled, creates a delete marker.
	// If versionID is provided, permanently deletes that specific version.
	DeleteObjectWithVersion(ctx context.Context, bucket, key, versionID string) (*DeleteObjectResult, error)

	// DeleteObjects batch deletes multiple objects.
	DeleteObjects(ctx context.Context, req *DeleteObjectsRequest) (*DeleteObjectsResult, error)

	// CopyObject copies an object within or between buckets.
	// For server-side copy, no data transfer occurs.
	CopyObject(ctx context.Context, req *CopyObjectRequest) (*CopyObjectResult, error)

	// ListObjects lists objects using v1 API pagination.
	ListObjects(ctx context.Context, req *ListObjectsRequest) (*ListObjectsResult, error)

	// ListObjectsV2 lists objects using v2 API pagination.
	ListObjectsV2(ctx context.Context, req *ListObjectsV2Request) (*ListObjectsV2Result, error)
}

type Tag struct {
	Key   string
	Value string
}