using Voyager.Common.Results;
using Voyager.Common.Resilience;
// Create a circuit breaker policy
var circuitBreaker = new CircuitBreakerPolicy(
failureThreshold: 5, // Open after 5 consecutive failures
openTimeout: TimeSpan.FromSeconds(30), // Stay open for 30 seconds
halfOpenMaxAttempts: 3 // Allow 3 recovery test attempts
);
// Execute operations through the circuit breaker
var result = await GetUser(userId)
.BindWithCircuitBreakerAsync(
user => CallExternalApiAsync(user),
circuitBreaker
);
// Handle results including circuit breaker state
var message = result.Match(
onSuccess: data => $"Success: {data}",
onFailure: error => error.Type == ErrorType.CircuitBreakerOpen
? "Service temporarily unavailable - circuit breaker is open"
: $"Error: {error.Message}"
);
🎯 Circuit Breaker States
The circuit breaker implements a 3-state model and only counts infrastructure errors (Unavailable, Timeout, Database, Unexpected) towards failure thresholds. Business errors (Validation, NotFound, Permission, etc.) are ignored.
🟢 Closed (Normal Operation)
All requests flow through to the protected operation
Failures are counted
When failure threshold is reached → transitions to Open
🔴 Open (Failing Fast)
Requests immediately fail with ErrorType.CircuitBreakerOpen
No calls are made to the protected operation (prevents cascading failures)
After openTimeout → transitions to HalfOpen
🟡 HalfOpen (Testing Recovery)
Limited number of test requests are allowed (halfOpenMaxAttempts)
If all test requests succeed → transitions to Closed
If any test request fails → transitions back to Open
🔧 Configuration Options
var policy = new CircuitBreakerPolicy(
failureThreshold: 10, // Number of failures before opening
openTimeout: TimeSpan.FromMinutes(1), // How long to stay open
halfOpenMaxAttempts: 5 // Test attempts in half-open state
);
Best Practices:
failureThreshold: 3-10 for most scenarios (lower = more sensitive)
openTimeout: 30-60 seconds for typical services (longer for slow recovery)
halfOpenMaxAttempts: 3-5 attempts (enough to verify recovery without overload)
Infrastructure Errors (counted towards threshold):
ErrorType.Unavailable - Service down, network issues
var policy = new CircuitBreakerPolicy(
failureThreshold: 5,
openTimeout: TimeSpan.FromSeconds(30),
halfOpenMaxAttempts: 3
);
// Sync function
var result = await GetUserId()
.BindWithCircuitBreakerAsync(
id => _externalService.GetUserData(id),
policy
);
// Async function
var result = await GetUserIdAsync()
.BindWithCircuitBreakerAsync(
id => _externalService.GetUserDataAsync(id),
policy
);
With Async Result Chains
var result = await ValidateRequestAsync(request)
.BindAsync(req => AuthenticateAsync(req))
.BindWithCircuitBreakerAsync(
user => _externalApi.FetchDataAsync(user),
circuitBreaker
)
.MapAsync(data => ProcessData(data));
Monitoring Circuit State
// Check current state
switch (policy.State)
{
case CircuitBreakerState.Closed:
_logger.LogInfo("Circuit healthy");
break;
case CircuitBreakerState.Open:
_logger.LogWarning("Circuit open - service degraded");
break;
case CircuitBreakerState.HalfOpen:
_logger.LogInfo("Circuit testing recovery");
break;
}
// Manual reset if needed (e.g., after manual intervention)
policy.Reset();
Error Handling
var result = await operation.BindWithCircuitBreakerAsync(CallServiceAsync, policy);
result.Switch(
onSuccess: data => Console.WriteLine($"Success: {data}"),
onFailure: error =>
{
if (error.Type == ErrorType.CircuitBreakerOpen)
{
// Circuit breaker is open
var cbError = error; // Contains last failure in message
_logger.LogWarning($"Circuit open: {error.Message}");
// Implement fallback behavior
return GetCachedData();
}
else
{
// Other error types
_logger.LogError($"Operation failed: {error.Message}");
}
}
);
Combining with Retry
using Voyager.Common.Results.Extensions;
// Retry for transient failures + Circuit Breaker for cascading failures
var result = await GetConnectionAsync()
.BindWithRetryAsync(
conn => ExecuteQueryAsync(conn),
RetryPolicies.TransientErrors(maxAttempts: 3)
)
.BindWithCircuitBreakerAsync(
data => CallDownstreamServiceAsync(data),
circuitBreaker
);
🏗️ Architecture
The Resilience library is designed as a separate package to:
✅ Keep core Results library dependency-free
✅ Allow independent versioning of resilience patterns
✅ Enable optional adoption (use only what you need)
✅ Future-proof for additional patterns (Bulkhead, RateLimiter, etc.)
