cos

type Api interface {
	Baser
	Uploader
	Downloader
	Deleter
	Querier
}

type Baser interface {
	// Ping 测试连接。
	Ping(ctx context.Context) error

	// GenerateAuthorization 生成 HTTP 请求的签名字符串。
	GenerateAuthorization(fileId, method string, query url.Values, header http.Header, expiration time.Duration) string
}

type Deleter interface {
	// Delete 删除文件。
	Delete(ctx context.Context, fileId string) error

	// Deletes 删除多个文件。
	Deletes(ctx context.Context, fileIds ...string) (undeleted map[string]error)
}

type Downloader interface {
	// Download 下载文件。
	//
	// 注意：调用方负责关闭 rc。
	Download(ctx context.Context, fileId string) (rc io.ReadCloser, fileSize int64, err error)

	// DownloadToWriter 下载文件。
	DownloadToWriter(ctx context.Context, fileId string, w io.Writer) error

	// DownloadToWriterWithSize 下载文件。
	DownloadToWriterWithSize(ctx context.Context, fileId string, contentLength int64, w io.Writer) error

	// DownloadToDisk 下载文件。
	DownloadToDisk(ctx context.Context, fileId, filePath string) error

	// DownloadToWriterAt 下载文件。
	DownloadToWriterAt(ctx context.Context, fileId string, wa io.WriterAt) error

	// GetDownloadUrl 获取文件下载链接。
	GetDownloadUrl(fileId string, expiration time.Duration) string
}

type File struct {
	// 文件ID。
	ID string
	// Size 文件大小。
	Size int64
	// EntityTag 对象被创建时标识对象内容的信息标签。
	EntityTag string
	// UploadTime 对象的最近一次上传的时间。
	UploadTime time.Time
}

type FileInfo struct {
	// Size 文件大小。
	Size int64
	// EntityTag 对象被创建时标识对象内容的信息标签。
	EntityTag string
	// 对象的 CRC64 值。
	Crc64 string
	// UploadTime 对象的最近一次上传的时间。
	UploadTime time.Time
	// ExpireTime 过期时间。
	ExpireTime time.Time
}

type FilePartInfo struct {
	// PartNumber 序号。
	PartNumber int
	// EntityTag 对象被创建时标识对象内容的信息标签。
	EntityTag string
	// Size 分片大小。
	Size int64
}

type MultiUploader interface {
	// InitMultiUpload 初始化分片上传区域。
	InitMultiUpload(ctx context.Context, fileId string) (uploadId string, err error)

	// UploadPart 上传分片。
	UploadPart(ctx context.Context, fileId, uploadId string, partNumber int64, reqBody []byte) error

	// UploadPartByReader 上传分片。
	UploadPartByReader(ctx context.Context, fileId, uploadId string, partNumber, contentLength int64, r io.Reader) error

	// ListFileParts 获取已上传的分片信息。
	ListFileParts(ctx context.Context, fileId, uploadId string) ([]*FilePartInfo, error)

	// CompleteMultiUpload 结束分片上传。
	CompleteMultiUpload(ctx context.Context, fileId, uploadId string) error

	// AbortMultiUpload 丢弃上传的分片。
	AbortMultiUpload(ctx context.Context, fileId, uploadId string) error
}

type Querier interface {
	// Info 获取文件信息。
	Info(ctx context.Context, fileId string) (*FileInfo, error)

	// Exist 文件是否存在。
	Exist(ctx context.Context, fileId string) (bool, error)

	// ListFiles 获取文件列表信息列表。
	ListFiles(ctx context.Context, dir, fileNamePrefix, offset string, limit int64) (
		files []*File, nextOffset string, err error)
}

type Uploader interface {
	// Upload 上传文件。
	Upload(ctx context.Context, fileId string, content []byte) error

	// UploadFromReader 上传文件。
	UploadFromReader(ctx context.Context, fileId string, r io.Reader) error

	// UploadFromReaderWithSize 上传文件。
	UploadFromReaderWithSize(ctx context.Context, fileId string, contentLength int64, r io.Reader) error

	// UploadFromDisk 上传文件。
	UploadFromDisk(ctx context.Context, fileId, filePath string) error

	MultiUploader
}