storage

type Cache interface {
	// Get retrieves the value associated with the given key.
	// It returns the cached value and an error if the key is not found.
	Get(ctx context.Context, key string) (string, error)

	// GetAndDelete retrieves the value associated with the given key and deletes it.
	// It returns the cached value and an error if the key is not found.
	GetAndDelete(ctx context.Context, key string) (string, error)

	// Exists checks if a value exists for the given key.
	// It returns an error if the key is not found.
	Exists(ctx context.Context, key string) (bool, error)

	// Set sets the value for the given key.
	// It returns an error if the operation fails.
	Set(ctx context.Context, key string, value string, exp ...time.Duration) error

	// Delete deletes the value associated with the given key.
	// It returns an error if the operation fails.
	Delete(ctx context.Context, key string) error

	// Close closes the cache.
	Close(ctx context.Context) error

	// Clear clears the cache.
	Clear(ctx context.Context) error
}

type CompletedPart struct {
	// PartNumber is the sequence number of the part, starting from 1.
	PartNumber int
	// ETag is the entity tag returned by the storage backend for the uploaded part.
	// It's used to verify the part's integrity upon completion.
	ETag string
}

type Database interface {
	// Name returns the name of the database service.
	Name() string

	// Dialect returns the database dialect.
	Dialect() string

	// DB returns the underlying *sql.DB instance.
	DB() *sql.DB

	// Close closes the database connection.
	Close() error
}

type FileInfo struct {
	Name    string
	Path    string
	IsDir   bool
	Size    int64
	ModTime time.Time
}

type FileStore interface {
	List(path string) ([]FileInfo, error)
	Stat(path string) (FileInfo, error)
	Read(path string) (io.ReadCloser, error)
	Mkdir(path string) error
	Delete(path string) error
	Rename(oldPath, newPath string) error

	// Write provides a simple, stream-based method for writing an object. It's ideal
	// for smaller files or when direct control over chunking is not required.
	// For large files, implementations should transparently handle multipart uploads internally.
	// The `size` parameter is a hint for the underlying driver. If the size is unknown, it should be -1.
	Write(path string, data io.Reader, size int64) error
}

type MultipartUpload interface {
	// UploadPart uploads a single chunk of data as a part of the multipart upload.
	// The provided reader is consumed. partNumber must be between 1 and 10000.
	// The `size` parameter is a hint for the underlying driver, similar to the one in Write.
	UploadPart(partNumber int, reader io.Reader, size int64) (CompletedPart, error)

	// Complete finalizes the multipart upload, assembling the uploaded parts into a single object.
	// The parts must be sorted by PartNumber.
	Complete(parts []CompletedPart) error

	// Abort cancels the multipart upload, cleaning up any uploaded parts that have been
	// stored temporarily by the backend.
	Abort() error

	// UploadID returns the unique identifier for this upload session.
	UploadID() string
}

type Provider interface {
	// FileStore returns the configured file storage service by name.
	FileStore(name string) (FileStore, error)
	// DefaultFileStore returns the default file storage service.
	DefaultFileStore() (FileStore, error)

	// Cache returns the configured cache service by name.
	Cache(name string) (Cache, error)
	// DefaultCache returns the default cache service.
	DefaultCache() (Cache, error)

	// Database returns the configured database service by name.
	Database(name string) (Database, error)
	// DefaultDatabase returns the default database service.
	DefaultDatabase() (Database, error)
}