ssh2-sftp-client 5.2.1 → 5.3.2

package/README.org

@@ -1,4 +1,7 @@
-* SSH2 SFTP Client
+#+OPTONS: H:2 toc:2
+#+TITLE: SSH2 SFTP Client
+
+* Overview
 
 an SFTP client for node.js, a wrapper around [[https://github.com/mscdex/ssh2][SSH2]]  which provides a high level
 convenience abstraction as well as a Promise based API.
@@ -6,20 +9,37 @@ 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]] and [[https://github.com/mscdex/ssh2-streams/blob/master/SFTPStream.md][SSH2-STREAMS]]  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.
 
-_WARNING_ 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 [[https://github.com/mscdex/ssh2-streams/issues/156][issue 156]].  
+_WARNING_ 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 [[https://github.com/mscdex/ssh2-streams/issues/156][issue 156]].
+
+_UPDATE_: 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.
+
+_UPDATE_: 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
 
@@ -221,7 +241,7 @@ reset to false in preparation for the next error.
    - Fix bug in checkRemotePath() relating to poor path specifications where
      you cannot determine parent directory.
 
-** Version 5.1.1 
+** Version 5.1.1
    - Bug fix for unexpected close of connections. It would seem that a
      connections can be unexpectedly closed without an accompanying error event.
      As methods only looked for error events, the method promise wold never
@@ -236,26 +256,54 @@ reset to false in preparation for the next error.
      inside promise chains. Common symptom is what appears to be truncated file
      upload/download. What is really happening is that the end method is being
      called before the transfer has completed.
-     
-** Version 5.1.2 
+
+** Version 5.1.2
    - Mainly a bug fix. We needed to add back a global close listener to ensure
-     the sftp object is unset whenever a close event occurs. As close events can 
+     the sftp object is unset whenever a close event occurs. As close events can
      occur outside main method calls, only having method based listeners was not
      sufficient.
    - Also added a utils.dumpListeners() method, useful when debugging issues with
      listener 'leakage' due to failure to remove listeners when no longer required.
-     
+
 ** Version 5.1.3
   - Fix issue with permissions for writing to root directory
   - Cleanup tests to use less connections and eliminate need for test delays
-  - Bumped some dependencies to latest versions  
+  - Bumped some dependencies to latest versions
 ** Version 5.2.0
    - Add posixRename() method. This is an openssh extension added in openssh
      v4.8 and will only work on servers which support this extension.conflict
    - Bumped through2 dependency version to 4.0.2
 
 ** Version 5.2.1
-   - Move some dev dependencies from dependencies to devDependencies. 
+   - Move some dev dependencies from dependencies to devDependencies.
+** Version 5.2.2
+   - 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
+   - 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
+   - 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
+   - Minor README typo fixes
+   - Fix error in local file path checks (#294)
 * Documentation
 
 The connection options are the same as those offered by the underlying SSH2
@@ -266,50 +314,63 @@ All the methods will return a Promise, except for ~on()~ and
 
 ** Specifying Paths
 
-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.
+   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~.
+
+   There is a small performance hit for using ~./~ and ~../~ as the module must
+   query the remote server to determine what the root path is and derive the
+   absolute path. Using absolute paths are therefore more efficient and likely
+   more robust.
+
+   When specifying file paths, ensure to include a full path i.e. include the
+   remote filename. Don't expect the module to append the local file name to the
+   path you provide. For example, the following will not work
 
-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~.
-
-There is a small performance hit for using ~./~ and ~../~ as the module must
-query the remote server to determine what the root path is and derive the
-absolute path. Using absolute paths are therefore more efficient and likely more
-robust.
-
-When specifying file paths, ensure to include a full path i.e. include the
-remote filename. Don't expect the module to append the local file name to the
-path you provide. For example, the following will not work
-
- #+begin_src javascript
-   client.put('/home/fred/test.txt', '/remote/dir');
- #+end_src
+   #+begin_src javascript
+     client.put('/home/fred/test.txt', '/remote/dir');
+   #+end_src
 
-will not result in the file ~test.txt~ being copied to
-~/remote/dir/test.txt~. You need to specify the target filename as well e.g.
+   will not result in the file ~test.txt~ being copied to
+   ~/remote/dir/test.txt~. You need to specify the target filename as well e.g.
 
-  #+begin_src javascript
-    client.put('/home/fred/test.txt', '/remote/dir/test.txt');
-  #+end_src
+   #+begin_src javascript
+     client.put('/home/fred/test.txt', '/remote/dir/test.txt');
+   #+end_src
 
-Note that the remote file name does not have to be the same as the local file
-name. The following works fine;
+   Note that the remote file name does not have to be the same as the local file
+   name. The following works fine;
 
-#+begin_src javascript
-  client.put('/home/fred/test.txt', '/remote/dir/test-copy.txt');
-#+end_src
+   #+begin_src javascript
+     client.put('/home/fred/test.txt', '/remote/dir/test-copy.txt');
+   #+end_src
 
-This will copy the local file ~test.txt~ to the remote file ~test-copy.txt~ in
-the directory ~/remote/dir~.
+   This will copy the local file ~test.txt~ to the remote file ~test-copy.txt~
+   in the directory ~/remote/dir~.
 
 ** Methods
 
@@ -381,7 +442,7 @@ for that package for an explanation of these values.
     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
@@ -869,6 +930,12 @@ action will fail.
 - 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.
+
 **** Example Use
 
 #+begin_src javascript
@@ -916,7 +983,7 @@ Delete a file on the remote server.
 Rename a file or directory from ~fromPath~ to ~toPath~. You must have the
 necessary permissions to modify the remote file.
 
-- fromPath :: string. Path to existing file to be renamed 
+- fromPath :: string. Path to existing file to be renamed
 - toPath :: string. Path to new file existing file is to be renamed to. Should
   not already exist.
 
@@ -940,7 +1007,7 @@ necessary permissions to modify the remote file.
 #+end_src
 
 *** posixRename(fromPath, toPath) ==> string
-    
+
 This method uses the openssh POSIX rename extension introduced in OpenSSH 4.8.
 The advantage of this version of rename over standard SFTP rename is that it is
 an atomic operation and will allow renaming a resource where the destination
@@ -970,7 +1037,7 @@ protocol and therefore is not supported on all sSFTP servers.
       console.error(err.message);
     });
 #+end_src
-    
+
 *** chmod(path, mode) ==> string
 
 Change the mode (read, write or execute permissions) of a remote file or
@@ -983,7 +1050,7 @@ directory.
 
 #+begin_src 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)
@@ -1001,8 +1068,15 @@ directory.
 *** realPath(path) ===> string
 
 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.
+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 '~'.
@@ -1044,36 +1118,36 @@ using the ~on()~ method.
        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
+   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 => {
-	     console.log(`Listener: Uploaded ${info.source}`);
-	   });
-	   let rslt = await client.uploadDir(src, dst);
-	   return rslt;
-	 } finally {
-	   client.end();
-	 }
+   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 => {
+       console.log(`Listener: Uploaded ${info.source}`);
+     });
+     let rslt = await client.uploadDir(src, dst);
+     return rslt;
+   } finally {
+     client.end();
+   }
        }
 
        main()
