ssh2-sftp-client 6.0.1 → 7.0.3

package/src/index.js

@@ -4,20 +4,23 @@
 
 'use strict';
 
-const {Client} = require('ssh2');
+const { Client } = require('ssh2');
 const fs = require('fs');
 const concat = require('concat-stream');
 const promiseRetry = require('promise-retry');
-const {join, parse} = require('path');
+const { join, parse } = require('path');
 const {
   fmtError,
   addTempListeners,
   removeTempListeners,
   haveConnection,
   normalizeRemotePath,
-  localExists
+  localExists,
+  haveLocalAccess,
+  haveLocalCreate,
+  sleep,
 } = require('./utils');
-const {errorCode} = require('./constants');
+const { errorCode } = require('./constants');
 
 class SftpClient {
   constructor(clientName) {
@@ -26,31 +29,43 @@ class SftpClient {
     this.clientName = clientName ? clientName : 'sftp';
     this.endCalled = false;
     this.errorHandled = false;
+    this.closeHandled = false;
+    this.endHandled = false;
     this.remotePathSep = '/';
     this.remotePlatform = 'unix';
     this.debug = undefined;
 
     this.client.on('close', () => {
-      if (!this.endCalled) {
-        this.debugMsg('Unexpected close event raised by server');
+      if (this.endCalled || this.closeHandled) {
+        // we are processing an expected end event or close event handled elsewhere
+        this.debugMsg('Global: Ignoring handled close event');
+      } else {
+        this.debugMsg('Global: Handling unexpected close event');
         this.sftp = undefined;
       }
     });
+
     this.client.on('end', () => {
-      if (!this.endCalled) {
-        this.debugMsg('Unexpected end event raised by server');
+      if (this.endCalled || this.endHandled) {
+        // end event expected or handled elsewhere
+        this.debugMsg('Global: Ignoring hanlded end event');
+      } else {
+        this.debugMsg('Global: Handling unexpected end event');
         this.sftp = undefined;
       }
     });
+
     this.client.on('error', (err) => {
-      if (!this.errorHandled) {
-        throw fmtError(
-          `Unexpected error: ${err.message}`,
-          'global-error-handler',
-          err.code
-        );
+      if (this.endCalled || this.errorHandled) {
+        // error event expected or handled elsewhere
+        this.debugMsg('Global: Ignoring handled error');
       } else {
-        this.errorHandled = false;
+        this.debugMsg(`Global; Handling unexpected error; ${err.message}`);
+        this.sftp = undefined;
+        console.log(
+          `ssh2-sftp-client: Unexpected error: ${err.message}. Error code: ${err.code}`
+        );
+        //throw fmtError(err, 'Global');
       }
     });
   }
@@ -77,81 +92,125 @@ class SftpClient {
    * @param {function} callback - function called when event triggers
    */
   on(eventType, callback) {
-    this.debugMsg(`Adding listener to ${eventType}`);
-    this.client.on(eventType, callback);
+    this.debugMsg(`Adding listener to ${eventType} event`);
+    this.client.prependListener(eventType, callback);
   }
 
   removeListener(eventType, callback) {
-    this.debugMsg(`Removing listener from ${eventType}`);
+    this.debugMsg(`Removing listener from ${eventType} event`);
     this.client.removeListener(eventType, callback);
   }
 
+  _resetEventFlags() {
+    this.closeHandled = false;
+    this.endHandled = false;
+    this.errorHandled = false;
+  }
+
   /**
    * @async
    *
    * Create a new SFTP connection to a remote SFTP server
    *
    * @param {Object} config - an SFTP configuration object
-   * @param {string} connectMethod - ???
    *
    * @return {Promise} which will resolve to an sftp client object
    *
    */
-  sftpConnect(config) {
-    let connectReady;
+  getConnection(config) {
+    let doReady;
+    return (
+      new Promise((resolve, reject) => {
+        addTempListeners(this, 'getConnection', reject);
+        this.debugMsg('getConnection: created promise');
+        doReady = () => {
+          this.debugMsg('getConnection: got connection - promise resolved');
+          resolve(true);
+        };
+        this.on('ready', doReady);
+        this.client.connect(config);
+      })
+        // .catch((err) => {
+        //   return Promise.reject(err);
+        // })
+        .finally(async (resp) => {
+          this.debugMsg('getConnection: finally clause fired');
+          await sleep(500);
+          this.removeListener('ready', doReady);
+          removeTempListeners(this, 'getConnection');
+          this._resetEventFlags();
+          return resp;
+        })
+    );
+  }
 
+  getSftpChannel() {
     return new Promise((resolve, reject) => {
-      addTempListeners(this, 'sftpConnect', reject);
-      connectReady = () => {
-        this.client.sftp((err, sftp) => {
-          if (err) {
-            this.debugMsg(`SFTP channel error: ${err.message} ${err.code}`);
-            reject(fmtError(err, 'sftpConnect', err.code));
-          } else {
-            this.debugMsg('SFTP channel established');
-            resolve(sftp);
-          }
-        });
-      };
-      // addTempListeners(this, 'sftpConnect', reject);
-      this.client.on('ready', connectReady).connect(config);
-    }).finally((rsp) => {
-      this.removeListener('ready', connectReady);
-      removeTempListeners(this.client);
-      return rsp;
+      addTempListeners(this, 'getSftpChannel', reject);
+      this.debugMsg('getSftpChannel: created promise');
+      this.client.sftp((err, sftp) => {
+        if (err) {
+          this.debugMsg(`getSftpChannel: SFTP Channel Error: ${err.message}`);
+          reject(fmtError(err, 'getSftpChannel', err.code));
+        } else {
+          this.debugMsg('getSftpChannel: SFTP channel established');
+          this.sftp = sftp;
+          resolve(sftp);
+        }
+      });
+    }).finally((resp) => {
+      this.debugMsg('getSftpChannel: finally clause fired');
+      removeTempListeners(this, 'getSftpChannel');
+      this._resetEventFlags();
     });
   }
 
-  connect(config) {
-    if (config.debug) {
-      this.debug = config.debug;
-      this.debugMsg('Debugging turned on');
-    }
-    if (this.sftp) {
-      this.debugMsg('Already connected - reject');
-      return Promise.reject(
-        fmtError(
+  /**
+   * @async
+   *
+   * Create a new SFTP connection to a remote SFTP server.
+   * The connection options are the same as those offered
+   * by the underlying SSH2 module.
+   *
+   * @param {Object} config - an SFTP configuration object
+   *
+   * @return {Promise} which will resolve to an sftp client object
+   *
+   */
+  async connect(config) {
+    try {
+      if (config.debug) {
+        this.debug = config.debug;
+        this.debugMsg('connect: Debugging turned on');
+      }
+      if (this.sftp) {
+        this.debugMsg('connect: Already connected - reject');
+        throw fmtError(
           'An existing SFTP connection is already defined',
           'connect',
           errorCode.connect
-        )
+        );
+      }
+      await promiseRetry(
+        (retry, attempt) => {
+          this.debugMsg(`connect: Connect attempt ${attempt}`);
+          return this.getConnection(config).catch((err) => {
+            this.debugMsg('getConnection retry catch');
+            retry(err);
+          });
+        },
+        {
+          retries: config.retries || 1,
+          factor: config.retry_factor || 2,
+          minTimeout: config.retry_minTimeout || 1000,
+        }
       );
+      await this.getSftpChannel();
+    } catch (err) {
+      this.debugMsg(`connect: Error ${err.message}`);
+      this._resetEventFlags();
+      throw fmtError(err, 'connect');
     }
-    return promiseRetry(
-      (retry, attempt) => {
-        this.debugMsg(`Connect attempt ${attempt}`);
-        return this.sftpConnect(config).catch((err) => {
-          retry(err);
-        });
-      },
-      {
-        retries: config.retries || 1,
-        factor: config.retry_factor || 2,
-        minTimeout: config.retry_minTimeout || 1000
-      }
-    ).then((sftp) => {
-      this.sftp = sftp;
-    });
   }
 
   /**
@@ -160,11 +219,10 @@ class SftpClient {
    * Returns the real absolute path on the remote server. Is able to handle
    * both '.' and '..' in path names, but not '~'. If the path is relative
    * then the current working directory is prepended to create an absolute path.
-   * Returns undefined if the
-   * path does not exists.
+   * Returns undefined if the path does not exists.
    *
    * @param {String} remotePath - remote path, may be relative
-   * @returns {}
+   * @returns {Promise} - remote absolute path or undefined
    */
   realPath(remotePath) {
     return new Promise((resolve, reject) => {
@@ -187,7 +245,8 @@ class SftpClient {
         });
       }
     }).finally((rsp) => {
-      removeTempListeners(this.client);
+      removeTempListeners(this, 'realPath');
+      this._resetEventFlags();
       return rsp;
     });
   }
@@ -199,17 +258,17 @@ class SftpClient {
   /**
    * Retrieves attributes for path
    *
-   * @param {String} path, a string containing the path to a file
-   * @return {Promise} stats, attributes info
+   * @param {String} remotePath - a string containing the path to a file
+   * @return {Promise} stats - attributes info
    */
   async stat(remotePath) {
     const _stat = (aPath) => {
       return new Promise((resolve, reject) => {
-        this.debugMsg(`stat -> ${aPath}`);
-        addTempListeners(this, 'stat', reject);
+        this.debugMsg(`_stat: ${aPath}`);
+        addTempListeners(this, '_stat', reject);
         this.sftp.stat(aPath, (err, stats) => {
           if (err) {
-            this.debugMsg(`stat error ${err.message} code: ${err.code}`);
+            this.debugMsg(`_stat: Error ${err.message} code: ${err.code}`);
             if (err.code === 2 || err.code === 4) {
               reject(
                 fmtError(
@@ -224,8 +283,7 @@ class SftpClient {
               );
             }
           } else {
-            this.debugMsg('stats <- ', stats);
-            resolve({
+            let result = {
               mode: stats.mode,
               uid: stats.uid,
               gid: stats.gid,
@@ -238,12 +296,14 @@ class SftpClient {
               isCharacterDevice: stats.isCharacterDevice(),
               isSymbolicLink: stats.isSymbolicLink(),
               isFIFO: stats.isFIFO(),
-              isSocket: stats.isSocket()
-            });
+              isSocket: stats.isSocket(),
+            };
+            this.debugMsg('_stat: stats <- ', result);
+            resolve(result);
           }
         });
       }).finally((rsp) => {
-        removeTempListeners(this.client);
+        removeTempListeners(this, 'stat');
         return rsp;
       });
     };
@@ -253,11 +313,8 @@ class SftpClient {
       let absPath = await normalizeRemotePath(this, remotePath);
       return _stat(absPath);
     } catch (err) {
-      if (err.custom) {
-        throw err;
-      } else {
-        throw fmtError(err, 'stat', err.code);
-      }
+      this._resetEventFlags();
+      throw err.custom ? err : fmtError(err, 'stat', err.code);
     }
   }
 
@@ -267,47 +324,53 @@ class SftpClient {
    * Tests to see if an object exists. If it does, return the type of that object
    * (in the format returned by list). If it does not exist, return false.
    *
-   * @param {string} path - path to the object on the sftp server.
+   * @param {string} remotePath - path to the object on the sftp server.
    *
-   * @return {boolean} returns false if object does not exist. Returns type of
+   * @return {Promise} returns false if object does not exist. Returns type of
    *                   object if it does
    */
   async exists(remotePath) {
     try {
       if (haveConnection(this, 'exists')) {
         if (remotePath === '.') {
+          this.debugMsg('exists: . = d');
           return 'd';
         }
         let absPath = await normalizeRemotePath(this, remotePath);
         try {
-          this.debugMsg(`exists -> ${absPath}`);
+          this.debugMsg(`exists: ${remotePath} -> ${absPath}`);
           let info = await this.stat(absPath);
-          this.debugMsg('exists <- ', info);
+          this.debugMsg('exists: <- ', info);
           if (info.isDirectory) {
+            this.debugMsg(`exists: ${remotePath} = d`);
             return 'd';
           }
           if (info.isSymbolicLink) {
+            this.debugMsg(`exists: ${remotePath} = l`);
             return 'l';
           }
           if (info.isFile) {
+            this.debugMsg(`exists: ${remotePath} = -`);
             return '-';
           }
+          this.debugMsg(`exists: ${remotePath} = false`);
           return false;
         } catch (err) {
           if (err.code === errorCode.notexist) {
+            this.debugMsg(
+              `exists: ${remotePath} = false errorCode = ${err.code}`
+            );
             return false;
           }
+          this.debugMsg(`exists: throw error ${err.message} ${err.code}`);
           throw err;
         }
-      } else {
-        return false;
       }
+      this.debugMsg(`exists: default ${remotePath} = false`);
+      return false;
     } catch (err) {
-      if (err.custom) {
-        throw err;
-      } else {
-        throw fmtError(err, 'exists', err.code);
-      }
+      this._resetEventFlags();
+      throw err.custom ? err : fmtError(err, 'exists', err.code);
     }
   }
 
@@ -322,21 +385,20 @@ class SftpClient {
    *
    * @param {String} remotePath - path to remote directory
    * @param {RegExp} pattern - regular expression to match filenames
-   * @returns {Array} file description objects
+   * @returns {Promise} array of file description objects
    * @throws {Error}
    */
   list(remotePath, pattern = /.*/) {
     return new Promise((resolve, reject) => {
       if (haveConnection(this, 'list', reject)) {
         const reg = /-/gi;
-        this.debugMsg(`list -> ${remotePath} filter -> ${pattern}`);
+        this.debugMsg(`list: ${remotePath} filter: ${pattern}`);
         addTempListeners(this, 'list', reject);
         this.sftp.readdir(remotePath, (err, fileList) => {
           if (err) {
-            this.debugMsg(`list error ${err.message} code: ${err.code}`);
+            this.debugMsg(`list: Error ${err.message} code: ${err.code}`);
             reject(fmtError(`${err.message} ${remotePath}`, 'list', err.code));
           } else {
-            this.debugMsg('list <- ', fileList);
             let newList = [];
             // reset file info
             if (fileList) {
@@ -350,10 +412,10 @@ class SftpClient {
                   rights: {
                     user: item.longname.substr(1, 3).replace(reg, ''),
                     group: item.longname.substr(4, 3).replace(reg, ''),
-                    other: item.longname.substr(7, 3).replace(reg, '')
+                    other: item.longname.substr(7, 3).replace(reg, ''),
                   },
                   owner: item.attrs.uid,
-                  group: item.attrs.gid
+                  group: item.attrs.gid,
                 };
               });
             }
@@ -365,12 +427,15 @@ class SftpClient {
               let newPattern = pattern.replace(/\*([^*])*?/gi, '.*');
               regex = new RegExp(newPattern);
             }
-            resolve(newList.filter((item) => regex.test(item.name)));
+            let filteredList = newList.filter((item) => regex.test(item.name));
+            this.debugMsg('list: result: ', filteredList);
+            resolve(filteredList);
           }
         });
       }
     }).finally((rsp) => {
-      removeTempListeners(this.client);
+      removeTempListeners(this, 'list');
+      this._resetEventFlags();
       return rsp;
     });
   }
@@ -383,35 +448,56 @@ class SftpClient {
    * piped into the stream or undefined, in which case the data is returned as
    * a Buffer object.
    *
-   * @param {String} path, remote file path
-   * @param {string|stream|undefined} dst, data destination
-   * @param {Object} userOptions, options passed to get
+   * @param {String} remotePath - remote file path
+   * @param {string|stream|undefined} dst - data destination
+   * @param {Object} options - options object with supported properties of readStreamOptions,
+   *                          writeStreamOptions and pipeOptions.
    *
    * @return {Promise}
    */
-  get(remotePath, dst, options = {}) {
+  get(
+    remotePath,
+    dst,
+    options = { readStreamOptions: {}, writeStreamOptions: {}, pipeOptions: {} }
+  ) {
+    let rdr, wtr;
+
     return new Promise((resolve, reject) => {
       if (haveConnection(this, 'get', reject)) {
         this.debugMsg(`get -> ${remotePath} `, options);
         addTempListeners(this, 'get', reject);
-        let rdr = this.sftp.createReadStream(remotePath, options);
+        rdr = this.sftp.createReadStream(
+          remotePath,
+          options.readStreamOptions ? options.readStreamOptions : {}
+        );
         rdr.once('error', (err) => {
           reject(fmtError(`${err.message} ${remotePath}`, 'get', err.code));
         });
         if (dst === undefined) {
           // no dst specified, return buffer of data
           this.debugMsg('get returning buffer of data');
-          let concatStream = concat((buff) => {
-            rdr.removeAllListeners('error');
+          wtr = concat((buff) => {
+            //rdr.removeAllListeners('error');
             resolve(buff);
           });
-          rdr.pipe(concatStream);
         } else {
-          let wtr;
           if (typeof dst === 'string') {
             // dst local file path
             this.debugMsg('get returning local file');
-            wtr = fs.createWriteStream(dst);
+            const localCheck = haveLocalCreate(dst);
+            if (!localCheck.status) {
+              return reject(
+                fmtError(
+                  `Bad path: ${dst}: ${localCheck.details}`,
+                  'get',
+                  localCheck.code
+                )
+              );
+            }
+            wtr = fs.createWriteStream(
+              dst,
+              options.writeStreamOptions ? options.writeStreamOptions : {}
+            );
           } else {
             this.debugMsg('get returning data into supplied stream');
             wtr = dst;
@@ -424,25 +510,35 @@ class SftpClient {
                 err.code
               )
             );
-            if (options.autoClose === false) {
-              rdr.destroy();
-            }
           });
-          wtr.once('finish', () => {
-            if (options.autoClose === false) {
-              rdr.destroy();
-            }
+          rdr.once('end', () => {
             if (typeof dst === 'string') {
               resolve(dst);
             } else {
               resolve(wtr);
             }
           });
-          rdr.pipe(wtr);
         }
+        rdr.pipe(wtr, options.pipeOptions ? options.pipeOptions : {});
       }
     }).finally((rsp) => {
-      removeTempListeners(this.client);
+      removeTempListeners(this, 'get');
+      this._resetEventFlags();
+      if (
+        rdr &&
+        options.readStreamOptions &&
+        options.readStreamOptions.autoClose === false
+      ) {
+        rdr.destroy();
+      }
+      if (
+        wtr &&
+        options.writeStreamOptions &&
+        options.writeStreamOptions.autoClose === false &&
+        typeof dst === 'string'
+      ) {
+        wtr.destroy();
+      }
       return rsp;
     });
   }
@@ -460,40 +556,47 @@ class SftpClient {
    * @param {Object} options
    * @return {Promise} the result of downloading the file
    */
-  fastGet(remotePath, localPath, options) {
-    return this.exists(remotePath)
-      .then((ftype) => {
-        if (ftype !== '-') {
-          let msg =
-            ftype === false
-              ? `No such file ${remotePath}`
-              : `Not a regular file ${remotePath}`;
-          return Promise.reject(fmtError(msg, 'fastGet', errorCode.badPath));
+  async fastGet(remotePath, localPath, options) {
+    try {
+      const ftype = await this.exists(remotePath);
+      if (ftype !== '-') {
+        const msg =
+          ftype === false
+            ? `No such file ${remotePath}`
+            : `Not a regular file ${remotePath}`;
+        let err = new Error(msg);
+        err.code = errorCode.badPath;
+        throw err;
+      }
+      const localCheck = haveLocalCreate(localPath);
+      if (!localCheck.status) {
+        let err = new Error(`Bad path: ${localPath}: ${localCheck.details}`);
+        err.code = errorCode.badPath;
+        throw err;
+      }
+      await new Promise((resolve, reject) => {
+        if (haveConnection(this, 'fastGet', reject)) {
+          this.debugMsg(
+            `fastGet -> remote: ${remotePath} local: ${localPath} `,
+            options
+          );
+          addTempListeners(this, 'fastGet', reject);
+          this.sftp.fastGet(remotePath, localPath, options, (err) => {
+            if (err) {
+              this.debugMsg(`fastGet error ${err.message} code: ${err.code}`);
+              reject(err);
+            }
+            resolve(`${remotePath} was successfully download to ${localPath}!`);
+          });
         }
-      })
-      .then(() => {
-        return new Promise((resolve, reject) => {
-          if (haveConnection(this, 'fastGet', reject)) {
-            this.debugMsg(
-              `fastGet -> remote: ${remotePath} local: ${localPath} `,
-              options
-            );
-            addTempListeners(this, 'fastGet', reject);
-            this.sftp.fastGet(remotePath, localPath, options, (err) => {
-              if (err) {
-                this.debugMsg(`fastGet error ${err.message} code: ${err.code}`);
-                reject(fmtError(err, 'fastGet'));
-              }
-              resolve(
-                `${remotePath} was successfully download to ${localPath}!`
-              );
-            });
-          }
-        }).finally((rsp) => {
-          removeTempListeners(this.client);
-          return rsp;
-        });
+      }).finally((rsp) => {
+        removeTempListeners(this, 'fastGet');
+        return rsp;
       });
+    } catch (err) {
+      this._resetEventFlags();
+      throw fmtError(err, 'fastGet');
+    }
   }
 
   /**
@@ -511,60 +614,51 @@ class SftpClient {
    */
   fastPut(localPath, remotePath, options) {
     this.debugMsg(`fastPut -> local ${localPath} remote ${remotePath}`);
-    return localExists(localPath)
-      .then((localStatus) => {
-        this.debugMsg(`fastPut <- localStatus ${localStatus}`);
-        if (localStatus !== '-') {
-          this.debugMsg('fastPut reject bad source path');
-          return Promise.reject(
-            fmtError(`Bad path ${localPath}`, 'fastPut', errorCode.badPath)
-          );
-        }
-        return new Promise((resolve, reject) => {
-          fs.access(localPath, fs.constants.F_OK | fs.constants.R_OK, (err) => {
-            if (err) {
-              this.debugMsg('fastPut reject no access source');
-              reject(
-                fmtError(`${err.message} ${localPath}`, 'fastPut', err.code)
-              );
-            } else {
-              this.debugMsg('fastPut source access ok');
-              resolve(true);
-            }
-          });
-        });
-      })
-      .then(() => {
-        return new Promise((resolve, reject) => {
-          if (haveConnection(this, 'fastPut', reject)) {
-            this.debugMsg(
-              `fastPut -> local: ${localPath} remote: ${remotePath} opts: ${JSON.stringify(
-                options
-              )}`
+    return new Promise((resolve, reject) => {
+      const localCheck = haveLocalAccess(localPath);
+      if (!localCheck.status) {
+        reject(
+          fmtError(
+            `Bad path: ${localPath}: ${localCheck.details}`,
+            'fastPut',
+            localCheck.code
+          )
+        );
+      } else if (localCheck.status && localExists(localPath) === 'd') {
+        reject(
+          fmtError(
+            `Bad path: ${localPath} not a regular file`,
+            'fastPut',
+            errorCode.badPath
+          )
+        );
+      } else if (haveConnection(this, 'fastPut', reject)) {
+        this.debugMsg(
+          `fastPut -> local: ${localPath} remote: ${remotePath} opts: ${JSON.stringify(
+            options
+          )}`
+        );
+        addTempListeners(this, 'fastPut', reject);
+        this.sftp.fastPut(localPath, remotePath, options, (err) => {
+          if (err) {
+            this.debugMsg(`fastPut error ${err.message} ${err.code}`);
+            reject(
+              fmtError(
+                `${err.message} Local: ${localPath} Remote: ${remotePath}`,
+                'fastPut',
+                err.code
+              )
             );
-            addTempListeners(this, 'fastPut', reject);
-            this.sftp.fastPut(localPath, remotePath, options, (err) => {
-              if (err) {
-                this.debugMsg(`fastPut error ${err.message} ${err.code}`);
-                reject(
-                  fmtError(
-                    `${err.message} Local: ${localPath} Remote: ${remotePath}`,
-                    'fastPut',
-                    err.code
-                  )
-                );
-              }
-              this.debugMsg('fastPut file transferred');
-              resolve(
-                `${localPath} was successfully uploaded to ${remotePath}!`
-              );
-            });
           }
-        }).finally((rsp) => {
-          removeTempListeners(this.client);
-          return rsp;
+          this.debugMsg('fastPut file transferred');
+          resolve(`${localPath} was successfully uploaded to ${remotePath}!`);
         });
-      });
+      }
+    }).finally((rsp) => {
+      removeTempListeners(this, 'fastPut');
+      this._resetEventFlags();
+      return rsp;
+    });
   }
 
   /**
@@ -572,140 +666,148 @@ class SftpClient {
    * can be a buffer, string or read stream. If 'src' is a string, it
    * should be the path to a local file.
    *
-   * @param  {String|Buffer|stream} src - source data to use
+   * @param  {String|Buffer|stream} localSrc - source data to use
    * @param  {String} remotePath - path to remote file
-   * @param  {Object} options - options used for write stream configuration
-   *                            value supported by node streams.
+   * @param  {Object} options - options used for read, write stream and pipe configuration
+   *                            value supported by node. Allowed properties are readStreamOptions,
+   *                            writeStreamOptions and pipeOptions.
    * @return {Promise}
    */
-  put(localSrc, remotePath, options = {}) {
-    this.debugMsg(
-      `put ${
-        typeof localSrc === 'string' ? localSrc : '<buffer | stream>'
-      } -> ${remotePath}`,
-      options
-    );
-    return localExists(typeof localSrc === 'string' ? localSrc : 'dummy')
-      .then((localStatus) => {
-        if (typeof localSrc === 'string' && localStatus !== '-') {
-          this.debugMsg(`put: file does not exist ${localSrc} - rejecting`);
-          return Promise.reject(
-            fmtError(`Bad path ${localSrc}`, 'put', errorCode.badPath)
+  put(
+    localSrc,
+    remotePath,
+    options = { readStreamOptions: {}, writeStreamOptions: {}, pipeOptions: {} }
+  ) {
+    let wtr, rdr;
+
+    return new Promise((resolve, reject) => {
+      if (typeof localSrc === 'string') {
+        const localCheck = haveLocalAccess(localSrc);
+        if (!localCheck.status) {
+          this.debugMsg(`put: local source check error ${localCheck.details}`);
+          return reject(
+            fmtError(
+              `Bad path: ${localSrc}: ${localCheck.details}`,
+              'put',
+              localCheck.code
+            )
           );
         }
-        return new Promise((resolve, reject) => {
+      }
+      if (haveConnection(this, 'put')) {
+        addTempListeners(this, 'put', reject);
+        wtr = this.sftp.createWriteStream(
+          remotePath,
+          options.writeStreamOptions ? options.writeStreamOptions : {}
+        );
+        wtr.once('error', (err) => {
+          this.debugMsg(`put: write stream error ${err.message}`);
+          reject(fmtError(`${err.message} ${remotePath}`, 'put', err.code));
+        });
+        wtr.once('finish', () => {
+          this.debugMsg('put: promise resolved');
+          resolve(`Uploaded data stream to ${remotePath}`);
+        });
+        if (localSrc instanceof Buffer) {
+          this.debugMsg('put source is a buffer');
+          wtr.end(localSrc);
+        } else {
           if (typeof localSrc === 'string') {
-            fs.access(
+            this.debugMsg(`put source is a file path: ${localSrc}`);
+            rdr = fs.createReadStream(
               localSrc,
-              fs.constants.F_OK | fs.constants.R_OK,
-              (err) => {
-                if (err) {
-                  this.debugMsg(`put: Cannot read ${localSrc} - rejecting`);
-                  reject(
-                    fmtError(
-                      `Permission denied ${localSrc}`,
-                      'put',
-                      errorCode.permission
-                    )
-                  );
-                } else {
-                  this.debugMsg('put: localSrc file OK');
-                  resolve(true);
-                }
-              }
+              options.readStreamOptions ? options.readStreamOptions : {}
             );
           } else {
-            this.debugMsg('put: localSrc buffer or string OK');
-            resolve(true);
+            this.debugMsg('put source is a stream');
+            rdr = localSrc;
           }
-        });
-      })
-      .then(() => {
-        return new Promise((resolve, reject) => {
-          if (haveConnection(this, 'put', reject)) {
-            addTempListeners(this, 'put', reject);
-            let stream = this.sftp.createWriteStream(remotePath, options);
-            stream.once('error', (err) => {
-              reject(fmtError(`${err.message} ${remotePath}`, 'put', err.code));
-            });
-            stream.once('finish', () => {
-              if (options.autoClose === false) {
-                stream.destroy();
-              }
-              resolve(`Uploaded data stream to ${remotePath}`);
-            });
-            if (localSrc instanceof Buffer) {
-              this.debugMsg('put source is a buffer');
-              stream.end(localSrc);
-            } else {
-              let rdr;
-              if (typeof localSrc === 'string') {
-                this.debugMsg(`put source is a file path: ${localSrc}`);
-                rdr = fs.createReadStream(localSrc);
-              } else {
-                this.debugMsg('put source is a stream');
-                rdr = localSrc;
-              }
-              rdr.once('error', (err) => {
-                reject(
-                  fmtError(
-                    `${err.message} ${
-                      typeof localSrc === 'string' ? localSrc : ''
-                    }`,
-                    'put',
-                    err.code
-                  )
-                );
-                if (options.autoClose === false) {
-                  stream.destroy();
-                }
-              });
-              rdr.pipe(stream);
-            }
-          }
-        }).finally((rsp) => {
-          removeTempListeners(this.client);
-          return rsp;
-        });
-      });
+          rdr.once('error', (err) => {
+            this.debugMsg(`put: read stream error ${err.message}`);
+            reject(
+              fmtError(
+                `${err.message} ${
+                  typeof localSrc === 'string' ? localSrc : ''
+                }`,
+                'put',
+                err.code
+              )
+            );
+          });
+          rdr.pipe(wtr, options.pipeOptions ? options.pipeOptions : {});
+        }
+      }
+    }).finally((resp) => {
+      removeTempListeners(this, 'put');
+      this._resetEventFlags();
+      if (
+        rdr &&
+        options.readStreamOptions &&
+        options.readStreamOptions.autoClose === false &&
+        typeof localSrc === 'string'
+      ) {
+        rdr.destroy();
+      }
+      if (
+        wtr &&
+        options.writeStreamOptions &&
+        options.writeStreamOptions.autoClose === false
+      ) {
+        wtr.destroy();
+      }
+      return resp;
+    });
   }
 
   /**
    * Append to an existing remote file
    *
    * @param  {Buffer|stream} input
-   * @param  {String} remotePath,
+   * @param  {String} remotePath
    * @param  {Object} options
    * @return {Promise}
    */
   append(input, remotePath, options = {}) {
-    return new Promise((resolve, reject) => {
-      if (haveConnection(this, 'append', reject)) {
-        if (typeof input === 'string') {
-          reject(fmtError('Cannot append one file to another', 'append'));
-        } else {
-          this.debugMsg(`append -> remote: ${remotePath} `, options);
-          addTempListeners(this, 'append', reject);
-          options.flags = 'a';
-          let stream = this.sftp.createWriteStream(remotePath, options);
-          stream.once('error', (err) => {
-            reject(
-              fmtError(`${err.message} ${remotePath}`, 'append', err.code)
-            );
-          });
-          stream.once('finish', () => {
-            resolve(`Appended data to ${remotePath}`);
-          });
-          if (input instanceof Buffer) {
-            stream.end(input);
+    return this.exists(remotePath).then((fileType) => {
+      if (fileType && fileType === 'd') {
+        return Promise.reject(
+          fmtError(
+            `Bad path: ${remotePath}: cannot append to a directory`,
+            'append',
+            errorCode.badPath
+          )
+        );
+      }
+      return new Promise((resolve, reject) => {
+        if (haveConnection(this, 'append', reject)) {
+          if (typeof input === 'string') {
+            reject(fmtError('Cannot append one file to another', 'append'));
           } else {
-            input.pipe(stream);
+            this.debugMsg(`append -> remote: ${remotePath} `, options);
+            addTempListeners(this, 'append', reject);
+            options.flags = 'a';
+            let stream = this.sftp.createWriteStream(remotePath, options);
+            stream.on('error', (err) => {
+              reject(
+                fmtError(`${err.message} ${remotePath}`, 'append', err.code)
+              );
+            });
+            stream.on('finish', () => {
+              resolve(`Appended data to ${remotePath}`);
+            });
+            if (input instanceof Buffer) {
+              stream.write(input);
+              stream.end();
+            } else {
+              input.pipe(stream);
+            }
           }
         }
-      }
-    }).finally((rsp) => {
-      removeTempListeners(this.client);
-      return rsp;
+      }).finally((rsp) => {
+        removeTempListeners(this, 'append');
+        this._resetEventFlags();
+        return rsp;
+      });
     });
   }
 
@@ -714,24 +816,40 @@ class SftpClient {
    *
    * Make a directory on remote server
    *
-   * @param {string} path, remote directory path.
-   * @param {boolean} recursive, if true, recursively create directories
-   * @return {Promise}.
+   * @param {string} remotePath - remote directory path.
+   * @param {boolean} recursive - if true, recursively create directories
+   * @return {Promise}
    */
   async mkdir(remotePath, recursive = false) {
     const _mkdir = (p) => {
       return new Promise((resolve, reject) => {
-        this.debugMsg(`mkdir -> ${p}`);
-        addTempListeners(this, 'mkdir', reject);
+        this.debugMsg(`_mkdir: create ${p}`);
+        addTempListeners(this, '_mkdir', reject);
         this.sftp.mkdir(p, (err) => {
           if (err) {
-            this.debugMsg(`mkdir error ${err.message} code: ${err.code}`);
-            reject(fmtError(`${err.message} ${p}`, '_mkdir', err.code));
+            this.debugMsg(`_mkdir: Error ${err.message} code: ${err.code}`);
+            if (err.code === 4) {
+              //fix for windows dodgy error messages
+              let error = new Error(`Bad path: ${p} permission denied`);
+              error.code = errorCode.badPath;
+              reject(error);
+            } else if (err.code === 2) {
+              let error = new Error(
+                `Bad path: ${p} parent not a directory or not exist`
+              );
+              error.code = errorCode.badPath;
+              reject(error);
+            } else {
+              reject(err);
+            }
+          } else {
+            this.debugMsg('_mkdir: directory created');
+            resolve(`${p} directory created`);
           }
-          resolve(`${p} directory created`);
         });
       }).finally((rsp) => {
-        removeTempListeners(this.client);
+        removeTempListeners(this, '_mkdir');
+        this._resetEventFlags();
         return rsp;
       });
     };
@@ -740,22 +858,22 @@ class SftpClient {
       haveConnection(this, 'mkdir');
       let rPath = await normalizeRemotePath(this, remotePath);
       if (!recursive) {
-        return _mkdir(rPath);
+        return await _mkdir(rPath);
       }
       let dir = parse(rPath).dir;
       if (dir) {
         let dirExists = await this.exists(dir);
         if (!dirExists) {
           await this.mkdir(dir, true);
+        } else if (dirExists !== 'd') {
+          let error = new Error(`Bad path: ${dir} not a directory`);
+          error.code = errorCode.badPath;
+          throw error;
         }
       }
-      return _mkdir(rPath);
+      return await _mkdir(rPath);
     } catch (err) {
-      if (err.custom) {
-        throw err;
-      } else {
-        throw fmtError(`${err.message} ${remotePath}`, 'mkdir', err.code);
-      }
+      throw fmtError(`${err.message}`, 'mkdir', err.code);
     }
   }
 
@@ -764,10 +882,10 @@ class SftpClient {
    *
    * Remove directory on remote server
    *
-   * @param {string} path, path to directory to be removed
-   * @param {boolean} recursive, if true, remove directories/files in target
+   * @param {string} remotePath - path to directory to be removed
+   * @param {boolean} recursive - if true, remove directories/files in target
    *                             directory
-   * @return {Promise}..
+   * @return {Promise}
    */
   async rmdir(remotePath, recursive = false) {
     const _rmdir = (p) => {
@@ -782,7 +900,7 @@ class SftpClient {
           resolve('Successfully removed directory');
         });
       }).finally((rsp) => {
-        removeTempListeners(this.client);
+        removeTempListeners(this, 'rmdir');
         return rsp;
       });
     };
@@ -808,11 +926,8 @@ class SftpClient {
       }
       return _rmdir(absPath);
     } catch (err) {
-      if (err.custom) {
-        throw err;
-      } else {
-        throw fmtError(err, 'rmdir', err.code);
-      }
+      this._resetEventFlags();
+      throw err.custom ? err : fmtError(err, 'rmdir', err.code);
     }
   }
 
@@ -821,10 +936,10 @@ class SftpClient {
    *
    * Delete a file on the remote SFTP server
    *
-   * @param {string} path - path to the file to delete
+   * @param {string} remotePath - path to the file to delete
    * @param {boolean} notFoundOK - if true, ignore errors for missing target.
    *                               Default is false.
-   * @return {Promise} with string 'Successfully deleeted file' once resolved
+   * @return {Promise} with string 'Successfully deleted file' once resolved
    *
    */
   delete(remotePath, notFoundOK = false) {
@@ -848,7 +963,8 @@ class SftpClient {
         });
       }
     }).finally((rsp) => {
-      removeTempListeners(this.client);
+      removeTempListeners(this, 'delete');
+      this._resetEventFlags();
       return rsp;
     });
   }
@@ -884,7 +1000,8 @@ class SftpClient {
         });
       }
     }).finally((rsp) => {
-      removeTempListeners(this.client);
+      removeTempListeners(this, 'rename');
+      this._resetEventFlags();
       return rsp;
     });
   }
@@ -921,7 +1038,8 @@ class SftpClient {
         });
       }
     }).finally((rsp) => {
-      removeTempListeners(this.client);
+      removeTempListeners(this, 'posixRename');
+      this._resetEventFlags();
       return rsp;
     });
   }
@@ -932,9 +1050,9 @@ class SftpClient {
    * Change the mode of a remote file on the SFTP repository
    *
    * @param {string} remotePath - path to the remote target object.
-   * @param {Octal} mode - the new mode to set
+   * @param {number | string} mode - the new octal mode to set
    *
-   * @return {Promise}.
+   * @return {Promise}
    */
   chmod(remotePath, mode) {
     return new Promise((resolve, reject) => {
@@ -947,7 +1065,8 @@ class SftpClient {
         resolve('Successfully change file mode');
       });
     }).finally((rsp) => {
-      removeTempListeners(this.client);
+      removeTempListeners(this, 'chmod');
+      this._resetEventFlags();
       return rsp;
     });
   }
@@ -960,7 +1079,7 @@ class SftpClient {
    * server.
    * @param {String} srcDir - local source directory
    * @param {String} dstDir - remote destination directory
-   * @param {regex} filter - (Optional) a regular expression used to select
+   * @param {RegExp} filter - (Optional) a regular expression used to select
    *                         files and directories to upload
    * @returns {String}
    * @throws {Error}
@@ -968,6 +1087,14 @@ class SftpClient {
   async uploadDir(srcDir, dstDir, filter = /.*/) {
     try {
       this.debugMsg(`uploadDir -> ${srcDir} ${dstDir}`);
+      const srcType = localExists(srcDir);
+      if (srcType !== 'd') {
+        throw fmtError(
+          `Bad path: ${srcDir}: not a directory`,
+          'uploadDir',
+          errorCode.badPath
+        );
+      }
       haveConnection(this, 'uploadDir');
       let dstStatus = await this.exists(dstDir);
       if (dstStatus && dstStatus !== 'd') {
@@ -978,7 +1105,7 @@ class SftpClient {
       }
       let dirEntries = fs.readdirSync(srcDir, {
         encoding: 'utf8',
-        withFileTypes: true
+        withFileTypes: true,
       });
       dirEntries = dirEntries.filter((item) => filter.test(item.name));
       for (let e of dirEntries) {
@@ -990,7 +1117,7 @@ class SftpClient {
           let src = join(srcDir, e.name);
           let dst = dstDir + this.remotePathSep + e.name;
           await this.fastPut(src, dst);
-          this.client.emit('upload', {source: src, destination: dst});
+          this.client.emit('upload', { source: src, destination: dst });
         } else {
           this.debugMsg(
             `uploadDir: File ignored: ${e.name} not a regular file`
@@ -999,11 +1126,8 @@ class SftpClient {
       }
       return `${srcDir} uploaded to ${dstDir}`;
     } catch (err) {
-      if (err.custom) {
-        throw err;
-      } else {
-        throw fmtError(err, 'uploadDir');
-      }
+      this._resetEventFlags();
+      throw err.custom ? err : fmtError(err, 'uploadDir');
     }
   }
 
@@ -1015,9 +1139,9 @@ class SftpClient {
    * file system.
    * @param {String} srcDir - remote source directory
    * @param {String} dstDir - local destination directory
-   * @param {regex} filter - (Optional) a regular expression used to select
+   * @param {RegExp} filter - (Optional) a regular expression used to select
    *                         files and directories to upload
-   * @returns {String}
+   * @returns {Promise}
    * @throws {Error}
    */
   async downloadDir(srcDir, dstDir, filter = /.*/) {
@@ -1025,12 +1149,21 @@ class SftpClient {
       this.debugMsg(`downloadDir -> ${srcDir} ${dstDir}`);
       haveConnection(this, 'downloadDir');
       let fileList = await this.list(srcDir, filter);
-      let dstStatus = await localExists(dstDir);
-      if (dstStatus && dstStatus !== 'd') {
-        throw fmtError(`Bad path ${dstDir}`, 'downloadDir', errorCode.badPath);
-      }
-      if (!dstStatus) {
-        fs.mkdirSync(dstDir, {recursive: true});
+      const localCheck = haveLocalCreate(dstDir);
+      if (!localCheck.status && localCheck.details === 'permission denied') {
+        throw fmtError(
+          `Bad path: ${dstDir}: ${localCheck.details}`,
+          'downloadDir',
+          localCheck.code
+        );
+      } else if (localCheck.status && !localCheck.type) {
+        fs.mkdirSync(dstDir, { recursive: true });
+      } else if (localCheck.status && localCheck.type !== 'd') {
+        throw fmtError(
+          `Bad path: ${dstDir}: not a directory`,
+          'downloadDir',
+          errorCode.badPath
+        );
       }
       for (let f of fileList) {
         if (f.type === 'd') {
@@ -1041,7 +1174,7 @@ class SftpClient {
           let src = srcDir + this.remotePathSep + f.name;
           let dst = join(dstDir, f.name);
           await this.fastGet(src, dst);
-          this.client.emit('download', {source: src, destination: dst});
+          this.client.emit('download', { source: src, destination: dst });
         } else {
           this.debugMsg(
             `downloadDir: File ignored: ${f.name} not regular file`
@@ -1050,11 +1183,8 @@ class SftpClient {
       }
       return `${srcDir} downloaded to ${dstDir}`;
     } catch (err) {
-      if (err.custom) {
-        throw err;
-      } else {
-        throw fmtError(err, 'downloadDir', err.code);
-      }
+      this._resetEventFlags();
+      throw err.custom ? err : fmtError(err, 'downloadDir', err.code);
     }
   }
 
@@ -1071,17 +1201,21 @@ class SftpClient {
       addTempListeners(this, 'end', reject);
       endCloseHandler = () => {
         this.sftp = undefined;
+        this.debugMsg('end: Connection closed');
         resolve(true);
       };
       this.on('close', endCloseHandler);
       if (haveConnection(this, 'end', reject)) {
-        this.debugMsg('Have connection - calling end()');
+        this.debugMsg('end: Have connection - calling end()');
         this.client.end();
       }
-    }).finally(() => {
-      removeTempListeners(this.client);
+    }).finally((resp) => {
+      this.debugMsg('end: finally clause fired');
+      removeTempListeners(this, 'end');
       this.removeListener('close', endCloseHandler);
-      return true;
+      this.endCalled = false;
+      this._resetEventFlags();
+      return resp;
     });
   }
 }