Represents the set of protocols supported by the FTP listener and client.



SFTP

Protocol

Represents an FTP client that intracts with an FTP server


Gets invoked during object initialization.



init

clientConfig

ClientConfiguration

`ftp:Error` in case of errors or `()` otherwise


Error

Retrieves the file content from a remote resource.
```ballerina
stream<byte[] & readonly, io:Error?>|ftp:Error channel
  = client->get(path);
```



path

string

A byte stream from which the file can be read or `ftp:Error` in case of errors


Appends the content to an existing file in an FTP server.
```ballerina
ftp:Error? response = client->append(path, channel);
```



append

Content to be written to the file in server


content

`()` or else an `ftp:Error` if failed to establish
the communication with the FTP server


Adds a file to an FTP server.
```ballerina
ftp:Error? response = client->put(path, channel);
```



Type of the compression to be used, if
the file should be compressed before
uploading


compressionType

Compression

Creates a new direcotry in an FTP server.
```ballerina
ftp:Error? response = client->mkdir(path);
```



mkdir

Deletes an empty directory in an FTP server.
```ballerina
ftp:Error? response = client->rmdir(path);
```



rmdir

Renames a file or moves it to a new location within
the same FTP server.
```ballerina
ftp:Error? response = client->rename(origin, destination);
```



rename

origin

destination

Gets the size of a file resource.
```ballerina
int|ftp:Error response = client->size(path);
```



size

The file size in bytes or an `ftp:Error` if
failed to establish the communication with the FTP server


Gets the file name list in a given folder.
```ballerina
ftp:FileInfo[]|ftp:Error response = client->list(path);
```



list

An array of file names or an `ftp:Error` if failed to
establish the communication with the FTP server


Checks if a given resource is a direcotry.
```ballerina
boolean|ftp:Error response = client->isDirectory(path);
```



isDirectory

`true` if given resource is a direcotry or an `ftp:Error` if
an error occurred while checking the path


Deletes a file from an FTP server.
```ballerina
ftp:Error? response = client->delete(path);
```



delete

Client

## Overview

This module provides an FTP/SFTP client and an FTP/SFTP server listener implementation to facilitate an FTP/SFTP connection connected to a remote location.

### FTP Client

The `ftp:Client` connects to an FTP server and performs various operations on the files. Currently, it supports the
generic FTP operations; `get`, `delete`, `put`, `append`, `mkdir`, `rmdir`, `isDirectory`, `rename`, `size`, and
 `list`.

An FTP client is defined using the `protocol` and `host` parameters and optionally, the `port` and
`auth`. Authentication configuration can be configured using the `auth` parameter for Basic Auth and
private key.

An authentication-related configuration can be given to the FTP client with the `auth` configuration.

##### Creating a Client

The following code creates an FTP client and performs the I/O operations, which connect to the FTP server with Basic Auth.
```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);
```

##### Creating a Directory

The following code creates a directory in the remote FTP server.

```ballerina
ftp:Error? mkdirResponse = ftpClient->mkdir("<The directory path>");
```

##### Uploading File to a Remote Server

The following code uploads a file to a remote FTP server.

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

##### Compressing and Uploading a File to a Remote Server

The following code compresses and uploads a file to a remote FTP server.

```ballerina
// Set the optional boolean flag as 'true' to compress before uploading
stream<io:Block, io:Error?> fileByteStream
    = check io:fileReadBlocksAsStream(putFilePath, <Block size>);
ftp:Error? compressedPutResponse = ftpClient->put("<Resource path>",
    fileByteStream, compressionType=ZIP);
```

##### Getting the Size of a Remote File

The following code gets the size of a file in a remote FTP server.

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

##### Reading the Content of a Remote File

The following code reads the content of a file in a remote FTP server.

```ballerina
stream<byte[], io:Error?>|Error str = clientEP -> get("<The file path>");
if (str is stream<byte[], io:Error?>) {
    record {|byte[] value;|}|io:Error? arr1 = str.next();
    if (arr1 is record {|byte[] value;|}) {
        string fileContent = check strings:fromBytes(arr1.value);
        // `fileContent` is the `string` value of first byte array
        record {|byte[] value;|}|io:Error? arr2 = str.next();
        // Similarly following content chunks can be iteratively read with `next` method.
        // Final chunk will contain the terminal value which is `()`.
    }
    io:Error? closeResult = str.close();
}
```

##### Renaming or Moving a Remote file to Another Remote Location in the Same FTP Server

The following code renames or moves a file to another location in the same remote FTP server.

```ballerina
ftp:Error? renameResponse = ftpClient->rename("<The source file path>",
    "<The destination file path>");
```

##### Deleting a Remote File

The following code deletes a remote file in a remote FTP server.

```ballerina
ftp:Error? deleteResponse = ftpClient->delete("<The resource path>");
```

##### Removing a Directory From a Remote Server

The following code removes a directory in a remote FTP server.

