namespace StorageService.Infrastructure.Caching;

/// <summary>
/// EN: Interface for Redis caching operations.
/// VI: Interface cho các thao tác Redis caching.
/// </summary>
public interface IRedisCacheService
{
    /// <summary>
    /// EN: Get value from cache.
    /// VI: Lấy giá trị từ cache.
    /// </summary>
    /// <typeparam name="T">Type of cached value / Kiểu giá trị cache</typeparam>
    /// <param name="key">Cache key / Key cache</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Cached value or default / Giá trị cache hoặc default</returns>
    Task<T?> GetAsync<T>(string key, CancellationToken cancellationToken = default) where T : class;

    /// <summary>
    /// EN: Set value in cache with TTL.
    /// VI: Lưu giá trị vào cache với TTL.
    /// </summary>
    /// <typeparam name="T">Type of value / Kiểu giá trị</typeparam>
    /// <param name="key">Cache key / Key cache</param>
    /// <param name="value">Value to cache / Giá trị cần cache</param>
    /// <param name="expiry">Time to live / Thời gian sống của cache</param>
    /// <param name="cancellationToken">Cancellation token</param>
    Task SetAsync<T>(string key, T value, TimeSpan? expiry = null, CancellationToken cancellationToken = default) where T : class;

    /// <summary>
    /// EN: Delete key from cache.
    /// VI: Xóa key khỏi cache.
    /// </summary>
    /// <param name="key">Cache key / Key cache</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>True if key existed and was removed / True nếu key tồn tại và đã xóa</returns>
    Task<bool> DeleteAsync(string key, CancellationToken cancellationToken = default);

    /// <summary>
    /// EN: Delete multiple keys matching pattern.
    /// VI: Xóa nhiều keys theo pattern.
    /// </summary>
    /// <param name="pattern">Pattern (e.g., "user:123:*") / Pattern (ví dụ: "user:123:*")</param>
    /// <param name="cancellationToken">Cancellation token</param>
    Task DeleteByPatternAsync(string pattern, CancellationToken cancellationToken = default);

    /// <summary>
    /// EN: Check if key exists in cache.
    /// VI: Kiểm tra key có tồn tại trong cache.
    /// </summary>
    /// <param name="key">Cache key / Key cache</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>True if exists / True nếu tồn tại</returns>
    Task<bool> ExistsAsync(string key, CancellationToken cancellationToken = default);

    /// <summary>
    /// EN: Get value from cache, or execute factory and cache result.
    /// VI: Lấy giá trị từ cache, hoặc thực thi factory và cache kết quả.
    /// </summary>
    /// <typeparam name="T">Type of cached value / Kiểu giá trị cache</typeparam>
    /// <param name="key">Cache key / Key cache</param>
    /// <param name="factory">Factory function to create value if not cached / Factory để tạo value nếu chưa cache</param>
    /// <param name="expiry">Time to live / Thời gian sống của cache</param>
    /// <param name="cancellationToken">Cancellation token</param>
    /// <returns>Cached or newly created value / Giá trị từ cache hoặc mới tạo</returns>
    Task<T?> GetOrSetAsync<T>(
        string key, 
        Func<Task<T?>> factory, 
        TimeSpan? expiry = null,
        CancellationToken cancellationToken = default) where T : class;

    /// <summary>
    /// EN: Check if Redis is connected.
    /// VI: Kiểm tra Redis đã kết nối.
    /// </summary>
    bool IsConnected { get; }
}
