### 'start()

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/listener.md

Starts the FTP listener and begins monitoring for file changes.

```APIDOC
## 'start()

### Description
Starts the FTP listener and begins monitoring for file changes.

### Returns
- **error?** - () on success or error on failure

### Example
```ballerina
check listener.'start();
```
```

--------------------------------

### Run RabbitMQ Docker Container

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/examples/covid19-stat-publisher/An example on file handling using Ballerina FTP.md

Starts a RabbitMQ server using a Docker image. This is necessary for the example to publish messages to a queue.

```shell
sudo docker run -it --rm --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3.9-management
```

--------------------------------

### Start FTP Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/listener.md

Initiates the monitoring process for file changes on the configured FTP server.

```ballerina
check listener.'start();
```

--------------------------------

### Run SFTP Server

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/examples/covid19-stat-publisher/An example on file handling using Ballerina FTP.md

Executes the Ballerina FTP server project to start the SFTP server. This server will be monitored by the FTP listener.

```shell
./gradlew run
```

--------------------------------

### Configure and handle FTP Circuit Breaker

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/errors.md

Example showing client configuration with circuit breaker settings and error handling for CircuitBreakerOpenError.

```ballerina
ftp:ClientConfiguration config = {
    protocol: ftp:FTP,
    host: "ftp.example.com",
    port: 21,
    circuitBreaker: {
        failureThreshold: 0.5,
        resetTime: 30,
        rollingWindow: {
            requestVolumeThreshold: 10,
            timeWindow: 60,
            bucketSize: 10
        },
        failureCategories: [ftp:CONNECTION_ERROR, ftp:TRANSIENT_ERROR]
    }
};

ftp:Client client = check new(config);

do {
    byte[] content = check client->getBytes("/file.txt");
} on fail ftp:CircuitBreakerOpenError as err {
    io:println("Circuit breaker is open, server unavailable: " + err.message());
    // Implement fallback logic
}
```

--------------------------------

### Start the Processor

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/examples/covid19-stat-publisher/An example on file handling using Ballerina FTP.md

Runs the Ballerina application that acts as the FTP listener and message processor. It initializes the file listening and processing job.

```shell
$ bal run
```

--------------------------------

### Handle AllRetryAttemptsFailedError

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/errors.md

Example of configuring retry settings and catching AllRetryAttemptsFailedError after exhaustion.

```ballerina
ftp:ClientConfiguration config = {
    protocol: ftp:FTP,
    host: "ftp.example.com",
    port: 21,
    auth: { credentials: { username: "user", password: "pass" } },
    retryConfig: {
        count: 3,
        interval: 1.0,
        backOffFactor: 2.0,
        maxWaitInterval: 30.0
    }
};

ftp:Client client = check new(config);

do {
    byte[] content = check client->getBytes("/file.txt");
} on fail ftp:AllRetryAttemptsFailedError as err {
    io:println("Failed after 3 retry attempts: " + err.message());
}
```

--------------------------------

### FTP Listener with Distributed Coordination Configuration

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Configure an FTP listener for distributed coordination by providing a CoordinationConfig. Ensure all instances share the same coordinationGroup name and have unique memberIds. This setup requires a shared database for state management.

```ballerina
listener ftp:Listener ftpListener = check new ({
    protocol: ftp:SFTP,
    host: "sftp.example.com",
    port: 22,
    auth: {credentials: {username: "user", password: "pass"}},
    coordination: {
        memberId: "node-1",
        coordinationGroup: "ftp-processors",
        livenessCheckInterval: 30,
        heartbeatFrequency: 1,
        databaseConfig: <task:MysqlConfig>{
            host: "db.example.com",
            user: "dbuser",
            password: "dbpass",
            database: "coordination_db"
        }
    }
});
```

--------------------------------

### onFileChange with ftp:Caller

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/proposals/caller-param-in-onfilechange.md

Example of an `onFileChange` implementation that accepts `ftp:Caller` as the first argument, allowing direct use of FTP client APIs.

```ballerina
ftp:Service ftpService = service object {
    remote function onFileChange(ftp:Caller caller, ftp:WatchEvent & readonly event) {
        // process event
    }
};
```

--------------------------------

### onFileChange without ftp:Caller

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/proposals/caller-param-in-onfilechange.md

Example of a traditional `onFileChange` implementation that does not accept `ftp:Caller`, requiring manual `ftp:Client` creation for operations.

```ballerina
ftp:Service ftpService = service object {
    remote function onFileChange(ftp:WatchEvent & readonly event) {
        // process event
    }
};
```

--------------------------------

### Move File on Success or Failure

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

This example shows how to move files to different directories based on processing outcome. Successful processing moves the file to a success archive, while errors move it to a failed archive. It uses `afterProcess: {moveTo: ...}` and `afterError: {moveTo: ...}`.

```ballerina
service on ftpListener {
    @ftp:FunctionConfig {
        afterProcess: {moveTo: "/archive/success/"},
        afterError: {moveTo: "/archive/failed/"}
    }
    remote function onFileXml(xml content, ftp:FileInfo fileInfo) returns error? {
        check processXml(content);
    }
}
```

--------------------------------

### init(ClientConfiguration clientConfig)

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/client.md

Initializes an FTP client instance with the provided configuration settings.

```APIDOC
## init(ClientConfiguration clientConfig)

### Description
Initializes an FTP client with the provided configuration.

### Signature
`public isolated function init(ClientConfiguration clientConfig) returns Error?`

### Parameters
- **clientConfig** (ClientConfiguration) - Required - Configuration for the FTP client connection

### Returns
- **Error?** - Returns () on success or ftp:Error on failure

### Example
```ballerina
ftp:ClientConfiguration config = {
    protocol: ftp:FTP,
    host: "ftp.example.com",
    port: 21,
    auth: {
        credentials: {
            username: "user",
            password: "pass"
        }
    }
};
ftp:Client|ftp:Error client = new(config);
```
```

