yeganeahmadnejad opened a new pull request, #13764:
URL: https://github.com/apache/apisix/pull/13764
## What this PR does / why we need it
This PR implements error ratio-based circuit breaking (`unhealthy-ratio`
policy) for the `api-breaker` plugin, providing more intelligent and adaptive
circuit breaking behavior based on error rates within a sliding time window,
rather than just consecutive failure counts.
Closes #12763
## Context: reviving #12765
This is a revival of #12765 by @HaoTien, which was closed by the stale-bot
for inactivity on 2026-07-24 despite:
- Passing all CI checks (build, lint, docs, kubernetes-discovery, tars, etc.)
- ~20 rounds of review with @Baoyuantop, addressing sliding-window-reset,
half-open-failure-fallback, and over-limit half-open call test coverage
- A `CHANGES_REQUESTED` review from @moonming on 2026-03-16 asking for a
summary of the design decisions made during review, which @HaoTien answered in
full on 2026-03-17, followed by two more pings for re-review that went
unanswered
The commit here carries over the final reviewed tree from #12765 unchanged
(rebased onto current master; no functional changes), with commit authorship
preserved for @HaoTien. Opening a fresh PR since the original was auto-closed
and I don't have push access to reopen it or its branch.
### Current Limitations
- The existing failure count-based approach only considers consecutive
failures
- It doesn't account for the overall error rate in relation to total requests
- May be too sensitive during low traffic periods or not sensitive enough
during high traffic periods
### New Features Added
- **Error ratio-based circuit breaking**: New `unhealthy-ratio` policy that
triggers circuit breaker based on error rate within a sliding time window
- **Configurable parameters**: Support for error ratio threshold, minimum
request threshold, sliding window size, etc.
- **Circuit breaker states**: Explicit CLOSED, OPEN, and HALF_OPEN states
- **Backward compatibility**: Existing configurations continue to work
unchanged (`unhealthy-count` remains the default policy)
### New Configuration Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `policy` | string | `"unhealthy-count"` | Circuit breaker policy |
| `unhealthy.error_ratio` | number | `0.5` | Error rate threshold (0-1) to
trigger circuit breaker |
| `unhealthy.min_request_threshold` | integer | `10` | Minimum requests
needed before evaluating error rate |
| `unhealthy.sliding_window_size` | integer | `300` | Sliding window size in
seconds for error rate calculation |
| `unhealthy.half_open_max_calls` | integer | `3` | Number of permitted
calls in half-open state |
| `healthy.success_ratio` | number | `0.6` | Success rate threshold to close
circuit breaker from half-open state |
### Example Configuration
```json
{
"plugins": {
"api-breaker": {
"break_response_code": 503,
"policy": "unhealthy-ratio",
"max_breaker_sec": 60,
"unhealthy": {
"http_statuses": [500, 502, 503, 504],
"error_ratio": 0.5,
"min_request_threshold": 10,
"sliding_window_size": 300,
"half_open_max_calls": 3
},
"healthy": {
"http_statuses": [200, 201, 202],
"success_ratio": 0.6
}
}
}
}
```
## Types of changes
- [x] New feature (non-breaking change which adds functionality)
- [x] Documentation update
## How Has This Been Tested?
- [x] Schema validation tests for new parameters
- [x] Functional tests for error ratio calculation
- [x] Circuit breaker state transition tests (CLOSED → OPEN → HALF_OPEN →
CLOSED/OPEN)
- [x] Sliding window expiration/reset tests
- [x] Half-open failure fallback tests
- [x] Over-limit half-open call rejection tests
- [x] Backward-compatibility tests for the existing `unhealthy-count` policy
This is the same test coverage that was previously reviewed and passed full
CI on #12765.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
