sprints work

src/__Libraries/StellaOps.Provcache/IProvcacheRepository.cs

@@ -0,0 +1,137 @@
+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);
+}
+
+/// <summary>
+/// Cache statistics for monitoring and diagnostics.
+/// </summary>
+public sealed record ProvcacheStatistics
+{
+    /// <summary>
+    /// Total number of entries in the cache.
+    /// </summary>
+    public long TotalEntries { get; init; }
+
+    /// <summary>
+    /// Total number of cache hits.
+    /// </summary>
+    public long TotalHits { get; init; }
+
+    /// <summary>
+    /// Number of entries expiring within the next hour.
+    /// </summary>
+    public long ExpiringWithinHour { get; init; }
+
+    /// <summary>
+    /// Number of unique policy hashes.
+    /// </summary>
+    public int UniquePolicies { get; init; }
+
+    /// <summary>
+    /// Number of unique signer set hashes.
+    /// </summary>
+    public int UniqueSignerSets { get; init; }
+
+    /// <summary>
+    /// Oldest entry timestamp.
+    /// </summary>
+    public DateTimeOffset? OldestEntry { get; init; }
+
+    /// <summary>
+    /// Newest entry timestamp.
+    /// </summary>
+    public DateTimeOffset? NewestEntry { get; init; }
+}