Add Circuit breaker support

ballerina/client_endpoint.bal

@@ -454,6 +454,8 @@ public enum Compression {
 #                 malformed CSV records are skipped and written to a separate file in the current directory
 # + retryConfig - Configuration for retry behavior on transient failures for non-streaming read operations
 #                 (getBytes, getText, getJson, getXml, getCsv). If not specified, no retry is attempted.
+# + circuitBreaker - Circuit breaker configuration for handling server failures gracefully.
+#                    When enabled, the client will fail fast if the server is experiencing issues.
 public type ClientConfiguration record {|
     Protocol protocol = FTP;
     string host = "127.0.0.1";
@@ -469,6 +471,7 @@ public type ClientConfiguration record {|
     string sftpSshKnownHosts?;
     FailSafeOptions csvFailSafe?;
     RetryConfig retryConfig?;
+    CircuitBreakerConfig circuitBreaker?;
 |};
 
 isolated function getInputContent(string path, stream<byte[] & readonly, io:Error?>|string|xml|json content,

ballerina/commons.bal

@@ -255,3 +255,48 @@ public type FileDependencyCondition record {|
     DependencyMatchingMode matchingMode = ALL;
     int requiredFileCount = 1;
 |};
+
+# Categories of errors that can trip the circuit breaker.
+# Used to configure which types of failures should count towards the circuit breaker threshold.
+public enum FailureCategory {
+    # Connection-level failures (timeout, refused, reset, DNS resolution).
+    # Maps to ConnectionError type.
+    CONNECTION_ERROR,
+    # Authentication failures (invalid credentials, key rejected).
+    # Detected via FTP 530 response code.
+    AUTHENTICATION_ERROR,
+    # Transient server errors that may succeed on retry.
+    # Maps to ServiceUnavailableError type (FTP codes 421, 425, 426, 450, 451, 452).
+    TRANSIENT_ERROR,
+    # All errors regardless of type
+    ALL_ERRORS
+}
+
+# Configuration for the sliding time window used in failure calculation.
+# The rolling window divides time into discrete buckets for efficient tracking of request success/failure rates.
+#
+# + requestVolumeThreshold - Minimum number of requests in the window before evaluating failure threshold.
+#                            Circuit breaker will not trip until this many requests have been made.
+# + timeWindow - Time period in seconds for the sliding window
+# + bucketSize - Granularity of time buckets in seconds. Must be less than timeWindow.
+public type RollingWindow record {|
+    int requestVolumeThreshold = 10;
+    decimal timeWindow = 60;
+    decimal bucketSize = 10;
+|};
+
+# Configuration for circuit breaker behavior.
+# The circuit breaker prevents cascade failures by temporarily blocking requests when the server is experiencing issues.
+#
+# + rollingWindow - Time window configuration for failure tracking
+# + failureThreshold - Failure ratio threshold (0.0 to 1.0) that trips the circuit.
+#                      For example, 0.5 means the circuit will open when 50% of requests fail.
+# + resetTime - Seconds to wait in OPEN state before transitioning to HALF_OPEN to test recovery
+# + failureCategories - Error categories that count as failures for the circuit breaker.
+#                       Only errors matching these categories will contribute to the failure ratio.
+public type CircuitBreakerConfig record {|
+    RollingWindow rollingWindow = {};
+    float failureThreshold = 0.5;
+    decimal resetTime = 30;
+    FailureCategory[] failureCategories = [CONNECTION_ERROR, TRANSIENT_ERROR];
+|};

ballerina/error.bal

@@ -40,3 +40,9 @@ public type ServiceUnavailableError distinct Error;
 # Represents an error that occurs when all retry attempts have been exhausted.
 # This error wraps the last failure encountered during retry attempts.
 public type AllRetryAttemptsFailedError distinct Error;
+
+# Error returned when the circuit breaker is in OPEN state.
+# This indicates the FTP server is unavailable and requests are being blocked
+# to prevent cascade failures. The client should implement fallback logic
+# or wait for the circuit to transition to HALF_OPEN state.
+public type CircuitBreakerOpenError distinct ServiceUnavailableError;