Add Circuit breaker support

[niveathika]

Purpose

Fixes ballerina-platform/ballerina-library#8382

Examples

Checklist

• Linked to an issue
• Updated the changelog
• Added tests
• Updated the spec
• Checked native-image compatibility

[Copilot]

Pull request overview

This PR adds circuit breaker support to the FTP library to prevent cascade failures when the FTP server is experiencing issues. The circuit breaker implementation follows the classic three-state pattern (CLOSED, OPEN, HALF_OPEN) and uses a sliding window of time buckets to track failure rates.

Changes:

• Added circuit breaker implementation with configurable failure thresholds and sliding window tracking
• Integrated circuit breaker checks into FTP client operations to fail fast when the server is unavailable
• Added new CircuitBreakerOpenError error type as a subtype of ServiceUnavailableError
• Added comprehensive configuration options for circuit breaker behavior including failure categories
• Updated documentation and added test coverage

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
native/src/main/java/io/ballerina/stdlib/ftp/util/FtpUtil.java	Added CircuitBreakerOpenError to ErrorType enum
native/src/main/java/io/ballerina/stdlib/ftp/util/FtpConstants.java	Added circuit breaker constants for configuration
native/src/main/java/io/ballerina/stdlib/ftp/client/circuitbreaker/*.java	Core circuit breaker implementation including state machine, health tracking, failure categorization, and configuration
native/src/main/java/io/ballerina/stdlib/ftp/client/FtpClient.java	Integrated circuit breaker checks before operations and outcome recording after operations
ballerina/error.bal	Added CircuitBreakerOpenError type definition
ballerina/commons.bal	Added FailureCategory enum, RollingWindow and CircuitBreakerConfig types
ballerina/client_endpoint.bal	Added circuitBreaker configuration field to ClientConfiguration
docs/spec/spec.md	Added circuit breaker documentation including configuration, state machine, and usage examples
changelog.md	Added circuit breaker feature to changelog
ballerina/tests/circuit_breaker_test.bal	Added tests for circuit breaker configuration validation and basic functionality

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[niveathika]

@copilot open a new pull request to apply changes based on the comments in this thread

[Copilot]

@niveathika I've opened a new pull request, #1535, to work on those changes. Once the pull request is ready, I'll request review from you.

[codecov]

Codecov Report

❌ Patch coverage is 63.74408% with 153 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.64%. Comparing base (ebe3428) to head (9d506b3).
⚠️ Report is 18 commits behind head on master.

Files with missing lines	Patch %	Lines
.../ftp/client/circuitbreaker/FailureCategorizer.java	0.00%	83 Missing ⚠️
...dlib/ftp/client/circuitbreaker/CircuitBreaker.java	74.31%	18 Missing and 10 partials ⚠️
...tdlib/ftp/client/circuitbreaker/CircuitHealth.java	72.13%	12 Missing and 5 partials ⚠️
...java/io/ballerina/stdlib/ftp/client/FtpClient.java	83.09%	6 Missing and 6 partials ⚠️
...tp/client/circuitbreaker/CircuitBreakerConfig.java	89.28%	2 Missing and 4 partials ⚠️
...lib/ftp/client/circuitbreaker/FailureCategory.java	60.00%	3 Missing and 1 partial ⚠️
...io/ballerina/stdlib/ftp/client/FtpRetryHelper.java	75.00%	1 Missing and 1 partial ⚠️
...erina/stdlib/ftp/client/circuitbreaker/Bucket.java	94.44%	1 Missing ⚠️

❌ Your project status has failed because the head coverage (78.64%) is below the target coverage (80.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@             Coverage Diff              @@
##             master    #1534      +/-   ##
============================================
- Coverage     80.38%   78.64%   -1.75%     
- Complexity      831      914      +83     
============================================
  Files            63       70       +7     
  Lines          3712     4125     +413     
  Branches        621      717      +96     
============================================
+ Hits           2984     3244     +260     
- Misses          461      587     +126     
- Partials        267      294      +27     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 14 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[niveathika]

@copilot open a new pull request to apply changes based on the comments in this thread. Only fix the unresolved comments

[Copilot]

@niveathika I've opened a new pull request, #1536, to work on those changes. Once the pull request is ready, I'll request review from you.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ niveathika
❌ Copilot
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
1.3% Duplication on New Code

See analysis details on SonarQube Cloud