acc-create-circuit-breaker

# Circuit Breaker Generator

Creates Circuit Breaker pattern infrastructure for resilience and fault tolerance.

## When to Use

| Scenario | Example |
|----------|---------|
| External service calls | API integrations, payment gateways |
| Database connections | Prevent connection exhaustion |
| Cascading failures | Stop failure propagation |
| Service degradation | Graceful fallback when service unavailable |

## Component Characteristics

### CircuitState Enum
- **Closed**: Normal operation, requests pass through
- **Open**: Failing, requests rejected immediately
- **HalfOpen**: Testing recovery, limited requests allowed

### CircuitBreaker
- Wraps external service calls
- Tracks failures and successes
- Automatic state transitions
- Configurable thresholds and timeouts

### CircuitBreakerConfig
- Failure threshold count
- Success threshold for recovery
- Open state timeout duration

---

## Generation Process

### Step 1: Generate Core Components

**Path:** `src/Infrastructure/Resilience/CircuitBreaker/`

1. `CircuitState.php` — Enum with state transitions
2. `CircuitBreakerConfig.php` — Configuration value object
3. `CircuitBreakerException.php` — Exception for open circuit

### Step 2: Generate Circuit Breaker

**Path:** `src/Infrastructure/Resilience/CircuitBreaker/`

1. `CircuitBreaker.php` — Main implementation with state management

### Step 3: Generate Factory and Registry

**Path:** `src/Infrastructure/Resilience/CircuitBreaker/`

1. `CircuitBreakerFactory.php` — Creates configured breakers
2. `CircuitBreakerRegistry.php` — Per-service breaker management

### Step 4: Generate Tests

1. `CircuitStateTest.php` — State transition tests
2. `CircuitBreakerTest.php` — Breaker behavior tests

---

## File Placement

| Component | Path |
|-----------|------|
| All Classes | `src/Infrastructure/Resilience/CircuitBreaker/` |
| Unit Tests | `tests/Unit/Infrastructure/Resilience/CircuitBreaker/` |

---

## Naming Conventions

| Component | Pattern | Example |
|-----------|---------|---------|
| State Enum | `CircuitState` | `CircuitState` |
| Config | `CircuitBreakerConfig` | `CircuitBreakerConfig` |
| Main Class | `CircuitBreaker` | `CircuitBreaker` |
| Factory | `CircuitBreakerFactory` | `CircuitBreakerFactory` |
| Registry | `CircuitBreakerRegistry` | `CircuitBreakerRegistry` |
| Exception | `CircuitBreakerException` | `CircuitBreakerException` |
| Test | `{ClassName}Test` | `CircuitBreakerTest` |

---

## Quick Template Reference

### CircuitState

```php
enum CircuitState: string
{
    case Closed = 'closed';
    case Open = 'open';
    case HalfOpen = 'half_open';

    public function allowsRequest(): bool;
    public function canTransitionTo(self $next): bool;
}
```

### CircuitBreakerConfig

```php
final readonly class CircuitBreakerConfig
{
    public function __construct(
        public int $failureThreshold = 5,
        public int $successThreshold = 3,
        public int $openTimeoutSeconds = 30,
        public int $halfOpenMaxAttempts = 3
    ) {}

    public static function default(): self;
    public static function aggressive(): self;
    public static function lenient(): self;
}
```

### CircuitBreaker

```php
final class CircuitBreaker
{
    public function execute(callable $operation, ?callable $fallback = null): mixed;
    public function canExecute(): bool;
    public function getState(): CircuitState;
    public function forceOpen(): void;
    public function forceClose(): void;
}
```

---

## Usage Example

```php
$breaker = $circuitBreakers->get('payment-gateway');

try {
    $result = $breaker->execute(
        operation: fn() => $paymentClient->charge($request),
        fallback: fn() => PaymentResult::deferred($request->id)
    );
} catch (CircuitBreakerException $e) {
    // Circuit is open
    return PaymentResult::serviceUnavailable($request->id);
}
```

---

## State Transitions

```
CLOSED ─────failure threshold reached────→ OPEN
   ↑                                          │
   │                                          │ timeout elapsed
   │                                          ↓
success threshold reached              HALF-OPEN
   └────────────────────────────────────────┘
                        │
            failure in half-open
                        │
                        ↓
                      OPEN
```

---

## Anti-patterns to Avoid

| Anti-pattern | Problem | Solution |
|--------------|---------|----------|
| Global Circuit Breaker | One breaker for all services | Per-service breakers |
| No Fallback | Hard failure on open | Provide fallback strategy |
| Immediate Retry | Hammering failed service | Use timeout before HalfOpen |
| No Metrics | Can't monitor health | Log state transitions |
| Static Thresholds | Can't tune per service | Configurable per service |
| No Manual Override | Can't force open/close | Add force methods |

---

## References

For complete PHP templates and examples, see:
- `references/templates.md` — CircuitState, CircuitBreakerConfig, CircuitBreaker, Factory, Registry templates
- `references/examples.md` — HTTP client, payment gateway examples and tests