Add Minimum Success Threshold for Circuit Breaker Half-Open State

[sideshowbandana]

Currently, the circuit breaker transitions from half-open to closed state after a single successful request. This can be risky in production environments where a service might appear healthy momentarily but still be unstable. A single successful request might not be sufficient to determine if a service has truly recovered.

Proposed Solution

Add a configuration option to require multiple successful requests before transitioning from half-open to closed state. This would make the circuit breaker more robust by ensuring a service is truly healthy before fully closing the circuit.

Current Behavior

• Circuit breaker opens after fail_max failures
• After reset_timeout seconds, transitions to half-open state
• Transitions to closed state after a single successful request in half-open state
• Resets failure counter when transitioning to closed state

Proposed Changes

Configuration Changes

Add a new parameter to the CircuitBreaker class:

def __init__(
    self,
    fail_max: int = 5,
    reset_timeout: float = 60,
    success_threshold: int = 1,  # New parameter
    exclude: Iterable[type[ExceptionType] | Callable[[Any], bool]] | None = None,
    listeners: Sequence[CBListenerType] | None = None,
    state_storage: CircuitBreakerStorage | None = None,
    name: str | None = None,
    throw_new_error_on_trip: bool = True,
) -> None:

Storage Changes

• Add a success counter to track successful requests in half-open state
• Reset success counter when transitioning to open state
• Increment success counter on successful requests in half-open state
• Only transition to closed state when success counter reaches success_threshold

State Management

• Modify CircuitHalfOpenState to track successful requests
• Only call close() when success threshold is reached
• Reset success counter when transitioning to open state

Benefits

1. More reliable circuit breaker behavior in production environments
2. Reduced risk of premature circuit closing
3. Better protection against flaky services
4. More configurable circuit breaker behavior

Implementation Considerations

1. Backward compatibility - default success_threshold=1 maintains current behavior
2. Storage implementation needs to handle success counter persistence
3. Redis storage implementation needs to be updated to support success counter
4. Documentation updates needed for new parameter
5. Unit tests needed for new behavior

Example Usage

# Create a circuit breaker that requires 3 successful requests before closing
breaker = CircuitBreaker(
    fail_max=5,
    reset_timeout=60,
    success_threshold=3  # New parameter
)

# Circuit will only close after 3 successful requests in half-open state

Testing Requirements

1. Unit tests for new parameter validation
2. Tests for success counter behavior
3. Tests for state transitions with different success thresholds
4. Tests for storage implementations (memory and Redis)

Documentation Updates

1. Update class documentation to include new parameter
2. Update README with new feature description and examples showing different success threshold configurations

Migration Path

Default value of 1 maintains backward compatibility

[danielfm]

Can you send a PR instead?

[danielfm]

Also, if you could provide the prompt you used to generate this text, it might be helpful.

[danielfm]

Resolved in #97