--------------------------------

### Get file size

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/caller.md

Retrieves the size of a file in bytes.

```ballerina
remote isolated function size(string path) returns int|Error
```

--------------------------------

### Initialize FTP Client Configuration

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Demonstrates a comprehensive configuration for an SFTP client, including authentication, socket timeouts, and resilience policies.

```ballerina
ftp:ClientConfiguration config = {
    protocol: ftp:SFTP,
    host: "sftp.example.com",
    port: 22,
    connectTimeout: 30.0,
    auth: {
        credentials: {
            username: "user",
            password: "pass"
        },
        privateKey: {
            path: "/home/user/.ssh/id_rsa",
            password: "key_passphrase"
        },
        preferredMethods: [ftp:PUBLICKEY, ftp:PASSWORD]
    },
    fileTransferMode: ftp:BINARY,
    sftpCompression: [ftp:ZLIB],
    sftpSshKnownHosts: "/home/user/.ssh/known_hosts",
    userDirIsRoot: true,
    laxDataBinding: false,
    socketConfig: {
        ftpDataTimeout: 120.0,
        ftpSocketTimeout: 60.0,
        sftpSessionTimeout: 300.0
    },
    csvFailSafe: {
        contentType: ftp:RAW_AND_METADATA
    },
    retryConfig: {
        count: 3,
        interval: 1.0,
        backOffFactor: 2.0,
        maxWaitInterval: 30.0
    },
    circuitBreaker: {
        failureThreshold: 0.5,
        resetTime: 30,
        rollingWindow: {
            requestVolumeThreshold: 10,
            timeWindow: 60,
            bucketSize: 10
        },
        failureCategories: [ftp:CONNECTION_ERROR, ftp:TRANSIENT_ERROR]
    }
};
```

--------------------------------

### Handle ServiceUnavailableError

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/errors.md

Example of catching a ServiceUnavailableError during an FTP delete operation.

```ballerina
do {
    check client->delete("/file.txt");
} on fail ftp:ServiceUnavailableError as err {
    io:println("Server temporarily unavailable, may retry: " + err.message());
}
```

--------------------------------

### init(*ListenerConfiguration listenerConfig)

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/listener.md

Initializes an FTP listener with the provided configuration.

```APIDOC
## init(*ListenerConfiguration listenerConfig)

### Description
Initializes an FTP listener with the provided configuration.

### Parameters
- **listenerConfig** (*ListenerConfiguration) - Required - Configuration for the FTP listener

### Returns
- **Error?** - Returns () on success or ftp:Error on failure

### Example
```ballerina
listener ftp:Listener ftpListener = check new ({
    protocol: ftp:FTP,
    host: "ftp.example.com",
    port: 21,
    auth: {
        credentials: {
            username: "user",
            password: "pass"
        }
    }
});
```
```

--------------------------------

### Create FTP Client with Basic Auth

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Creates an FTP client configuration and initializes the client using Basic Authentication. Ensure to replace placeholders with your actual FTP host, port, username, and password.

```ballerina
// Define the FTP client configuration.
ftp:ClientConfiguration ftpConfig = {
    protocol: ftp:FTP,
    host: "<The FTP host>",
    port: <The FTP port>,
    auth: {
        credentials: {
            username: "<The FTP username>",
            password: "<The FTP passowrd>"
        }
    }
};

// Create the FTP client.
ftp:Client|ftp:Error ftpClient = new(ftpConfig);
```

--------------------------------

### Initialize SFTP Client with Credentials

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Initializes a secure SFTP client using the SFTP protocol, host, port, and user credentials. The user directory is set as the root.

```ballerina
ftp:Client sftpClient = check new ({
    protocol: ftp:SFTP,
    host: "sftp.example.com",
    port: 22,
    auth: {
        credentials: {
            username: "user",
            password: "pass"
        }
    },
    userDirIsRoot: true
});
```

--------------------------------

### Handle ContentBindingError

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/errors.md

Example of catching a ContentBindingError when JSON parsing fails during a getJson operation.

```ballerina
do {
    type User record {
        string name;
        int age;
    };
    User user = check client->getJson("/user.json");  // JSON parsing fails
} on fail ftp:ContentBindingError as err {
    io:println("Content binding error: " + err.message());
    if err.detail().filePath is string {
        io:println("File: " + err.detail().filePath);
    }
}
```

--------------------------------

### Configuring an FTP Client

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/README.md

Defines the client configuration and initializes an FTP client instance.

```ballerina
ftp:ClientConfiguration config = {
    protocol: ftp:FTP,
    host: "ftp.example.com",
    port: 21,
    auth: {
        credentials: {
            username: "user",
            password: "pass"
        }
    }
};
ftp:Client client = check new(config);
```

--------------------------------

### Get Remote File Size

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/README.md

Retrieves the size of a specified file on a remote FTP server.

```ballerina
int|ftp:Error sizeResponse = ftpClient->size("<The resource path>");

```

--------------------------------

### Create FTP Client with Basic Auth

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/README.md

Creates an FTP client instance configured for basic authentication. Ensure the host, port, username, and password are provided.

