"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.FTPContext = exports.FTPError = void 0;
const net_1 = require("net");
const parseControlResponse_1 = require("./parseControlResponse");
/**
* Describes an FTP server error response including the FTP response code.
*/
class FTPError extends Error {
constructor(res) {
super(res.message);
this.name = this.constructor.name;
this.code = res.code;
}
}
exports.FTPError = FTPError;
function doNothing() {
/** Do nothing */
}
/**
* FTPContext holds the control and data sockets of an FTP connection and provides a
* simplified way to interact with an FTP server, handle responses, errors and timeouts.
*
* It doesn't implement or use any FTP commands. It's only a foundation to make writing an FTP
* client as easy as possible. You won't usually instantiate this, but use `Client`.
*/
class FTPContext {
/**
* Instantiate an FTP context.
*
* @param timeout - Timeout in milliseconds to apply to control and data connections. Use 0 for no timeout.
* @param encoding - Encoding to use for control connection. UTF-8 by default. Use "latin1" for older servers.
*/
constructor(timeout = 0, encoding = "utf8") {
this.timeout = timeout;
/** Debug-level logging of all socket communication. */
this.verbose = false;
/** IP version to prefer (4: IPv4, 6: IPv6, undefined: automatic). */
this.ipFamily = undefined;
/** Options for TLS connections. */
this.tlsOptions = {};
/** A multiline response might be received as multiple chunks. */
this._partialResponse = "";
this._encoding = encoding;
// Help Typescript understand that we do indeed set _socket in the constructor but use the setter method to do so.
this._socket = this.socket = this._newSocket();
this._dataSocket = undefined;
}
/**
* Close the context.
*/
close() {
// Internally, closing a context is always described with an error. If there is still a task running, it will
// abort with an exception that the user closed the client during a task. If no task is running, no exception is
// thrown but all newly submitted tasks after that will abort the exception that the client has been closed.
// In addition the user will get a stack trace pointing to where exactly the client has been closed. So in any
// case use _closingError to determine whether a context is closed. This also allows us to have a single code-path
// for closing a context making the implementation easier.
const message = this._task ? "User closed client during task" : "User closed client";
const err = new Error(message);
this.closeWithError(err);
}
/**
* Close the context with an error.
*/
closeWithError(err) {
// If this context already has been closed, don't overwrite the reason.
if (this._closingError) {
return;
}
this._closingError = err;
// Close the sockets but don't fully reset this context to preserve `this._closingError`.
this._closeControlSocket();
this._closeSocket(this._dataSocket);
// Give the user's task a chance to react, maybe cleanup resources.
this._passToHandler(err);
// The task might not have been rejected by the user after receiving the error.
this._stopTrackingTask();
}
/**
* Returns true if this context has been closed or hasn't been connected yet. You can reopen it with `access`.
*/
get closed() {
return this.socket.remoteAddress === undefined || this._closingError !== undefined;
}
/**
* Reset this contex and all of its state.
*/
reset() {
this.socket = this._newSocket();
}
/**
* Get the FTP control socket.
*/
get socket() {
return this._socket;
}
/**
* Set the socket for the control connection. This will only close the current control socket
* if the new one is not an upgrade to the current one.
*/
set socket(socket) {
// No data socket should be open in any case where the control socket is set or upgraded.
this.dataSocket = undefined;
// This being a reset, reset any other state apart from the socket.
this.tlsOptions = {};
this._partialResponse = "";
if (this._socket) {
const newSocketUpgradesExisting = socket.localPort === this._socket.localPort;
if (newSocketUpgradesExisting) {
this._removeSocketListeners(this.socket);
}
else {
this._closeControlSocket();
}
}
if (socket) {
// Setting a completely new control socket is in essence something like a reset. That's
// why we also close any open data connection above. We can go one step further and reset
// a possible closing error. That means that a closed FTPContext can be "reopened" by
// setting a new control socket.
this._closingError = undefined;
// Don't set a timeout yet. Timeout for control sockets is only active during a task, see handle() below.
socket.setTimeout(0);
socket.setEncoding(this._encoding);
socket.setKeepAlive(true);
socket.on("data", data => this._onControlSocketData(data));
// Server sending a FIN packet is treated as an error.
socket.on("end", () => this.closeWithError(new Error("Server sent FIN packet unexpectedly, closing connection.")));
// Control being closed without error by server is treated as an error.
socket.on("close", hadError => { if (!hadError)
this.closeWithError(new Error("Server closed connection unexpectedly.")); });
this._setupDefaultErrorHandlers(socket, "control socket");
}
this._socket = socket;
}
/**
* Get the current FTP data connection if present.
*/
get dataSocket() {
return this._dataSocket;
}
/**
* Set the socket for the data connection. This will automatically close the former data socket.
*/
set dataSocket(socket) {
this._closeSocket(this._dataSocket);
if (socket) {
// Don't set a timeout yet. Timeout data socket should be activated when data transmission starts
// and timeout on control socket is deactivated.
socket.setTimeout(0);
this._setupDefaultErrorHandlers(socket, "data socket");
}
this._dataSocket = socket;
}
/**
* Get the currently used encoding.
*/
get encoding() {
return this._encoding;
}
/**
* Set the encoding used for the control socket.
*
* See https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings for what encodings
* are supported by Node.
*/
set encoding(encoding) {
this._encoding = encoding;
if (this.socket) {
this.socket.setEncoding(encoding);
}
}
/**
* Send an FTP command without waiting for or handling the result.
*/
send(command) {
const containsPassword = command.startsWith("PASS");
const message = containsPassword ? "> PASS ###" : `> ${command}`;
this.log(message);
this._socket.write(command + "\r\n", this.encoding);
}
/**
* Send an FTP command and handle the first response. Use this if you have a simple
* request-response situation.
*/
request(command) {
return this.handle(command, (res, task) => {
if (res instanceof Error) {
task.reject(res);
}
else {
task.resolve(res);
}
});
}
/**
* Send an FTP command and handle any response until you resolve/reject. Use this if you expect multiple responses
* to a request. This returns a Promise that will hold whatever the response handler passed on when resolving/rejecting its task.
*/
handle(command, responseHandler) {
if (this._task) {
const err = new Error("User launched a task while another one is still running. Forgot to use 'await' or '.then()'?");
err.stack += `\nRunning task launched at: ${this._task.stack}`;
this.closeWithError(err);
// Don't return here, continue with returning the Promise that will then be rejected
// because the context closed already. That way, users will receive an exception where
// they called this method by mistake.
}
return new Promise((resolveTask, rejectTask) => {
this._task = {
stack: new Error().stack || "Unknown call stack",
responseHandler,
resolver: {
resolve: arg => {
this._stopTrackingTask();
resolveTask(arg);
},
reject: err => {
this._stopTrackingTask();
rejectTask(err);
}
}
};
if (this._closingError) {
// This client has been closed. Provide an error that describes this one as being caused
// by `_closingError`, include stack traces for both.
const err = new Error(`Client is closed because ${this._closingError.message}`); // Type 'Error' is not correctly defined, doesn't have 'code'.
err.stack += `\nClosing reason: ${this._closingError.stack}`;
err.code = this._closingError.code !== undefined ? this._closingError.code : "0";
this._passToHandler(err);
return;
}
// Only track control socket timeout during the lifecycle of a task. This avoids timeouts on idle sockets,
// the default socket behaviour which is not expected by most users.
this.socket.setTimeout(this.timeout);
if (command) {
this.send(command);
}
});
}
/**
* Log message if set to be verbose.
*/
log(message) {
if (this.verbose) {
// tslint:disable-next-line no-console
console.log(message);
}
}
/**
* Return true if the control socket is using TLS. This does not mean that a session
* has already been negotiated.
*/
get hasTLS() {
return "encrypted" in this._socket;
}
/**
* Removes reference to current task and handler. This won't resolve or reject the task.
* @protected
*/
_stopTrackingTask() {
// Disable timeout on control socket if there is no task active.
this.socket.setTimeout(0);
this._task = undefined;
}
/**
* Handle incoming data on the control socket. The chunk is going to be of type `string`
* because we let `socket` handle encoding with `setEncoding`.
* @protected
*/
_onControlSocketData(chunk) {
this.log(`< ${chunk}`);
// This chunk might complete an earlier partial response.
const completeResponse = this._partialResponse + chunk;
const parsed = (0, parseControlResponse_1.parseControlResponse)(completeResponse);
// Remember any incomplete remainder.
this._partialResponse = parsed.rest;
// Each response group is passed along individually.
for (const message of parsed.messages) {
const code = parseInt(message.substr(0, 3), 10);
const response = { code, message };
const err = code >= 400 ? new FTPError(response) : undefined;
this._passToHandler(err ? err : response);
}
}
/**
* Send the current handler a response. This is usually a control socket response
* or a socket event, like an error or timeout.
* @protected
*/
_passToHandler(response) {
if (this._task) {
this._task.responseHandler(response, this._task.resolver);
}
// Errors other than FTPError always close the client. If there isn't an active task to handle the error,
// the next one submitted will receive it using `_closingError`.
// There is only one edge-case: If there is an FTPError while no task is active, the error will be dropped.
// But that means that the user sent an FTP command with no intention of handling the result. So why should the
// error be handled? Maybe log it at least? Debug logging will already do that and the client stays useable after
// FTPError. So maybe no need to do anything here.
}
/**
* Setup all error handlers for a socket.
* @protected
*/
_setupDefaultErrorHandlers(socket, identifier) {
socket.once("error", error => {
error.message += ` (${identifier})`;
this.closeWithError(error);
});
socket.once("close", hadError => {
if (hadError) {
this.closeWithError(new Error(`Socket closed due to transmission error (${identifier})`));
}
});
socket.once("timeout", () => {
socket.destroy();
this.closeWithError(new Error(`Timeout (${identifier})`));
});
}
/**
* Close the control socket. Sends QUIT, then FIN, and ignores any response or error.
*/
_closeControlSocket() {
this._removeSocketListeners(this._socket);
this._socket.on("error", doNothing);
this.send("QUIT");
this._closeSocket(this._socket);
}
/**
* Close a socket, ignores any error.
* @protected
*/
_closeSocket(socket) {
if (socket) {
this._removeSocketListeners(socket);
socket.on("error", doNothing);
socket.destroy();
}
}
/**
* Remove all default listeners for socket.
* @protected
*/
_removeSocketListeners(socket) {
socket.removeAllListeners();
// Before Node.js 10.3.0, using `socket.removeAllListeners()` without any name did not work: https://github.com/nodejs/node/issues/20923.
socket.removeAllListeners("timeout");
socket.removeAllListeners("data");
socket.removeAllListeners("end");
socket.removeAllListeners("error");
socket.removeAllListeners("close");
socket.removeAllListeners("connect");
}
/**
* Provide a new socket instance.
*
* Internal use only, replaced for unit tests.
*/
_newSocket() {
return new net_1.Socket();
}
}
exports.FTPContext = FTPContext;
