Specification: Ballerina FTP Library

Owners: @shafreenAnfar @dilanSachi @Bhashinee
Reviewers: @shafreenAnfar @Bhashinee
Created: 2020/10/28
Updated: 2022/03/09
Edition: Swan Lake

Introduction

This is the specification for the FTP standard library of Ballerina language, which provides FTP client/listener functionalities to send and receive files by connecting to FTP/SFTP server.

The FTP library specification has evolved and may continue to evolve in the future. The released versions of the specification can be found under the relevant Github tag.

If you have any feedback or suggestions about the library, start a discussion via a GitHub issue or in the Slack channel. Based on the outcome of the discussion, the specification and implementation can be updated. Community feedback is always welcome. Any accepted proposal, which affects the specification is stored under /docs/proposals. Proposals under discussion can be found with the label type/proposal in GitHub.

The conforming implementation of the specification is released and included in the distribution. Any deviation from the specification is considered a bug.

Contents

  1. Overview
  2. Configurations
  3. Client
  4. Listener
  5. Caller
  6. Samples

1. Overview

FTP is a file transfer protocol. It’s a basic way of using the Internet to share files. SFTP (or Secure File Transfer Protocol) is an alternative to FTP that also allows transferring files, but adds a layer of security to the process. SFTP uses SSH (or secure shell) encryption to protect data as it’s being transferred. This means data is not exposed to outside entities on the Internet when it is sent to another party. This library provides support for both protocols.

Ballerina FTP library contains two core apis:

  • Client - The ftp:Client is used to connect to FTP server and perform various operations on the files.
  • Listener - The ftp:Listener is used to listen to a remote FTP location and notify if files are added or removed from the FTP location.

2. Configurations

2.1. Security Configurations

  • PrivateKey record represents the configuration related to a private key.
  • Credentials record represents the username and password configurations.
  • AuthConfiguration record represents the configurations needed for facilitating secure communication with a remote FTP server.

2.2. FileInfo

  • FileInfo record contains the metadata of the files.

3. Client

The ftp:Client connects to 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.

3.1. Configurations

  • When initializing the ftp:Client, ftp:ClientConfiguration configuration can be provided.
  • InputContent record represents the configurations for the input given for put and append operations.
  • Following Compression options can be used when adding a file to the FTP server.

3.2. Initialization

3.2.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.

3.2.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.

3.3. Functions

  • FTP Client API can be used to put files on the FTP server. For this, the put() method can be used.
  • append() can be used to append the content to an existing file in FTP server.
  • To retrieve file content from FTP server, get() can be used.
  • mkdir() can be used to create a new directory in FTP server.
  • rmdir() can be used to remove an empty directory in the server.
  • To delete a file, delete() can be used.
  • To rename a file or move it to another directory, rename() can be used.
  • size() function can be used to get the size of a file.
  • To get the file list in a directory, list() can be used.
  • To check if a resource is a directory, isDirectory() can be used.

4. 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 onFileChange function is invoked when a new file is added and/or deleted.

4.1. Configurations

  • When initializing the ftp:Listener, following configurations can be provided.
  • WatchEvent record represents the latest status change of the server from the last status change.

4.2. Initialization

4.2.1. Insecure Listener

An insecure FTP listener can be initialized by providing the mandatory protocol, host, and path parameters to the ftp:ListenerConfiguration.

4.2.2. Secure Listener

A secure listener can be initialized by providing ftp:SFTP as the protocol and by providing ftp:Credentials and ftp:PrivateKey to ftp:AuthConfiguration.

4.3. Usage

After initializing the listener, a service must be attached to the listener. There are two ways for this.

  1. Attach the service to the listener directly.
  1. Attach the service dynamically.

The remote function onFileChange() is invoked when the listener notices a file change in the FTP server. This function supports having both ftp:WatchEvent and ftp:Caller parameters or having only ftp:WatchEvent parameter.

The Listener has following functions to manage a service.

  • attach() - can be used to bind a service to the ftp:Listener.
  • detach() - can be used to detach a service from the ftp:Listener.
  • start() - needs to be called to start the listener.
  • gracefulStop() - can be used to gracefully stop the listener.
  • immediateStop() - can be used to forcefully stop the listener.
  • poll() - can be used to poll new files from the FTP server.
  • register() can be used to register an FTP service in an ftp:listener.

5. Caller

ftp:Caller is like a wrapper on the ftp:Client. It has an ftp:Client defined inside and contains all the APIs of ftp:Client like get(), put(), append() etc. However, ftp:Caller can only be created internally to be passed to the onFileChange method. ftp:Caller is created in the runtime when the ftp:Listener gets attached to a ftp:Service by checking whether the user has added ftp:Caller as a parameter in the onFileChange method.

5.1. Initialization

ftp:Caller can be both secure and insecure and this depends on the type of ftp:Listener. If the ftp:Listener is a secure type, ftp:Caller will also be secure since the wrapping ftp:Client is created using a subset of the ftp:ListenerConfiguration.

5.2. Functions

  • put() method can be used to put files on the server.
  • append() can be used to append the content to an existing file in FTP server.
  • To retrieve file content from FTP server, get() can be used.
  • mkdir() can be used to create a new directory in FTP server.
  • rmdir() can be used to remove an empty directory in the server.
  • To delete a file, delete() can be used.
  • To rename a file or move it to another directory, rename() can be used.
  • size() function can be used to get the size of a file.
  • To get the file list in a directory, list() can be used.
  • To check if a resource is a directory, isDirectory() can be used.

6. Samples

6.1. Sending Files

6.2. Listening to file changes