```ballerina
import ballerina/ftp;
import ballerina/io;

// Define the FTP client configuration.
ftp:ClientConfiguration ftpConfig = {
    protocol: ftp:FTP,
    host: "<The FTP host>",
    port: <The FTP port>,
    auth: {
        credentials: {
            username: "<The FTP username>",
            password: "<The FTP passowrd>"
        }
    }
};

// Create the FTP client.
ftp:Client|ftp:Error ftpClient = new(ftpConfig);
```

--------------------------------

### Get file size with Ballerina FTP client

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/client.md

Retrieves the size of a file in bytes from the specified path.

```ballerina
int fileSize = check client->size("/remote/file.bin");
```

--------------------------------

### Configure SFTP Listener with Password and Private Key Authentication

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Set up an SFTP listener with support for both username/password and private key authentication. Includes host, port, path, polling interval, and file name pattern.

```ballerina
listener ftp:Listener remoteServer = check new({
    protocol: ftp:SFTP,
    host: "<The SFTP host>",
    port: <The SFTP port>,
    path: "<The remote SFTP directory location>",
    pollingInterval: <Polling interval>,
    fileNamePattern: "<File name pattern>",
    auth: {
        credentials: {username: "<The SFTP username>", password: "<The SFTP password>"},
        privateKey: {
            path: "<The private key file path>",
            password: "<The private key file password>"
        }
    }
});
```

--------------------------------

### Handle ContentBindingError in Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/errors.md

Example of handling ContentBindingError within a service listener's onError function.

```ballerina
service on listener {
    remote function onFileJson(User content, ftp:FileInfo fileInfo) returns error? {
        // Automatically invoked for .json files
        io:println("User: " + content.name);
    }
    
    remote function onError(error err, ftp:FileInfo? fileInfo) returns error? {
        // Called if onFileJson binding fails
        if err is ftp:ContentBindingError {
            io:println("Failed to parse JSON: " + err.message());
        }
    }
}
```

--------------------------------

### Get Remote File Size

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Retrieves the size of a specified file on the remote FTP server. The size is returned in bytes.

```ballerina
int|ftp:Error sizeResponse = ftpClient->size("<The resource path>");
```

--------------------------------

### Initialize SFTP Client with Private Key

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Initializes a secure SFTP client using a private key for authentication. Specifies the private key path, passphrase, and preferred authentication method.

```ballerina
ftp:Client sftpClient = check new ({
    protocol: ftp:SFTP,
    host: "sftp.example.com",
    port: 22,
    auth: {
        credentials: {username: "user"},
        privateKey: {
            path: "/path/to/private.key",
            password: "keypassphrase"
        },
        preferredMethods: [ftp:PUBLICKEY]
    },
    userDirIsRoot: true
});
```

--------------------------------

### Initialize FTP Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/listener.md

Initializes a new FTP listener instance with specific protocol, host, port, and authentication credentials.

```ballerina
listener ftp:Listener ftpListener = check new ({
    protocol: ftp:FTP,
    host: "ftp.example.com",
    port: 21,
    auth: {
        credentials: {
            username: "user",
            password: "pass"
        }
    }
});
```

--------------------------------

### Setting up an FTP Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/README.md

Configures a listener service to process files based on filename patterns.

```ballerina
listener ftp:Listener ftpListener = check new ({
    protocol: ftp:FTP,
    host: "ftp.example.com",
    port: 21,
    auth: { credentials: { username: "user", password: "pass" } }
});

service on ftpListener {
    @ftp:FunctionConfig { fileNamePattern: "(.*)\\.txt" }
    remote function onFileText(string content, ftp:FileInfo fileInfo) returns error? {
        io:println("Received text file: " + fileInfo.name);
    }
    
    @ftp:FunctionConfig { fileNamePattern: "(.*)\\.json" }
    remote function onFileJson(json content, ftp:FileInfo fileInfo) returns error? {
        io:println("Received JSON file: " + fileInfo.name);
    }
}

check ftpListener.'start();
```

--------------------------------

### Initialize FTP Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Configures an SFTP listener with authentication, polling, resilience, and coordination settings.

```ballerina
listener ftp:Listener ftpListener = check new ({
    protocol: ftp:SFTP,
    host: "sftp.example.com",
    port: 22,
    pollingInterval: 30,
    connectTimeout: 30.0,
    auth: {
        credentials: {
            username: "user",
            password: "pass"
        }
    },
    fileTransferMode: ftp:BINARY,
    sftpCompression: [ftp:ZLIB],
    userDirIsRoot: true,
    laxDataBinding: false,
    socketConfig: {
        sftpSessionTimeout: 300.0
    },
    csvFailSafe: {
        contentType: ftp:METADATA
    },
    retryConfig: {
        count: 3,
        interval: 1.0,
        backOffFactor: 2.0
    },
    coordination: {
        memberId: "node-1",
        coordinationGroup: "ftp-listeners",
        livenessCheckInterval: 30,
        heartbeatFrequency: 1
    }
});
```

--------------------------------

### Build Ballerina FTP Library

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/README.md

Execute this command to clean and build the Ballerina FTP library from source.

```bash
./gradlew clean build
```

--------------------------------

### FTP Client with Circuit Breaker Configuration

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Configures an FTP client with a circuit breaker to prevent cascading failures. This setup defines thresholds and timings for tripping the circuit breaker when the server becomes unavailable.

```ballerina
ftp:Client ftpClient = check new ({
    protocol: ftp:FTP,
    host: "ftp.example.com",
    circuitBreaker: {
        failureThreshold: 0.5,
        resetTime: 30,
        rollingWindow: {
            requestVolumeThreshold: 5,
            timeWindow: 60,
            bucketSize: 10
        },
        failureCategories: [ftp:CONNECTION_ERROR, ftp:TRANSIENT_ERROR]
    }
});
```

