namespace StellaOps.Provcache;

/// <summary>
/// Repository interface for Provcache entries in persistent storage (Postgres).
/// </summary>
public interface IProvcacheRepository
{
    /// <summary>
    /// Gets a cache entry by VeriKey.
    /// </summary>
    /// <param name="veriKey">The cache key.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The cache entry if found, null otherwise.</returns>
    Task<ProvcacheEntry?> GetAsync(string veriKey, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets multiple cache entries by VeriKeys.
    /// </summary>
    /// <param name="veriKeys">The cache keys.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Dictionary of found entries.</returns>
    Task<IReadOnlyDictionary<string, ProvcacheEntry>> GetManyAsync(
        IEnumerable<string> veriKeys,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Inserts or updates a cache entry.
    /// </summary>
    /// <param name="entry">The cache entry to upsert.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task UpsertAsync(ProvcacheEntry entry, CancellationToken cancellationToken = default);

    /// <summary>
    /// Inserts or updates multiple cache entries in a batch.
    /// </summary>
    /// <param name="entries">The cache entries to upsert.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task UpsertManyAsync(IEnumerable<ProvcacheEntry> entries, CancellationToken cancellationToken = default);

    /// <summary>
    /// Deletes a cache entry by VeriKey.
    /// </summary>
    /// <param name="veriKey">The cache key.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>True if the entry existed and was deleted.</returns>
    Task<bool> DeleteAsync(string veriKey, CancellationToken cancellationToken = default);

    /// <summary>
    /// Deletes entries matching a policy hash.
    /// Used when policy is updated.
    /// </summary>
    /// <param name="policyHash">The policy hash to match.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Number of entries deleted.</returns>
    Task<long> DeleteByPolicyHashAsync(string policyHash, CancellationToken cancellationToken = default);

    /// <summary>
    /// Deletes entries matching a signer set hash.
    /// Used when a signer is revoked.
    /// </summary>
    /// <param name="signerSetHash">The signer set hash to match.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Number of entries deleted.</returns>
    Task<long> DeleteBySignerSetHashAsync(string signerSetHash, CancellationToken cancellationToken = default);

    /// <summary>
    /// Deletes entries older than a feed epoch.
    /// Used when feeds are updated.
    /// </summary>
    /// <param name="feedEpoch">The minimum feed epoch to keep.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Number of entries deleted.</returns>
    Task<long> DeleteByFeedEpochOlderThanAsync(string feedEpoch, CancellationToken cancellationToken = default);

    /// <summary>
    /// Deletes expired entries.
    /// </summary>
    /// <param name="asOf">The reference timestamp for expiry check.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Number of entries deleted.</returns>
    Task<long> DeleteExpiredAsync(DateTimeOffset asOf, CancellationToken cancellationToken = default);

    /// <summary>
    /// Increments the hit count for an entry.
    /// </summary>
    /// <param name="veriKey">The cache key.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    Task IncrementHitCountAsync(string veriKey, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets cache statistics.
    /// </summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Cache statistics.</returns>
    Task<ProvcacheStatistics> GetStatisticsAsync(CancellationToken cancellationToken = default);
}