Mostlylucid.Ephemeral.Patterns.CircuitBreaker 2.5.0

Mostlylucid.Ephemeral.Patterns.CircuitBreaker

Stateless circuit breaker that reads state from the ephemeral signal window.

dotnet add package mostlylucid.ephemeral.patterns.circuitbreaker

Quick Start

using Mostlylucid.Ephemeral.Patterns.CircuitBreaker;

var breaker = new SignalBasedCircuitBreaker(
    failureSignal: "api.failure",
    threshold: 5,
    windowSize: TimeSpan.FromSeconds(30));

if (breaker.IsOpen(coordinator))
{
    var retryAfter = breaker.GetTimeUntilClose(coordinator);
    throw new CircuitOpenException("Too many failures", retryAfter);
}

All Options

new SignalBasedCircuitBreaker(
    // Signal name to count as failure
    // Default: "failure"
    failureSignal: "api.failure",

    // Number of failures to open circuit
    // Default: 5
    threshold: 5,

    // Time window for counting failures
    // Default: 30 seconds
    windowSize: TimeSpan.FromSeconds(30)
)

API Reference

// Check if circuit is open (too many failures)
bool isOpen = breaker.IsOpen(coordinator);

// Check using glob pattern matching
bool isOpen = breaker.IsOpenMatching(coordinator, "error.*");

// Get current failure count
int failures = breaker.GetFailureCount(coordinator);

// Get time until circuit closes (null if already closed)
TimeSpan? retryAfter = breaker.GetTimeUntilClose(coordinator);

How It Works

The circuit breaker is stateless - it calculates state from the coordinator's signal window on each check:

Window: [now - 30s] ────────────────────> [now]
        failure  failure  failure  failure  failure
        ─────────────────────────────────────────────
        Count: 5 failures
        Threshold: 5
        Result: CIRCUIT OPEN

When the oldest failure ages out of the window, the circuit automatically closes.

Example: API Protection

var breaker = new SignalBasedCircuitBreaker("api.failure", threshold: 5);

await using var coordinator = new EphemeralWorkCoordinator<ApiRequest>(
    async (req, ct) =>
    {
        // Check circuit before calling
        if (breaker.IsOpen(coordinator))
        {
            var retry = breaker.GetTimeUntilClose(coordinator);
            throw new CircuitOpenException("API circuit open", retry);
        }

        try
        {
            await CallApi(req, ct);
        }
        catch
        {
            coordinator.Signal("api.failure");
            throw;
        }
    });

Example: Pattern-Based Circuit

var breaker = new SignalBasedCircuitBreaker(
    failureSignal: "error",
    threshold: 10,
    windowSize: TimeSpan.FromMinutes(1));

// Opens on any signal matching "error.*"
if (breaker.IsOpenMatching(coordinator, "error.*"))
{
    // Circuit is open due to various error types
}

CircuitOpenException

public class CircuitOpenException : Exception
{
    // Time until circuit might close
    public TimeSpan? RetryAfter { get; }
}

// Usage
try
{
    await service.CallAsync();
}
catch (CircuitOpenException ex)
{
    if (ex.RetryAfter.HasValue)
        await Task.Delay(ex.RetryAfter.Value);
}

Related Packages

License

Unlicense (public domain)