--------------------------------

### Configure FTP Client for Development

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Use this configuration for development environments with short timeouts and basic retry settings.

```ballerina
// Short timeouts, retry enabled, CSV fail-safe
ftp:ClientConfiguration devConfig = {
    protocol: ftp:FTP,
    host: "ftp.dev.example.com",
    connectTimeout: 10.0,
    retryConfig: { count: 1, interval: 0.5 },
    csvFailSafe: { contentType: ftp:RAW_AND_METADATA }
};
```

--------------------------------

### Create Directory

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/caller.md

Creates a new directory at the specified path.

```ballerina
remote isolated function mkdir(string path) returns Error?
```

--------------------------------

### Process CSV Only When Marker File Exists

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

This example demonstrates conditional file processing using `fileDependencyConditions`. It configures the service to process CSV files only if a corresponding '.marker' file exists in the same directory. It uses `targetPattern` and `requiredFiles` with `matchingMode: ftp:ALL`.

```ballerina
@ftp:ServiceConfig {
    path: "/incoming/orders",
    fileNamePattern: "order_.*\\.csv",
    fileDependencyConditions: [
        {
            targetPattern: "order_(\d+)\\.csv",
            requiredFiles: ["order_$1.marker"],
            matchingMode: ftp:ALL
        }
    ]
}
service on ftpListener {
    remote function onFileCsv(record {}[] content, ftp:FileInfo fileInfo, ftp:Caller caller) returns error? {
        check caller->move(fileInfo.path, "/processed/" + fileInfo.name);
    }
}
```

--------------------------------

### Create directory with mkdir

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/client.md

Creates a new directory at the specified path on the FTP server.

```ballerina
remote isolated function mkdir(string path) returns Error?
```

```ballerina
check client->mkdir("/remote/newdir");
```

--------------------------------

### Configure Basic Username/Password Authentication

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/README.md

Use this configuration for standard FTP or SFTP connections requiring simple credentials.

```ballerina
auth: {
    credentials: { username: "user", password: "pass" }
}
```

--------------------------------

### Initialize Insecure FTP Client

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Initializes an insecure FTP client by specifying the FTP protocol, host, and port.

```ballerina
ftp:Client ftpClient = check new ({
    protocol: ftp:FTP,
    host: "ftp.example.com",
    port: 21
});
```

--------------------------------

### Configure FTPS Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Set up an FTPS listener to monitor a secure directory. Requires authentication credentials and truststore configuration for secure connections.

```ballerina
listener ftp:Listener ftpsListener = check new({
    protocol: ftp:FTPS,
    host: "ftps.example.com",
    port: 990,
    path: "/upload",
    pollingInterval: 5,
    auth: {
        credentials: { username: "user", password: "password" },
        secureSocket: {
            cert: { path: "/path/to/truststore.jks", password: "password" },
            mode: ftp:IMPLICIT
        }
    }
});
```

--------------------------------

### List Files in a Directory

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Lists files in a specified directory and prints their names and sizes. Requires the ftp:FileInfo type and io:println for output.

```ballerina
ftp:FileInfo[] files = check ftpClient->list("/incoming");
foreach ftp:FileInfo file in files {
    io:println(file.name + " (" + file.size.toString() + " bytes)");
}
```

--------------------------------

### Handle Binary Files with FTP Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Configure an FTP listener to process binary files. The `onFile` method receives the file content as a byte array and file information.

```ballerina
service on remoteServer {
    // Handle as byte array
    remote function onFile(byte[] content, ftp:FileInfo fileInfo) returns error? {
        log:print("Binary file: " + fileInfo.path);
        log:print("File size: " + content.length().toString());
    }
}
```

--------------------------------

### mkdir(string path)

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/caller.md

Creates a new directory at the specified path.

```APIDOC
## remote isolated function mkdir(string path)

### Description
Creates a new directory.

### Parameters
- **path** (string) - Required - The directory path to create

### Return
- **Error?** - () on success or ftp:Error
```

--------------------------------

### Configure FTPS Client

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Set up an FTPS client configuration, specifying the protocol, host, port, and secure socket details including keystore, truststore, and connection mode (Explicit/Implicit).

```ballerina
ftp:ClientConfiguration ftpsConfig = {
    protocol: ftp:FTPS,
    host: "ftps.example.com",
    port: 21, // 21 for EXPLICIT, 990 for IMPLICIT
    auth: {
        credentials: { username: "user", password: "password" },
        secureSocket: {
            key: {
                path: "/path/to/keystore.p12",
                password: "keystore-password"
            },
            cert: {
                path: "/path/to/truststore.p12",
                password: "truststore-password"
            },
            mode: ftp:EXPLICIT, // or ftp:IMPLICIT
            dataChannelProtection: ftp:PRIVATE // PROT P (Encrypted data channel)
        }
    }
};

ftp:Client ftpsClient = check new(ftpsConfig);
```

--------------------------------

### Configure FTP Client for Production

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Use this configuration for production environments requiring robust retry logic, circuit breakers, and extended timeouts.

```ballerina
// Longer timeouts, robust retry, circuit breaker
ftp:ClientConfiguration prodConfig = {
    protocol: ftp:SFTP,
    host: "sftp.prod.example.com",
    connectTimeout: 30.0,
    retryConfig: {
        count: 5,
        interval: 1.0,
        backOffFactor: 2.0,
        maxWaitInterval: 60.0
    },
    circuitBreaker: {
        failureThreshold: 0.3,
        resetTime: 60,
        rollingWindow: {
            requestVolumeThreshold: 20,
            timeWindow: 120
        }
    },
    socketConfig: {
        sftpSessionTimeout: 600.0
    }
};
```

