Add documentation

Author: niveathika

changelog.md

@@ -5,7 +5,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## unreleased
 
+### Added
+
+- [Add Circuit breaker support](https://github.com/ballerina-platform/ballerina-library/issues/8382)
 - [Add automatic retry support with exponential backoff for FTP client and listener operations](https://github.com/ballerina-platform/ballerina-library/issues/8585)
+- [Add distinct error types](https://github.com/ballerina-platform/ballerina-library/issues/8597)
 - [Incorporate the csv fail safe support in the FTP listener](https://github.com/ballerina-platform/ballerina-library/issues/8502)
 
 ### Fixed

docs/spec/spec.md

@@ -3,7 +3,7 @@
 _Owners_: @shafreenAnfar @dilanSachi @Bhashinee    
 _Reviewers_: @shafreenAnfar @Bhashinee  
 _Created_: 2020/10/28   
-_Updated_: 2025/11/20  
+_Updated_: 2026/01/28  
 _Edition_: Swan Lake    
 
 ## Introduction
@@ -24,21 +24,21 @@ The conforming implementation of the specification is released and included in t
     - [2.1. Security Configurations](#21-security-configurations)
     - [2.2. FileInfo](#22-fileinfo)
     - [2.3. Error Types](#23-error-types)
-    - [2.3. Error Types](#23-error-types-1)
     - [2.4. Retry Configuration](#24-retry-configuration)
   - [3. Client](#3-client)
     - [3.1. Configurations](#31-configurations)
-    - [3.2. Initialization](#32-initialization)
-      - [3.2.1. Insecure Client](#321-insecure-client)
-      - [3.2.2. Secure Client](#322-secure-client)
-      - [3.2.3. Client with Retry Configuration](#323-client-with-retry-configuration)
-    - [3.3. Functions](#33-functions)
+    - [3.2. Circuit Breaker](#32-circuit-breaker)
+    - [3.3. Initialization](#33-initialization)
+      - [3.3.1. Insecure Client](#331-insecure-client)
+      - [3.3.2. Secure Client](#332-secure-client)
+      - [3.3.3. Client with Retry Configuration](#333-client-with-retry-configuration)
+    - [3.4. Functions](#34-functions)
   - [4. Listener](#4-listener)
     - [4.1. Configurations](#41-configurations)
     - [4.2. Initialization](#42-initialization)
       - [4.2.1. Insecure Listener](#421-insecure-listener)
       - [4.2.2. Secure Listener](#422-secure-listener)
-      - [4.3. Usage](#43-usage)
+    - [4.3. Usage](#43-usage)
       - [4.3.1. Format-Specific Listener Callbacks](#431-format-specific-listener-callbacks)
   - [5. Caller](#5-caller)
     - [5.1. Initialization](#51-initialization)
@@ -161,7 +161,6 @@ public type Error distinct error;
 
 * `ConnectionError` - Represents errors that occur when connecting to the FTP/SFTP server. This includes network failures, host unreachable, connection refused, etc.
 ```ballerina
-# Represents an error that occurs when connecting to the FTP/SFTP server.
 public type ConnectionError distinct Error;
 ```
 
@@ -180,55 +179,19 @@ public type FileAlreadyExistsError distinct Error;
 public type InvalidConfigurationError distinct Error;
 ```
 
-* `ServiceUnavailableError` - Represents errors that occur when the FTP/SFTP service is temporarily unavailable. This is a transient error indicating the operation may succeed on retry. Common causes include server overload (FTP code 421), connection issues (425, 426), temporary file locks (450), or server-side processing errors (451). This error type is designed for use with retry and circuit breaker patterns.
+* `ServiceUnavailableError` - Represents errors that occur when the FTP/SFTP service is temporarily unavailable. This is a transient error indicating the operation may succeed on retry. Common causes include server overload (FTP code 421), connection issues (425, 426), temporary file locks (450), or server-side processing errors (451).
 ```ballerina
 public type ServiceUnavailableError distinct Error;
 ```
 
-All specific error types are subtypes of the base `Error` type, allowing for both specific and general error handling:
-```ballerina
-// Handle specific error types
-ftp:Client|ftp:Error result = new(config);
-if result is ftp:ConnectionError {
-    // Handle connection failures specifically
-} else if result is ftp:ServiceUnavailableError {
-    // Transient error - retry the operation
-} else if result is ftp:Error {
-    // Handle any other FTP error
-}
-```
-### 2.3. Error Types
-The FTP module provides a hierarchy of error types for better error handling and more precise error identification.
-
-* `Error` - The base error type for all FTP-related errors.
-```ballerina
-public type Error distinct error;
-```
-
-* `ConnectionError` - Represents errors that occur when connecting to the FTP/SFTP server. This includes network failures, host unreachable, connection refused, etc.
-```ballerina
-# Represents an error that occurs when connecting to the FTP/SFTP server.
-public type ConnectionError distinct Error;
-```
-
-* `FileNotFoundError` - Represents errors that occur when a requested file or directory is not found on the remote server.
-```ballerina
-public type FileNotFoundError distinct Error;
-```
-
-* `FileAlreadyExistsError` - Represents errors that occur when attempting to create a file or directory that already exists.
+* `AllRetryAttemptsFailedError` - Represents an error that occurs when all retry attempts have been exhausted. This error wraps the last failure encountered during retry attempts.
 ```ballerina
-public type FileAlreadyExistsError distinct Error;
-```
-
-* `InvalidConfigurationError` - Represents errors that occur when FTP/SFTP configuration is invalid (e.g., invalid port numbers, invalid regex patterns, invalid timeout values).
-```ballerina
-public type InvalidConfigurationError distinct Error;
+public type AllRetryAttemptsFailedError distinct Error;
 ```
 
-* `ServiceUnavailableError` - Represents errors that occur when the FTP/SFTP service is temporarily unavailable. This is a transient error indicating the operation may succeed on retry. Common causes include server overload (FTP code 421), connection issues (425, 426), temporary file locks (450), or server-side processing errors (451). This error type is designed for use with retry and circuit breaker patterns.
+* `CircuitBreakerOpenError` - 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. This is a subtype of `ServiceUnavailableError`.
 ```ballerina
-public type ServiceUnavailableError distinct Error;
+public type CircuitBreakerOpenError distinct ServiceUnavailableError;
 ```
 
 All specific error types are subtypes of the base `Error` type, allowing for both specific and general error handling:
@@ -237,6 +200,10 @@ All specific error types are subtypes of the base `Error` type, allowing for bot
 ftp:Client|ftp:Error result = new(config);
 if result is ftp:ConnectionError {
     // Handle connection failures specifically
+} else if result is ftp:CircuitBreakerOpenError {
+    // Circuit breaker is open - implement fallback logic
+} else if result is ftp:AllRetryAttemptsFailedError {
+    // All retries exhausted - consider alerting
 } else if result is ftp:ServiceUnavailableError {
     // Transient error - retry the operation
 } else if result is ftp:Error {
@@ -284,6 +251,8 @@ public type ClientConfiguration record {|
     boolean laxDataBinding = false;
     # Retry configuration for read operations
     RetryConfig retryConfig?;
+    # Circuit breaker configuration to prevent cascade failures
+    CircuitBreakerConfig circuitBreaker?;
 |};
 ```
 * InputContent record represents the configurations for the input given for `put` and `append` operations.
@@ -319,8 +288,84 @@ public enum FileWriteOption {
     APPEND
 }
 ```
-### 3.2. Initialization
-#### 3.2.1. Insecure Client
+### 3.2. Circuit Breaker
+The circuit breaker pattern prevents cascade failures by temporarily blocking requests to an FTP server experiencing issues. When failures reach a threshold, the circuit "opens" and subsequent requests fail fast with `CircuitBreakerOpenError` without attempting the actual operation.
+
+#### State Machine
+The circuit breaker operates in three states:
+- **CLOSED**: Normal operation. Requests are allowed and failures are tracked.
+- **OPEN**: Circuit is tripped. All requests are rejected immediately with `CircuitBreakerOpenError`.
+- **HALF_OPEN**: After the reset time elapses, one trial request is allowed. Success returns to CLOSED; failure returns to OPEN.
+
+#### Configuration
+* CircuitBreakerConfig record contains the circuit breaker settings.
+```ballerina
+public type CircuitBreakerConfig record {|
+    # Rolling window configuration for failure tracking
+    RollingWindow rollingWindow = {};
+    # Failure ratio threshold (0.0 to 1.0) that trips the circuit
+    float failureThreshold = 0.5;
+    # Time in seconds to wait before transitioning from OPEN to HALF_OPEN
+    decimal resetTime = 30;
+    # Categories of failures that count towards tripping the circuit
+    FailureCategory[] failureCategories = [CONNECTION_ERROR, TRANSIENT_ERROR];
+|};
+```
+* RollingWindow record configures the sliding window for tracking failures.
+```ballerina
+public type RollingWindow record {|
+    # Minimum number of requests in the window before the circuit can trip
+    int requestVolumeThreshold = 10;
+    # Time window in seconds for tracking failures
+    decimal timeWindow = 60;
+    # Size of each time bucket in seconds (timeWindow / bucketSize = number of buckets)
+    decimal bucketSize = 10;
+|};
+```
+* FailureCategory enum specifies which types of failures count towards tripping the circuit.
+```ballerina
+public enum FailureCategory {
+    # Connection failures (network issues, timeouts)
+    CONNECTION_ERROR,
+    # Authentication failures (invalid credentials)
+    AUTHENTICATION_ERROR,
+    # Server disconnection during operation
+    TRANSIENT_ERROR,
+    # All errors count as failures
+    ALL_ERRORS
+}
+```
+#### Usage Example
+```ballerina
+ftp:ClientConfiguration ftpConfig = {
+    protocol: ftp:FTP,
+    host: "ftp.example.com",
+    port: 21,
+    auth: {
+        credentials: {username: "user", password: "pass"}
+    },
+    circuitBreaker: {
+        failureThreshold: 0.5,
+        resetTime: 30,
+        rollingWindow: {
+            requestVolumeThreshold: 5,
+            timeWindow: 60,
+            bucketSize: 10
+        },
+        failureCategories: [ftp:CONNECTION_ERROR, ftp:TRANSIENT_ERROR]
+    }
+};
+
+ftp:Client ftpClient = check new(ftpConfig);
+
+// Operations will fail fast with CircuitBreakerOpenError when circuit is open
+byte[]|ftp:Error content = ftpClient->getBytes("/file.txt");
+if content is ftp:CircuitBreakerOpenError {
+    // Handle circuit breaker open state - server is unavailable
+}
+```
+### 3.3. Initialization
+#### 3.3.1. Insecure Client
 A simple insecure client can be initialized by providing `ftp:FTP` as the protocol and the host and optionally, the port 
 to the `ftp:ClientConfiguration`.
 ```ballerina
@@ -330,7 +375,7 @@ to the `ftp:ClientConfiguration`.
 # + return - `ftp:Error` in case of errors or `()` otherwise
 public isolated function init(ClientConfiguration clientConfig) returns Error?;
 ```
-#### 3.2.2. Secure Client
+#### 3.3.2. Secure Client
 A secure client can be initialized by providing `ftp:SFTP` as the protocol and by providing `ftp:Credentials`
 and `ftp:PrivateKey` to `ftp:AuthConfiguration`.
 ```ballerina
@@ -347,7 +392,7 @@ ftp:ClientConfiguration ftpConfig = {
     userDirIsRoot: true
 };
 ```
-#### 3.2.3. Client with Retry Configuration
+#### 3.3.3. Client with Retry Configuration
 A client can be initialized with retry configuration to automatically retry failed read operations:
 ```ballerina
 ftp:ClientConfiguration ftpConfig = {
@@ -367,7 +412,7 @@ ftp:Client ftpClient = check new(ftpConfig);
 // All read operations will automatically retry on failure
 byte[] bytes = check ftpClient->getBytes("/path/to/file.txt");
 ```
-### 3.3. Functions
+### 3.4. Functions
 * FTP Client API can be used to put files on the FTP server. For this, the `put()` method can be used.
 ```ballerina
 # Adds a file to FTP server.