cleveragents/cleveragents-core

Fork 3

CircuitBreaker missing validation for failure_threshold parameter allows circuit to open on first call #8402

New issue

Open

opened 2026-04-13 18:40:23 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-13 18:40:23 +00:00

Owner

Metadata

Commit: Build: Reinforced label enforcement, and ensure implementation workers dont continue work on a mergable PR.
Branch: main
SHA: 5a9aaa79ed

Background and Context

CircuitBreaker.__init__ in src/cleveragents/core/circuit_breaker.py validates half_open_max_successes >= 1 but does not validate failure_threshold. Passing failure_threshold=0 causes the circuit to open after the very first failure because _on_failure increments failure_count to 1 and then checks failure_count >= failure_threshold (i.e., 1 >= 0 = True), immediately transitioning to the OPEN state.

This is an inconsistent validation pattern — one parameter is validated, the other is not — and violates the code quality standard: "All public/protected methods validate arguments first."

Current Behavior

cb = CircuitBreaker(failure_threshold=0)  # No error raised
cb.call(lambda: (_ for _ in ()).throw(ValueError("fail")))
# Circuit is now OPEN after just 1 failure, regardless of threshold intent

With failure_threshold=0, the circuit opens on the very first failure, making it effectively unusable. There is no guard at construction time to prevent this misconfiguration.

Relevant code in circuit_breaker.py:

def __init__(
    self,
    failure_threshold: int = 5,
    ...
    half_open_max_successes: int = 2,
    ...
):
    if half_open_max_successes < 1:
        raise ValueError("half_open_max_successes must be >= 1")
    # ← No equivalent check for failure_threshold
    self.failure_threshold = failure_threshold

And in _on_failure:

self.failure_count += 1
...
if self.failure_count >= self.failure_threshold:  # 1 >= 0 = True when threshold=0
    self.state = CircuitBreakerState.OPEN
    return True

Expected Behavior

CircuitBreaker.__init__ should validate failure_threshold >= 1 and raise a ValueError:

if failure_threshold < 1:
    raise ValueError("failure_threshold must be >= 1")

This is consistent with the existing half_open_max_successes validation.

Acceptance Criteria

CircuitBreaker(failure_threshold=0) raises ValueError at construction time
CircuitBreaker(failure_threshold=-1) raises ValueError at construction time
CircuitBreaker(failure_threshold=1) continues to work correctly
BDD test scenario covers the invalid failure_threshold boundary

Subtasks

Add if failure_threshold < 1: raise ValueError(...) guard in CircuitBreaker.__init__
Add BDD test for boundary condition failure_threshold=0
Verify no existing tests break

Definition of Done

The issue is closed when CircuitBreaker raises ValueError for failure_threshold < 1 at construction time, with a passing BDD test, merged to main.

Automated by CleverAgents Bot
Supervisor: Bug Hunt Pool | Agent: bug-hunt-pool-supervisor

## Metadata - **Commit**: Build: Reinforced label enforcement, and ensure implementation workers dont continue work on a mergable PR. - **Branch**: main - **SHA**: 5a9aaa79edaefb1a257114f054ea87facb8efe69 ## Background and Context `CircuitBreaker.__init__` in `src/cleveragents/core/circuit_breaker.py` validates `half_open_max_successes >= 1` but does **not** validate `failure_threshold`. Passing `failure_threshold=0` causes the circuit to open after the very first failure because `_on_failure` increments `failure_count` to 1 and then checks `failure_count >= failure_threshold` (i.e., `1 >= 0` = True), immediately transitioning to the OPEN state. This is an inconsistent validation pattern — one parameter is validated, the other is not — and violates the code quality standard: *"All public/protected methods validate arguments first."* ## Current Behavior ```python cb = CircuitBreaker(failure_threshold=0) # No error raised cb.call(lambda: (_ for _ in ()).throw(ValueError("fail"))) # Circuit is now OPEN after just 1 failure, regardless of threshold intent ``` With `failure_threshold=0`, the circuit opens on the very first failure, making it effectively unusable. There is no guard at construction time to prevent this misconfiguration. Relevant code in `circuit_breaker.py`: ```python def __init__( self, failure_threshold: int = 5, ... half_open_max_successes: int = 2, ... ): if half_open_max_successes < 1: raise ValueError("half_open_max_successes must be >= 1") # ← No equivalent check for failure_threshold self.failure_threshold = failure_threshold ``` And in `_on_failure`: ```python self.failure_count += 1 ... if self.failure_count >= self.failure_threshold: # 1 >= 0 = True when threshold=0 self.state = CircuitBreakerState.OPEN return True ``` ## Expected Behavior `CircuitBreaker.__init__` should validate `failure_threshold >= 1` and raise a `ValueError`: ```python if failure_threshold < 1: raise ValueError("failure_threshold must be >= 1") ``` This is consistent with the existing `half_open_max_successes` validation. ## Acceptance Criteria - [ ] `CircuitBreaker(failure_threshold=0)` raises `ValueError` at construction time - [ ] `CircuitBreaker(failure_threshold=-1)` raises `ValueError` at construction time - [ ] `CircuitBreaker(failure_threshold=1)` continues to work correctly - [ ] BDD test scenario covers the invalid `failure_threshold` boundary ## Subtasks - [ ] Add `if failure_threshold < 1: raise ValueError(...)` guard in `CircuitBreaker.__init__` - [ ] Add BDD test for boundary condition `failure_threshold=0` - [ ] Verify no existing tests break ## Definition of Done The issue is closed when `CircuitBreaker` raises `ValueError` for `failure_threshold < 1` at construction time, with a passing BDD test, merged to `main`. --- **Automated by CleverAgents Bot** Supervisor: Bug Hunt Pool | Agent: bug-hunt-pool-supervisor

HAL9000 added the

labels

2026-04-13 18:51:10 +00:00

HAL9000 added this to the v3.3.0 milestone

2026-04-13 18:51:10 +00:00

HAL9000 added

and removed

labels

2026-04-13 19:15:07 +00:00

HAL9000 commented

2026-04-13 19:19:34 +00:00

Author

Owner

✅ Verified — Missing validation for failure_threshold in CircuitBreaker allows misconfiguration that causes premature circuit opening. MoSCoW: Should Have for v3.3.0 — defensive validation is expected. [AUTO-OWNR-1]

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: project-owner-pool-supervisor

✅ **Verified** — Missing validation for failure_threshold in CircuitBreaker allows misconfiguration that causes premature circuit opening. **MoSCoW: Should Have** for v3.3.0 — defensive validation is expected. [AUTO-OWNR-1] --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor