storage

type CDNStorage interface {
	Storage
	URLHandler
	UploadAuthorizer
}

type DownloadResult struct {
	Reader io.ReadCloser
	MIME   string
	Size   int64
}

type FileDeleter interface {
	// DeleteFile removes a file from the storage backend.
	DeleteFile(ctx context.Context, key string) error
}

type FileDownloader interface {
	// IsFileExists checks whether a file exists in the storage backend.
	IsFileExists(ctx context.Context, key string) (bool, error)

	// DownloadFile retrieves a file from storage.
	// The caller is responsible for closing DownloadResult.Reader.
	DownloadFile(ctx context.Context, key string) (DownloadResult, error)
}

type FileMoverCopier interface {
	// MoveFile relocates a file from source to destination key.
	// If overwrite is false, returns an error if destination already exists.
	MoveFile(ctx context.Context, sourceKey string, destinationKey string, overwrite bool) error

	// CopyFile duplicates a file from source to destination key.
	// If overwrite is false, returns an error if destination already exists.
	CopyFile(ctx context.Context, sourceKey string, destinationKey string, overwrite bool) error
}

type FileUploader interface {
	// UploadFile uploads data from a reader to the storage backend with the specified key.
	// Returns the storage key or an error if upload fails.
	UploadFile(ctx context.Context, file io.Reader, key string) (string, error)

	// UploadLocalFile uploads a local file to the storage backend with the specified key.
	// Returns the storage key or an error if upload fails.
	UploadLocalFile(ctx context.Context, file string, key string) (string, error)
}

type Storage interface {
	FileDeleter
	FileUploader
	FileDownloader
	FileMoverCopier
}

type URLHandler interface {
	// GenerateURL creates a public URL for accessing the file identified by the given key.
	// Optional params are encoded into query string. When multiple values are provided,
	// only the first non-nil params is used.
	GenerateURL(key string, params ...url.Values) string

	// GenerateURLs creates public URLs for multiple files in batch.
	// Optional params are encoded into query string for each generated URL.
	GenerateURLs(keys []string, params ...url.Values) []string

	// ExtractKeyFromURL extracts the storage key from a given URL.
	ExtractKeyFromURL(uri string) string

	// ExtractKeyFromURLWithMode extracts the storage key from a URL with strict mode option.
	// When strict is true, returns an error if the URL format is invalid.
	ExtractKeyFromURLWithMode(uri string, strict bool) (string, error)
}

type UploadAuthRequest struct {
	FileName string `json:"file_name" yaml:"file_name"`
	Dir      string `json:"dir,omitempty" yaml:"dir,omitempty"`
}

type UploadAuthResult struct {
	Authorization UploadAuthorization `json:"authorization" yaml:"authorization"`
	File          UploadFileInfo      `json:"file" yaml:"file"`
}

type UploadAuthorization struct {
	Type    UploadAuthorizationType `json:"type" yaml:"type"`
	Value   string                  `json:"value" yaml:"value"`
	Method  string                  `json:"method" yaml:"method"`
	Headers map[string]string       `json:"headers,omitempty" yaml:"headers,omitempty"`
}

type UploadAuthorizationType string

type UploadAuthorizer interface {
	// GenerateUploadAuth creates upload authorization and target file information.
	GenerateUploadAuth(ctx context.Context, req UploadAuthRequest) (UploadAuthResult, error)
}

type UploadFileInfo struct {
	Key string `json:"key" yaml:"key"`
	URL string `json:"url" yaml:"url"`
}

type UploadNamingStrategy string