namespace ZB.MOM.WW.OtOpcUa.Configuration.LocalCache;

/// <summary>
///     Per-node local cache of the most-recently-applied generation(s). Used to bootstrap the
///     address space when the central DB is unreachable (degraded-but-running).
/// </summary>
/// <remarks>
///     <para><b>Concurrency contract:</b> implementations must serialize writes — specifically,
///     <see cref="PutAsync"/> for the same <c>(ClusterId, GenerationId)</c> from concurrent
///     callers must not produce duplicate rows. Reads may run concurrently with reads and writes.
///     The <see cref="LiteDbConfigCache"/> implementation enforces this via an instance-level
///     <see cref="SemaphoreSlim"/> around the find-then-insert/update window.</para>
/// </remarks>
public interface ILocalConfigCache
{
    /// <summary>Retrieves the most recent generation snapshot for the specified cluster.</summary>
    /// <param name="clusterId">The cluster identifier.</param>
    /// <param name="ct">The cancellation token.</param>
    /// <returns>The most recent generation snapshot, or null if none exists.</returns>
    Task<GenerationSnapshot?> GetMostRecentAsync(string clusterId, CancellationToken ct = default);
    /// <summary>Stores a generation snapshot in the local cache.</summary>
    /// <param name="snapshot">The generation snapshot to store.</param>
    /// <param name="ct">The cancellation token.</param>
    /// <returns>A task that represents the asynchronous operation.</returns>
    Task PutAsync(GenerationSnapshot snapshot, CancellationToken ct = default);
    /// <summary>Removes old generations, keeping only the most recent N.</summary>
    /// <param name="clusterId">The cluster identifier.</param>
    /// <param name="keepLatest">The number of latest generations to keep.</param>
    /// <param name="ct">The cancellation token.</param>
    /// <returns>A task that represents the asynchronous operation.</returns>
    Task PruneOldGenerationsAsync(string clusterId, int keepLatest = 10, CancellationToken ct = default);
}