ssh2-sftp-client 5.2.1 → 5.3.2

package/README.md

@@ -1,4 +1,4 @@
-- [SSH2 SFTP Client](#sec-1)
+- [Overview](#sec-1)
 - [Installation](#sec-2)
 - [Basic Usage](#sec-3)
 - [Version 5.x](#sec-4)
@@ -14,6 +14,10 @@
   - [Version 5.1.3](#sec-4-8)
   - [Version 5.2.0](#sec-4-9)
   - [Version 5.2.1](#sec-4-10)
+  - [Version 5.2.2](#sec-4-11)
+  - [Version 5.3.0](#sec-4-12)
+  - [Version 5.3.1](#sec-4-13)
+  - [Version 5.3.2](#sec-4-14)
 - [Documentation](#sec-5)
   - [Specifying Paths](#sec-5-1)
   - [Methods](#sec-5-2)
@@ -39,49 +43,19 @@
     - [downloadDir(srcDir, dstDir) ==> string](#sec-5-2-20)
     - [end() ==> boolean](#sec-5-2-21)
     - [Add and Remove Listeners](#sec-5-2-22)
-- [FAQ](#sec-6)
-  - [Remote server drops connections with only an end event](#sec-6-1)
-  - [How can you pass writable stream as dst for get method?](#sec-6-2)
-  - [How can I upload files without having to specify a password?](#sec-6-3)
-  - [How can I connect through a Socks Proxy](#sec-6-4)
-  - [Timeout while waiting for handshake or handshake errors](#sec-6-5)
-- [Examples](#sec-7)
-- [Change Log](#sec-8)
-  - [v5.2.1 (Prod Version)](#sec-8-1)
-  - [v5.2.0](#sec-8-2)
-  - [v5.1.3](#sec-8-3)
-  - [v5.1.2](#sec-8-4)
-  - [v5.1.1](#sec-8-5)
-  - [v5.1.0](#sec-8-6)
-  - [v5.0.2](#sec-8-7)
-  - [v5.0.1](#sec-8-8)
-  - [v5.0.0](#sec-8-9)
-  - [v4.3.1](#sec-8-10)
-  - [v4.3.0](#sec-8-11)
-  - [v4.2.4](#sec-8-12)
-  - [v4.2.3](#sec-8-13)
-  - [v4.2.2](#sec-8-14)
-  - [v4.2.1](#sec-8-15)
-  - [v4.2.0](#sec-8-16)
-  - [v4.1.0](#sec-8-17)
-  - [v4.0.4](#sec-8-18)
-  - [v4.0.3](#sec-8-19)
-  - [v4.0.2](#sec-8-20)
-  - [v4.0.0](#sec-8-21)
-  - [Older Versions](#sec-8-22)
-    - [v2.5.2](#sec-8-22-1)
-    - [v2.5.1](#sec-8-22-2)
-    - [v2.5.0](#sec-8-22-3)
-    - [v2.4.3](#sec-8-22-4)
-    - [v2.4.2](#sec-8-22-5)
-    - [v2.4.1](#sec-8-22-6)
-    - [v2.4.0](#sec-8-22-7)
-    - [v2.3.0](#sec-8-22-8)
-    - [v3.0.0 – deprecate this version](#sec-8-22-9)
-    - [v2.1.1](#sec-8-22-10)
-    - [v2.0.1](#sec-8-22-11)
-    - [v1.1.0](#sec-8-22-12)
-    - [v1.0.5:](#sec-8-22-13)
+- [Platform Quirks & Warnings](#sec-6)
+  - [Server Capabilities](#sec-6-1)
+  - [Promises & Events](#sec-6-2)
+  - [Windows Based Servers](#sec-6-3)
+  - [Don't Re-use SftpClient Objects](#sec-6-4)
+- [FAQ](#sec-7)
+  - [Remote server drops connections with only an end event](#sec-7-1)
+  - [How can I pass writable stream as dst for get method?](#sec-7-2)
+  - [How can I upload files without having to specify a password?](#sec-7-3)
+  - [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)
+- [Examples](#sec-8)
 - [Troubleshooting](#sec-9)
   - [Common Errors](#sec-9-1)
     - [Not returning the promise in a `then()` block](#sec-9-1-1)
@@ -92,19 +66,28 @@
 - [Pull Requests](#sec-11)
 - [Contributors](#sec-12)
 
-# SSH2 SFTP Client<a id="sec-1"></a>
+
+# Overview<a id="sec-1"></a>
 
 an SFTP client for node.js, a wrapper around [SSH2](https://github.com/mscdex/ssh2) which provides a high level 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 [SSH2](https://github.com/mscdex/ssh2) and [SSH2-STREAMS](https://github.com/mscdex/ssh2-streams/blob/master/SFTPStream.md) project pages.
 
-Current stable release is **v5.2.1**.
+Current stable release is **v5.3.2**.
 
 Code has been tested against Node versions 12.18.2 and 13.14.0
 
 Node versions < 10.x are not supported.
 
-<span class="underline">WARNING</span> There is currently an issue with both the fastPut() and fastGet() methods when using Node versions greater than 14.0.0. This is a bug in the underlying ssh2-streams library and needs to be fixed upstream. The issue appears to be related to the concurrency operations of these two functions. A workaround is to set concurrency to 1 using the options object. Alternatively, use get() or put(), which do not use concurrency and which will provide the same performance as fastGet() or fastPut() when they are set to use a concurrency of 1. A bug report has been logged against the ssh2-streams library as [issue 156](https://github.com/mscdex/ssh2-streams/issues/156).
+<span class="underline">WARNING</span> There is currently a regression error with versions of node later than version 14.0. It appears that when using streams with chunk sizes which exceed the high water mark for the stream, a drain event is no longer emitted. As a result, streams with sufficient data will hang indefinitely. This appears to affect fastput, fastget, put and possibly get operations. Until this issue is resolved and a new version of ssh2/ssh2-streams is released, using node v14 is not recommended.
+
+A bug report hass been logged against the ssh2-streams library as [issue 156](https://github.com/mscdex/ssh2-streams/issues/156).
+
+<span class="underline">UPDATE</span>: The author of the upstream ssh2 and ssh2-streams module has decided on a re-write of the ssh2 module to address the above issues as well as some other design limitations and to allow the module to better fit in with newer versions of node. As part of that process, the functionality of ssh2-streams is being incorporated into the main ssh2 module and the ssh2-streams module is being deprecated. This will require a significant update to this module and may result in some API changes, depending on what changes in the re-write of ssh2.
+
+To support these changes, a new branch called *version-6* has been created. This branch will use the newest version of ssh2 and for now is very much experimental and subject to change.
+
+<span class="underline">UPDATE</span>: Apparently the change in core node which cause the issue with ssh2 has been rolled back in node version 15.3.0. Testing seems to indicate the above issue does not exist in that version of node.
 
 # Installation<a id="sec-2"></a>
 
@@ -222,6 +205,26 @@ In addition to the Promise error handlers, there is a default error handler whic
 
 -   Move some dev dependencies from dependencies to devDependencies.
 
+## Version 5.2.2<a id="sec-4-11"></a>
+
+-   Bug fix. Some servers appear to issue errors with code 4 instead of code 2 for file not found errors. This version adds checks for error code 4 to the stat() method. Thanks to teenangst for the fix.
+
+## Version 5.3.0<a id="sec-4-12"></a>
+
+-   Add code to only add connect() and end() event handlers if they are not already active. For connect(), remove event handlers as late as possible to help catch error events raised late on some platforms (like win32). don't remove end() error handler as some platforms, like win32, send an additional error event even after a successful and requested end() call.
+-   Fix path handling when connecting to a remoe SFTP server running on win32 platform. Assume server honours 'nix' path convention rather than using native win32 path format.
+-   Add additional documentation on events/promises, platform quirks and platform differences.
+
+## Version 5.3.1<a id="sec-4-13"></a>
+
+-   Fix bug in handling of relative local paths
+-   Modified `get()` and `put()` methods to support special purpose streams which require `autoClose` to be `false`. These methods will now look for the `autoClose: false` property in the options object and if it is false, will issue a `destroy()` on the underlying stream just before the promise is resolved. The default is `autoClose: true` and this default should be used unless there is a known specific reason to change it to false.
+
+## Version 5.3.2<a id="sec-4-14"></a>
+
+-   Minor README typo fixes
+-   Fix error in local file path checks (#294)
+
 # Documentation<a id="sec-5"></a>
 
 The connection options are the same as those offered by the underlying SSH2 module. For full details, please see [SSH2 client methods](https://github.com/mscdex/ssh2#user-content-client-methods)
@@ -230,6 +233,8 @@ All the methods will return a Promise, except for `on()` and `removeListener()`,
 
 ## Specifying Paths<a id="sec-5-1"></a>
 
+The convention with both FTP and SFTP is that paths are specified using a 'nix' style i.e. use '*' as the path separator. This means that even if your SFTP server is running on a win32 platform, you should use '*' instead of '\\' as the path separator. For example, for a win32 path of 'C:\Users\fred' you would actually use '/C:/Users/fred'. If your win32 server does not support the 'nix' path convention, you can try setting the `remotePathSep` property of the `SftpClient` object to the path separator of your remote server. This **might** work, but has not been tested. Please let me know if you need to do this and provide details of the SFTP server so that I can try to create an appropriate environment and adjust things as necessary. At this point, I'm not aware of any win32 based SFTP servers which do not support the 'nix' path convention.
+
 All remote paths must either be absolute e.g. `/absolute/path/to/file` or they can be relative with a prefix of either `./` (relative to current remote directory) or `../` (relative to parent of current remote directory) e.g. `./relative/path/to/file` or `../relative/to/parent/file`. It is also possible to do things like `../../../file` to specify the parent of the parent of the parent of the current remote directory. The shell tilde (`~`) and common environment variables like `$HOME` are NOT supported.
 
 It is important to recognise that the current remote directory may not always be what you may expect. A lot will depend on the remote platform of the SFTP server and how the SFTP server has been configured. When things don't seem to be working as expected, it is often a good idea to verify your assumptions regarding the remote directory and remote paths. One way to do this is to login using a command line program like `sftp` or `lftp`.
@@ -270,17 +275,17 @@ Constructor to create a new `ssh2-sftp-client` object. An optional `name` string
 
     ```javascript
     'use strict';
-    
+
     const Client = require('ssh2-sftp-client');
-    
+
     const config = {
       host: 'example.com',
       username: 'donald',
       password: 'my-secret'
     };
-    
+
     const sftp = new Client('example-client');
-    
+
     sftp.connect(config)
       .then(() => {
         return sftp.cwd();
@@ -301,12 +306,12 @@ Connect to an sftp server. Full documentation for connection options is availabl
 1.  Connection Options
 
     This module is based on the excellent [SSH2](https://github.com/mscdex/ssh2#client) module. That module is a general SSH2 client and server library and provides much more functionality than just SFTP connectivity. Many of the connect options provided by that module are less relevant for SFTP connections. It is recommended you keep the config options to the minimum needed and stick to the options listed in the `commonOpts` below.
-    
+
     The `retries`, `retry_factor` and `retry_minTimeout` options are not part of the SSH2 module. These are part of the configuration for the [retry](https://www.npmjs.com/package/retry) package and what is used to enable retrying of sftp connection attempts. See the documentation for that package for an explanation of these values.
-    
+
     ```javascript
     // common options
-    
+
     let commonOpts {
       host: 'localhost', // string Hostname or IP of server.
       port: 22, // Port number of the server.
@@ -316,7 +321,7 @@ Connect to an sftp server. Full documentation for connection options is availabl
       password: 'borsch', // string Password for password-based user authentication
       agent: process.env.SSH_AGENT, // string - Path to ssh-agent's UNIX socket
       privateKey: fs.readFileSync('/path/to/key'), // Buffer or string that contains
-      passphrase; 'a pass phrase', // string - For an encrypted private key
+      passphrase: 'a pass phrase', // string - For an encrypted private key
       readyTimeout: 20000, // integer How long (in ms) to wait for the SSH handshake
       strictVendor: true // boolean - Performs a strict server vendor check
       debug: myDebug // function - Set this to a function that receives a single
@@ -325,9 +330,9 @@ Connect to an sftp server. Full documentation for connection options is availabl
       retry_factor: 2 // integer. Time factor used to calculate time between retries
       retry_minTimeout: 2000 // integer. Minimum timeout between attempts
     };
-    
+
     // rarely used options
-    
+
     let advancedOpts {
       localAddress,
       localPort,
@@ -368,16 +373,16 @@ Retrieves a directory listing. This method returns a Promise, which once realise
 
     ```javascript
     const Client = require('ssh2-sftp-client');
-    
+
     const config = {
       host: 'example.com',
       port: 22,
       username: 'red-don',
       password: 'my-secret'
     };
-    
+
     let sftp = new Client;
-    
+
     sftp.connect(config)
       .then(() => {
         return sftp.list('/path/to/remote/dir');
@@ -396,7 +401,7 @@ Retrieves a directory listing. This method returns a Promise, which once realise
 2.  Return Objects
 
     The objects in the array returned by `list()` have the following properties;
-    
+
     ```javascript
     {
       type: // file type(-, d, l)
@@ -417,11 +422,11 @@ Retrieves a directory listing. This method returns a Promise, which once realise
 3.  Pattern Filter
 
     The filter options can be a regular expression (most powerful option) or a simple *glob*-like string where \* will match any number of characters, e.g.
-    
+
         foo* => foo, foobar, foobaz
         *bar => bar, foobar, tabbar
         *oo* => foo, foobar, look, book
-    
+
     The *glob*-style matching is very simple. In most cases, you are best off using a real regular expression which will allow you to do more powerful matching and anchor matches to the beginning/end of the string etc.
 
 ### exists(path) ==> boolean<a id="sec-5-2-4"></a>
@@ -432,16 +437,16 @@ Tests to see if remote file or directory exists. Returns type of remote object i
 
     ```javascript
     const Client = require('ssh2-sftp-client');
-    
+
     const config = {
       host: 'example.com',
       port: 22,
       username: 'red-don',
       password: 'my-secret'
     };
-    
+
     let sftp = new Client;
-    
+
     sftp.connect(config)
       .then(() => {
         return sftp.exists('/path/to/remote/dir');
@@ -466,7 +471,7 @@ Returns the attributes associated with the object pointed to by `path`.
 1.  Attributes
 
     The `stat()` method returns an object with the following properties;
-    
+
     ```javascript
     let stats = {
       mode: 33279, // integer representing type and permissions
@@ -489,7 +494,7 @@ Returns the attributes associated with the object pointed to by `path`.
 
     ```javascript
     let client = new Client();
-    
+
     client.connect(config)
       .then(() => {
         return client.stat('/path/to/remote/file');
@@ -518,7 +523,7 @@ In general, if your going to pass in a string as the destination, you are better
 1.  Options
 
     The options object can be used to pass options to the underlying readStream used to read the data from the remote server.
-    
+
     ```javascript
     {
       flags: 'r',
@@ -528,17 +533,17 @@ In general, if your going to pass in a string as the destination, you are better
       autoClose: true
     }
     ```
-    
+
     Most of the time, you won't want to use any options. Sometimes, it may be useful to set the encoding. For example, to 'utf-8'. However, it is important not to do this for binary files to avoid data corruption.
 
 2.  Example Use
 
     ```javascript
     let client = new Client();
-    
+
     let remotePath = '/remote/server/path/file.txt';
     let dst = fs.createWriteStream('/local/file/path/copy.txt');
-    
+
     client.connect(config)
       .then(() => {
         return client.get(remotePath, dst);
@@ -550,7 +555,7 @@ In general, if your going to pass in a string as the destination, you are better
         console.error(err.message);
       });
     ```
-    
+
     -   **Tip:** See examples file in the Git repository for more examples. You can pass any writeable stream in as the destination. For example, if you pass in `zlib.createGunzip()` writeable stream, you can both download and decompress a gzip file 'on the fly'.
 
 ### fastGet(remotePath, localPath, options) ===> string<a id="sec-5-2-7"></a>
@@ -571,7 +576,7 @@ Downloads a file at remotePath to localPath using parallel reads for faster thro
                                                       // chunk is transferred
     }
     ```
-    
+
     -   **Warning:** Some servers do not respond correctly to requests to alter chunk size. This can result in lost or corrupted data.
 
 2.  Sample Use
@@ -580,7 +585,7 @@ Downloads a file at remotePath to localPath using parallel reads for faster thro
     let client = new Client();
     let remotePath = '/server/path/file.txt';
     let localPath = '/local/path/file.txt';
-    
+
     client.connect(config)
       .then(() => {
         client.fastGet(remotePath, localPath);
@@ -604,7 +609,7 @@ Upload data from local system to remote server. If the `src` argument is a strin
 1.  Options
 
     The following options are supported;
-    
+
     ```javascript
     {
       flags: 'w',  // w - write and a - append
@@ -613,17 +618,17 @@ Upload data from local system to remote server. If the `src` argument is a strin
       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.
 
 2.  Example Use
 
     ```javascript
     let client = new Client();
-    
+
     let data = fs.createReadStream('/path/to/local/file.txt');
     let remote = '/path/to/remote/file.txt';
-    
+
     client.connect(config)
       .then(() => {
         return client.put(data, remote);
@@ -635,7 +640,7 @@ Upload data from local system to remote server. If the `src` argument is a strin
         console.error(err.message);
       });
     ```
-    
+
     -   **Tip:** If the src argument is a path string, consider just using `fastPut()`.
 
 ### fastPut(localPath, remotePath, options) ==> string<a id="sec-5-2-9"></a>
@@ -657,7 +662,7 @@ Uploads the data in file at `localPath` to a new file on remote server at `remot
       // a part of a file was transferred
     }
     ```
-    
+
     -   **Warning:** There have been reports that some SFTP servers will not honour requests for non-default chunk sizes. This can result in data loss or corruption.
 
 2.  Example Use
@@ -666,7 +671,7 @@ Uploads the data in file at `localPath` to a new file on remote server at `remot
     let localFile = '/path/to/file.txt';
     let remoteFile = '/path/to/remote/file.txt';
     let client = new Client();
-    
+
     client.connect(config)
       .then(() => {
         client.fastPut(localFile, remoteFile);
@@ -690,7 +695,7 @@ Append the `input` data to an existing remote file. There is no integrity checki
 1.  Options
 
     The following options are supported;
-    
+
     ```javascript
     {
       flags: 'a',  // w - write and a - append
@@ -699,7 +704,7 @@ Append the `input` data to an existing remote file. There is no integrity checki
       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. Generally, I would not attempt to append binary files.
 
 2.  Example Use
@@ -707,7 +712,7 @@ Append the `input` data to an existing remote file. There is no integrity checki
     ```javascript
     let remotePath = '/path/to/remote/file.txt';
     let client = new Client();
-    
+
     client.connect(config)
       .then(() => {
         return client.append(Buffer.from('Hello world'), remotePath);
@@ -732,7 +737,7 @@ Create a new directory. If the recursive flag is set to true, the method will cr
     ```javascript
     let remoteDir = '/path/to/new/dir';
     let client = new Client();
-    
+
     client.connect(config)
       .then(() => {
         return client.mkdir(remoteDir, true);
@@ -752,12 +757,14 @@ Remove a directory. If removing a directory and recursive flag is set to `true`,
 -   **path:** string. Path to remote directory
 -   **recursive:** boolean. If true, remove all files and directories in target directory. Defaults to false
 
+**Note**: There has been at least one report that some SFTP servers will allow non-empty directories to be removed even without the recursive flag being set to true. While this is not standard behaviour, it is recommended that users verify the behaviour of rmdir if there are plans to rely on the recursive flag to prevent removal of non-empty directories.
+
 1.  Example Use
 
     ```javascript
     let remoteDir = '/path/to/remote/dir';
     let client = new Client();
-    
+
     client.connect(config)
       .then(() => {
         return client.rmdir(remoteDir, true);
@@ -781,7 +788,7 @@ Delete a file on the remote server.
     ```javascript
     let remoteFile = '/path/to/remote/file.txt';
     let client = new Client();
-    
+
     client.connect(config)
       .then(() => {
         return client.delete(remoteFile);
@@ -807,7 +814,7 @@ Rename a file or directory from `fromPath` to `toPath`. You must have the necess
     let from = '/remote/path/to/old.txt';
     let to = '/remote/path/to/new.txt';
     let client = new Client();
-    
+
     client.connect(config)
       .then(() => {
         return client.rename(from, to);
@@ -855,9 +862,9 @@ Change the mode (read, write or execute permissions) of a remote file or directo
 
     ```javascript
     let path = '/path/to/remote/file.txt';
-    let ndwMode = 0o644;  // rw-r-r
+    let newMode = 0o644;  // rw-r-r
     let client = new Client();
-    
+
     client.connect(config)
       .then(() => {
         return client.chmod(path, newMode);
@@ -872,7 +879,9 @@ Change the mode (read, write or execute permissions) of a remote file or directo
 
 ### realPath(path) ===> string<a id="sec-5-2-17"></a>
 
-Converts a relative path to an absolute path on the remote server. This method is mainly used internally to resolve remote path names. Returns '' if the path is not valid.
+Converts a relative path to an absolute path on the remote server. This method is mainly used internally to resolve remote path names.
+
+**Warning**: Currently, there is a platform inconsistency with this method on win32 platforms. For servers running on non-win32 platforms, providing a path which does not exist on the remote server will result in an empty e.g. '', absolute path being returned. On servers running on win32 platforms, a normalised path will be returned even if the path does not exist on the remote server. It is therefore advised not to use this method to also verify a path exists. instead, use the `exist()` method.
 
 -   **path:** A file path, either relative or absolute. Can handle '.' and '..', but does not expand '~'.
 
@@ -893,28 +902,28 @@ The upload process also emits 'upload' events. These events are fired for each s
 
     ```javascript
         'use strict';
-    
+
         // Example of using the uploadDir() method to upload a directory
         // to a remote SFTP server
-    
+
         const path = require('path');
         const SftpClient = require('../src/index');
-    
+
         const dotenvPath = path.join(__dirname, '..', '.env');
         require('dotenv').config({path: dotenvPath});
-    
+
         const config = {
     host: process.env.SFTP_SERVER,
     username: process.env.SFTP_USER,
     password: process.env.SFTP_PASSWORD,
     port: process.env.SFTP_PORT || 22
         };
-    
+
         async function main() {
     const client = new SftpClient('upload-test');
     const src = path.join(__dirname, '..', 'test', 'testData', 'upload-src');
     const dst = '/home/tim/upload-test';
-    
+
     try {
       await client.connect(config);
       client.on('upload', info => {
@@ -926,7 +935,7 @@ The upload process also emits 'upload' events. These events are fired for each s
       client.end();
     }
         }
-    
+
         main()
     .then(msg => {
       console.log(msg);
@@ -934,7 +943,7 @@ The upload process also emits 'upload' events. These events are fired for each s
     .catch(err => {
       console.log(`main error: ${err.message}`);
     });
-    
+
     ```
 
 ### downloadDir(srcDir, dstDir) ==> string<a id="sec-5-2-20"></a>
@@ -950,28 +959,28 @@ The method also emites `download` events to provide a way to monitor download pr
 
     ```javascript
     'use strict';
-    
+
     // Example of using the downloadDir() method to upload a directory
     // to a remote SFTP server
-    
+
     const path = require('path');
     const SftpClient = require('../src/index');
-    
+
     const dotenvPath = path.join(__dirname, '..', '.env');
     require('dotenv').config({path: dotenvPath});
-    
+
     const config = {
       host: process.env.SFTP_SERVER,
       username: process.env.SFTP_USER,
       password: process.env.SFTP_PASSWORD,
       port: process.env.SFTP_PORT || 22
     };
-    
+
     async function main() {
       const client = new SftpClient('upload-test');
       const dst = '/tmp';
       const src = '/home/tim/upload-test';
-    
+
       try {
         await client.connect(config);
         client.on('download', info => {
@@ -983,7 +992,7 @@ The method also emites `download` events to provide a way to monitor download pr
         client.end();
       }
     }
-    
+
     main()
       .then(msg => {
         console.log(msg);
@@ -991,7 +1000,7 @@ The method also emites `download` events to provide a way to monitor download pr
       .catch(err => {
         console.log(`main error: ${err.message}`);
       });
-    
+
     ```
 
 ### end() ==> boolean<a id="sec-5-2-21"></a>
@@ -1002,7 +1011,7 @@ Ends the current client session, releasing the client socket and associated reso
 
     ```javascript
     let client = new Client();
-    
+
     client.connect(config)
       .then(() => {
         // do some sftp stuff
@@ -1031,9 +1040,43 @@ Although normally not required, you can add and remove custom listeners on the s
 
     Removes the specified listener from the event specified in eventType. Note that the `end()` method automatically removes all listeners from the client object.
 
-# FAQ<a id="sec-6"></a>
+# Platform Quirks & Warnings<a id="sec-6"></a>
+
+## Server Capabilities<a id="sec-6-1"></a>
+
+All SFTP servers and platforms are not equal. Some facilities provided by `ssh2-sfto-client` either depend on capabilities of the remote server or the underlying capabilities of the remote server platform. As an example, consider `chmod()`. This command depends on a remote filesystem which implements the 'nix' concept of users and groups. The *win32* platform does not have the same concept of users and groups, so `chmod()` will not behave in the same way.
+
+One way to determine whether an issue you are encountering is due to `ssh2-sftp-client` or due to the remote server or server platform is to use a simple CLI sftp program, such as openSSH's sftp command. If you observe the same behaviour using plain `sftp` on the command line, the issue is likely due to server or remote platform limitations. Note that you should not use a GUI sftp client, like `Filezilla` or `winSCP` as such GUI programs often attempt to hide these server and platform incompatibilities and will take additional steps to simulate missing functionality etc. You want to use a CLI program which does as little as possible.
+
+One way to determine whether an issue you are encountering is due to `ssh2-sftp-client` or due to the remote server or server platform is to use a simple CLI sftp program, such as openSSH's sftp command. If you observe the same behaviour using plain `sftp` on the command line, the issue is likely due to server or remote platform limitations. Note that you should not use a GUI sftp client, like `Filezilla` or `winSCP` as such GUI programs often attempt to hide these server and platform incompatibilities and will take additional steps to simulate missing functionality etc.
+
+## Promises & Events<a id="sec-6-2"></a>
+
+The reality of the current Node environment is that Promises and Events don't play nicely together. Part of the problem is that events are asynchronous in nature and can occur at any time. It is very difficult to ensure an event is captured inside a Promise and handled appropriately. More information can be found in the Node documentation for Events.
+
+Node v12 has introduced some experimental features to make working with Events and Promises a little easier. At this stage, we are not using these features because they are experimental and because it would mean you cannot use this module with Node v10. Use of these features will likely be examined more closely once they become stable and non-experimental.
+
+So, what does this mean for this module? The `ssh2-sftp-client` module works hard to ensure things work as expected. In most cases, events are handled appropriately. However, there are some edge cases where events may not be handled and you may see an uncaught error exception. The most common place to see this is when you keep an SFTP connection open, but don't use it for some time. When the connection is open, but no methods are active (running), there are no error handlers defined. Should an error event be emitted (for exmaple, because the network connection has been lost), there is no handler and you will get an uncaught error exception.
 
-## Remote server drops connections with only an end event<a id="sec-6-1"></a>
+One way to handle this is to add your own error handler using the on() method. Note however, you need to be careful how many times your error handler is added. If you begin to see a warning about a possible memory leak, it is an indication your error handler is being added multiple times (Node will generate this warning if it finds more than 11 listeners attached to an event emitter).
+
+The other issue that can occur is that in some rare cases, the error message you get will be potentially misleading. For example, SFTP servers running on Windows appear to emit an *ECONNRESET* error in addition to the main error (for example, for failed authentication). This can result in an error which looks like a connection was reset by the remote host when in fact the real error was due to bad authentication (bad password or bad username). This situation can be made even worse by some platforms which deliberately hide the real error for security reasons e.g. does not report an error indicating a bad username because that information can be used to try and identify legitimate usernames. While this module attempts to provide meaningful error messages which can assist developers track down problems, it is a good idea to consider these errors with a grain of salt and verify the error when possible.
+
+## Windows Based Servers<a id="sec-6-3"></a>
+
+It appears that when the sftp server is running on Windows, a *ECONNRESET* error signal is raised when the end() method is called. Unfortunately, this signal is raised after a considerable delay. This means we cannot remove the error handler used in the end() promise as otherwise you will get an uncaught exception error. Leaving the handler in place, even though we will ignore this error, solves that issue, but unfortunately introduces a new problem. Because we are not removing the listener, if you re-use the client object for subsequent connections, an additional error handler will be added. If this happens more than 11 times, you will eventually see the Node warning about a possible memory leak. This is because node monitors the number of error handlers and if it sees more than 11 added to an object, it assumes there is a problem and generates the warning.
+
+The best way to avoid this issue is to not re-use client objects. Always generate a new sftp client object for each new connection.
+
+## Don't Re-use SftpClient Objects<a id="sec-6-4"></a>
+
+Due to an issue with *ECONNRESET* error signals when connecting to Windows based SFTP servers, it is not possible to remove the error handler in the end() method. This means that if you re-use the SftpClient object for multiple connections e.g. calling connect(), then end(), then connect() etc, you run the risk of multiple error handlers being added to the SftpClient object. After 11 handlers have been added, Node will generate a possible memory leak warning.
+
+To avoid this problem, don't re-use SftpClient objects. Generate a new SftpClient object for each connection. You can perform multiple actions with a single connection e.g. upload multiple files, download multiple files etc, but after you have called end(), you should not try to re-use the object with a further connect() call. Create a new object instead.
+
+# FAQ<a id="sec-7"></a>
+
+## Remote server drops connections with only an end event<a id="sec-7-1"></a>
 
 Many SFTP servers have rate limiting protection which will drop connections once a limit has been reached. In particular, openSSH has the setting `MaxStartups`, which can be a tuple of the form `max:drop:full` where `max` is the maximum allowed unauthenticated connections, `drop` is a percentage value which specifies percentage of connections to be dropped once `max` connections has been reached and `full` is the number of connections at which point all subsequent connections will be dropped. e.g. `10:30:60` means allow up to 10 unauthenticated connections after which drop 30% of connection attempts until reaching 60 unauthenticated connections, at which time, drop all attempts.
 
@@ -1041,7 +1084,7 @@ Clients first make an unauthenticated connection to the SFTP server to begin neg
 
 One way to avoid this type of issue is to add a delay between connection attempts. It does not need to be a very long delay - just sufficient to permit the previous connection to be authenticated. In fact, the default setting for openSSH is `10:30:60`, so you really just need to have enough delay to ensure that the 1st connection has completed authentication before the 11th connection is attempted.
 
-## How can you pass writable stream as dst for get method?<a id="sec-6-2"></a>
+## How can I pass writable stream as dst for get method?<a id="sec-7-2"></a>
 
 If the dst argument passed to the get method is a writeable stream, the remote file will be piped into that writeable. If the writeable you pass in is a writeable stream created with `fs.createWriteStream()`, the data will be written to the file specified in the constructor call to `createWriteStream()`.
 
@@ -1097,7 +1140,7 @@ sftp
   });
 ```
 
-## How can I upload files without having to specify a password?<a id="sec-6-3"></a>
+## How can I upload files without having to specify a password?<a id="sec-7-3"></a>
 
 There are a couple of ways to do this. Essentially, you want to setup SSH keys and use these for authentication to the remote server.
 
@@ -1129,7 +1172,7 @@ sftp.connect({
 }
 ```
 
-## How can I connect through a Socks Proxy<a id="sec-6-4"></a>
+## How can I connect through a Socks Proxy<a id="sec-7-4"></a>
 
 This solution was provided by @jmorino.
 
@@ -1162,218 +1205,50 @@ client.connect({
 // client is connected
 ```
 
-## Timeout while waiting for handshake or handshake errors<a id="sec-6-5"></a>
+## Timeout while waiting for handshake or handshake errors<a id="sec-7-5"></a>
 
 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.
 
-# Examples<a id="sec-7"></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.
-
-# Change Log<a id="sec-8"></a>
-
-## v5.2.1 (Prod Version)<a id="sec-8-1"></a>
-
--   Move some dependencies into dev-Dependencies
-
-## v5.2.0<a id="sec-8-2"></a>
-
--   Add new method posixRename() which uses the openSSH POSIX rename extension.
-
-## v5.1.3<a id="sec-8-3"></a>
-
--   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<a id="sec-8-4"></a>
-
--   Added back global close handler
--   Added dumpListeners() method
-
-## v5.1.1<a id="sec-8-5"></a>
-
--   Added separate close handlers to each method.
--   Added missing return statement in connect method
--   Added additional troubleshooting documentation for common errors.
-
-## v5.1.0<a id="sec-8-6"></a>
-
--   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<a id="sec-8-7"></a>
-
--   Fix bugs related to win32 platform and local tests for valid directories
--   Fix problem with parsing of file paths
-
-## v5.0.1<a id="sec-8-8"></a>
-
--   Turn down error checking to be less stringent and handle situations where user does not have read permission on parent directory.
-
-## v5.0.0<a id="sec-8-9"></a>
-
--   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<a id="sec-8-10"></a>
-
--   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<a id="sec-8-11"></a>
-
--   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<a id="sec-8-12"></a>
-
--   Bumped ssh2 to v0.8.6
--   Added exists() usage example to examples directory
--   Clarify documentation on get() method
-
-## v4.2.3<a id="sec-8-13"></a>
-
--   Fix bug in `exist()` where tests on root directory returned false
--   Minor documentation fixes
--   Clean up mkdir example
-
-## v4.2.2<a id="sec-8-14"></a>
-
--   Minor documentation fixes
--   Added additional examples in the `example` directory
-
-## v4.2.1<a id="sec-8-15"></a>
-
--   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
+## How can I limit upload/download speed<a id="sec-7-6"></a>
 
-## v4.2.0<a id="sec-8-16"></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.
 
--   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<a id="sec-8-17"></a>
-
--   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<a id="sec-8-18"></a>
-
--   Minor documentation fix
--   Fix return value from `get()`
-
-## v4.0.3<a id="sec-8-19"></a>
-
--   Fix bug in mkdir() relating to handling of relative paths
--   Modify exists() to always return 'd' if path is '.'
-
-## v4.0.2<a id="sec-8-20"></a>
-
--   Fix some minor packaging issues
-
-## v4.0.0<a id="sec-8-21"></a>
-
--   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<a id="sec-8-22"></a>
-
-### v2.5.2<a id="sec-8-22-1"></a>
-
--   Repository transferred to theophilusx
--   Fix error in package.json pointing to wrong repository
-
-### v2.5.1<a id="sec-8-22-2"></a>
-
--   Apply 4 pull requests to address minor issues prior to transfer
-
-### v2.5.0<a id="sec-8-22-3"></a>
-
--   ???
-
-### v2.4.3<a id="sec-8-22-4"></a>
-
--   merge #108, #110
-    -   fix connect promise if connection ends
-
-### v2.4.2<a id="sec-8-22-5"></a>
-
--   merge #105
-    -   fix windows path
-
-### v2.4.1<a id="sec-8-22-6"></a>
-
--   merge pr #99, #100
-    -   bug fix
-
-### v2.4.0<a id="sec-8-22-7"></a>
-
--   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<a id="sec-8-22-8"></a>
-
--   add: `stat` method
--   add `fastGet` and `fastPut` method.
--   fix: `mkdir` file exists decision logic
-
-### v3.0.0 &#x2013; deprecate this version<a id="sec-8-22-9"></a>
+```javascript
 
--   change: `sftp.get` will return chunk not stream anymore
--   fix: get readable not emitting data events in node 10.0.0
 
-### v2.1.1<a id="sec-8-22-10"></a>
+const Throttle = require('throttle');
+const progress = require('progress-stream');
 
--   add: event listener. [doc](https://github.com/jyu213/ssh2-sftp-client#Event)
--   add: `get` or `put` method add extra options [pr#52](https://github.com/jyu213/ssh2-sftp-client/pull/52)
+// limit download speed
+const throttleStream = new Throttle(config.throttle);
 
-### v2.0.1<a id="sec-8-22-11"></a>
+// download progress stream
+const progressStream = progress({
+  length: fileSize,
+  time: 500,
+});
+progressStream.on('progress', (progress) => {
+  console.log(progress.percentage.toFixed(2));
+});
 
--   add: `chmod` method [pr#33](https://github.com/jyu213/ssh2-sftp-client/pull/33)
--   update: upgrade ssh2 to V0.5.0 [pr#30](https://github.com/jyu213/ssh2-sftp-client/pull/30)
--   fix: get method stream error reject unwork [#22](https://github.com/jyu213/ssh2-sftp-client/issues/22)
--   fix: return Error object on promise rejection [pr#20](https://github.com/jyu213/ssh2-sftp-client/pull/20)
+const outStream = createWriteStream(localPath);
 
-### v1.1.0<a id="sec-8-22-12"></a>
+// pipe streams together
+throttleStream.pipe(progressStream).pipe(outStream);
 
--   fix: add encoding control support for binary stream
+try {
+  // set autoClose to false
+  await client.get(remotePath, throttleStream, { autoClose: false });
+} catch (e) {
+  console.log('sftp error', e);
+} finally {
+  await client.end();
+}
+```
 
-### v1.0.5:<a id="sec-8-22-13"></a>
+# Examples<a id="sec-8"></a>
 
--   fix: multi image upload
--   change: remove `this.client.sftp` to `connect` function
+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.
 
 # Troubleshooting<a id="sec-9"></a>
 
@@ -1407,7 +1282,7 @@ sftp.connect(config)
   });
 ```
 
-In the above code, the `sftp.end()` method will almost certainly be called before `sftp.gastGet()` has been fulfilled (unless the *foo.txt* file is really small!). In fact, the whole promise chain will complete and exit even before the `sftp.end()` call has been fulfilled. The correct code would be something like
+In the above code, the `sftp.end()` method will almost certainly be called before `sftp.fastGet()` has been fulfilled (unless the *foo.txt* file is really small!). In fact, the whole promise chain will complete and exit even before the `sftp.end()` call has been fulfilled. The correct code would be something like
 
 ```javascript
 sftp.connect(config)
@@ -1508,6 +1383,18 @@ node script.js 2> debug.log
 
 ```
 
+If you just want to see debug messages from `ssh2-sftp-client` and exclude debug messages from the underlying `ssh2` and `ssh2-streams` modules, you can filter based on messages which start with 'CLIENT' e.g.
+
+```javascript
+{
+  debug: (msg) => {
+    if (msg.startsWith('CLIENT')) {
+      console.error(msg);
+    }
+  }
+}
+```
+
 # Logging Issues<a id="sec-10"></a>
 
 Please log an issue for all bugs, questions, feature and enhancement requests. Please ensure you include the module version, node version and platform.
@@ -1544,3 +1431,6 @@ Thanks to the following for their contributions -
 -   **waldyrious:** Documentation fixes
 -   **james-pellow:** Cleanup and fix for connect method logic
 -   **jhorbulyk:** Contributed posixRename() functionality
+-   **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