Core.BluePrint.Packages/Core.Blueprint.Storage/Contracts/IBlobStorageProvider.cs

using Azure;
using Azure.Storage.Blobs;
using Azure.Storage.Blobs.Models;
using Azure.Storage.Sas;
using Core.Blueprint.Storage.Adapters;

namespace Core.Blueprint.Storage.Contracts
{
    /// <summary>
    /// Defines a contract for managing blobs and containers in Azure Blob Storage.
    /// </summary>
    public interface IBlobStorageProvider
    {
        /// <summary>
        /// Creates the blob container if it does not exist.
        /// </summary>
        /// <returns>A <see cref="Response{T}"/> containing the container information.</returns>
        Task<Response<BlobContainerInfo>> CreateIfNotExistsAsync();

        /// <summary>
        /// Deletes the blob container if it exists.
        /// </summary>
        Task DeleteIfExistsAsync();

        /// <summary>
        /// Gets properties of the blob container.
        /// </summary>
        /// <returns>A <see cref="Response{T}"/> containing container properties.</returns>
        Task<Response<BlobContainerProperties>> GetPropertiesAsync();

        /// <summary>
        /// Sets metadata for the blob container.
        /// </summary>
        /// <param name="metadata">The metadata to set for the container.</param>
        Task SetMetadataAsync(IDictionary<string, string> metadata);

        /// <summary>
        /// Uploads a blob to the container.
        /// </summary>
        /// <param name="blobName">The name of the blob.</param>
        /// <param name="content">The content to upload.</param>
        /// <returns>A <see cref="Response{T}"/> containing blob content information.</returns>
        Task<Response<BlobContentInfo>> UploadBlobAsync(string blobName, Stream content);

        /// <summary>
        /// Downloads a blob from the container.
        /// </summary>
        /// <param name="blobName">The name of the blob.</param>
        /// <returns>A <see cref="Response{T}"/> containing blob download information.</returns>
        /// <exception cref="FileNotFoundException">Thrown if the blob does not exist.</exception>
        Task<Response<BlobDownloadInfo>> DownloadBlobAsync(string blobName);

        /// <summary>
        /// Deletes a blob from the container.
        /// </summary>
        /// <param name="blobName">The name of the blob.</param>
        Task<bool> DeleteBlobAsync(string blobName);

        /// <summary>
        /// Lists all blobs in the container with an optional prefix.
        /// </summary>
        /// <param name="prefix">The prefix to filter blobs.</param>
        /// <returns>A collection of <see cref="BlobItem"/>.</returns>
        Task<IEnumerable<BlobItem>> ListBlobItemAsync(string? prefix = null);

        /// <summary>
        /// Retrieves the account information for the associated Blob Service Client.
        /// </summary>
        /// <param name="cancellation">
        /// A <see cref="CancellationToken"/> that can be used to cancel the operation.
        /// </param>
        /// <returns>
        /// A task that represents the asynchronous operation. The task result contains the
        /// <see cref="AccountInfo"/> object, which provides details about the account, such as the SKU
        /// and account kind.
        Task<AccountInfo> GetAccountInfoAsync(CancellationToken cancellation);

        /// <summary>
        /// Gets a blob client for a specific blob.
        /// </summary>
        /// <param name="blobName">The name of the blob.</param>
        /// <returns>A <see cref="BlobClient"/> for the blob.</returns>
        BlobClient GetBlobClient(string blobName);

        /// <summary>
        /// Lists blobs hierarchically using a delimiter.
        /// </summary>
        /// <param name="prefix">The prefix to filter blobs.</param>
        /// <param name="delimiter">The delimiter to use for hierarchy.</param>
        /// <returns>A collection of <see cref="BlobHierarchyItem"/>.</returns>
        Task<IEnumerable<BlobHierarchyItem>> ListBlobsByHierarchyAsync(string? prefix = null, string delimiter = "/");

        /// <summary>
        /// Generates a SAS token for the container with specified permissions.
        /// </summary>
        /// <param name="permissions">The permissions to assign to the SAS token.</param>
        /// <param name="expiresOn">The expiration time for the SAS token.</param>
        /// <returns>A <see cref="Uri"/> containing the SAS token.</returns>
        /// <exception cref="InvalidOperationException">Thrown if SAS URI generation is not supported.</exception>
        Uri GenerateContainerSasUri(BlobContainerSasPermissions permissions, DateTimeOffset expiresOn);

