ssh2-sftp-client 7.0.1 → 7.1.0

package/README.md

@@ -6,7 +6,7 @@
   - [Specifying Paths](#sec-5-1)
   - [Methods](#sec-5-2)
     - [new SftpClient(name) ===> SFTP client object](#sec-5-2-1)
-    - [connect(config) ===> SFTPstream](#sec-5-2-2)
+    - [connect(config) ===> SFTP object](#sec-5-2-2)
     - [list(path, pattern) ==> Array[object]](#sec-5-2-3)
     - [exists(path) ==> boolean](#sec-5-2-4)
     - [stat(path) ==> object](#sec-5-2-5)
@@ -40,6 +40,7 @@
   - [How can I connect through a Socks Proxy](#sec-7-4)
   - [Timeout while waiting for handshake or handshake errors](#sec-7-5)
   - [How can I limit upload/download speed](#sec-7-6)
+  - [Connection hangs or fails for larger files](#sec-7-7)
 - [Examples](#sec-8)
 - [Troubleshooting](#sec-9)
   - [Common Errors](#sec-9-1)
@@ -60,9 +61,9 @@ an SFTP client for node.js, a wrapper around [SSH2](https://github.com/mscdex/ss
 
 Documentation on the methods and available options in the underlying modules can be found on the [SSH2](https://github.com/mscdex/ssh2) project pages.
 
-Current stable release is **v7.0.0**.
+Current stable release is **v7.1.0**.
 
-Code has been tested against Node versions 12.22.1, 14.17.0 and 16.2.0
+Code has been tested against Node versions 12.22.6, 14.17.6 and 16.10.0
 
 Node versions < 10.x are not supported.
 
@@ -94,10 +95,12 @@ sftp.connect({
 
 # Version 7.x Changes<a id="sec-4"></a>
 
--   This version is based on version 1.1.0 of `ssh2`. This version of `ssh2` is a complete re-write of the `ssh2` library. This re-write addresses issues encountered when using node v14 as well as some design weaknesses in the previous 0.8.x version.
+-   This version is based on version 1.x.x of `ssh2`. This version of `ssh2` is a complete re-write of the `ssh2` library. This re-write addresses issues encountered when using node v14 as well as some design weaknesses in the previous 0.8.x version.
 
 -   **Breaking Change** Expanded option handling for `get()` and `put()` methods. A number of use cases were identified where setting specific options on the read and write streams and the pipe operation are necessary. For example, disabling `autoClose` on streams or the `end` event in pipes. The `options` argument for `get()` and `put()` calls now supports properties for `readStreamOptions`, `writeStreamOptions` and `pipeOptions`. Note that options are only applied to streams created by the `get()` and `put()` methods. Streams passed into these methods are under the control of the client code and therefore cannot have options supplied in arguments to those streams (you would apply such options when you create the streams). Options are typically only necessary in special use cases. Most of the time, no options are required. However, if you are currently using options to either `put()` or `get()`, you will need to update your code to map these options to the new structure.
 
+-   **Breaking Change 7.1.0** A race condition was identified when using a put() call with a writeStream option of `autoClose: false`. In some situations, the promise would be resolved before the final close of the write stream. This could result in errors if you immediately attempt to access the uploaded file. To avoid this situatioin, the promise is now resolved once a `close` event is emitted. This means that setting `autoClose: false` can no longer be supported. The write stream for `put()` will autoClose once data writing has completed.
+
 -   Improved event handling. A listener for a global error event is now defined to catch errors which occur in-between method calls i.e. connection lost in-between calls to the library methods. A new mechanism has also been added for removal of listeners when no longer required.
 
 # Documentation<a id="sec-5"></a>
@@ -174,7 +177,7 @@ Constructor to create a new `ssh2-sftp-client` object. An optional `name` string
       });
     ```
 
-### connect(config) ===> SFTPstream<a id="sec-5-2-2"></a>
+### connect(config) ===> SFTP object<a id="sec-5-2-2"></a>
 
 Connect to an sftp server. Full documentation for connection options is available [here](https://github.com/mscdex/ssh2#user-content-client-methods)
 
@@ -496,11 +499,12 @@ Upload data from local system to remote server. If the `src` argument is a strin
         flags: 'w',  // w - write and a - append
         encoding: null, // use null for binary files
         mode: 0o666, // mode to use for created file (rwx)
-        autoClose: true // automatically close the write stream when finished
     }}
     ```
     
     The most common options to use are mode and encoding. The values shown above are the defaults. You do not have to set encoding to utf-8 for text files, null is fine for all file types. However, using utf-8 encoding for binary files will often result in data corruption.
+    
+    Note that you cannot set `autoClose: false` for `writeStreamOptions`. If you attempt to set this property to false, it will be ignored. This is necessary to avoid a race condition which may exist when setting `autoClose` to false on the writeStream. As there is no easy way to access the writeStream once the promise has been resolved, setting this to autoClose false is not terribly useful as there is no easy way to manually close the stream after the promise has been resolved.
 
 2.  Example Use
 
@@ -1106,6 +1110,8 @@ client.connect({
 
 Some users have encountered the error 'Timeout while waiting for handshake' or 'Handshake failed, no matching client->server ciphers. This is often due to the client not having the correct configuration for the transport layer algorithms used by ssh2. One of the connect options provided by the ssh2 module is `algorithm`, which is an object that allows you to explicitly set the key exchange, ciphers, hmac and compression algorithms as well as server host key used to establish the initial secure connection. See the SSH2 documentation for details. Getting these parameters correct usually resolves the issue.
 
+When encountering this type of problem, one worthwhile approach is to use openSSH's CLI sftp program with the `-v` switch to raise loggin levels. This will show you what algorithms the CLI is using. You can then use this information to match the names with the accepted algorithm names documented in the `ssh2` README to set the properties in the `algorithms` object.
+
 ## How can I limit upload/download speed<a id="sec-7-6"></a>
 
 If you want to limit the amount of bandwidth used during upload/download of data, you can use a stream to limit throughput. The following example was provided by *kennylbj*. Note that there is a caveat that we must set the `autoClose` flag to false to avoid calling an extra `_read()` on a closed stream that may cause \_get Permission Denied error in ssh2-streams.
@@ -1143,6 +1149,14 @@ try {
 }
 ```
 
+## Connection hangs or fails for larger files<a id="sec-7-7"></a>
+
+This was contributed by Ladislav Jacho. Thanks.
+
+A symptom of this issue is that you are able to upload small files, but uploading larger ones fail. You probably have an MTU/fragmentation problem. For each network interface on both client and server set the MTU to 576, e.g. `ifconfig eth0 mtu 576`. If that works, you need to find the largest MTU which will work for your network. An MTU which is too small will adversely affect throughput speed. A common value to use is an MTU of 1400.
+
+For more explanation, see [issue #342](https://github.com/theophilusx/ssh2-sftp-client/issues/342).
+
 # Examples<a id="sec-8"></a>
 
 I have started collecting example scripts in the example directory of the repository. These are mainly scripts I have put together in order to investigate issues or provide samples for users. They are not robust, lack adequate error handling and may contain errors. However, I think they are still useful for helping developers see how the module and API can be used.
@@ -1320,6 +1334,8 @@ Perhaps the best assistance is a minimal reproducible example of the issue. Once
 
 Pull requests are always welcomed. However, please ensure your changes pass all tests and if your adding a new feature, that tests for that feature are included. Likewise, for new features or enhancements, please include any relevant documentation updates.
 
+**Note**: The `README.md` file is generated from the `README.org` file. Therefore, any documentation updates or fixes need to be made to the `README.org` file. This file is *tangled* using `Emacs` org mode. If you don't use Emacs or org-mode, don't be too concerned. The org-mode syntax is straight-forward and similar to *markdown*. I will verify any updates to `README.org` and generate a new `README.md` when necessary. The main point to note is that any changes made directly to `README.md` will not persist and will be lost when a new version is generated, so don't modify that file.
+
 This module will adopt a standard semantic versioning policy. Please indicate in your pull request what level of change it represents i.e.
 
 -   **Major:** Change to API or major change in functionality which will require an increase in major version number.
@@ -1341,3 +1357,7 @@ Thanks to the following for their contributions -
 -   **teenangst:** Contributed fix for error code 4 in stat() method
 -   **kennylbj:** Contributed example of using a throttle stream to limit upload/download bandwidth.
 -   **anton-erofeev:** Documentation fix
+-   **Ladislav Jacho:** Contributed solution explanation for connections hanging when transferring larger files.
+-   **Emma Milner:** Contributed fix for put() bug
+-   **Witni Davis:** Contributed PR to fix put() RCE when using 'finish' rather than 'close' to resolve promise
+-   **Maik Marschner:** Contributed fix for connect() not returning sftp object. Also included test to check for this regression in future.

package/README.org

@@ -9,9 +9,9 @@ convenience abstraction as well as a Promise based API.
 Documentation on the methods and available options in the underlying modules can
 be found on the [[https://github.com/mscdex/ssh2][SSH2]] project pages.
 
-Current stable release is *v7.0.0*.
+Current stable release is *v7.1.0*.
 
-Code has been tested against Node versions 12.22.1, 14.17.0 and 16.2.0
+Code has been tested against Node versions 12.22.6, 14.17.6 and 16.10.0
 
 Node versions < 10.x are not supported.
 
@@ -43,7 +43,7 @@ npm install ssh2-sftp-client
 
 * Version 7.x Changes
 
-- This version is based on version 1.1.0 of ~ssh2~. This version of ~ssh2~ is a
+- This version is based on version 1.x.x of ~ssh2~. This version of ~ssh2~ is a
   complete re-write of the ~ssh2~ library. This re-write addresses issues
   encountered when using node v14 as well as some design weaknesses in the
   previous 0.8.x version.
@@ -62,6 +62,14 @@ npm install ssh2-sftp-client
   currently using options to either ~put()~ or ~get()~, you will need to update
   your code to map these options to the new structure. 
 
+- *Breaking Change 7.1.0* A race condition was identified when using a put()
+  call with a writeStream option of ~autoClose: false~. In some situations, the
+  promise would be resolved before the final close of the write stream. This
+  could result in errors if you immediately attempt to access the uploaded
+  file. To avoid this situatioin, the promise is now resolved once a ~close~
+  event is emitted. This means that setting ~autoClose: false~ can no longer be
+  supported. The write stream for ~put()~ will autoClose once data writing has completed.
+   
 - Improved event handling. A listener for a global error event is now defined to
   catch errors which occur in-between method calls i.e. connection lost
   in-between calls to the library methods. A new mechanism has also been added
@@ -175,7 +183,7 @@ client has thrown the error.
     });
 #+end_src
 
-*** connect(config) ===> SFTPstream
+*** connect(config) ===> SFTP object
 
 Connect to an sftp server. Full documentation for connection options is
 available [[https://github.com/mscdex/ssh2#user-content-client-methods][here]]
@@ -546,7 +554,6 @@ option value. For example, you might use the following to set ~writeStream~ opti
       flags: 'w',  // w - write and a - append
       encoding: null, // use null for binary files
       mode: 0o666, // mode to use for created file (rwx)
-      autoClose: true // automatically close the write stream when finished
   }}
 #+end_src
 
@@ -555,6 +562,14 @@ the defaults. You do not have to set encoding to utf-8 for text files, null is
 fine for all file types. However, using utf-8 encoding for binary files will
 often result in data corruption.
 
+Note that you cannot set ~autoClose: false~ for ~writeStreamOptions~. If you
+attempt to set this property to false, it will be ignored. This is necessary to
+avoid a race condition which may exist when setting ~autoClose~ to false on the
+writeStream. As there is no easy way to access the writeStream once the promise
+has been resolved, setting this to autoClose false is not terribly useful as
+there is no easy way to manually close the stream after the promise has been
+resolved.
+
 **** Example Use
 
 #+begin_src javascript
@@ -1355,6 +1370,12 @@ host key used to establish the initial secure connection. See the SSH2
 documentation for details. Getting these parameters correct usually resolves the
 issue.
 
+When encountering this type of problem, one worthwhile approach is to use
+openSSH's CLI sftp program with the =-v= switch to raise loggin levels. This
+will show you what algorithms the CLI is using. You can then use this
+information to match the names with the accepted algorithm names documented in
+the =ssh2= README to set the properties in the =algorithms= object.
+
 ** How can I limit upload/download speed
 
    If you want to limit the amount of bandwidth used during upload/download of
@@ -1396,6 +1417,19 @@ issue.
        await client.end();
      }
    #+end_src
+** Connection hangs or fails for larger files
+
+ This was contributed by Ladislav Jacho. Thanks. 
+
+ A symptom of this issue is that you are able to upload small files, but
+ uploading larger ones fail. You probably have an MTU/fragmentation problem. For
+ each network interface on both client and server set the MTU to 576, e.g.
+ =ifconfig eth0 mtu 576=. If that works, you need to find the largest MTU which
+ will work for your network. An MTU which is too small will adversely affect
+ throughput speed. A common value to use is an MTU of 1400.
+ 
+ For more explanation, see [[https://github.com/theophilusx/ssh2-sftp-client/issues/342][issue #342]].
+ 
 * Examples
 
 I have started collecting example scripts in the example directory of the
@@ -1705,6 +1739,15 @@ tests and if your adding a new feature, that tests for that feature are
 included. Likewise, for new features or enhancements, please include any
 relevant documentation updates.
 
+*Note*: The =README.md= file is generated from the =README.org= file. Therefore,
+any documentation updates or fixes need to be made to the =README.org= file.
+This file is /tangled/ using =Emacs= org mode. If you don't use Emacs or
+org-mode, don't be too concerned. The org-mode syntax is straight-forward and
+similar to /markdown/. I will verify any updates to =README.org= and generate a
+new =README.md= when necessary. The main point to note is that any changes made
+directly to =README.md= will not persist and will be lost when a new version is
+generated, so don't modify that file. 
+
 This module will adopt a standard semantic versioning policy. Please indicate in
 your pull request what level of change it represents i.e.
 
@@ -1734,3 +1777,10 @@ Thanks to the following for their contributions -
 - kennylbj :: Contributed example of using a throttle stream to limit
   upload/download bandwidth.
 - anton-erofeev :: Documentation fix
+- Ladislav Jacho :: Contributed solution explanation for connections hanging
+  when transferring larger files.
+- Emma Milner :: Contributed fix for put() bug
+- Witni Davis :: Contributed PR to fix put() RCE when using 'finish' rather than
+  'close' to resolve promise
+- Maik Marschner :: Contributed fix for connect() not returning sftp object.
+  Also included test to check for this regression in future.

package/package.json

@@ -1,17 +1,24 @@
 {
   "name": "ssh2-sftp-client",
-  "version": "7.0.1",
+  "version": "7.1.0",
   "description": "ssh2 sftp client for node",
   "main": "src/index.js",
   "repository": {
     "type": "git",
     "url": "https://github.com/theophilusx/ssh2-sftp-client"
   },
-  "keywords": ["sftp", "nodejs", "promises"],
+  "keywords": [
+    "sftp",
+    "nodejs",
+    "promises"
+  ],
   "scripts": {
     "test": "mocha",
     "coverage": "nyc npm run test",
-    "lint": "eslint \"src/**/*.js\" --quiet"
+    "lint": "eslint \"src/**/*.js\" \"test/**/*.js\""
+  },
+  "engines": {
+    "node": ">=10.24.1"
   },
   "author": "Tim Cross",
   "email": "theophilusx@gmail.com",
@@ -25,17 +32,24 @@
   "dependencies": {
     "concat-stream": "^2.0.0",
     "promise-retry": "^2.0.1",
-    "ssh2": "^1.2.0"
+    "ssh2": "^1.5.0"
   },
   "devDependencies": {
-    "chai": "^4.2.0",
+    "chai": "^4.3.4",
     "chai-as-promised": "^7.1.1",
     "chai-subset": "^1.6.0",
-    "checksum": "^0.1.1",
+    "checksum": "^1.0.0",
     "dotenv": "^10.0.0",
-    "mocha": "^9.0.2",
+    "eslint": "^7.32.0",
+    "eslint-config-prettier": "^8.3.0",
+    "eslint-plugin-mocha": "^9.0.0",
+    "eslint-plugin-node": "^11.1.0",
+    "eslint-plugin-promise": "^5.1.0",
+    "eslint-plugin-unicorn": "^36.0.0",
+    "mocha": "^9.1.2",
     "moment": "^2.29.1",
     "nyc": "^15.1.0",
+    "prettier": "^2.4.1",
     "through2": "^4.0.2",
     "winston": "^3.3.3"
   }

package/src/constants.js

@@ -1,12 +1,10 @@
-'use strict';
-
 const errorCode = {
   generic: 'ERR_GENERIC_CLIENT',
   connect: 'ERR_NOT_CONNECTED',
   badPath: 'ERR_BAD_PATH',
   permission: 'EACCES',
   notexist: 'ENOENT',
-  notdir: 'ENOTDIR'
+  notdir: 'ENOTDIR',
 };
 
 const targetType = {
@@ -15,10 +13,10 @@ const targetType = {
   writeDir: 3,
   readDir: 4,
   readObj: 5,
-  writeObj: 6
+  writeObj: 6,
 };
 
 module.exports = {
   errorCode,
-  targetType
+  targetType,
 };

package/src/index.js

@@ -114,7 +114,7 @@ class SftpClient {
    *
    * @param {Object} config - an SFTP configuration object
    *
-   * @return {Promise} which will resolve to an sftp client object
+   * @return {Promise<Object>} which will resolve to an sftp client object
    *
    */
   getConnection(config) {
@@ -133,13 +133,12 @@ class SftpClient {
         // .catch((err) => {
         //   return Promise.reject(err);
         // })
-        .finally(async (resp) => {
+        .finally(async () => {
           this.debugMsg('getConnection: finally clause fired');
           await sleep(500);
           this.removeListener('ready', doReady);
           removeTempListeners(this, 'getConnection');
           this._resetEventFlags();
-          return resp;
         })
     );
   }
@@ -158,7 +157,7 @@ class SftpClient {
           resolve(sftp);
         }
       });
-    }).finally((resp) => {
+    }).finally(() => {
       this.debugMsg('getSftpChannel: finally clause fired');
       removeTempListeners(this, 'getSftpChannel');
       this._resetEventFlags();
@@ -174,7 +173,7 @@ class SftpClient {
    *
    * @param {Object} config - an SFTP configuration object
    *
-   * @return {Promise} which will resolve to an sftp client object
+   * @return {Promise<Object>} which will resolve to an sftp client object
    *
    */
   async connect(config) {
@@ -205,7 +204,7 @@ class SftpClient {
           minTimeout: config.retry_minTimeout || 1000,
         }
       );
-      await this.getSftpChannel();
+      return this.getSftpChannel();
     } catch (err) {
       this.debugMsg(`connect: Error ${err.message}`);
       this._resetEventFlags();
@@ -222,7 +221,7 @@ class SftpClient {
    * Returns undefined if the path does not exists.
    *
    * @param {String} remotePath - remote path, may be relative
-   * @returns {Promise} - remote absolute path or undefined
+   * @returns {Promise<String>} - remote absolute path or ''
    */
   realPath(remotePath) {
     return new Promise((resolve, reject) => {
@@ -244,13 +243,19 @@ class SftpClient {
           resolve(absPath);
         });
       }
-    }).finally((rsp) => {
+    }).finally(() => {
       removeTempListeners(this, 'realPath');
       this._resetEventFlags();
-      return rsp;
     });
   }
 
+  /**
+   * @async
+   *
+   * Return the current workding directory path
+   *
+   * @returns {Promise<String>} - current remote working directory
+   */
   cwd() {
     return this.realPath('.');
   }
@@ -259,7 +264,7 @@ class SftpClient {
    * Retrieves attributes for path
    *
    * @param {String} remotePath - a string containing the path to a file
-   * @return {Promise} stats - attributes info
+   * @return {Promise<Object>} stats - attributes info
    */
   async stat(remotePath) {
     const _stat = (aPath) => {
@@ -302,9 +307,8 @@ class SftpClient {
             resolve(result);
           }
         });
-      }).finally((rsp) => {
+      }).finally(() => {
         removeTempListeners(this, 'stat');
-        return rsp;
       });
     };
 
@@ -314,11 +318,7 @@ class SftpClient {
       return _stat(absPath);
     } catch (err) {
       this._resetEventFlags();
-      if (err.custom) {
-        throw err;
-      } else {
-        throw fmtError(err, 'stat', err.code);
-      }
+      throw err.custom ? err : fmtError(err, 'stat', err.code);
     }
   }
 
@@ -330,7 +330,7 @@ class SftpClient {
    *
    * @param {string} remotePath - path to the object on the sftp server.
    *
-   * @return {Promise} returns false if object does not exist. Returns type of
+   * @return {Promise<Boolean|String>} returns false if object does not exist. Returns type of
    *                   object if it does
    */
   async exists(remotePath) {
@@ -369,17 +369,12 @@ class SftpClient {
           this.debugMsg(`exists: throw error ${err.message} ${err.code}`);
           throw err;
         }
-      } else {
-        this.debugMsg(`exists: ${remotePath} = false`);
-        return false;
       }
+      this.debugMsg(`exists: default ${remotePath} = false`);
+      return false;
     } catch (err) {
       this._resetEventFlags();
-      if (err.custom) {
-        throw err;
-      } else {
-        throw fmtError(err, 'exists', err.code);
-      }
+      throw err.custom ? err : fmtError(err, 'exists', err.code);
     }
   }
 
@@ -394,8 +389,7 @@ class SftpClient {
    *
    * @param {String} remotePath - path to remote directory
    * @param {RegExp} pattern - regular expression to match filenames
-   * @returns {Promise} array of file description objects
-   * @throws {Error}
+   * @returns {Promise<Array>} array of file description objects
    */
   list(remotePath, pattern = /.*/) {
     return new Promise((resolve, reject) => {
@@ -413,15 +407,15 @@ class SftpClient {
             if (fileList) {
               newList = fileList.map((item) => {
                 return {
-                  type: item.longname.substr(0, 1),
+                  type: item.longname.slice(0, 1),
                   name: item.filename,
                   size: item.attrs.size,
                   modifyTime: item.attrs.mtime * 1000,
                   accessTime: item.attrs.atime * 1000,
                   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, ''),
+                    user: item.longname.slice(1, 4).replace(reg, ''),
+                    group: item.longname.slice(4, 7).replace(reg, ''),
+                    other: item.longname.slice(7, 10).replace(reg, ''),
                   },
                   owner: item.attrs.uid,
                   group: item.attrs.gid,
@@ -442,10 +436,9 @@ class SftpClient {
           }
         });
       }
-    }).finally((rsp) => {
+    }).finally(() => {
       removeTempListeners(this, 'list');
       this._resetEventFlags();
-      return rsp;
     });
   }
 
@@ -462,7 +455,7 @@ class SftpClient {
    * @param {Object} options - options object with supported properties of readStreamOptions,
    *                          writeStreamOptions and pipeOptions.
    *
-   * @return {Promise}
+   * @return {Promise<String|Stream|Buffer>}
    */
   get(
     remotePath,
@@ -530,7 +523,7 @@ class SftpClient {
         }
         rdr.pipe(wtr, options.pipeOptions ? options.pipeOptions : {});
       }
-    }).finally((rsp) => {
+    }).finally(() => {
       removeTempListeners(this, 'get');
       this._resetEventFlags();
       if (
@@ -548,7 +541,6 @@ class SftpClient {
       ) {
         wtr.destroy();
       }
-      return rsp;
     });
   }
 
@@ -563,7 +555,7 @@ class SftpClient {
    * @param {String} remotePath
    * @param {String} localPath
    * @param {Object} options
-   * @return {Promise} the result of downloading the file
+   * @return {Promise<String>} the result of downloading the file
    */
   async fastGet(remotePath, localPath, options) {
     try {
@@ -583,7 +575,7 @@ class SftpClient {
         err.code = errorCode.badPath;
         throw err;
       }
-      await new Promise((resolve, reject) => {
+      let rslt = await new Promise((resolve, reject) => {
         if (haveConnection(this, 'fastGet', reject)) {
           this.debugMsg(
             `fastGet -> remote: ${remotePath} local: ${localPath} `,
@@ -598,10 +590,10 @@ class SftpClient {
             resolve(`${remotePath} was successfully download to ${localPath}!`);
           });
         }
-      }).finally((rsp) => {
+      }).finally(() => {
         removeTempListeners(this, 'fastGet');
-        return rsp;
       });
+      return rslt;
     } catch (err) {
       this._resetEventFlags();
       throw fmtError(err, 'fastGet');
@@ -619,7 +611,7 @@ class SftpClient {
    * @param {String} localPath
    * @param {String} remotePath
    * @param {Object} options
-   * @return {Promise} the result of downloading the file
+   * @return {Promise<String>} the result of downloading the file
    */
   fastPut(localPath, remotePath, options) {
     this.debugMsg(`fastPut -> local ${localPath} remote ${remotePath}`);
@@ -663,10 +655,9 @@ class SftpClient {
           resolve(`${localPath} was successfully uploaded to ${remotePath}!`);
         });
       }
-    }).finally((rsp) => {
+    }).finally(() => {
       removeTempListeners(this, 'fastPut');
       this._resetEventFlags();
-      return rsp;
     });
   }
 
@@ -680,12 +671,16 @@ class SftpClient {
    * @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}
+   * @return {Promise<String>}
    */
   put(
     localSrc,
     remotePath,
-    options = { readStreamOptions: {}, writeStreamOptions: {}, pipeOptions: {} }
+    options = {
+      readStreamOptions: {},
+      writeStreamOptions: { autoClose: true },
+      pipeOptions: {},
+    }
   ) {
     let wtr, rdr;
 
@@ -693,6 +688,7 @@ class SftpClient {
       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}`,
@@ -706,12 +702,16 @@ class SftpClient {
         addTempListeners(this, 'put', reject);
         wtr = this.sftp.createWriteStream(
           remotePath,
-          options.writeStreamOptions ? options.writeStreamOptions : {}
+          options.writeStreamOptions
+            ? { ...options.writeStreamOptions, autoClose: true }
+            : {}
         );
         wtr.once('error', (err) => {
+          this.debugMsg(`put: write stream error ${err.message}`);
           reject(fmtError(`${err.message} ${remotePath}`, 'put', err.code));
         });
-        wtr.once('finish', () => {
+        wtr.once('close', () => {
+          this.debugMsg('put: promise resolved');
           resolve(`Uploaded data stream to ${remotePath}`);
         });
         if (localSrc instanceof Buffer) {
@@ -722,13 +722,14 @@ class SftpClient {
             this.debugMsg(`put source is a file path: ${localSrc}`);
             rdr = fs.createReadStream(
               localSrc,
-              options.readStreamOptions ? options.readStreamOptons : {}
+              options.readStreamOptions ? options.readStreamOptions : {}
             );
           } else {
             this.debugMsg('put source is a stream');
             rdr = localSrc;
           }
           rdr.once('error', (err) => {
+            this.debugMsg(`put: read stream error ${err.message}`);
             reject(
               fmtError(
                 `${err.message} ${
@@ -742,7 +743,7 @@ class SftpClient {
           rdr.pipe(wtr, options.pipeOptions ? options.pipeOptions : {});
         }
       }
-    }).finally((resp) => {
+    }).finally(() => {
       removeTempListeners(this, 'put');
       this._resetEventFlags();
       if (
@@ -753,14 +754,6 @@ class SftpClient {
       ) {
         rdr.destroy();
       }
-      if (
-        wtr &&
-        options.writeStreamOptions &&
-        options.writeStreamOptions.autoClose === false
-      ) {
-        wtr.destroy();
-      }
-      return resp;
     });
   }
 
@@ -770,49 +763,45 @@ class SftpClient {
    * @param  {Buffer|stream} input
    * @param  {String} remotePath
    * @param  {Object} options
-   * @return {Promise}
+   * @return {Promise<String>}
    */
-  append(input, remotePath, options = {}) {
-    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'));
+  async append(input, remotePath, options = {}) {
+    const fileType = await this.exists(remotePath);
+    if (fileType && fileType === 'd') {
+      throw fmtError(
+        `Bad path: ${remotePath}: cannot append to a directory`,
+        'append',
+        errorCode.badPath
+      );
+    }
+    return await 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.on('error', (err_1) => {
+            reject(
+              fmtError(`${err_1.message} ${remotePath}`, 'append', err_1.code)
+            );
+          });
+          stream.on('finish', () => {
+            resolve(`Appended data to ${remotePath}`);
+          });
+          if (input instanceof Buffer) {
+            stream.write(input);
+            stream.end();
           } else {
-            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);
-            }
+            input.pipe(stream);
           }
         }
-      }).finally((rsp) => {
-        removeTempListeners(this, 'append');
-        this._resetEventFlags();
-        return rsp;
-      });
+      }
+    }).finally(() => {
+      removeTempListeners(this, 'append');
+      this._resetEventFlags();
     });
   }
 
@@ -823,7 +812,7 @@ class SftpClient {
    *
    * @param {string} remotePath - remote directory path.
    * @param {boolean} recursive - if true, recursively create directories
-   * @return {Promise}
+   * @return {Promise<String>}
    */
   async mkdir(remotePath, recursive = false) {
     const _mkdir = (p) => {
@@ -838,6 +827,12 @@ class SftpClient {
               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);
             }
@@ -846,10 +841,9 @@ class SftpClient {
             resolve(`${p} directory created`);
           }
         });
-      }).finally((rsp) => {
+      }).finally(() => {
         removeTempListeners(this, '_mkdir');
         this._resetEventFlags();
-        return rsp;
       });
     };
 
@@ -884,7 +878,7 @@ class SftpClient {
    * @param {string} remotePath - path to directory to be removed
    * @param {boolean} recursive - if true, remove directories/files in target
    *                             directory
-   * @return {Promise}
+   * @return {Promise<String>}
    */
   async rmdir(remotePath, recursive = false) {
     const _rmdir = (p) => {
@@ -898,9 +892,8 @@ class SftpClient {
           }
           resolve('Successfully removed directory');
         });
-      }).finally((rsp) => {
+      }).finally(() => {
         removeTempListeners(this, 'rmdir');
-        return rsp;
       });
     };
 
@@ -926,11 +919,7 @@ class SftpClient {
       return _rmdir(absPath);
     } catch (err) {
       this._resetEventFlags();
-      if (err.custom) {
-        throw err;
-      } else {
-        throw fmtError(err, 'rmdir', err.code);
-      }
+      throw err.custom ? err : fmtError(err, 'rmdir', err.code);
     }
   }
 
@@ -942,7 +931,7 @@ class SftpClient {
    * @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 deleted file' once resolved
+   * @return {Promise<String>} with string 'Successfully deleted file' once resolved
    *
    */
   delete(remotePath, notFoundOK = false) {
@@ -965,10 +954,9 @@ class SftpClient {
           resolve(`Successfully deleted ${remotePath}`);
         });
       }
-    }).finally((rsp) => {
+    }).finally(() => {
       removeTempListeners(this, 'delete');
       this._resetEventFlags();
-      return rsp;
     });
   }
 
@@ -980,7 +968,7 @@ class SftpClient {
    * @param {string} fromPath - path to the file to be renamed.
    * @param {string} toPath - path to the new name.
    *
-   * @return {Promise}
+   * @return {Promise<String>}
    *
    */
   rename(fromPath, toPath) {
@@ -1002,10 +990,9 @@ class SftpClient {
           resolve(`Successfully renamed ${fromPath} to ${toPath}`);
         });
       }
-    }).finally((rsp) => {
+    }).finally(() => {
       removeTempListeners(this, 'rename');
       this._resetEventFlags();
-      return rsp;
     });
   }
 
@@ -1018,7 +1005,7 @@ class SftpClient {
    * @param {string} fromPath - path to the file to be renamed.
    * @param {string} toPath - path  the new name.
    *
-   * @return {Promise}
+   * @return {Promise<String>}
    *
    */
   posixRename(fromPath, toPath) {
@@ -1040,10 +1027,9 @@ class SftpClient {
           resolve(`Successful POSIX rename ${fromPath} to ${toPath}`);
         });
       }
-    }).finally((rsp) => {
+    }).finally(() => {
       removeTempListeners(this, 'posixRename');
       this._resetEventFlags();
-      return rsp;
     });
   }
 
@@ -1055,7 +1041,7 @@ class SftpClient {
    * @param {string} remotePath - path to the remote target object.
    * @param {number | string} mode - the new octal mode to set
    *
-   * @return {Promise}
+   * @return {Promise<String>}
    */
   chmod(remotePath, mode) {
     return new Promise((resolve, reject) => {
@@ -1067,10 +1053,9 @@ class SftpClient {
         }
         resolve('Successfully change file mode');
       });
-    }).finally((rsp) => {
+    }).finally(() => {
       removeTempListeners(this, 'chmod');
       this._resetEventFlags();
-      return rsp;
     });
   }
 
@@ -1084,8 +1069,7 @@ class SftpClient {
    * @param {String} dstDir - remote destination directory
    * @param {RegExp} filter - (Optional) a regular expression used to select
    *                         files and directories to upload
-   * @returns {String}
-   * @throws {Error}
+   * @returns {Promise<String>}
    */
   async uploadDir(srcDir, dstDir, filter = /.*/) {
     try {
@@ -1130,11 +1114,7 @@ class SftpClient {
       return `${srcDir} uploaded to ${dstDir}`;
     } catch (err) {
       this._resetEventFlags();
-      if (err.custom) {
-        throw err;
-      } else {
-        throw fmtError(err, 'uploadDir');
-      }
+      throw err.custom ? err : fmtError(err, 'uploadDir');
     }
   }
 
@@ -1148,8 +1128,7 @@ class SftpClient {
    * @param {String} dstDir - local destination directory
    * @param {RegExp} filter - (Optional) a regular expression used to select
    *                         files and directories to upload
-   * @returns {Promise}
-   * @throws {Error}
+   * @returns {Promise<String>}
    */
   async downloadDir(srcDir, dstDir, filter = /.*/) {
     try {
@@ -1191,11 +1170,7 @@ class SftpClient {
       return `${srcDir} downloaded to ${dstDir}`;
     } catch (err) {
       this._resetEventFlags();
-      if (err.custom) {
-        throw err;
-      } else {
-        throw fmtError(err, 'downloadDir', err.code);
-      }
+      throw err.custom ? err : fmtError(err, 'downloadDir', err.code);
     }
   }
 
@@ -1204,6 +1179,7 @@ class SftpClient {
    *
    * End the SFTP connection
    *
+   * @returns {Promise<Boolean>}
    */
   end() {
     let endCloseHandler;
@@ -1220,13 +1196,12 @@ class SftpClient {
         this.debugMsg('end: Have connection - calling end()');
         this.client.end();
       }
-    }).finally((resp) => {
+    }).finally(() => {
       this.debugMsg('end: finally clause fired');
       removeTempListeners(this, 'end');
       this.removeListener('close', endCloseHandler);
       this.endCalled = false;
       this._resetEventFlags();
-      return resp;
     });
   }
 }

package/src/utils.js

@@ -99,7 +99,7 @@ function endListener(client, name, reject) {
         client.debugMsg(`${name}: handling end event with reject'`);
         reject(fmtError('Unexpected end event raised', name));
       } else {
-        client.debugMst(`${name}: handling end event with throw`);
+        client.debugMsg(`${name}: handling end event with throw`);
         throw fmtError('Unexpected end event raised', name);
       }
     }
@@ -157,26 +157,16 @@ function removeTempListeners(obj, name) {
  * @returns {string | boolean} returns a string for object type if it exists, false otherwise
  */
 function localExists(filePath) {
-  try {
-    const stats = fs.statSync(filePath);
-    if (stats.isSymbolicLink()) {
-      return 'l';
-    } else if (stats.isDirectory()) {
-      return 'd';
-    } else if (stats.isSocket()) {
-      return 's';
-    } else if (stats.isFile()) {
-      return '-';
-    } else {
-      throw fmtError(
-        `Bad path: ${filePath}: unsupported file type`,
-        'localExists',
-        errorCode.badPath
-      );
-    }
-  } catch (err) {
+  const stats = fs.statSync(filePath, { throwIfNoEntry: false });
+  if (!stats) {
+    return false;
+  } else if (stats.isDirectory()) {
+    return 'd';
+  } else if (stats.isFile()) {
+    return '-';
+  } else {
     throw fmtError(
-      `Bad path: ${filePath}: not exist`,
+      `Bad path: ${filePath}: target must be a file or directory`,
       'localExists',
       errorCode.badPath
     );
@@ -213,23 +203,33 @@ function haveLocalAccess(filePath, mode = 'r') {
       code: 0,
     };
   } catch (err) {
-    if (err.errno === -2) {
-      return {
-        status: false,
-        type: null,
-        details: 'not exist',
-        code: -2,
-      };
-    } else if (err.errno === -13) {
-      const type = localExists(filePath);
-      return {
-        status: false,
-        type: type,
-        details: 'permission denied',
-        code: -13,
-      };
-    } else {
-      throw err;
+    switch (err.errno) {
+      case -2:
+        return {
+          status: false,
+          type: null,
+          details: 'not exist',
+          code: -2,
+        };
+      case -13:
+        return {
+          status: false,
+          type: localExists(filePath),
+          details: 'permission denied',
+          code: -13,
+        };
+      case -20:
+        return {
+          status: false,
+          type: null,
+          details: 'parent not a directory',
+        };
+      default:
+        return {
+          status: false,
+          type: null,
+          details: err.message,
+        };
     }
   }
 }
@@ -246,14 +246,29 @@ function haveLocalAccess(filePath, mode = 'r') {
 function haveLocalCreate(filePath) {
   const { status, details, type } = haveLocalAccess(filePath, 'w');
   if (!status && details === 'permission denied') {
-    throw new Error(`Bad path: ${filePath}: permission denied`);
+    //throw new Error(`Bad path: ${filePath}: permission denied`);
+    return {
+      status,
+      details,
+      type,
+    };
   } else if (!status) {
     const dirPath = path.dirname(filePath);
     const localCheck = haveLocalAccess(dirPath, 'w');
     if (localCheck.status && localCheck.type !== 'd') {
-      throw new Error(`Bad path: ${dirPath}: not a directory`);
+      //throw new Error(`Bad path: ${dirPath}: not a directory`);
+      return {
+        status: false,
+        details: `${dirPath}: not a directory`,
+        type: null,
+      };
     } else if (!localCheck.status) {
-      throw new Error(`Bad path: ${dirPath}: ${localCheck.details}`);
+      //throw new Error(`Bad path: ${dirPath}: ${localCheck.details}`);
+      return {
+        status: localCheck.status,
+        details: `${dirPath}: ${localCheck.details}`,
+        type: null,
+      };
     } else {
       return {
         status: true,
@@ -270,10 +285,10 @@ async function normalizeRemotePath(client, aPath) {
   try {
     if (aPath.startsWith('..')) {
       let root = await client.realPath('..');
-      return root + client.remotePathSep + aPath.substring(3);
+      return root + client.remotePathSep + aPath.slice(3);
     } else if (aPath.startsWith('.')) {
       let root = await client.realPath('.');
-      return root + client.remotePathSep + aPath.substring(2);
+      return root + client.remotePathSep + aPath.slice(2);
     }
     return aPath;
   } catch (err) {

package/CHANGELOG.org

@@ -1,245 +0,0 @@
-* Change Logging
-
-** v7.0.1
-   - New version based on ssh2 version 1.2.0
-   - Added some additional path checks to deal with poor error messages and
-     unreliable behaviour when connecting to an sftp server on Windows based
-     platforms.
-   - Added additional tests for local resources (files/directories) to provide
-     better error handling and informative error messages.
-   - Updated README to provide more info on managing exceptions
-   - Changed behaviour of global error handler. This error handler now just logs
-     the error to the console and sets the client.sftp property to undefined to
-     ensure any subsequent calls to client methods fail immediately with an
-     error indicating there is no active connection.
-     
-** V7.0.0
-   - New version based on new SSH2 version 1.1.0.
-   - Expand option handling for get() and put() methods *Breaking Change*
-   - Re-factored the retry code in the connect() method
-   - Improve error reporting for adding/removing listeners
-   - Extend localExists() method to also verify read or write access
-       
-** V6.0.1
-   - Fix issue with connect retry not releasing 'ready' listeners
-   - Add finally clauses to all promises to ensure temporary listeners are deleted
-   - Add nyc module to report on code test coverage
-   - Add additional utils tests to increase test coverage
-   - Removed some dead code and unused utility functions to reduce download size
-   - Cleanup tests and reduce inter-test dependencies
-
-** V6.0.0.0
-   - Update connection retry code to use the promise-retry module instead of
-     plain rety module
-   - Added optional filter argument for uploadDir/downlDir to select which files
-     and directories are included
-   - Added an optional boolean argument to delete to turn off raising an error
-     when delete target does not exists
-   - Reduced/simplified argument verification code to reduce package size and
-     increase performance
-   - Refactored handling of events and add default close and error listeners to
-     catch connections closed abruptly without an error being raised.
-
-** V5.3.2
-   - Minor README typo fixes
-   - Fix error in local file path checks (#294)
-
-** V5.3.1
-   - Fix bug in handling of relative local paths
-   - Change handling of stream closures in ~get()~ and ~put()~ methods
-
-** v5.3.0
-   - Refine event handler management
-   - Fix path processing for win32 based sftp servers
-   - Update documentation
-** v5.2.2
-   - Bug fix release. Add error code 4 check to stat() method.
-   - bump Mocha version for tests
-
-** v5.2.1
-   - Move some dependencies into dev-Dependencies
-** v5.2.0
-   - Add new method posixRename() which uses the openSSH POSIX rename extension.
-** v5.1.3
-   - Fix bug when writing to root directory and failure due to not being able to
-     determine parent
-   - Refactor some tests to eliminate need to have artificial delays between
-     tests
-   - Bumped some dependency versions to latest version
-** v5.1.2
-   - Added back global close handler
-   - Added dumpListeners() method
-
-** v5.1.1
-   - Added separate close handlers to each method.
-   - Added missing return statement in connect method
-   - Added additional troubleshooting documentation for
-     common errors.
-
-** v5.1.0
-   - Fix bug in checkRemotePath() relating to handling of badly
-     specified paths (issue #213)
-   - Added additional debugging support
-   - Add missing test for valid connection in end() method.
-   - Bump ssh2 version to v0.8.8
-
-** v5.0.2
-   - Fix bugs related to win32 platform and local tests for valid directories
-   - Fix problem with parsing of file paths
-
-** v5.0.1
-   - Turn down error checking to be less stringent and handle situations
-     where user does not have read permission on parent directory.
-
-** v5.0.0
-   - Added two new methods ~uploadDir()~ and ~downloadDir()~
-   - Removed deprecated ~auxList()~ method
-   - Improved error message consistency
-   - Added additional error checking to enable more accurate and useful error
-     messages.
-   - Added default error handler to deal with event errors which fire outside of
-     active SftpClient methods (i.e. connection unexpectedly reset by remote host).
-   - Modified event handlers to ensure that only event handlers added by the
-     module are removed by the module (users now responsible for removing any
-     custom event handlers they add).
-   - Module error handlers added using ~prependListener~ to ensure they are
-     called before any additional custom handlers added by client code.
-   - Any error events fired during an ~end()~ call are now ignored.
-
-** v4.3.1
-   - Updated end() method to resolve once close event fires
-   - Added errorListener to error event in each promise to catch error events
-     and reject the promise. This should resolve the issue of some error events
-     causing uncaughtException erros and causing the process to exit.
-
-** v4.3.0
-   - Ensure errors include an err.code property and pass through the error code
-     from the originating error
-   - Change tests for error type to use ~error.code~ instead of matching on
-     ~error.message~.
-
-** v4.2.4
-   - Bumped ssh2 to v0.8.6
-   - Added exists() usage example to examples directory
-   - Clarify documentation on get() method
-** v4.2.3
-   - Fix bug in ~exist()~ where tests on root directory returned false
-   - Minor documentation fixes
-   - Clean up mkdir example
-
-** v4.2.2
-   - Minor documentation fixes
-   - Added additional examples in the ~example~ directory
-
-** v4.2.1
-   - Remove default close listener. changes in ssh2 API removed the utility of a
-     default close listener
-   - Fix path handling. Under mixed environments (where client platform and
-     server platform were different i.e. one windows the other unix), path
-     handling was broken due tot he use of path.join().
-   - Ensure error messages include path details. Instead of errors such as "No
-     such file" now report "No such file /path/to/missing/file" to help with
-     debugging
-
-** v4.2.0
-   - Work-around for SSH2 =end= event bug
-   - Added ability to set client name in constructor method
-   - Added additional error checking to prevent ~connect()~ being called on
-     already connected client
-   - Added additional examples in =example= directory
-
-** v4.1.0
-   - move ~end()~ call to resolve into close hook
-   - Prevent ~put()~ and ~get()~ from creating empty files in destination when
-     unable to read source
-   - Expand tests for operations when lacking required permissions
-   - Add additional data checks for ~append()~
-     - Verify file exists
-     - Verify file is writeable
-     - Verify file is a regular file
-   - Fix handling of relative paths
-   - Add ~realPath()~ method
-   - Add ~cwd()~ method
-
-** v4.0.4
-   - Minor documentation fix
-   - Fix return value from ~get()~
-
-** v4.0.3
-   - Fix bug in mkdir() relating to handling of relative paths
-   - Modify exists() to always return 'd' if path is '.'
-
-** v4.0.2
-   - Fix some minor packaging issues
-
-** v4.0.0
-   - Remove support for node < 8.x
-   - Fix connection retry feature
-   - sftp connection object set to null when 'end' signal is raised
-   - Removed 'connectMethod' argument from connect method.
-   - Refined adding/removing of listeners in connect() and end() methods to enable
-     errors to be adequately caught and reported.
-   - Deprecate auxList() and add pattern/regexp filter option to list()
-   - Refactored handling of event signals to provide better feedback to clients
-   - Removed pointless 'permissions' property from objects returned by ~stat()~
-     (same as mode property). Added additional properties describing the type of
-     object.
-   - Added the ~removeListener()~ method to compliment the existing ~on()~ method.
-
-** Older Versions
-*** v2.5.2
-    - Repository transferred to theophilusx
-    - Fix error in package.json pointing to wrong repository
-
-*** v2.5.1
-    - Apply 4 pull requests to address minor issues prior to transfer
-
-*** v2.5.0
-    - ???
-
-*** v2.4.3
-    - merge #108, #110
-      - fix connect promise if connection ends
-
-*** v2.4.2
-    - merge #105
-      - fix windows path
-
-*** v2.4.1
-    - merge pr #99, #100
-      - bug fix
-
-*** v2.4.0
-    - Requires node.js v7.5.0 or above.
-    - merge pr #97, thanks for @theophilusx
-      - Remove emitter.maxListener warnings
-      - Upgraded ssh2 dependency from 0.5.5 to 0.6.1
-      - Enhanced error messages to provide more context and to be more consistent
-      - re-factored test
-      - Added new 'exists' method and re-factored mkdir/rmdir
-
-*** v2.3.0
-    - add: ~stat~ method
-    - add ~fastGet~ and ~fastPut~ method.
-    - fix: ~mkdir~ file exists decision logic
-
-*** v3.0.0 -- deprecate this version
-   - change: ~sftp.get~ will return chunk not stream anymore
-   - fix: get readable not emitting data events in node 10.0.0
-
-*** v2.1.1
-    - add: event listener. [[https://github.com/jyu213/ssh2-sftp-client#Event][doc]]
-    - add: ~get~ or ~put~ method add extra options [[https://github.com/jyu213/ssh2-sftp-client/pull/52][pr#52]]
-
-*** v2.0.1
-    - add: ~chmod~ method [[https://github.com/jyu213/ssh2-sftp-client/pull/33][pr#33]]
-    - update: upgrade ssh2 to V0.5.0 [[https://github.com/jyu213/ssh2-sftp-client/pull/30][pr#30]]
-    - fix: get method stream error reject unwork [[https://github.com/jyu213/ssh2-sftp-client/issues/22][#22]]
-    - fix: return Error object on promise rejection [[https://github.com/jyu213/ssh2-sftp-client/pull/20][pr#20]]
-
-*** v1.1.0
-    - fix: add encoding control support for binary stream
-
-*** v1.0.5:
-    - fix: multi image upload
-    - change: remove ~this.client.sftp~ to ~connect~ function