feat(circuit-breaker): time-based failure-rate trip mode (0.13.0)

[lesnik512]

Summary

Adds an opt-in time-based failure-rate trip mode to AsyncCircuitBreaker / CircuitBreaker. The classic consecutive-failure model stays the default and is byte-unchanged. Rate mode opens the circuit when the failure rate over a rolling time window meets a threshold, once a minimum call volume is observed — catching partial degradation (e.g. a steady 50% error rate that never forms a consecutive streak) that the classic breaker misses.

from httpware.middleware.resilience import AsyncCircuitBreaker

breaker = AsyncCircuitBreaker(
    failure_rate_threshold=0.5,  # open at ≥50% failures
    window_seconds=30.0,         # over a rolling 30s window
    minimum_calls=20,            # but only once 20+ calls are observed
)

Closes the deferred "CircuitBreaker v2 (a)" item. Ships as 0.13.0 (additive, no breaking changes).

What's in it

• _RollingWindow — time-bucketed success/failure counters (10 buckets), eviction-on-read/write, with a Hypothesis property test.
• Config + validation — failure_rate_threshold (opt-in switch, range (0,1]), window_seconds (30.0), minimum_calls (20); threaded through the shared _CircuitBreakerState so both clients reach parity.
• Trip integration — rate mode changes only the CLOSED→OPEN decision (records every outcome, opens when total ≥ minimum_calls and failures/total ≥ threshold); checked after both successes and failures. Half-open recovery + event names identical to classic; window cleared on close. Mode-aware circuit.opened message + rate attributes.
• Docs — architecture/resilience.md, docs/resilience.md, module docstring, and 0.13.0 release notes.

Time-based (not count-based) was chosen because it matches the HTTP-service mental model and degrades sanely under variable traffic; Hystrix/Polly/Envoy are all time-based. Count-based windows, the slow-call axis, and manual control / state introspection remain deliberately deferred.

Design + plan: planning/changes/active/2026-06-16.02-circuit-breaker-rate-mode/.

Test plan

• just test — 699 passed, 100% coverage
• just lint — clean (ruff format/check + ty)
• Behavior tests (async + sync): trips on partial failure, no trip below minimum_calls, time eviction, clear-on-close; validation; observability attribute set
• Hypothesis property test for the rolling-window recorder
• Classic-mode tests unchanged (no regression)
• mkdocs build --strict — clean

🤖 Generated with Claude Code