namespace Svrnty.MCP.Gateway.Core.Interfaces;

/// <summary>
/// Defines the contract for circuit breaker implementations.
/// Provides fault tolerance by preventing cascading failures.
/// </summary>
public interface ICircuitBreaker
{
    /// <summary>
    /// Executes an operation with circuit breaker protection.
    /// If the circuit is open (too many failures), the operation is not executed.
    /// </summary>
    /// <typeparam name="T">Return type of the operation.</typeparam>
    /// <param name="operation">The operation to execute.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The result of the operation.</returns>
    /// <exception cref="InvalidOperationException">Thrown when the circuit is open.</exception>
    Task<T> ExecuteAsync<T>(Func<Task<T>> operation, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the current state of the circuit breaker.
    /// </summary>
    /// <returns>The current state ("Closed", "Open", or "HalfOpen").</returns>
    string GetState();

    /// <summary>
    /// Manually resets the circuit breaker to the closed state.
    /// </summary>
    void Reset();
}