```ballerina
ftp:Error? rmdirResponse = ftpClient->rmdir("<The directory path>");
```

### FTP Listener

The `ftp:Listener` is used to listen to a remote FTP location and trigger a `WatchEvent` type of event when new
files are added to or deleted from the directory. The `fileResource` function is invoked when a new file is added
and/or deleted.

An FTP listener is defined using the mandatory `protocol`, `host`, and  `path` parameters. The authentication
configuration can be done using the `auth` parameter and the polling interval can be configured using the `pollingInterval` parameter.
The default polling interval is 60 seconds.

The `fileNamePattern` parameter can be used to define the type of files the FTP listener will listen to.
For instance, if the listener gets invoked for text files, the value `(.*).txt` can be given for the config.

An authentication-related configuration can be given to the FTP listener with the `auth` configuration.

##### Creating a Listener

The FTP Listener can be used to listen to a remote directory. It will keep listening to the specified directory and
notify on file addition and deletion periodically.

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

service on remoteServer {
    remote function onFileChange(ftp:WatchEvent fileEvent) {

        foreach ftp:FileInfo addedFile in fileEvent.addedFiles {
            log:print("Added file path: " + addedFile.path);
        }
        foreach string deletedFile in fileEvent.deletedFiles {
            log:print("Deleted file path: " + deletedFile);
        }
    }
}
```

### Secure access with SFTP

SFTP is a secure protocol alternative to the FTP, which runs on top of the SSH protocol.
There are several ways to authenticate an SFTP server. One is using the username and the password.
Another way is using the client's private key. The Ballerina SFTP client and the listener support only those authentication standards.
An authentication-related configuration can be given to the SFTP client/listener with the `auth` configuration.
Password-based authentication is defined with the `credentials` configuration while the private key based authentication is defined with the `privateKey` configuration.

#### SFTP Client Configuration

```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>"
        }
    }
};
```

#### SFTP Listener Configuration

```ballerina
listener ftp:Listener remoteServer = check new({
    protocol: ftp:SFTP,
    host: "<The SFTP host>",
    port: <The SFTP port>,
    path: "<The remote SFTP direcotry 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>"
        }
    }
});
```


NONE

Defines the common error type for the module.


Represents a service listener that monitors the FTP location.


listenerConfig

ListenerConfiguration

`()` or else an `ftp:Error` upon failure to initialize the listener


Binds a service to the `ftp:Listener`.
```ballerina
error? response = listener->attach(service1);
```



attach

Service to be detached from the listener


ftpService

Service

Name of the service to be detached from the listener


name

`()` or else an `error` upon failure to register the listener


error

Starts the `ftp:Listener`.
```ballerina
error? response = listener->start();
```



'start

`()` or else an `error` upon failure to start the listener


Stops consuming messages and detaches the service from the `ftp:Listener`.
```ballerina
error? response = listener->detach(service1);
```



detach

`()` or else an `error` upon failure to detach the service


Stops the `ftp:Listener` forcefully.
```ballerina
error? response = listener->immediateStop();
```



immediateStop

`()` or else an `error` upon failure to stop the listener


Stops the `ftp:Listener` gracefully.
```ballerina
error? response = listener->gracefulStop();
```



gracefulStop

Poll new files from a FTP server.
```ballerina
error? response = listener->poll();
```



poll

An `error` if failed to establish communication with the FTP
server


Register a FTP service in an FTP listener
server.
```ballerina
error? response = listener->register(ftpService, name);
```



register

Listener

Configurations for facilitating secure communication with a remote
FTP server.



credentials

Credentials

privateKey

PrivateKey

AuthConfiguration

protocol

host

port

auth

Username/password authentication related configurations.



username

password

Relative file path for a newly-added file


Last-modified timestamp of the file in
UNIX Epoch time


lastModifiedTimestamp

isFolder

boolean

isFile

Normalized absolute path of this file
within its file system


pathDecoded

extension

Receiver as a URI String for public display


publicURIString

fileType

isAttached

`true` if someone reads/writes from/to this file


isContentOpen

isExecutable

isHidden

isReadable

isWritable

Depth of the file name within its file system


depth

scheme

Root URI of the file system in which the file exists


rootURI

A "friendly path" is a path, which can be accessed without a password


friendlyURI

FileInfo

Configuration for the input given for `put` and `append` operations of
the FTP module.



Path of the file to be created or appended


filePath

The content read from the input file, if the input is a file


fileContent

stream

The input content, for other input types


textContent

If true, input will be compressed before uploading


compressInput

InputContent

File name pattern that event need to trigger


fileNamePattern

Periodic time interval to check new update


pollingInterval

decimal

This represents the latest status change of the server from the last
status change.



Array of `ftp:FileInfo` that represents newly added files


addedFiles

Array of strings that contains deleted file names


deletedFiles

WatchEvent

This module provides an FTP/SFTP client and an FTP/SFTP server listener implementation to facilitate an FTP/SFTP connection connected to a remote location.


Enum: Protocol

Members