Mostlylucid.Ephemeral.Patterns.CircuitBreaker 2.6.3

Mostlylucid.Ephemeral.Patterns.CircuitBreaker

👁 NuGet

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)