using Dpz.Core.Entity.Base.PublicStruct;
using Dpz.Core.Shard.Service;

namespace Dpz.Core.Service.ObjectStorage.Services;

/// <summary>
/// 对象存储操作
/// </summary>
public interface IObjectStorageOperation
{
    /// <summary>
    /// 储存筒
    /// </summary>
    string Bucket { get; }

    /// <summary>
    /// 上传文件
    /// </summary>
    /// <param name="stream">文件流</param>
    /// <param name="path">文件夹路径</param>
    /// <param name="filename">文件名</param>
    /// <param name="cancellationToken">传播通知操作应取消的通知令牌</param>
    /// <returns></returns>
    Task<IFileMetadata> UploadAsync(
        Stream stream,
        ICollection<string> path,
        string filename,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 断点续传
    /// </summary>
    /// <param name="file"></param>
    /// <param name="cancellationToken">传播通知操作应取消的通知令牌</param>
    /// <returns></returns>
    Task<FileAddress?> UploadFileAsync(
        CloudFile file,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 上传文件
    /// </summary>
    /// <param name="bytes">bytes</param>
    /// <param name="path">文件夹路径</param>
    /// <param name="filename">文件名</param>
    /// <param name="cancellationToken">传播通知操作应取消的通知令牌</param>
    /// <returns></returns>
    Task<IFileMetadata> UploadAsync(
        byte[] bytes,
        List<string> path,
        string filename,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 下载文件
    /// </summary>
    /// <param name="pathToFile">路径级文件</param>
    /// <param name="cancellationToken">传播通知操作应取消的通知令牌</param>
    /// <returns></returns>
    Task<Stream> DownloadAsync(string pathToFile, CancellationToken cancellationToken = default);

    /// <summary>
    /// 下载文件另存为
    /// </summary>
    /// <param name="pathToFile">路径级文件</param>
    /// <param name="path">保存路径</param>
    /// <param name="cancellationToken">传播通知操作应取消的通知令牌</param>
    /// <returns></returns>
    Task SaveAsAsync(string pathToFile, string path, CancellationToken cancellationToken = default);

    /// <summary>
    /// 删除文件
    /// </summary>
    /// <param name="pathToFile"></param>
    /// <param name="cancellationToken">传播通知操作应取消的通知令牌</param>
    /// <returns></returns>
    Task DeleteAsync(string? pathToFile, CancellationToken cancellationToken = default);

    /// <summary>
    /// 获取目录列表文件和文件夹信息
    /// </summary>
    /// <param name="path">路径</param>
    /// <param name="cancellationToken">传播通知操作应取消的通知令牌</param>
    /// <returns></returns>
    Task<IList<FolderResult>> GetFolderListAsync(
        string path,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 获取文件信息
    /// </summary>
    /// <param name="pathToFile"></param>
    /// <param name="cancellationToken">传播通知操作应取消的通知令牌</param>
    /// <returns></returns>
    Task<FileInformation> GetFileInformationAsync(
        string pathToFile,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 批量上传本地目录下所有文件到远程目录，默认覆盖已有文件
    /// </summary>
    /// <param name="localDirectory">本地目录路径</param>
    /// <param name="remoteDirectory">远程目录路径</param>
    /// <param name="bucket">储存桶名称，为 null 时使用当前 <see cref="Bucket"/> 属性</param>
    /// <param name="cancellationToken">传播通知操作应取消的通知令牌</param>
    /// <returns>成功上传的文件数量</returns>
    Task<int> UploadDirectoryAsync(
        string localDirectory,
        string remoteDirectory,
        string? bucket = null,
        CancellationToken cancellationToken = default
    );

    /// <summary>
    /// 清理云储存中的空目录（删除没有文件的、以 "/" 结尾的零字节 marker 对象）
    /// </summary>
    /// <param name="prefix">限定扫描的根前缀，为 null 时扫描整个储存桶</param>
    /// <param name="cancellationToken">传播通知操作应取消的通知令牌</param>
    /// <returns>删除的空目录数量</returns>
    Task<int> CleanEmptyDirectoriesAsync(
        string? prefix = null,
        CancellationToken cancellationToken = default
    );
}