pail

type Bucket interface {
	// Check validity of the bucket. This is dependent on the underlying
	// implementation.
	Check(context.Context) error

	// Exists returns whether the given key exists in the bucket or not.
	Exists(context.Context, string) (bool, error)

	// Join concatenates elements with the appropriate path separator of
	// the bucket, ignoring empty elements. This is analogous to
	// `filepath.Join`.
	Join(...string) string

	// Produces a Writer and Reader interface to the file named by
	// the string.
	Writer(context.Context, string) (io.WriteCloser, error)
	Reader(context.Context, string) (io.ReadCloser, error)

	// Put and Get write simple byte streams (in the form of
	// io.Readers) to/from specified keys.
	//
	// TODO: consider if these, particularly Get are not
	// substantively different from Writer/Reader methods, or
	// might just be a wrapper.
	Put(context.Context, string, io.Reader) error
	Get(context.Context, string) (io.ReadCloser, error)

	// Upload and Download write files from the local file
	// system to the specified key.
	Upload(context.Context, string, string) error
	Download(context.Context, string, string) error

	SyncBucket

	// Copy does a special copy operation that does not require downloading
	// a file. Note that CopyOptions.DestinationBucket must have the same
	// type as the calling bucket object.
	Copy(context.Context, CopyOptions) error

	// Remove the specified object(s) from the bucket.
	// RemoveMany continues on error and returns any accumulated errors.
	Remove(context.Context, string) error
	RemoveMany(context.Context, ...string) error

	// Remove all objects with the given prefix, continuing on error and
	// returning any accumulated errors.
	// Note that this operation is not atomic.
	RemovePrefix(context.Context, string) error

	// Remove all objects matching the given regular expression, continuing
	// on error and returning any accumulated errors.
	// Note that this operation is not atomic.
	RemoveMatching(context.Context, string) error

	// List returns an iterator over the contents of a bucket with the
	// the given prefix. Contents are iterated lexicographically by key
	// name.
	List(context.Context, string) (BucketIterator, error)

	// String returns the bucket name.
	String() string

	// MoveObjects moves multiple objects from sourceKeys in this bucket to destKeys in another bucket specified by destBucket.
	// The lengths of sourceKeys and destKeys must match.
	MoveObjects(ctx context.Context, destBucket Bucket, sourceKeys, destKeys []string) error
}

type BucketItem interface {
	Bucket() string
	Name() string
	Hash() string
	// Size returns the object size in bytes.
	Size() int64
	Get(context.Context) (io.ReadCloser, error)
}

type BucketIterator interface {
	Next(context.Context) bool
	Err() error
	Item() BucketItem
}

type CopyOptions struct {
	SourceKey         string
	DestinationKey    string
	DestinationBucket Bucket
	IsDestination     bool
}

type FastGetS3Bucket interface {
	Bucket
	// GetToWriter allows the user to pass in an io.WriterAt (which is likely
	// going to be a file) that has the contents of the remote key automatically
	// copied to it in parallel. GetToWriter is significantly more efficient for
	// large files than a Bucket.Get.
	GetToWriter(context.Context, string, io.WriterAt) error
}

type GridFSOptions struct {
	Name         string
	Prefix       string
	Database     string
	MongoDBURI   string
	DryRun       bool
	DeleteOnSync bool
	DeleteOnPush bool
	DeleteOnPull bool
	Verbose      bool
}

type LifecycleRule struct {
	// ID is the unique identifier for the rule
	ID string

	// Prefix is the object key prefix that the rule applies to (extracted from Filter or deprecated Prefix field)
	Prefix string

	// Status indicates whether the rule is currently active ("Enabled" or "Disabled")
	Status string

	// ExpirationDays is the number of days after creation when objects expire (nil if not set)
	ExpirationDays *int32

	// TransitionToIADays is the number of days after creation when objects should transition to STANDARD_IA (nil if not set)
	TransitionToIADays *int32

	// TransitionToGlacierDays is the number of days after creation when objects transition to GLACIER (nil if not set)
	TransitionToGlacierDays *int32

	// Transitions contains all transition rules with full details (empty if none)
	Transitions []Transition
}

type LocalOptions struct {
	Path   string
	Prefix string
	// UseSlash sets the prefix separator to the slash ('/') character
	// instead of the OS specific separator.
	UseSlash     bool
	DryRun       bool
	DeleteOnSync bool
	DeleteOnPush bool
	DeleteOnPull bool
	Verbose      bool
}

type ParallelBucketOptions struct {
	// Workers sets the number of worker threads.
	Workers int
	// DryRun enables running in a mode that will not execute any
	// operations that modify the bucket.
	DryRun bool
	// DeleteOnSync will delete all objects from the target that do not
	// exist in the source after the completion of a sync operation
	// (Push/Pull).
	DeleteOnSync bool
	// DeleteOnPush will delete all objects from the target that do not
	// exist in the source after the completion of Push.
	DeleteOnPush bool
	// DeleteOnPull will delete all objects from the target that do not
	// exist in the source after the completion of Pull.
	DeleteOnPull bool
}

