search

lumphe / ftp-ts

FTP-ts is an FTP client module for node that provides an asynchronous interface for communicating with a FTP server.
MIT License
9 stars 5 forks source link

readme

FTP-ts

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

It is a rewritten version of the ftp package from mscdex.

Requirements

node.js -- v8.0 or newer

Note: For node version < 10, one of the --harmony_async_iteration or --harmony flags must be used.

Install

npm install ftp-ts

Examples

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

  import Client from "ftp-ts";

  // connect to localhost:21 as anonymous
  Client.connect({host: "127.0.0.1", port: 21}).then(async (c) => {
    console.dir(await c.list());
    c.end();
  });

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

  import Client from "ftp-ts";
  import { createWriteStream } from "fs";

  // connect to localhost:21 as anonymous
  Client.connect({host: "127.0.0.1", port: 21}).then(async (c) => {
    const stream = await c.get('foo.txt');
    stream.pipe(createWriteStream('foo.local-copy.txt'));
    c.end();
  });

Upload local file 'foo.txt' to the server

  import Client from "ftp-ts";

  // connect to localhost:21 as anonymous
  Client.connect({host: "127.0.0.1", port: 21}).then((c) => {
    c.put('foo.txt', 'foo.remote-copy.txt');
    c.end();
  })

Fallback to using PORT for data connections

  import Client from "ftp-ts";

  // connect to localhost:21 as anonymous
  // Config PORT address and PORT range
  Client.connect({host: "127.0.0.1", port: 2111, portAddress: "127.0.0.1", portRange: "6000-7000"}).then(async (c) => {
    console.dir(await c.list());
    c.end();
  });

Implementation

List of implemented required "standard" commands (RFC 959):

List of implemented optional "standard" commands (RFC 959):

List of implemented extended commands (RFC 3659)

Class: FTP, default

new FTP()

Creates a new FTP client.

Class Method: FTP.connect([options])

Event: 'greeting'

Emitted after connection.

Event: 'ready'

Emitted when connection and authentication were sucessful.

Event: 'close'

Emitted when the connection has fully closed.

Event: 'end'

Emitted when the connection has ended.

Event: 'error'

Emitted when an error occurs. In case of protocol-level errors, the error contains a code property that references the related 3-digit FTP response code.

Override: ftp.localPort(bindIp[, portRange])

This method may be overridden on the instance to allow for better managed PORT/EPRT commands.

For example, you may wish to bind only to a specific network interface for security reasons. In that case you may override this method to return the bindIp with a value of 127.0.0.1 instead of 0.0.0.0 to only allow incoming connections from localhost.

Another reason may be to decide upon a port number and await some NAT rules to propagate before the remote server connects.

This could also be useful if your external IP family does not match the family of your interface due to proxying or NAT rules. By default the zero bindIp will always be in the same IP family as the external IP set as portAddress in the IOption object.

ftp.connect([options])

Connects to an FTP server.

ftp.end()

Closes the connection to the server after any/all enqueued commands have been executed.

ftp.destroy()

Closes the connection to the server immediately.

ftp.list([path[, useCompression]])

Get a directory listing from the server.

ftp.get(path[, useCompression])

Retrieves a file at path from the server.

ftp.put(input, destPath[, useCompression])

Sends data to the server to be stored as destPath.

ftp.append(input, destPath[, useCompression])

Sends data to the server to be stored as destPath, except if destPath already exists, it will be appended to instead of overwritten.

ftp.rename(oldPath, newPath)

Renames oldPath to newPath on the server.

ftp.logout()

Logout the user from the server.

ftp.delete(path)

Deletes the file represented by path on the server.

ftp.cwd(path[, promote])

Changes the current working directory to path.

ftp.abort(immediate)

Aborts the current data transfer (e.g. from get(), put(), or list()).

ftp.site(command)

Sends command (e.g. 'CHMOD 755 foo', 'QUOTA') using SITE.

ftp.status()

Retrieves human-readable information about the server's status.

ftp.ascii()

Sets the transfer data type to ASCII.

ftp.binary()

Sets the transfer data type to binary (default at time of connection).

ftp.mkdir(path[, recursive])

Creates a new directory, path, on the server.

ftp.rmdir(path[, recursive])

Removes a directory, path, on the server.

ftp.cdup()

Changes the working directory to the parent of the current directory.

ftp.pwd()

Retrieves the current working directory.

ftp.system()

Retrieves the server's operating system.

ftp.listSafe([path[, useCompression]])

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.

ftp.size(path)

Retrieves the size of path.

ftp.lastMod(path)

Retrieves the last modified date and time for path.

ftp.restart(byteOffset)

Sets the file byte offset for the next file transfer action (get/put) to byteOffset.