        /// <summary>
        /// Acquires a lease on the blob container.
        /// </summary>
        /// <param name="proposedId">The optional proposed lease ID.</param>
        /// <param name="duration">The optional lease duration.</param>
        /// <returns>A <see cref="Response{T}"/> containing lease information.</returns>
        Task<Response<BlobLease>> AcquireLeaseAsync(string? proposedId = null, TimeSpan? duration = null);

        /// <summary>
        /// Releases a lease on the blob container.
        /// </summary>
        /// <param name="leaseId">The lease ID to release.</param>
        Task ReleaseLeaseAsync(string leaseId);

        /// <summary>
        /// Sets access policies for the blob container.
        /// </summary>
        /// <param name="accessType">The type of public access to allow.</param>
        /// <param name="identifiers">The optional list of signed identifiers for access policy.</param>
        Task SetAccessPolicyAsync(PublicAccessType accessType, IEnumerable<BlobSignedIdentifier>? identifiers = null);

        /// <summary>
        /// Lists blobs in the container with an optional prefix.
        /// </summary>
        /// <param name="prefix">The prefix to filter blobs.</param>
        /// <returns>A collection of <see cref="BlobFileAdapter"/>.</returns>
        Task<IEnumerable<BlobFileAdapter>> ListBlobsAsync(string? prefix = null);

        /// <summary>
        /// Uploads a blob to the container.
        /// </summary>
        /// <param name="newBlob">The blob to upload.</param>
        /// <returns>A <see cref="BlobFileAdapter"/> representing the uploaded blob.</returns>
        Task<BlobFileAdapter> UploadBlobAsync(BlobAddDto newBlob);

        /// <summary>
        /// Deletes a blob from the container.
        /// </summary>
        /// <param name="fileName">The name of the blob to delete.</param>
        /// <returns>A <see cref="BlobFileAdapter"/> representing the deleted blob, or null if the blob was not found.</returns>
        Task<BlobFileAdapter?> DeleteBlobsAsync(string fileName);

        /// <summary>
        /// Downloads a blob's content.
        /// </summary>
        /// <param name="blobName">The name of the blob.</param>
        /// <returns>A <see cref="BlobDownloadInfo"/> representing the downloaded blob.</returns>
        /// <exception cref="FileNotFoundException">Thrown if the blob does not exist.</exception>
        Task<BlobDownloadInfo> DownloadBlobsAsync(string blobName);

        /// <summary>
        /// Generates a secure download URI for a specified blob in the storage container.
        /// </summary>
        /// <param name="blobName">The name of the blob for which the download URI is being generated.</param>
        /// <returns>
        /// An instance of <see cref="BlobDownloadUriAdapter"/> containing the generated URI, blob name, and status.
        /// </returns>
        /// <remarks>
        /// The generated URI includes a Shared Access Signature (SAS) token, which allows secure, time-limited access to the blob.
        /// The SAS token grants read-only access to the blob for a duration of 5 minutes starting from the current time.
        /// </remarks>
        /// <exception cref="ArgumentNullException">Thrown if <paramref name="blobName"/> is null or empty.</exception>
        /// <exception cref="StorageException">Thrown if there is an issue communicating with the Azure Blob service.</exception>
        ValueTask<BlobDownloadUriAdapter?> GenerateBlobDownloadUri(string blobName);

        /// <summary>
        /// Retrieves the hierarchical folder structure.
        /// </summary>
        /// <param name="prefix">The prefix to start the hierarchy retrieval.</param>
        /// <returns>A list of <see cref="BlobStorageFolder"/> representing the folder structure.</returns>
        Task<List<BlobStorageFolder>> GetFolderHierarchyAsync(string prefix);

        /// <summary>
        /// Lists neighboring folders based on a prefix.
        /// </summary>
        /// <param name="prefix">The prefix to search for neighboring folders.</param>
        /// <returns>A dictionary grouping folder names by their prefix.</returns>
        Task<Dictionary<string, List<string>>> ListNeighborFoldersAsync(string? prefix);
    }
}