--------------------------------

### Initialize Secure SFTP Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Initializes a secure SFTP listener with authentication credentials and private key configuration. The user directory is set as the root.

```ballerina
listener ftp:Listener ftpListener = check new ({
    protocol: ftp:SFTP,
    host: "sftp.example.com",
    port: 22,
    auth: {
        credentials: {
            username: "user",
            password: "pass"
        },
        privateKey: {
            path: "/path/to/private.key",
            password: "keypassphrase"
        }
    },
    pollingInterval: 60,
    userDirIsRoot: true
});
```

--------------------------------

### Build Library Without Tests

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/README.md

Execute this command to build the Ballerina FTP library, excluding the test execution.

```bash
./gradlew clean build -x test
```

--------------------------------

### list(string path)

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/caller.md

Lists files and directories in a specified folder.

```APIDOC
## list(string path)

### Description
Lists files and directories in a folder.

### Signature
`remote isolated function list(string path) returns FileInfo[]|Error`

### Parameters
- **path** (string) - Required - The directory path to list

### Return
- **FileInfo[]|Error** - Array of file information or ftp:Error
```

--------------------------------

### Initialize Insecure FTP Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Initializes an insecure FTP listener. The monitored directory is configured at the service level.

```ballerina
listener ftp:Listener ftpListener = check new ({
    protocol: ftp:FTP,
    host: "ftp.example.com",
    port: 21,
    pollingInterval: 30
});
```

--------------------------------

### Configure FTPS with Certificate Authentication

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/README.md

Use this configuration for secure FTPS connections requiring truststore certificates and explicit data channel protection.

```ballerina
auth: {
    credentials: { username: "user", password: "pass" },
    secureSocket: {
        cert: "/path/to/truststore.p12",
        mode: ftp:EXPLICIT,
        dataChannelProtection: ftp:PRIVATE
    }
}
```

--------------------------------

### Configure SFTP Compression

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/README.md

Enable ZLIB compression for SFTP operations.

```ballerina
sftpCompression: [ftp:ZLIB]
```

--------------------------------

### Initialize FTP Caller

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/caller.md

Initializes the caller with an existing FTP client instance.

```ballerina
isolated function init(Client 'client)
```

--------------------------------

### Debug Library Implementation

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/README.md

Use this command to build the Ballerina FTP library with debugging enabled for the Java implementation, specifying the debug port.

```bash
./gradlew clean build -Pdebug=<port>
```

--------------------------------

### Listener File Events by Type (PromQL)

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Derives counts for listener file events, filtered by event type. Use this to monitor file creation events.

```promql
# Listener file events by type
rate(requests_total_value{action_type="event", event_type="create"}[1m])
```

--------------------------------

### Handle Text Files with FTP Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Configure an FTP listener to process text files. The `onFileText` method receives file content as a string and file information.

```ballerina
service on remoteServer {
    remote function onFileText(string content, ftp:FileInfo fileInfo) returns error? {
        log:print("Text file: " + fileInfo.path);
        log:print("Content: " + content);
    }
}
```

--------------------------------

### Run Ballerina FTP Tests

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/README.md

Execute this command to clean and run all tests for the Ballerina FTP library.

```bash
./gradlew clean test
```

--------------------------------

### caller->mkdir(string path)

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/caller.md

Creates a new directory at the specified remote path.

```APIDOC
## caller->mkdir(string path)

### Description
Creates a new directory at the specified remote path.

### Parameters
- **path** (string) - Required - The remote path where the directory should be created.

### Returns
- **error?** - Returns an error if the operation fails.
```

--------------------------------

### register(Service ftpService, string? name)

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/listener.md

Registers an FTP service with the listener to begin processing files.

```APIDOC
## register(Service ftpService, string? name)

### Description
Registers an FTP service with the listener.

### Signature
`public isolated function register(Service ftpService, string? name) returns error?`

### Parameters
- **ftpService** (Service) - Required - The FTP service to register.
- **name** (string?) - Optional - Optional service name.

### Returns
- `error?` - `()` on success or error on failure.

### Example
```ballerina
check listener.register(ftpService);
```
```

--------------------------------

### Publish to Local Ballerina Central

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/README.md

Run this command to publish the generated artifacts to the local Ballerina central repository.

```bash
./gradlew clean build -PpublishToLocalCentral=true
```

--------------------------------

### Debug with Ballerina Language

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/README.md

Execute this command to build the Ballerina FTP library with debugging enabled for the Ballerina language, specifying the debug port.

```bash
./gradlew clean build -PbalJavaDebug=<port>
```

--------------------------------

### Initialize Secure FTPS Client

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Initializes a secure FTPS client with credentials and custom SSL/TLS configurations, including a truststore and explicit connection mode.

```ballerina
ftp:Client ftpsClient = check new ({
    protocol: ftp:FTPS,
    host: "ftps.example.com",
    port: 21,
    auth: {
        credentials: {username: "user", password: "pass"},
        secureSocket: {
            cert: {path: "/path/to/truststore.p12", password: "changeit"},
            mode: ftp:EXPLICIT
        }
    }
});
```

--------------------------------

### All FTP Activity on a Specific Node (PromQL)

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Calculates the rate of all FTP activity on a specific node over a 1-minute window, filtering by host and Ballerina FTP module. Use this for overall FTP traffic monitoring on a given node.

```promql
# All FTP activity on a specific node
rate(requests_total_value{host="node-1", src_module=~"ballerina/ftp.*"}[1m])
```

--------------------------------

### Route File by Name Pattern with Post-Processing

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