-	 .then(msg => {
-	   console.log(msg);
-	 })
-	 .catch(err => {
-	   console.log(`main error: ${err.message}`);
-	 });
+   .then(msg => {
+     console.log(msg);
+   })
+   .catch(err => {
+     console.log(`main error: ${err.message}`);
+   });
 
      #+end_src
 
@@ -1124,7 +1198,7 @@ the ~on()~ method.
     try {
       await client.connect(config);
       client.on('download', info => {
-	console.log(`Listener: Download ${info.source}`);
+  console.log(`Listener: Download ${info.source}`);
       });
       let rslt = await client.downloadDir(src, dst);
       return rslt;
@@ -1188,6 +1262,115 @@ type, which will be true when the client connection was closed due to errors.
 Removes the specified listener from the event specified in eventType. Note that
 the ~end()~ method automatically removes all listeners from the client object.
 
+* Platform Quirks & Warnings
+** Server Capabilities
+
+   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
+
+   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.
+
+   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
+
+   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
+
+   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
 
 ** Remote server drops connections with only an end event
@@ -1217,7 +1400,7 @@ 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?
+** How can I pass writable stream as dst for get method?
 
 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
@@ -1361,6 +1544,47 @@ host key used to establish the initial secure connection. See the SSH2
 documentation for details. Getting these parameters correct usually resolves the
 issue.
 
+** How can I limit upload/download speed
+
+   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.
+
+
+   #+begin_src javascript
+
+
+     const Throttle = require('throttle');
+     const progress = require('progress-stream');
+
+     // limit download speed
+     const throttleStream = new Throttle(config.throttle);
+
+     // download progress stream
+     const progressStream = progress({
+       length: fileSize,
+       time: 500,
+     });
+     progressStream.on('progress', (progress) => {
+       console.log(progress.percentage.toFixed(2));
+     });
+
+     const outStream = createWriteStream(localPath);
+
+     // pipe streams together
+     throttleStream.pipe(progressStream).pipe(outStream);
+
+     try {
+       // set autoClose to false
+       await client.get(remotePath, throttleStream, { autoClose: false });
+     } catch (e) {
+       console.log('sftp error', e);
+     } finally {
+       await client.end();
+     }
+   #+end_src
 * Examples
 
 I have started collecting example scripts in the example directory of the
@@ -1369,195 +1593,6 @@ 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
-** v5.2.1 (Prod Version)
-   - 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
-
 * Troubleshooting
 
 The ~ssh2-sftp-client~ module is essentially a wrapper around the ~ssh2~ and
@@ -1601,7 +1636,7 @@ trying to determine if the issue is with the underlying ~ssh2~ and
    There are some common errors people tend to make when using Promises or
    Asyc/Await. These are by far the most common problem found in issues logged
    against this module. Please check for some of these before logging your
-   issue. 
+   issue.
 
 *** Not returning the promise in a ~then()~ block
 
@@ -1611,9 +1646,9 @@ trying to determine if the issue is with the underlying ~ssh2~ and
     generates. Failing to do this will result in the ~then()~ block completing
     and your code starting execution of the next ~then()~, ~catch()~ or
     ~finally()~ block before your promise has been fulfilled. For exmaple, the
-    following will not do what you expect 
+    following will not do what you expect
 
-    #+begin_src javascript 
+    #+begin_src javascript
       sftp.connect(config)
         .then(() => {
           sftp.fastGet('foo.txt', 'bar.txt');
@@ -1624,14 +1659,14 @@ trying to determine if the issue is with the underlying ~ssh2~ and
           console.error(e.message);
         });
     #+end_src
-   
+
     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
+    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 
-    
-    #+begin_src javascript 
+    something like
+
+    #+begin_src javascript
       sftp.connect(config)
         .then(() => {
           return sftp.fastGet('foo.txt', 'bar.txt');
@@ -1642,20 +1677,20 @@ trying to determine if the issue is with the underlying ~ssh2~ and
           console.error(e.message);
         });
     #+end_src
-    
+
     Note the ~return~ statements. These ensure that the Promise returned by the
     client method is returned into the promise chain. It will be this promise
     the next block in the chain will wait on to be fulfilled before the next
     block is executed. Without the return statement, that block will return the
     default promise for that block, which essentially says /this block has been
     fulfilled/. What you really want is the promise which says /your sftp client
-    method call has been fulfilled/. 
+    method call has been fulfilled/.
 
     A common symptom of this type of error is for file uploads or download to
     fail to complete or for data in those files to be truncated. What is
     happening is that the connection is being ended before the transfer has
-    completed. 
-    
+    completed.
+
 *** Mixing Promise Chains and Async/Await
 
     Another common error is to mix Promise chains and async/await calls. This is
@@ -1689,14 +1724,14 @@ trying to determine if the issue is with the underlying ~ssh2~ and
     returning is a fulfilled promise which says the ~then()~ block has been run
     (note that the await'ed promise is not being returned and is therefore
     outside the main Promise chain). As a result, the ~finally()~ block will be
-    executed before the await promise has been fulfilled. 
+    executed before the await promise has been fulfilled.
 
     Using async/await inside the promise chain has created unnecessary
     complexity and leads to incorrect assumptions regarding how the code will
     execute. A quick glance at the code is likely to give the impression that
     execution will wait for the ~sftp.fastGet()~ call to be fulfilled before
     continuing. This is not the case. The code would be more clearly expressed
-    as either 
+    as either
 
     #+begin_src javascript
       sftp.connect(config)
@@ -1711,7 +1746,7 @@ trying to determine if the issue is with the underlying ~ssh2~ and
           return sftp.end();
         });
     #+end_src
