namespace IamService.Infrastructure.Caching;

/// <summary>
/// EN: Cache service interface for distributed caching
/// VI: Interface cache service cho distributed caching
/// </summary>
public interface ICacheService
{
    /// <summary>
    /// EN: Get a cached value by key
    /// VI: Lấy giá trị cache theo key
    /// </summary>
    Task<T?> GetAsync<T>(string key, CancellationToken cancellationToken = default) where T : class;
    
    /// <summary>
    /// EN: Get a cached string value by key
    /// VI: Lấy giá trị string cache theo key
    /// </summary>
    Task<string?> GetStringAsync(string key, CancellationToken cancellationToken = default);
    
    /// <summary>
    /// EN: Set a cached value with optional expiration
    /// VI: Đặt giá trị cache với thời gian hết hạn tùy chọn
    /// </summary>
    Task SetAsync<T>(string key, T value, TimeSpan? expiration = null, CancellationToken cancellationToken = default) where T : class;
    
    /// <summary>
    /// EN: Set a cached string value with optional expiration
    /// VI: Đặt giá trị string cache với thời gian hết hạn tùy chọn
    /// </summary>
    Task SetStringAsync(string key, string value, TimeSpan? expiration = null, CancellationToken cancellationToken = default);
    
    /// <summary>
    /// EN: Remove a cached value by key
    /// VI: Xóa giá trị cache theo key
    /// </summary>
    Task RemoveAsync(string key, CancellationToken cancellationToken = default);
    
    /// <summary>
    /// EN: Remove all cached values matching a pattern
    /// VI: Xóa tất cả giá trị cache theo pattern
    /// </summary>
    Task RemoveByPatternAsync(string pattern, CancellationToken cancellationToken = default);
    
    /// <summary>
    /// EN: Check if a key exists in cache
    /// VI: Kiểm tra key có tồn tại trong cache không
    /// </summary>
    Task<bool> ExistsAsync(string key, CancellationToken cancellationToken = default);
    
    /// <summary>
    /// EN: Get or set a cached value
    /// VI: Lấy hoặc đặt giá trị cache
    /// </summary>
    Task<T?> GetOrSetAsync<T>(string key, Func<Task<T>> factory, TimeSpan? expiration = null, CancellationToken cancellationToken = default) where T : class;
    
    /// <summary>
    /// EN: Add a value to a blacklist (e.g., invalidated tokens)
    /// VI: Thêm giá trị vào blacklist (ví dụ: token đã bị vô hiệu)
    /// </summary>
    Task BlacklistAsync(string key, TimeSpan expiration, CancellationToken cancellationToken = default);
    
    /// <summary>
    /// EN: Check if a value is blacklisted
    /// VI: Kiểm tra giá trị có trong blacklist không
    /// </summary>
    Task<bool> IsBlacklistedAsync(string key, CancellationToken cancellationToken = default);
}
