CMS/src/CMSMicroservice.Application/Common/Interfaces/IUserPaymentLock.cs

namespace CMSMicroservice.Application.Common.Interfaces;

/// <summary>
/// Per-scope in-process mutex for payment flows (initiate / verify).
/// Prevents the same user from running duplicate gateway operations concurrently.
/// </summary>
public interface IUserPaymentLock
{
    Task<T> ExecuteAsync<T>(
        string scope,
        PaymentLockStrategy strategy,
        Func<CancellationToken, Task<T>> action,
        CancellationToken cancellationToken = default);

    Task ExecuteAsync(
        string scope,
        PaymentLockStrategy strategy,
        Func<CancellationToken, Task> action,
        CancellationToken cancellationToken = default);
}

/// <summary>
/// How to behave when the payment lock is already held.
/// </summary>
public enum PaymentLockStrategy
{
    /// <summary>Wait up to the configured timeout (callback / verify paths).</summary>
    WaitForRelease,

    /// <summary>Reject immediately (initiate / double-click paths).</summary>
    FailFast
}