This snippet illustrates routing files based on a specific name pattern and performing a post-processing move action. It utilizes `fileNamePattern` to match files like 'order_*.csv' and moves them to '/processed/'.

```ballerina
service on ftpListener {
    @ftp:FunctionConfig {
        fileNamePattern: "order_.*\\.csv",
        afterProcess: {moveTo: "/processed/"}
    }
    remote function onFileCsv(Employee[] content, ftp:FileInfo fileInfo) returns error? {
        saveEmployees(content);
    }
}
```

--------------------------------

### Configure Combined Authentication for SFTP

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/README.md

Use this configuration to provide multiple authentication methods with a defined preference order.

```ballerina
auth: {
    credentials: { username: "user", password: "pass" },
    privateKey: { path: "/home/user/.ssh/id_rsa" },
    preferredMethods: [ftp:PUBLICKEY, ftp:PASSWORD]
}
```

--------------------------------

### List directory contents

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/caller.md

Returns an array of file information for the specified directory path.

```ballerina
remote isolated function list(string path) returns FileInfo[]|Error
```

--------------------------------

### Configure Retry Logic and Fallback

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/errors.md

Configure retry parameters in the FTP client and handle AllRetryAttemptsFailedError to implement fallback logic.

```ballerina
ftp:Client client = check new({
    protocol: ftp:FTP,
    host: "ftp.example.com",
    port: 21,
    retryConfig: {
        count: 3,
        interval: 1.0,
        backOffFactor: 2.0
    }
});

do {
    byte[] content = check client->getBytes("/file.txt");
} on fail ftp:AllRetryAttemptsFailedError as err {
    io:println("Retries exhausted, using local cache");
    // Fallback to local file
} on fail ftp:ConnectionError as err {
    io:println("Connection error, cannot retry");
}
```

--------------------------------

### Importing the FTP Module

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/INDEX.md

Required import statement to access FTP client and listener functionality.

```ballerina
import ballerina/ftp;
```

--------------------------------

### Configure SFTP Proxy Settings

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Define proxy configurations for SFTP connections, supporting both HTTP proxies and SSH jump-hosts.

```ballerina
proxy: {
    host: "proxy.example.com",
    port: 3128,
    'type: ftp:HTTP,
    auth: {
        username: "proxyuser",
        password: "proxypass"
    }
}
```

```ballerina
proxy: {
    host: "jump.example.com",
    port: 22,
    'type: ftp:STREAM,
    command: "ssh -W %h:%p user@jump.example.com"
}
```

--------------------------------

### Implement onFile handler

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/listener.md

Handles files that do not match other specific patterns. Use byte array or stream for content processing.

```ballerina
service on listener {
    // Handle as byte array
    remote function onFile(byte[] content, ftp:FileInfo fileInfo) returns error? {
        io:println("Binary file: " + fileInfo.name);
        io:println("Size: " + content.length().toString());
    }
}
```

```ballerina
service on listener {
    // Stream large files
    remote function onFile(stream<byte[], error?> content, ftp:FileInfo fileInfo) returns error? {
        io:println("Streaming file: " + fileInfo.name);
        record {|byte[] value;|} nextBytes = check content.next();
        while nextBytes is record {|byte[] value;|} {
            // Process chunk
            nextBytes = check content.next();
        }
        check content.close();
    }
}
```

--------------------------------

### ftp:ListenerConfiguration

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

The configuration record used to initialize an ftp:Listener instance.

```APIDOC
## ftp:ListenerConfiguration

### Description
Configuration record for the `ftp:Listener` initialization, covering connection, authentication, and operational settings.

### Parameters

#### Protocol Settings
- **protocol** (Protocol) - Optional - Connection protocol: `FTP`, `FTPS`, or `SFTP` (Default: `FTP`)
- **host** (string) - Optional - Remote server hostname or IP address (Default: `"127.0.0.1"`)
- **port** (int) - Optional - Server port (Default: `21`)

#### Polling Settings
- **pollingInterval** (decimal) - Optional - Polling interval in seconds (Default: `60`)

#### Connection Settings
- **connectTimeout** (decimal) - Optional - Connection timeout in seconds (Default: `30.0`)
- **socketConfig** (SocketConfig?) - Optional - Socket timeout configurations
- **userDirIsRoot** (boolean) - Optional - Treat login home directory as root (Default: `false`)
- **fileTransferMode** (FileTransferMode) - Optional - `BINARY` or `ASCII` mode (Default: `BINARY`)

#### Authentication
- **auth** (AuthConfiguration?) - Optional - Authentication configuration

#### SFTP Settings
- **sftpCompression** (TransferCompression[]) - Optional - Compression algorithms (Default: `[NO]`)
- **sftpSshKnownHosts** (string?) - Optional - Path to SSH known_hosts file
- **proxy** (ProxyConfiguration?) - Optional - Proxy configuration

#### Resilience & Coordination
- **retryConfig** (RetryConfig?) - Optional - Automatic retry configuration
- **coordination** (CoordinationConfig?) - Optional - Distributed task coordination

### Usage Example
```ballerina
listener ftp:Listener ftpListener = check new ({
    protocol: ftp:SFTP,
    host: "sftp.example.com",
    port: 22,
    pollingInterval: 30,
    auth: {
        credentials: {
            username: "user",
            password: "pass"
        }
    }
});
```
```

--------------------------------

### SFTP Client Configuration with Password and Private Key Authentication

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Define SFTP client configuration supporting both password-based and private key-based authentication. Specify paths and passwords for credentials and private keys.

