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";
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";
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();
});
import Client from "ftp-ts";
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";
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'
- <string> the text the server sent upon connection.
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'
- <Error> the error when an error occurs
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])
options
<Object>
host
<string> The hostname or IP address of the FTP server. Default: 'localhost'
.port
<number> The port of the FTP server. Default: 21
.portAddress
<string> The external IP address for the server to connect to when using PORT
.portRange
<string> The range of ports to use when setting up PORT
sockets.secure
<boolean> | <string> 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()
.user
<string> Username for authentication. Default: 'anonymous'
.password
<string> Password for authentication. Default: 'anonymous@'
.connTimeout
<number> How long (in milliseconds) to wait for the control connection to be established. Default: 10000
.dataTimeout
<number> How long (in milliseconds) to wait for a PASV
/PORT
data connection to be established. Default: 10000
.keepalive
<number> How often (in milliseconds) to send a 'dummy' (NOOP) command to keep the connection alive. Default: 10000
.
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]])
path
<string> Default: current directory.useCompression
<boolean> Default: false
.- Returns: <Promise<Object>> The promise is resolved to the following object.
- 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 <number> 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 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])
path
<string> The path to the new directory.recursive
<boolean> Is for enabling a 'mkdir -p' algorithm Default: false
.- Returns: <Promise>
Creates a new directory, path
, on the server.
ftp.rmdir(path[, recursive])
path
<string> The path of the directory to delete.recursive
<boolean> Will delete the contents of the directory if it is not empty Default: false
.- Returns: <Promise>
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]])
path
<string> Default: current directory.useCompression
<boolean> Default: false
.- Returns: <Promise<Object>> The promise is resolved to the following object.
- 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 <number> 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).
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
.