-    
+
    *or, using async/await*
 
    #+begin_src javascript
@@ -1735,14 +1770,14 @@ trying to determine if the issue is with the underlying ~ssh2~ and
     signals, such as an error event. In general, you cannot use try/catch blocks
     for asynchronous code and expect errors to be caught by the ~catch~ block.
     Handling errors in asynchronous code is one of the key reasons we now have
-    the Promise and async/await frameworks. 
+    the Promise and async/await frameworks.
 
     The basic problem is that the try/catch block will have completed execution
     before the asynchronous code has completed. If the asynchronous code has not
     compleed, then there is a potential for it to raise an error. However, as
     the try/catch block has already completed, there is no /catch/ waiting to
     catch the error. It will bubble up and probably result in your script
-    exiting with an uncaught exception error. 
+    exiting with an uncaught exception error.
 
     Error events are essentially asynchronous code. You don't know when such
     events will fire. Therefore, you cannot use a try/catch block to catch such
@@ -1753,8 +1788,8 @@ trying to determine if the issue is with the underlying ~ssh2~ and
     error exceptions that cause your script to exit abnormally despite having
     try/catch blocks in your script. What you need to do is look at your code
     and find where errors are raised asynchronously and use an event handler or
-    some other mechanism to manage any errors raised.  
-    
+    some other mechanism to manage any errors raised.
+
 ** Debugging Support
 
 You can add a ~debug~ property to the config object passed in to ~connect()~ to
@@ -1777,6 +1812,19 @@ using shell redirection e.g.
 
 #+end_src
 
+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.
+
+#+begin_src javascript
+  {
+    debug: (msg) => {
+      if (msg.startsWith('CLIENT')) {
+        console.error(msg);
+      }
+    }
+  }
+#+end_src
 * Logging Issues
 
 Please log an issue for all bugs, questions, feature and enhancement
@@ -1830,4 +1878,8 @@ Thanks to the following for their contributions -
 - henrytk :: Documentation fix
 - waldyrious :: Documentation fixes
 - james-pellow :: Cleanup and fix for connect method logic
-- jhorbulyk :: Contributed posixRename() functionality 
+- 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