type PreSignRequestParams struct {
	Bucket                string
	FileKey               string
	Region                string
	SignatureExpiryWindow time.Duration

	// Static credentials specific fields.
	AWSKey          string
	AWSSecret       string
	AWSSessionToken string

	// AssumeRole specific fields.
	AWSRoleARN string
	ExternalID *string
}

type PutCounter interface {
	Bucket
	UploadWithCount(ctx context.Context, key, path string) (int, error)
}

type S3Options struct {
	// DryRun enables running in a mode that will not execute any
	// operations that modify the bucket.
	DryRun bool
	// DeleteOnSync will delete all objects from the target that do not
	// exist in the destination after the completion of a sync operation
	// (Push/Pull).
	DeleteOnSync bool
	// DeleteOnPush will delete all objects from the target that do not
	// exist in the source after the completion of Push.
	DeleteOnPush bool
	// DeleteOnPull will delete all objects from the target that do not
	// exist in the source after the completion of Pull.
	DeleteOnPull bool
	// Compress enables gzipping of uploaded objects. For downloading, objects
	// that are compressed with gzip are automatically decoded.
	Compress bool
	// ExpectedChecksumSHA256 enables checksum verification of downloads using the
	// SHA256 checksum stored in S3. This requires that the object was
	// originally uploaded with the checksum information.
	ExpectedChecksumSHA256 string
	// UploadChecksumSHA256 enables sending the SHA256 checksum of uploads.
	UploadChecksumSHA256 bool
	// Verbose sets the logging mode to "debug".
	Verbose bool
	// MaxRetries sets the number of retry attempts for S3 operations.
	// By default it defers to the AWS SDK's default.
	MaxRetries *int
	// Credentials allows the passing in of explicit AWS credentials. These
	// will override the default credentials chain. (Optional)
	Credentials aws.CredentialsProvider
	// SharedCredentialsFilepath, when not empty, will override the default
	// credentials chain and the Credentials value (see above). (Optional)
	SharedCredentialsFilepath string
	// SharedCredentialsProfile, when not empty, will fetch the given
	// credentials profile from the shared credentials file. (Optional)
	SharedCredentialsProfile string
	// AssumeRoleARN specifies an IAM role ARN. When not empty, it will be
	// used to assume the given role for this session. See
	// `https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html` for
	// more information. (Optional)
	AssumeRoleARN string
	// AssumeRoleOptions provide a mechanism to override defaults by
	// applying changes to the AssumeRoleProvider struct created with this
	// session. This field is ignored if AssumeRoleARN is not set.
	// (Optional)
	AssumeRoleOptions []func(*stscreds.AssumeRoleOptions)
	// Region specifies the AWS region.
	Region string
	// Name specifies the name of the bucket.
	Name string
	// Prefix specifies the prefix to use. (Optional)
	Prefix string
	// Permissions sets the S3 permissions to use for each object. Defaults
	// to FULL_CONTROL. See
	// `https://docs.aws.amazon.com/AmazonS3/latest/dev/acl-overview.html`
	// for more information.
	Permissions S3Permissions
	// ContentType sets the standard MIME type of the object data. Defaults
	// to nil. See
	//`https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17`
	// for more information.
	ContentType string
	// StorageClass sets the S3 storage class for uploaded objects. Defaults
	// to S3's default storage class (STANDARD) if not set. See
	// https://aws.amazon.com/s3/storage-classes/ for more information.
	StorageClass s3Types.StorageClass
	// IfNotExists, when set to true, will avoid overwriting an already-existing
	// object at the destination key if it already exists.
	IfNotExists bool
	// MaxConcurrentCopies specifies the maximum number of concurrent copy
	// operations for MoveObjects. If nil or <=0, defaults to 20.
	// (Optional)
	MaxConcurrentCopies *int
	// VersionID pins download operations to a specific S3 object version.
	// When set, Get and Reader operations will request this version of the
	// object. (Optional)
	VersionID string
}

type S3Permissions string

type StreamPutCounter interface {
	Bucket
	PutWithCount(ctx context.Context, key string, r io.Reader) (int, error)
}

type StreamPutCounterWithBytes interface {
	Bucket
	PutWithCountAndBytes(ctx context.Context, key string, r io.Reader) (puts int, bytesWritten int64, err error)
}

type SyncBucket interface {
	// Sync methods: these methods are the recursive, efficient
	// copy methods of files from S3 to the local file
	// system.
	Push(context.Context, SyncOptions) error
	Pull(context.Context, SyncOptions) error
}

type SyncOptions struct {
	Local   string
	Remote  string
	Exclude string
}

type Transition struct {
	// Days is the number of days after creation when the transition occurs (nil if Date is used instead)
	Days *int32

	// StorageClass is the target storage class (e.g., "STANDARD_IA", "GLACIER", "DEEP_ARCHIVE")
	StorageClass string
}