feat: add error ratio-based circuit breaking policy to api-breaker pl…

[HaoTien]

feat: Add error ratio-based circuit breaking policy to api-breaker plugin

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]

Types of changes

• New feature (non-breaking change which adds functionality)
• Documentation update

Description

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: Proper implementation of CLOSED, OPEN, and HALF_OPEN states
• Backward compatibility: Existing configurations continue to work without changes

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.permitted_number_of_calls_in_half_open_state	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

{
  "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,
        "permitted_number_of_calls_in_half_open_state": 3
      },
      "healthy": {
        "http_statuses": [200, 201, 202],
        "success_ratio": 0.6
      }
    }
  }
}

How Has This Been Tested?

• Schema validation tests for new parameters
• Functional tests for error ratio calculation
• Circuit breaker state transition tests
• Integration tests with various traffic patterns
• Backward compatibility tests
• Performance tests to ensure no regression

Test Results

# Run the new test file
prove -I. -r t/plugin/api-breaker2.t

# Verify existing tests still pass
prove -I. -r t/plugin/api-breaker.t

Files Modified

• apisix/plugins/api-breaker.lua - Core plugin logic with new ratio-based policy
• t/plugin/api-breaker2.t - New comprehensive test file for ratio-based circuit breaking
• docs/en/latest/plugins/api-breaker.md - Updated English documentation
• docs/zh/latest/plugins/api-breaker.md - Updated Chinese documentation

Checklist

• My code follows the code style of this project
• My change requires a change to the documentation
• I have updated the documentation accordingly
• I have read the CONTRIBUTING document
• I have added tests to cover my changes
• All new and existing tests passed
• I have squashed my commits into logical units
• My commit messages are in the proper format

Additional Notes

This implementation:

• ✅ Maintains full backward compatibility - existing configurations work unchanged
• ✅ Follows APISIX patterns - consistent with existing plugin architecture
• ✅ Comprehensive testing - covers all scenarios and edge cases
• ✅ Performance optimized - efficient sliding window implementation
• ✅ Well documented - updated both English and Chinese docs

The feature addresses real-world use cases for:

• High-traffic services with better error spike handling
• Variable traffic patterns with adaptive behavior
• Microservices architectures requiring precise circuit breaking
• SLA-based circuit breaking with configurable error rates

Ready for review and feedback!