Description

promise-ftp is an FTP client module for node.js that provides an asynchronous interface for communicating with an FTP server.

This module is a wrapper around the node-ftp module, and provides some additional features as well as a convenient promise-based API.

This library is written primarily in CoffeeScript, but may be used just as easily in a Node app using Javascript or CoffeeScript. Promises in this module are provided by Bluebird.

Change Log

• Version 1.2.0 changes:

  • the FtpConnectionError and FtpReconectError classes have been moved to their own module, in anticipation of creating a semi-interchangeable API for promise-sftp. They are still exposed on the main module, but for npm 3+ the promise-ftp-errors module must now be listed as an explicit dependency.

• Version 1.1.0 adds:

  • the autoReconnect and preserveCwd options
  • the FtpReconectError error class
  • the reconnect() and getConnectionStatus() methods
  • the STATUSES and ERROR_CODES maps
  • completed API documentation

• Version 1.0.0 provides a promise-based API that mirrors the node-ftp API almost identically, except with a promise interface, plus:

  • the FtpConnectionError error class

Requirements

• node.js -- v0.8.0 or newer

Install

npm install promise-ftp
npm install promise-ftp-errors   # only necessary on npm 3+

Examples

Get a directory listing of the current (remote) working directory:

  var PromiseFtp = require('promise-ftp');
  
  var ftp = new PromiseFtp();
  ftp.connect({host: host, user: user, password: password})
  .then(function (serverMessage) {
    console.log('Server message: '+serverMessage);
    return ftp.list('/');
  }).then(function (list) {
    console.log('Directory listing:');
    console.dir(list);
    return ftp.end();
  });

Download remote file 'foo.txt' and save it to the local file system:

  var PromiseFtp = require('promise-ftp');
  var fs = require('fs');
  
  var ftp = new PromiseFtp();
  ftp.connect({host: host, user: user, password: password})
  .then(function (serverMessage) {
    return ftp.get('foo.txt');
  }).then(function (stream) {
    return new Promise(function (resolve, reject) {
      stream.once('close', resolve);
      stream.once('error', reject);
      stream.pipe(fs.createWriteStream('foo.local-copy.txt'));
    });
  }).then(function () {
    return ftp.end();
  });

Upload local file 'foo.txt' to the server:

  var PromiseFtp = require('promise-ftp');
  var fs = require('fs');
  
  var ftp = new PromiseFtp();
  ftp.connect({host: host, user: user, password: password})
  .then(function (serverMessage) {
    return ftp.put('foo.txt', 'foo.remote-copy.txt');
  }).then(function () {
    return ftp.end();
  });

API

For the most part, this module's API mirrors node-ftp's API, except that it returns promises which resolve or reject, rather than emitting events or calling callbacks. However, there are some minor differences and some additional features.

Errors

Errors generated by this module will be instances of one of the following:

• FtpConnectionError: Indicates the connection status was not appropriate for the method called; e.g. connect() or reconnect() was called when the connection was not in a disconnected state, end() was called when the connection has already closed, etc.

• FtpReconnectError: Only possible when the autoReconnect option is set true, this indicates a reconnect was attempted and failed. It includes information about both the original disconnect error (if any) as well as the error while attempting to reconnect.

In addition, errors from the underlying node-ftp library may be rejected unchanged through method calls. In the case of protocol-level errors, the rejected error will contain a code property that references the related 3-digit FTP response code. This code may be translated into a (generic) human-readable text explanation by referencing the map PromiseFtp.ERROR_CODES.

Methods

• [constructor](): Creates and returns a new PromiseFtp client instance.

• connect(config <object>): Connects to an FTP server; returned promise resolves to the server's greeting message. Valid config properties:

  • host <string>: The hostname or IP address of the FTP server. Default: 'localhost'

  • port <integer>: The port of the FTP server. Default: 21

  • secure <mixed>: Set to true for both control and data connection encryption, 'control' for control connection encryption only, or 'implicit' for implicitly encrypted control connection (this mode is deprecated in modern times, but usually uses port 990) Default: false

  • secureOptions <object>: Additional options to be passed to tls.connect(). Default: (none)

  • user <string>: Username for authentication. Default: 'anonymous'

  • password <string>: Password for authentication. Default: 'anonymous@'

  • connTimeout <integer>: How long (in milliseconds) to wait for the control connection to be established. Default: 10000

  • pasvTimeout <integer>: How long (in milliseconds) to wait for a PASV data connection to be established. Default: 10000

  • keepalive <integer>: How often (in milliseconds) to send a 'dummy' (NOOP) command to keep the connection alive. Default: 10000

  • autoReconnect <boolean>: Whether to attempt to automatically reconnect using the existing config if the connection is unexpectedly closed. Auto-reconnection is lazy, and so will wait until a command needs to be issued before attempting to reconnect. Default: false

  • preserveCwd <boolean>: Whether to attempt to return to the prior current working directory after a successful automatic reconnection. Only used if autoReconnect is true. Default: false