```ballerina
ftp:ClientConfiguration sftpConfig = {
    protocol: ftp:SFTP,
    host: "<The SFTP host>",
    port: <The SFTP port>,
    auth: {
        credentials: {username: "<The SFTP username>", password: "<The SFTP password>"},
        privateKey: {
            path: "<The private key file path>",
            password: "<The private key file password>"
        }
    }
};
```

--------------------------------

### Handle XML Files with FTP Listener

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Configure an FTP listener to process XML files, handling them as a typed record. The `onFileXml` method receives deserialized XML content and file information.

```ballerina
type Config record {
    string database;
    int timeout;
    boolean debug;
};

service on remoteServer {
    // Handle as typed record
    remote function onFileXml(Config content, ftp:FileInfo fileInfo) returns error? {
        log:print("Config file: " + fileInfo.path);
        log:print("Database: " + content.database);
    }
}
```

--------------------------------

### Configure FTPS with Certificate

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Use for secure FTPS connections requiring a truststore certificate and specific security modes.

```ballerina
auth: {
    credentials: {
        username: "user",
        password: "password"
    },
    secureSocket: {
        cert: "/path/to/truststore.p12",
        mode: ftp:EXPLICIT,
        dataChannelProtection: ftp:PRIVATE,
        verifyHostName: true
    }
}
```

--------------------------------

### Handle XML Files

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/listener.md

Implements the onFileXml remote function to process detected .xml files with schema binding.

```ballerina
type Config record {
    string database;
    int timeout;
    boolean debug;
};

service on listener {
    remote function onFileXml(Config content, ftp:FileInfo fileInfo) returns error? {
        io:println("Database: " + content.database);
    }
}
```

--------------------------------

### Publish to Ballerina Central

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/README.md

Execute this command to publish the generated artifacts to the main Ballerina central repository.

```bash
./gradlew clean build -PpublishToCentral=true
```

--------------------------------

### Configure FTP Listener for High-Volume Processing

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Use this configuration for high-volume scenarios involving SFTP compression and coordination groups.

```ballerina
listener ftp:Listener highVolumeListener = check new ({
    protocol: ftp:SFTP,
    pollingInterval: 10,  // Poll every 10 seconds
    sftpCompression: [ftp:ZLIB],
    csvFailSafe: { contentType: ftp:METADATA },
    coordination: {
        memberId: "worker-1",
        coordinationGroup: "batch-processing"
    }
});
```

--------------------------------

### Define File Dependencies

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/README.md

Ensures specific marker files exist before processing target files.

```ballerina
fileDependencyConditions: [
    {
        targetPattern: "(.*)\\.data",
        requiredFiles: ["$1.marker"]  // .data file must have .marker file
    }
]
```

--------------------------------

### FTP Client with Retry Configuration

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Initializes an FTP client with custom retry settings for read operations. This configuration helps in handling transient network issues by automatically retrying failed requests.

```ballerina
ftp:Client ftpClient = check new ({
    protocol: ftp:FTP,
    host: "ftp.example.com",
    retryConfig: {
        count: 5,
        interval: 2.0,
        backOffFactor: 1.5,
        maxWaitInterval: 20.0
    }
});
```

--------------------------------

### Upload File as Binary Stream

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/ballerina/README.md

Uploads a file to a remote FTP server by reading it as a stream of blocks. This is efficient for large files. Ensure the `putFilePath` and `<Block size>` are correctly defined.

```ballerina
stream<io:Block, io:Error?> fileByteStream
    = check io:fileReadBlocksAsStream(putFilePath, <Block size>);
ftp:Error? putResponse = ftpClient->put("<The resource path>", fileByteStream);
```

--------------------------------

### Define FTP Client Configuration

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/types.md

Use this record to configure the FTP client endpoint, including protocol, host, port, and various timeout or security settings.

```ballerina
public type ClientConfiguration record {|
    Protocol protocol = FTP;
    string host = "127.0.0.1";
    int port = 21;
    AuthConfiguration auth?;
    boolean userDirIsRoot = false;
    boolean laxDataBinding = false;
    decimal connectTimeout = 30.0;
    SocketConfig socketConfig?;
    ProxyConfiguration proxy?;
    FileTransferMode fileTransferMode = BINARY;
    TransferCompression[] sftpCompression = [NO];
    string sftpSshKnownHosts?;
    FailSafeOptions csvFailSafe?;
    RetryConfig retryConfig?;
    CircuitBreakerConfig circuitBreaker?;
|};
```

--------------------------------

### attach(Service ftpService, string[]|string? name)

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/listener.md

Attaches an FTP service to the listener.

```APIDOC
## attach(Service ftpService, string[]|string? name)

### Description
Attaches an FTP service to the listener.

### Parameters
- **ftpService** (Service) - Required - The FTP service to attach
- **name** (string[]|string?) - Optional - Optional service name

### Returns
- **error?** - () on success or error on failure

### Example
```ballerina
service ftpService = service {
    remote function onFile(byte[] content, ftp:FileInfo fileInfo) returns error? {
        // Handle binary file
    }
};

check listener.attach(ftpService);
```
```

--------------------------------

### Handle Text Files with onFileText

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Invoked when a .txt file is added. The file content is passed as a UTF-8 string.

```ballerina
remote function onFileText(string content, ftp:FileInfo fileInfo, ftp:Caller caller) returns error? {
    io:println("Processing: " + fileInfo.name);
    io:println(content);
}
```

--------------------------------

### Client File Operations by Type (PromQL)

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Derives counts for client file operations on SFTP, filtered by operation type and protocol. Use this to monitor specific client actions.

```promql
# Client file operations by type
rate(requests_total_value{action_type="operation", operation_type="admin", protocol="sftp"}[1m])
```

