# Circuit Breaker Pattern Guide

The Circuit Breaker prevents cascading failures by temporarily blocking calls to failing services.

## When to Use

- Calling external services that may fail
- Preventing resource waste on failing operations
- Fast-fail scenarios (don't wait for timeout)
- Protecting downstream services from overload

## When NOT to Use

- Operations that must always attempt execution
- Single-attempt operations (use Retry instead)
- Operations with no downstream dependencies

## Quick Start

```pascal
uses Murphy.Policy.CircuitBreaker;

var
  Policy: ICircuitBreakerPolicy;
begin
  Policy := TCircuitBreakerBuilder
    .Handle(Exception)
    .Fail(3)
    .Within(TTimeSpan.FromSeconds(30))
    .Build;

  Policy.Execute(procedure begin CallExternalService; end);
end;
```

## Common Scenarios

### Protecting External API Calls

```pascal
type
  TAPIClient = class
  private
    FCircuitBreaker: ICircuitBreakerPolicy;
  public
    constructor Create;
    function GetData: string;
  end;

constructor TAPIClient.Create;
begin
  FCircuitBreaker := TCircuitBreakerBuilder
    .Handle([EIdHTTPProtocolException, EIdSocketError])
    .Fail(5)
    .Within(TTimeSpan.FromMinutes(1))
    .Build;
end;

function TAPIClient.GetData: string;
begin
  try
    FCircuitBreaker.Execute(
      procedure
      begin
        Result := HTTP.Get('https://external-api.com/data');
      end);
  except
    on E: EBrokenCircuitException do
      raise Exception.Create('Service temporarily unavailable');
  end;
end;
```

### Manual Circuit Control

```pascal
var Policy: ICircuitBreakerPolicy;
begin
  Policy := TCircuitBreakerBuilder.Handle(Exception).Fail(3).Build;

  // Manual isolation for maintenance
  Policy.Isolate;

  // Later...
  Policy.Reset;
end;
```

### Monitoring Circuit State

```pascal
procedure MonitorService;
var
  Policy: ICircuitBreakerPolicy;
begin
  Policy := TCircuitBreakerBuilder.Handle(Exception).Fail(2).Build;

  while True do
  begin
    case Policy.CircuitState of
      TCircuitState.Closed:   WriteLn('Service: Healthy');
      TCircuitState.Open:     WriteLn('Service: DOWN');
      TCircuitState.HalfOpen: WriteLn('Service: Testing recovery');
      TCircuitState.Isolated: WriteLn('Service: Maintenance mode');
    end;

    Sleep(5000);
  end;
end;
```

## Best Practices

1. **Configure appropriate thresholds** - Balance between sensitivity and tolerance
2. **Set reasonable recovery times** - Allow enough time for service recovery
3. **Log circuit state changes** - For monitoring and alerting
4. **Handle broken circuit exceptions** - Provide fallback behavior
5. **Monitor circuit health** - Track open/close events

## State Machine

```
Closed → (failures >= threshold) → Open
Open → (duration elapsed) → HalfOpen
HalfOpen → (success) → Closed
HalfOpen → (failure) → Open
```

## See Also

- [Circuit Breaker API Reference](../API-Reference/CircuitBreaker-Policy.md)
- [Combining Patterns](Combining-Patterns.md)

---

[Back to Index](../Home.md)