using ZB.MOM.WW.ScadaBridge.Commons.Types.Transport;

namespace ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Transport;

public interface IBundleSessionStore
{
    /// <summary>Stores the session and returns it; overwrites any existing session with the same id.</summary>
    /// <param name="session">The session to store.</param>
    /// <returns>The stored session (same reference as <paramref name="session"/>).</returns>
    BundleSession Open(BundleSession session);
    /// <summary>Returns the session for the given id, or null if not found or expired.</summary>
    /// <param name="sessionId">The session identifier to look up.</param>
    /// <returns>The matching <see cref="BundleSession"/>, or null if not found or expired.</returns>
    BundleSession? Get(Guid sessionId);
    /// <summary>Removes the session for the given id, if present.</summary>
    /// <param name="sessionId">The session identifier to remove.</param>
    void Remove(Guid sessionId);
    /// <summary>Removes all sessions whose expiry has passed.</summary>
    void EvictExpired();

    /// <summary>
    /// T-003: returns the current unlock-failure count for a bundle keyed by its
    /// content hash. The counter is server-owned so a second tab / CLI caller
    /// cannot side-step the lockout by re-uploading the same bytes.
    /// </summary>
    /// <param name="bundleContentHash">SHA-256 hex from <c>BundleManifest.ContentHash</c>.</param>
    /// <returns>Number of recorded failures for this bundle (0 if none, or if any record has expired).</returns>
    int GetUnlockFailureCount(string bundleContentHash);

    /// <summary>
    /// T-003: atomically increments the unlock-failure counter for a bundle and
    /// returns the new count. Tracking is scoped by content hash so retries
    /// against identical bundle bytes are throttled regardless of client.
    /// </summary>
    /// <param name="bundleContentHash">SHA-256 hex from <c>BundleManifest.ContentHash</c>.</param>
    /// <returns>The new unlock-failure count after incrementing.</returns>
    int IncrementUnlockFailureCount(string bundleContentHash);

    /// <summary>
    /// T-003: clears the unlock-failure counter for a bundle (called on a
    /// successful unlock so a legitimate operator who eventually types the
    /// right passphrase is not penalised for earlier typos).
    /// </summary>
    /// <param name="bundleContentHash">SHA-256 hex from <c>BundleManifest.ContentHash</c>.</param>
    void ClearUnlockFailures(string bundleContentHash);
}