--------------------------------

### Check file existence

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/caller.md

Verifies if a file or directory exists at the specified path.

```ballerina
remote isolated function exists(string path) returns boolean|Error
```

--------------------------------

### Enable Observability Configuration

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Configuration settings for enabling metrics and tracing in the Ballerina runtime. Ensure these settings are present in your `Config.toml` file to activate observability.

```toml
[ballerina.observe]
metricsEnabled=true
metricsReporter="prometheus"
tracingEnabled=true
tracingProvider="jaeger"
```

--------------------------------

### Handle InvalidConfigError

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/errors.md

Catch configuration errors during client or listener initialization.

```ballerina
do {
    ftp:Client client = check new ({
        protocol: ftp:FTP,
        host: "ftp.example.com",
        port: 99999  // Invalid port
    });
} on fail ftp:InvalidConfigError as err {
    io:println("Invalid configuration: " + err.message());
}
```

--------------------------------

### Data Binding Configuration

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/docs/spec/spec.md

Explains how the `targetType` parameter in read methods supports data binding and the effect of the `laxDataBinding` client configuration.

```APIDOC
## Data Binding

### Description
The typed read methods (`getJson`, `getXml`, `getCsv`, `getCsvAsStream`) support data binding through the `targetType` parameter, which automatically binds parsed content to a specified Ballerina type. The `laxDataBinding` client configuration influences how structured data is bound, allowing for flexible handling of missing or null fields.

### Parameters
- **targetType** - Optional - The Ballerina type to bind the parsed content to.

### Configuration
- **laxDataBinding** (boolean) - Client configuration that controls strictness of data binding. `true` allows missing/null fields; `false` (default) enforces strict binding.

### Error Handling
- Returns `ContentBindingError` if parsing or binding fails.
```

--------------------------------

### Define FTP Listener Configuration

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/types.md

Use this record to configure the FTP listener endpoint, which includes polling intervals and coordination settings.

```ballerina
public type ListenerConfiguration record {|
    Protocol protocol = FTP;
    string host = "127.0.0.1";
    int port = 21;
    AuthConfiguration auth?;
    @deprecated string path = "/";
    @deprecated string fileNamePattern?;
    decimal pollingInterval = 60;
    boolean userDirIsRoot = false;
    @deprecated FileAgeFilter fileAgeFilter?;
    @deprecated FileDependencyCondition[] fileDependencyConditions = [];
    boolean laxDataBinding = false;
    decimal connectTimeout = 30.0;
    SocketConfig socketConfig?;
    ProxyConfiguration proxy?;
    FileTransferMode fileTransferMode = BINARY;
    TransferCompression[] sftpCompression = [NO];
    string sftpSshKnownHosts?;
    FailSafeOptions csvFailSafe?;
    CoordinationConfig coordination?;
    RetryConfig retryConfig?;
|};
```

--------------------------------

### Read File as Bytes

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/client.md

Retrieves the complete file content as a byte array.

```ballerina
remote isolated function getBytes(string path) returns byte[]|Error
```

```ballerina
byte[] content = check client->getBytes("/remote/file.bin");
```

--------------------------------

### Handle FileAlreadyExistsError

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/errors.md

Catch errors occurring when creating a resource that already exists.

```ballerina
do {
    check client->mkdir("/existing/dir");
} on fail ftp:FileAlreadyExistsError as err {
    io:println("Directory already exists: " + err.message());
}
```

--------------------------------

### Configure Distributed Coordination

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/README.md

Enable high-availability by configuring coordination parameters for listener deployments.

```ballerina
coordination: {
    memberId: "node-1",
    coordinationGroup: "ftp-listeners",
    databaseConfig: { /* MySQL config */ }
}
```

--------------------------------

### Configure File Dependency Conditions

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/configuration.md

Define patterns to process files only when specific related files are present. Use capture groups to map target files to their required counterparts.

```ballerina
fileDependencyConditions: [
    {
        targetPattern: "(.*)\\.data",      // Target pattern
        requiredFiles: ["$1.marker"],      // Capture group substitution
        matchingMode: ftp:ALL,             // All patterns must match
        requiredFileCount: 1               // For EXACT_COUNT mode
    }
]
```

--------------------------------

### move(string sourcePath, string destinationPath)

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/caller.md

Moves a file from the source path to the destination path.

```APIDOC
## remote isolated function move(string sourcePath, string destinationPath)

### Description
Moves a file to another location.

### Parameters
- **sourcePath** (string) - Required - The source file location
- **destinationPath** (string) - Required - The destination file location

### Return
- **Error?** - () on success or ftp:Error
```

--------------------------------

### Copy file with copy

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/client.md

Copies a file from one location to another on the FTP server.

```ballerina
remote isolated function copy(string sourcePath, string destinationPath) returns Error?
```

```ballerina
check client->copy("/remote/original.txt", "/remote/backup.txt");
```

--------------------------------

### copy(string sourcePath, string destinationPath)

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/caller.md

Copies a file from the source path to the destination path.

```APIDOC
## remote isolated function copy(string sourcePath, string destinationPath)

### Description
Copies a file to another location.

### Parameters
- **sourcePath** (string) - Required - The source file location
- **destinationPath** (string) - Required - The destination file location

### Return
- **Error?** - () on success or ftp:Error
```

--------------------------------

### Check if directory

Source: https://github.com/ballerina-platform/module-ballerina-ftp/blob/master/_autodocs/api-reference/caller.md

Determines if the resource at the given path is a directory.

```ballerina
remote isolated function isDirectory(string path) returns boolean|Error
```