• reconnect(): Connects to an FTP server using the config from the most recent call to connect(). Returned promise resolves to the server's greeting message.

• end(): Closes the connection to the server after any/all enqueued commands have been executed; returned promise resolves to any error associated with closing the connection, or true if there was an error but it wasn't captured.

• destroy(): Closes the connection to the server immediately. Returns a boolean indicating whether the connection was connected prior to the call to destroy().

• getConnectionStatus(): Returns a string describing the current connection state. Possible strings are enumerated in PromiseFtp.STATUSES, as well as below:

  • not yet connected

  • connecting

  • connected

  • logging out

  • disconnecting

  • disconnected

  • reconnecting

Required "standard" commands (RFC 959)

• list([path <string>][, useCompression <boolean>]): Retrieves the directory listing of path. path defaults to the current working directory. useCompression defaults to false. Returned promise resolves to an array of objects with these properties:

  * type <_string_>: A single character denoting the entry type: 'd' for directory, '-' for file (or 'l' for
  symlink on **\*NIX only**).
  
  * name <_string_>: The name of the entry.
  
  * size <_string_>: The size of the entry in bytes.
  
  * date <_Date_>: The last modified date of the entry.
  
  * rights <_object_>: The various permissions for this entry **(*NIX only)**.
  
      * user <_string_>: An empty string or any combination of 'r', 'w', 'x'.
  
      * group <_string_>: An empty string or any combination of 'r', 'w', 'x'.
  
      * other <_string_>: An empty string or any combination of 'r', 'w', 'x'.
   
  * owner <_string_>: The user name or ID that this entry belongs to **(*NIX only)**.
  
  * group <_string_>: The group name or ID that this entry belongs to **(*NIX only)**.
  
  * target <_string_>: For symlink entries, this is the symlink's target **(*NIX only)**.
  
  * sticky <_boolean_>: True if the sticky bit is set for this entry **(*NIX only)**.

• get(path <string>[, useCompression <boolean>]): Retrieves a file at path from the server. useCompression defaults to false. Returned promise resolves to a ReadableStream.

• put(input <mixed>, destPath <string>[, useCompression <boolean>]): Sends data to the server to be stored as destPath. input can be a ReadableStream, a Buffer, or a path to a local file. useCompression defaults to false. Returned promise resolves to undefined.

• append(input <mixed>, destPath <string>[, useCompression <boolean>]): Same as put(), except if destPath already exists, it will be appended to instead of overwritten.

• rename(oldPath <string>, newPath <string>): Renames/moves oldPath to newPath on the server. Returned promise resolves to undefined.

• logout(): Logs the user out from the server. Returned promise resolves to undefined.

• delete(path <string>): Deletes the file at path. Returned promise resolves to undefined.

• cwd(path <string>): Changes the current working directory to path. Returned promise resolves to the new current directory, if the server replies with it in the response text; otherwise resolves to undefined.

• abort(): Aborts the current data transfer (e.g. from get(), put(), or list()). Returned promise resolves to undefined.

• site(command <string>): Sends command (e.g. 'CHMOD 755 foo', 'QUOTA') using SITE; returned promise resolves to an object with the following attributes:

  • text <string>: responseText

  • code <integer>: responseCode.

• status(): Retrieves human-readable information about the server's status. Returned promise resolves to the status string sent by the server.

• ascii(): Sets the transfer data type to ASCII. Returned promise resolves to undefined.

• binary(): Sets the transfer data type to binary (default at time of connection). Returned promise resolves to undefined.

Optional "standard" commands (RFC 959)

• mkdir(path <string>[, recursive <boolean>]): Creates a new directory, path, on the server. recursive is for enabling a 'mkdir -p' algorithm and defaults to false. Returned promise resolves to undefined.

• rmdir(path <string>[, recursive <boolean>]): Removes a directory, path, on the server. If recursive, this call will delete the contents of the directory if it is not empty. Returned promise resolves to undefined.

• cdup(): Changes the working directory to the parent of the current directory. Returned promise resolves to undefined.

• pwd(): Retrieves the current working directory. Returned promise resolves to the current working directory.

• system(): Retrieves the server's operating system. Returned promise resolves to the OS string sent by the server.

• listSafe([path <string>][, useCompression <boolean>]): Similar to list(), except the directory is temporarily changed to path to retrieve the directory listing. This is useful for servers that do not handle characters like spaces and quotes in directory names well for the LIST command. This function is "optional" because it relies on pwd() being available.

Extended commands (RFC 3659)

• size(path <string>): Retrieves the size of path. Returned promise resolves to number of bytes.

• lastMod(path <string>): Retrieves the last modified date and time for path. Returned promise resolves an instance of Date.

• restart(byteOffset <integer>): Sets the file byte offset for the next file transfer action initiated via get() or put() to byteOffset. Returned promise resolves to undefined.