Recovery time: 10 seconds (coordinated via Redis)

✨ Features

📖 Usage Examples

Simple Call with Fallback

var result = await cb.CallWithFallback(
    primary: () => CallPrimaryApi(),
    fallback: () => CallBackupApi(),
    isSuccess: (r) => r?.StatusCode == 200
);
// result is ALWAYS valid (from primary or fallback)
// No try-catch needed!

Multiple Fallbacks

var result = await cb.CallWithFallback(
    primary: () => CallAzureApi(),
    isSuccess: (r) => r?.Data != null,
    fallbacks: new[] {
        () => CallAwsApi(),        // Try this first
        () => CallGcpApi(),        // Then this
        () => GetCachedData()      // Last resort
    }
);

With Logging

var result = await cb.CallWithFallback(
    primary: () => CallExternalService(),
    fallback: () => GetCachedResponse(),
    isSuccess: (r) => r != null,
    onCircuitOpen: () => logger.LogWarning("Circuit opened!"),
    onFallbackUsed: () => logger.LogInfo("Using fallback")
);

Full Configuration

var cb = DistributedCircuitBreaker.Create(config => config
    .WithCircuitId("payment-gateway")
    .WithRedis("your-cache.redis.cache.windows.net:6380,ssl=True,password=xxx")
    .FailWhen(failureRatio: 0.5, minimumCalls: 5)
    .StayOpenFor(TimeSpan.FromSeconds(30))
    .MeasureFailuresOver(TimeSpan.FromSeconds(10))
    .OnStateChange(change => 
    {
        logger.LogWarning($"Circuit {change.CircuitId} → {change.NewState}");
    })
);

ASP.NET Core Dependency Injection

// Program.cs
builder.Services.AddDistributedCircuitBreaker("payment", b => b
    .WithRedis(connectionString)
    .FailWhen(0.5, 5)
);

// PaymentService.cs
public class PaymentService
{
    private readonly IDistributedCircuitBreaker _cb;

    public PaymentService(
        [FromKeyedServices("payment")] IDistributedCircuitBreaker cb)
    {
        _cb = cb;
    }

    public async Task<PaymentResult> ProcessPayment(decimal amount)
    {
        return await _cb.CallWithFallback(
            primary: () => _primaryGateway.Charge(amount),
            fallback: () => _backupGateway.Charge(amount),
            isSuccess: (r) => r?.Approved == true
        );
    }
}

🔧 How It Works

State Machine

┌──────────────────────────────────────────────────┐
│                                                  │
│    CLOSED ────(failures exceed threshold)────►   │
│       │                                OPEN      │
│       │                                  │       │
│       ◄──(probe succeeds)── HALF-OPEN ◄──┘       │
│                                  │               │
│                     (probe fails)────────────►   │
│                                                  │
└──────────────────────────────────────────────────┘

Redis Keys Structure

cb:{circuitId}:state     → "Closed" | "Open" | "HalfOpen"
cb:{circuitId}:metrics   → { successCount, failureCount, windowStart }
cb:{circuitId}:blocked   → Timestamp when circuit opened
cb:{circuitId}:lock      → Distributed lock token

⚙️ Configuration Options

🌐 Supported Redis Providers

// Azure Redis Cache
.WithRedis("your-cache.redis.cache.windows.net:6380,ssl=True,password=xxx")

// AWS ElastiCache
.WithRedis("your-cluster.amazonaws.com:6379")

// Redis Cloud
.WithRedis("redis-12345.cloud.redislabs.com:12345,password=xxx")

// Self-hosted / Docker
.WithRedis("localhost:6379")

📊 Performance

Tested with Azure Redis Cache:

🔌 Real-World Scenarios

Scenario 1: Payment Gateway Failover

// Primary: Stripe, Fallback: PayPal
var payment = await cb.CallWithFallback(
    primary: () => _stripe.Charge(amount),
    fallback: () => _paypal.Charge(amount),
    isSuccess: (r) => r?.Approved == true,
    onFallbackUsed: () => _metrics.IncrementPaypalUsage()
);

Scenario 2: Database Read Replica

// Primary: Read/Write DB, Fallback: Read Replica
var user = await cb.CallWithFallback(
    primary: () => _primaryDb.GetUser(id),
    fallback: () => _replicaDb.GetUser(id),
    isSuccess: (r) => r != null
);

Scenario 3: External API with Cache

// Primary: Live API, Fallback: Cached data
var data = await cb.CallWithFallback(
    primary: () => _externalApi.GetData(),
    fallback: () => _cache.GetData(),
    isSuccess: (r) => r?.IsValid == true
);

Scenario 4: Multi-Region Failover

var response = await cb.CallWithFallback(
    primary: () => CallUsEastApi(),
    isSuccess: (r) => r?.Success == true,
    fallbacks: new[] {
        () => CallUsWestApi(),
        () => CallEuApi(),
        () => GetCachedResponse()
    }
);

📋 API Reference

IDistributedCircuitBreaker

public interface IDistributedCircuitBreaker
{
    // Properties
    string State { get; }           // Current state
    bool IsAllowingCalls { get; }   // Can calls go through?
    bool IsHealthy { get; }         // Is circuit closed?

    // Simple call with fallback (v2.0)
    Task<T> CallWithFallback<T>(
        Func<Task<T>> primary,
        Func<Task<T>> fallback,
        Func<T, bool> isSuccess,
        Action? onCircuitOpen = null,
        Action? onFallbackUsed = null);

    // Multiple fallbacks (v2.0)
    Task<T> CallWithFallback<T>(
        Func<Task<T>> primary,
        Func<T, bool> isSuccess,
        Func<Task<T>>[] fallbacks,
        Action? onCircuitOpen = null,
        Action? onFallbackUsed = null);

    // Manual control
    Task Open();    // Block all calls
    Task Close();   // Resume calls
}

🔄 Migration from v1.x

v2.0 is fully backward compatible. Your existing code works!

// v1.x code (still works)
using Polly.Redis;  // Old namespace still works
var cb = CircuitBreaker.Create("api", "redis");

// v2.0 code (recommended)
using CircuitBreaker.Redis.Distributed;  // New namespace
var cb = DistributedCircuitBreaker.Create("api", "redis");

New in v2.0:

• CallWithFallback - Simple API, no exceptions needed
• isSuccess - YOU define what success means
• Multiple fallbacks
• Better namespace

📚 Learn More

• Complete Feature List
• Internal Architecture
• Sliding Window Algorithm
• Distributed Locking

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide.

📄 License

BSD-3-Clause License. See LICENSE for details.

🙏 Acknowledgments

• Inspired by Polly circuit breaker patterns
• Uses StackExchange.Redis for Redis operations

Made with ❤️ by Sanket Singh