ssh2-sftp-client 8.0.0 → 8.1.0

package/README.md

@@ -1,85 +1,101 @@
-- [Overview](#sec-1)
-  - [Version 8.x.x Changes](#sec-1-1)
-- [Installation](#sec-2)
-- [Basic Usage](#sec-3)
-- [Documentation](#sec-4)
-  - [Specifying Paths](#sec-4-1)
-  - [Methods](#sec-4-2)
-    - [new SftpClient(name) ===> SFTP client object](#sec-4-2-1)
-    - [connect(config) ===> SFTP object](#sec-4-2-2)
-    - [list(path, pattern) ==> Array[object]](#sec-4-2-3)
-    - [exists(path) ==> boolean](#sec-4-2-4)
-    - [stat(path) ==> object](#sec-4-2-5)
-    - [get(path, dst, options) ==> String|Stream|Buffer](#sec-4-2-6)
-    - [fastGet(remotePath, localPath, options) ===> string](#sec-4-2-7)
-    - [put(src, remotePath, options) ==> string](#sec-4-2-8)
-    - [fastPut(localPath, remotePath, options) ==> string](#sec-4-2-9)
-    - [append(input, remotePath, options) ==> string](#sec-4-2-10)
-    - [mkdir(path, recursive) ==> string](#sec-4-2-11)
-    - [rmdir(path, recursive) ==> string](#sec-4-2-12)
-    - [delete(path, noErrorOK) ==> string](#sec-4-2-13)
-    - [rename(fromPath, toPath) ==> string](#sec-4-2-14)
-    - [posixRename(fromPath, toPath) ==> string](#sec-4-2-15)
-    - [chmod(path, mode) ==> string](#sec-4-2-16)
-    - [realPath(path) ===> string](#sec-4-2-17)
-    - [cwd() ==> string](#sec-4-2-18)
-    - [uploadDir(srcDir, dstDir, filter) ==> string](#sec-4-2-19)
-    - [downloadDir(srcDir, dstDir, filter) ==> string](#sec-4-2-20)
-    - [end() ==> boolean](#sec-4-2-21)
-    - [Add and Remove Listeners](#sec-4-2-22)
-- [Platform Quirks & Warnings](#sec-5)
-  - [Server Capabilities](#sec-5-1)
-  - [Promises, Events & Managing Exceptions](#sec-5-2)
-    - [Adding Custom Handlers](#sec-5-2-1)
-  - [Windows Based Servers](#sec-5-3)
-  - [Don't Re-use SftpClient Objects](#sec-5-4)
-- [FAQ](#sec-6)
-  - [Remote server drops connections with only an end event](#sec-6-1)
-  - [How can I 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)
-  - [How can I limit upload/download speed](#sec-6-6)
-  - [Connection hangs or fails for larger files](#sec-6-7)
-- [Examples](#sec-7)
-- [Troubleshooting](#sec-8)
-  - [Common Errors](#sec-8-1)
-    - [Not returning the promise in a `then()` block](#sec-8-1-1)
-    - [Mixing Promise Chains and Async/Await](#sec-8-1-2)
-    - [Try/catch and Error Handlers](#sec-8-1-3)
-    - [Server Differences](#sec-8-1-4)
-    - [Avoid Concurrent Operations](#sec-8-1-5)
-  - [Debugging Support](#sec-8-2)
-- [Logging Issues](#sec-9)
-- [Pull Requests](#sec-10)
-- [Contributors](#sec-11)
-
-
-# Overview<a id="sec-1"></a>
+- [Overview](#orgbeea605)
+  - [Version 8.x.x Changes](#org2589748)
+- [Installation](#orgd7b0a7e)
+- [Basic Usage](#org2e1bee4)
+- [Documentation](#orgfac43d1)
+  - [Specifying Paths](#org38509ac)
+  - [Methods](#org26ecc4f)
+    - [new SftpClient(name) ===> SFTP client object](#orga50cd31)
+    - [connect(config) ===> SFTP object](#orgbc0c617)
+    - [list(path, pattern) ==> Array[object]](#orgdfab34d)
+    - [exists(path) ==> boolean](#orgd09b949)
+    - [stat(path) ==> object](#org31bacc1)
+    - [get(path, dst, options) ==> String|Stream|Buffer](#org12ed2ca)
+    - [fastGet(remotePath, localPath, options) ===> string](#org7b0d9e8)
+    - [put(src, remotePath, options) ==> string](#orgd38e78b)
+    - [fastPut(localPath, remotePath, options) ==> string](#orge130096)
+    - [append(input, remotePath, options) ==> string](#org4f2a1b1)
+    - [mkdir(path, recursive) ==> string](#orga9acefe)
+    - [rmdir(path, recursive) ==> string](#org9e51da5)
+    - [delete(path, noErrorOK) ==> string](#org2054a87)
+    - [rename(fromPath, toPath) ==> string](#org7497d9f)
+    - [posixRename(fromPath, toPath) ==> string](#orgb179088)
+    - [chmod(path, mode) ==> string](#org335a008)
+    - [realPath(path) ===> string](#org384f34a)
+    - [cwd() ==> string](#org8fa77d4)
+    - [uploadDir(srcDir, dstDir, filter) ==> string](#orgb824235)
+    - [downloadDir(srcDir, dstDir, filter) ==> string](#org46aa66f)
+    - [end() ==> boolean](#orge3fcb81)
+    - [Add and Remove Listeners](#org4607268)
+- [Platform Quirks & Warnings](#org66a7061)
+  - [Server Capabilities](#org740553b)
+  - [Promises, Events & Managing Exceptions](#orgf97d765)
+    - [Adding Custom Handlers](#org6acf9c6)
+  - [Windows Based Servers](#orgb2f13ee)
+  - [Don't Re-use SftpClient Objects](#orgcd82e68)
+- [FAQ](#orge1aa1d7)
+  - [Remote server drops connections with only an end event](#org9296404)
+  - [How can I pass writable stream as dst for get method?](#org3e48901)
+  - [How can I upload files without having to specify a password?](#org1474028)
+  - [How can I connect through a Socks Proxy](#orgb9a0ec1)
+  - [Timeout while waiting for handshake or handshake errors](#org62e1f3a)
+  - [How can I limit upload/download speed](#org7f26ef8)
+  - [Connection hangs or fails for larger files](#orgfb52441)
+- [Examples](#orgbe2b99e)
+- [Troubleshooting](#orgd2dcb05)
+  - [Common Errors](#orgae04d0a)
+    - [Not returning the promise in a `then()` block](#org2018983)
+    - [Mixing Promise Chains and Async/Await](#org6a3654b)
+    - [Try/catch and Error Handlers](#org36087fd)
+    - [Server Differences](#orgd09c9c8)
+    - [Avoid Concurrent Operations](#org67e5a24)
+  - [Debugging Support](#org00c676b)
+- [Logging Issues](#org6f7f508)
+- [Pull Requests](#org2d2ad0d)
+- [Contributors](#orgba32989)
+
+
+
+<a id="orgbeea605"></a>
+
+# Overview
 
 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) project pages.
 
-Current stable release is **v8.0.0**.
+Current stable release is **v8.1.0**.
 
-Code has been tested against Node versions 14.19.1, 16.14.2 and 17.8.0
+Code has been tested against Node versions 14.19.1, 16.15.0 and 18.1.0
 
 Node versions < 12.x are not supported. However, node v10.x should still work, although some tests will fail due to changes in file system functions used in test setup and tear down.
 
-## Version 8.x.x Changes<a id="sec-1-1"></a>
+
+<a id="org2589748"></a>
+
+## Version 8.x.x Changes
 
 -   **Breaking Change**: The API for `uploadDir()` and `downloadDir()` has been changed. These methods now expect a function as the optional 3rd argument. Previously, the 3rd argument was a regular expression used to filter out which files and directories should be included in the upload or download action. The method now expects a predicate function which will return true if the target is to be included in the upload or download and false if it is to be excluded. The predicate function will be called with two arguments, a full path to the target object and a boolean value which is true when the target is a directory, false otherwise. If no filter predicate is supplied, all files and directories under the initial target directory will be transferred. At this time, asynchronous filter functions are not supported.
 
 -   Internal Change: The `rmdir()` method has been refactored to enable asynchronous deletion of files and sub-directories. This has significantly increased performance when deleting larger directory trees, especially trees which are *broad* with lots of files and directories at the same level. For deep narrow trees, there is less performance benefit because sub-directories must be removed before parents, which imposes synchronous processing. It is likely that for extremely large directory trees, the additional resources required to run large numbers of asynchronous tasks will become problematic. In such situations, it may be necessary to manually break up the deletion process into multiple `rmdir()` calls. However, this is considered a fairly extreme use case which is rare (a use case which wold also have been problematic with the old implementation as performance would have been very poor).
 
-# Installation<a id="sec-2"></a>
+-   v8.1.0: The `list()` method now includes a `longname` property in the descriptor object for each file in the listing. The `longname` value is a string which resembles the `ls -l` listing.
+
+-   v8.1.0: The `rmdir()` method has been further modified to not recurse into directories using async. It was found that on large directories, this could result in too many separate async processes. Only deletion of files is now handled with asynchronous calls.
+
+
+<a id="orgd7b0a7e"></a>
+
+# Installation
 
 ```shell
 npm install ssh2-sftp-client
 ```
 
-# Basic Usage<a id="sec-3"></a>
+
+<a id="org2e1bee4"></a>
+
+# Basic Usage
 
 ```javascript
 let Client = require('ssh2-sftp-client');
@@ -99,13 +115,19 @@ sftp.connect({
 });
 ```
 
-# Documentation<a id="sec-4"></a>
+
+<a id="orgfac43d1"></a>
+
+# Documentation
 
 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)
 
 All the methods will return a Promise, except for `on()` and `removeListener()`, which are typically only used in special use cases.
 
-## Specifying Paths<a id="sec-4-1"></a>
+
+<a id="org38509ac"></a>
+
+## Specifying Paths
 
 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.
 
@@ -135,9 +157,15 @@ client.put('/home/fred/test.txt', '/remote/dir/test-copy.txt');
 
 This will copy the local file `test.txt` to the remote file `test-copy.txt` in the directory `/remote/dir`.
 
-## Methods<a id="sec-4-2"></a>
 
-### new SftpClient(name) ===> SFTP client object<a id="sec-4-2-1"></a>
+<a id="org26ecc4f"></a>
+
+## Methods
+
+
+<a id="orga50cd31"></a>
+
+### new SftpClient(name) ===> SFTP client object
 
 Constructor to create a new `ssh2-sftp-client` object. An optional `name` string can be provided, which will be used in error messages to help identify which client has thrown the error.
 
@@ -173,7 +201,10 @@ Constructor to create a new `ssh2-sftp-client` object. An optional `name` string
       });
     ```
 
-### connect(config) ===> SFTP object<a id="sec-4-2-2"></a>
+
+<a id="orgbc0c617"></a>
+
+### connect(config) ===> SFTP object
 
 Connect to an sftp server. Full documentation for connection options is available [here](https://github.com/mscdex/ssh2#user-content-client-methods)
 
@@ -236,7 +267,10 @@ Connect to an sftp server. Full documentation for connection options is availabl
     });
     ```
 
-### list(path, pattern) ==> Array[object]<a id="sec-4-2-3"></a>
+
+<a id="orgdfab34d"></a>
+
+### list(path, pattern) ==> Array[object]
 
 Retrieves a directory listing. This method returns a Promise, which once realised, returns an array of objects representing items in the remote directory.
 
@@ -290,6 +324,7 @@ Retrieves a directory listing. This method returns a Promise, which once realise
       },
       owner: // user ID
       group: // group ID
+      longname: // like ls -l line
     }
     ```
 
@@ -303,7 +338,10 @@ Retrieves a directory listing. This method returns a Promise, which once realise
     
     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-4-2-4"></a>
+
+<a id="orgd09b949"></a>
+
+### exists(path) ==> boolean
 
 Tests to see if remote file or directory exists. Returns type of remote object if it exists or false if it does not.
 
@@ -336,7 +374,10 @@ Tests to see if remote file or directory exists. Returns type of remote object i
       });
     ```
 
-### stat(path) ==> object<a id="sec-4-2-5"></a>
+
+<a id="org31bacc1"></a>
+
+### stat(path) ==> object
 
 Returns the attributes associated with the object pointed to by `path`.
 
@@ -384,7 +425,10 @@ Returns the attributes associated with the object pointed to by `path`.
       });
     ```
 
-### get(path, dst, options) ==> String|Stream|Buffer<a id="sec-4-2-6"></a>
+
+<a id="org12ed2ca"></a>
+
+### get(path, dst, options) ==> String|Stream|Buffer
 
 Retrieve a file from a remote SFTP server. The `dst` argument defines the destination and can be either a string, a stream object or undefined. If it is a string, it is interpreted as the path to a location on the local file system (path should include the file name). If it is a stream object, the remote data is passed to it via a call to pipe(). If `dst` is undefined, the method will put the data into a buffer and return that buffer when the Promise is resolved. If `dst` is defined, it is returned when the Promise is resolved.
 
@@ -437,7 +481,10 @@ In general, if you're going to pass in a string as the destination, you are bett
     
     -   **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-4-2-7"></a>
+
+<a id="org7b0d9e8"></a>
+
+### fastGet(remotePath, localPath, options) ===> string
 
 Downloads a file at remotePath to localPath using parallel reads for faster throughput. This is the simplest method if you just want to download a file.
 
@@ -477,7 +524,10 @@ Downloads a file at remotePath to localPath using parallel reads for faster thro
       });
     ```
 
-### put(src, remotePath, options) ==> string<a id="sec-4-2-8"></a>
+
+<a id="orgd38e78b"></a>
+
+### put(src, remotePath, options) ==> string
 
 Upload data from local system to remote server. If the `src` argument is a string, it is interpreted as a local file path to be used for the data to transfer. If the `src` argument is a buffer, the contents of the buffer are copied to the remote file and if it is a readable stream, the contents of that stream are piped to the `remotePath` on the server.
 
@@ -524,7 +574,10 @@ Upload data from local system to remote server. If the `src` argument is a strin
     
     -   **Tip:** If the src argument is a path string, consider just using `fastPut()`.
 
-### fastPut(localPath, remotePath, options) ==> string<a id="sec-4-2-9"></a>
+
+<a id="orge130096"></a>
+
+### fastPut(localPath, remotePath, options) ==> string
 
 Uploads the data in file at `localPath` to a new file on remote server at `remotePath` using concurrency. The options object allows tweaking of the fast put process.
 
@@ -565,7 +618,10 @@ Uploads the data in file at `localPath` to a new file on remote server at `remot
       });
     ```
 
-### append(input, remotePath, options) ==> string<a id="sec-4-2-10"></a>
+
+<a id="org4f2a1b1"></a>
+
+### append(input, remotePath, options) ==> string
 
 Append the `input` data to an existing remote file. There is no integrity checking performed apart from normal writeStream checks. This function simply opens a writeStream on the remote file in append mode and writes the data passed in to the file.
 
@@ -606,7 +662,10 @@ Append the `input` data to an existing remote file. There is no integrity checki
       });
     ```
 
-### mkdir(path, recursive) ==> string<a id="sec-4-2-11"></a>
+
+<a id="orga9acefe"></a>
+
+### mkdir(path, recursive) ==> string
 
 Create a new directory. If the recursive flag is set to true, the method will create any directories in the path which do not already exist. Recursive flag defaults to false.
 
@@ -631,7 +690,10 @@ Create a new directory. If the recursive flag is set to true, the method will cr
       });
     ```
 
-### rmdir(path, recursive) ==> string<a id="sec-4-2-12"></a>
+
+<a id="org9e51da5"></a>
+
+### rmdir(path, recursive) ==> string
 
 Remove a directory. If removing a directory and recursive flag is set to `true`, the specified directory and all sub-directories and files will be deleted. If set to false and the directory has sub-directories or files, the action will fail.
 
@@ -658,7 +720,10 @@ Remove a directory. If removing a directory and recursive flag is set to `true`,
       });
     ```
 
-### delete(path, noErrorOK) ==> string<a id="sec-4-2-13"></a>
+
+<a id="org2054a87"></a>
+
+### delete(path, noErrorOK) ==> string
 
 Delete a file on the remote server.
 
@@ -684,7 +749,10 @@ Delete a file on the remote server.
       });
     ```
 
-### rename(fromPath, toPath) ==> string<a id="sec-4-2-14"></a>
+
+<a id="org7497d9f"></a>
+
+### rename(fromPath, toPath) ==> string
 
 Rename a file or directory from `fromPath` to `toPath`. You must have the necessary permissions to modify the remote file.
 
@@ -710,7 +778,10 @@ Rename a file or directory from `fromPath` to `toPath`. You must have the necess
       });
     ```
 
-### posixRename(fromPath, toPath) ==> string<a id="sec-4-2-15"></a>
+
+<a id="orgb179088"></a>
+
+### 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 name exists. The POSIX rename will also work on some filesystems which do not support standard SFTP rename because they don't support the system hardlink() call. The POSIX rename extension is available on all openSSH servers from 4.8 and some other implementations. This is an extension to the standard SFTP protocol and therefore is not supported on all sSFTP servers.
 
@@ -734,7 +805,10 @@ client.connect(config)
   });
 ```
 
-### chmod(path, mode) ==> string<a id="sec-4-2-16"></a>
+
+<a id="org335a008"></a>
+
+### chmod(path, mode) ==> string
 
 Change the mode (read, write or execute permissions) of a remote file or directory.
 
@@ -760,7 +834,10 @@ Change the mode (read, write or execute permissions) of a remote file or directo
       });
     ```
 
-### realPath(path) ===> string<a id="sec-4-2-17"></a>
+
+<a id="org384f34a"></a>
+
+### 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.
 
@@ -768,11 +845,17 @@ Converts a relative path to an absolute path on the remote server. This method i
 
 -   **path:** A file path, either relative or absolute. Can handle '.' and '..', but does not expand '~'.
 
-### cwd() ==> string<a id="sec-4-2-18"></a>
+
+<a id="org8fa77d4"></a>
+
+### cwd() ==> string
 
 Returns what the server believes is the current remote working directory.
 
-### uploadDir(srcDir, dstDir, filter) ==> string<a id="sec-4-2-19"></a>
+
+<a id="orgb824235"></a>
+
+### uploadDir(srcDir, dstDir, filter) ==> string
 
 Upload the directory specified by `srcDir` to the remote directory specified by `dstDir`. The `dstDir` will be created if necessary. Any sub directories within `srcDir` will also be uploaded. Any existing files in the remote path will be overwritten.
 
@@ -834,7 +917,10 @@ The optionsl *filter* argument is a function which will be called for each item
     
     ```
 
-### downloadDir(srcDir, dstDir, filter) ==> string<a id="sec-4-2-20"></a>
+
+<a id="org46aa66f"></a>
+
+### downloadDir(srcDir, dstDir, filter) ==> string
 
 Download the remote directory specified by `srcDir` to the local file system directory specified by `dstDir`. The `dstDir` directory will be created if required. All sub directories within `srcDir` will also be copied. Any existing files in the local path will be overwritten. No files in the local path will be deleted.
 
@@ -894,7 +980,10 @@ The optional *filter* argument is a predicate function which will be called with
     
     ```
 
-### end() ==> boolean<a id="sec-4-2-21"></a>
+
+<a id="orge3fcb81"></a>
+
+### end() ==> boolean
 
 Ends the current client session, releasing the client socket and associated resources. This function also removes all listeners associated with the client.
 
@@ -915,7 +1004,10 @@ Ends the current client session, releasing the client socket and associated reso
       });
     ```
 
-### Add and Remove Listeners<a id="sec-4-2-22"></a>
+
+<a id="org4607268"></a>
+
+### Add and Remove Listeners
 
 Although normally not required, you can add and remove custom listeners on the ssh2 client object. This object supports a number of events, but only a few of them have any meaning in the context of SFTP. These are
 
@@ -933,15 +1025,24 @@ 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.
 
-# Platform Quirks & Warnings<a id="sec-5"></a>
 
-## Server Capabilities<a id="sec-5-1"></a>
+<a id="org66a7061"></a>
+
+# Platform Quirks & Warnings
+
+
+<a id="org740553b"></a>
+
+## Server Capabilities
 
 All SFTP servers and platforms are not equal. Some facilities provided by `ssh2-sftp-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.
 
-## Promises, Events & Managing Exceptions<a id="sec-5-2"></a>
+
+<a id="orgf97d765"></a>
+
+## Promises, Events & Managing Exceptions
 
 One of the challenges in providing a Promise based API over a module like SSH2, which is event based is how to ensure events are handled appropriately. The challenge is due to the synchronous nature of events. You cannot use `try/catch` for events because you have no way of knowing when the event might fire. For example, it could easily fire after your `try/catch` block as completed execution.
 
@@ -957,25 +1058,40 @@ The other area where additional events are fired is during the end() call. To de
 
 In addition to the promise based event handlers, `ssh2-sftp-client` also implements global event handlers which will catch any `error`, `end` or `close` events. Essentially, these global handlers only reset the `sftp` property of the client object, effectively ensuring any subsequent calls are rejected and in the case of an error, send the error to the console.
 
-### Adding Custom Handlers<a id="sec-5-2-1"></a>
+
+<a id="org6acf9c6"></a>
+
+### Adding Custom Handlers
 
 While the above strategies appear to work for the majority of use cases, there are always going to be edge cases which require more flexible or powerful event handling. To support this, the `on()` and `removeListener()` methods are provided. Any event listener added using the `on()` method will be added at the beginning of the list of handlers for that event, ensuring it will be called before any global or promise local events. See the documentation for the `on()` method for details.
 
-## Windows Based Servers<a id="sec-5-3"></a>
+
+<a id="orgb2f13ee"></a>
+
+## 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<a id="sec-5-4"></a>
+
+<a id="orgcd82e68"></a>
+
+## 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<a id="sec-6"></a>
 
-## Remote server drops connections with only an end event<a id="sec-6-1"></a>
+<a id="orge1aa1d7"></a>
+
+# FAQ
+
+
+<a id="org9296404"></a>
+
+## Remote server drops connections with only an end event
 
 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.
 
@@ -983,7 +1099,10 @@ 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 I pass writable stream as dst for get method?<a id="sec-6-2"></a>
+
+<a id="org3e48901"></a>
+
+## 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 writeable stream created with `fs.createWriteStream()`, the data will be written to the file specified in the constructor call to `createWriteStream()`.
 
@@ -1039,7 +1158,10 @@ sftp
   });
 ```
 
-## How can I upload files without having to specify a password?<a id="sec-6-3"></a>
+
+<a id="org1474028"></a>
+
+## How can I upload files without having to specify a password?
 
 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.
 
@@ -1071,7 +1193,10 @@ sftp.connect({
 }
 ```
 
-## How can I connect through a Socks Proxy<a id="sec-6-4"></a>
+
+<a id="orgb9a0ec1"></a>
+
+## How can I connect through a Socks Proxy
 
 This solution was provided by @jmorino.
 
@@ -1083,7 +1208,7 @@ const host = 'my-sftp-server.net';
 const port = 22; // default SSH/SFTP port on remote server
 
 // connect to SOCKS 5 proxy
-const { socket } = await SocksClient.createConnection({
+const { socks } = await SocksClient.createConnection({
   proxy: {
     host: 'my.proxy', // proxy hostname
     port: 1080, // proxy port
@@ -1096,7 +1221,7 @@ const { socket } = await SocksClient.createConnection({
 const client = new SFTPClient();
 client.connect({
   host,
-  sock: socket, // pass the socket to proxy here (see ssh2 doc)
+  sock: socks.socket, // pass the socket to proxy here (see ssh2 doc)
   username: '.....',
   privateKey: '.....'
 })
@@ -1104,13 +1229,19 @@ client.connect({
 // client is connected
 ```
 
-## Timeout while waiting for handshake or handshake errors<a id="sec-6-5"></a>
+
+<a id="org62e1f3a"></a>
+
+## Timeout while waiting for handshake or handshake errors
 
 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-6-6"></a>
+
+<a id="org7f26ef8"></a>
+
+## 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.
 
@@ -1147,7 +1278,10 @@ try {
 }
 ```
 
-## Connection hangs or fails for larger files<a id="sec-6-7"></a>
+
+<a id="orgfb52441"></a>
+
+## Connection hangs or fails for larger files
 
 This was contributed by Ladislav Jacho. Thanks.
 
@@ -1155,11 +1289,17 @@ A symptom of this issue is that you are able to upload small files, but uploadin
 
 For more explanation, see [issue #342](https://github.com/theophilusx/ssh2-sftp-client/issues/342).
 
-# Examples<a id="sec-7"></a>
+
+<a id="orgbe2b99e"></a>
+
+# Examples
 
 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-8"></a>
+
+<a id="orgd2dcb05"></a>
+
+# Troubleshooting
 
 The `ssh2-sftp-client` module is essentially a wrapper around the `ssh2` and `ssh2-streams` modules, providing a higher level `promise` based API. When you run into issues, it is important to try and determine where the issue lies - either in the ssh2-sftp-client module or the underlying `ssh2` and `ssh2-streams` modules. One way to do this is to first identify a minimal reproducible example which reproduces the issue. Once you have that, try to replicate the functionality just using the `ssh2` and `ssh2-streams` modules. If the issue still occurs, then you can be fairly confident it is something related to those later 2 modules and therefore and issue which should be referred to the maintainer of that module.
 
@@ -1171,11 +1311,17 @@ Note also that in the repository there are two useful directories. The first is
 
 The second directory is the validation directory. I have some very simple scripts in this directory which perform basic tasks using only the `ssh2` modules (no `ssh2-sftp-client` module). These can be useful when trying to determine if the issue is with the underlying `ssh2` module or the `ssh2-sftp-client` wrapper module.
 
-## Common Errors<a id="sec-8-1"></a>
+
+<a id="orgae04d0a"></a>
+
+## Common Errors
 
 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.
 
-### Not returning the promise in a `then()` block<a id="sec-8-1-1"></a>
+
+<a id="org2018983"></a>
+
+### Not returning the promise in a `then()` block
 
 All methods in `ssh2-sftp-client` return a Promise. This means methods are executed *asynchrnously*. When you call a method inside the `then()` block of a promise chain, it is critical that you return the Promise that call 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 example, the following will not do what you expect
 
@@ -1209,7 +1355,10 @@ Note the `return` statements. These ensure that the Promise returned by the clie
 
 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.
 
-### Mixing Promise Chains and Async/Await<a id="sec-8-1-2"></a>
+
+<a id="org6a3654b"></a>
+
+### Mixing Promise Chains and Async/Await
 
 Another common error is to mix Promise chains and async/await calls. This is rarely a great idea. While you can do this, it tends to create complicated and difficult to maintain code. Select one approach and stick with it. Both approaches are functionally equivalent, so there is no reason to mix up the two paradigms. My personal preference would be to use async/await as I think that is more *natural* for most developers. For example, the following is more complex and difficult to follow than necessary (and has a bug!)
 
@@ -1266,7 +1415,10 @@ async function doSftp() {
 }
 ```
 
-### Try/catch and Error Handlers<a id="sec-8-1-3"></a>
+
+<a id="org36087fd"></a>
+
+### Try/catch and Error Handlers
 
 Another common error is to try and use a try/catch block to catch event 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.
 
@@ -1274,17 +1426,26 @@ The basic problem is that the try/catch block will have completed execution befo
 
 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 event errors. Even creating an error handler which then throws an exception won't help as the key problem is that your try/catch block has already executed. There are a number of alternative ways to deal with this situation. However, the key symptom is that you see occasional uncaught 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.
 
-### Server Differences<a id="sec-8-1-4"></a>
+
+<a id="orgd09c9c8"></a>
+
+### Server Differences
 
 Not all SFTP servers are the same. Like most standards, the SFTP protocol has some level of interpretation and allows different levels of compliance. This means there can be differences in behaviour between different servers and code which works with one server will not work the same with another. For example, the value returned by *realpath* for non-existent objects can differ significantly. Some servers will throw an error for a particular operation while others will just return null, some servers support concurrent operations (such as used by fastGet/fastPut) while others will not and of course, the text of error messages can vary significantly. In particular, we have noticed significant differences across different platforms. It is therefore advisable to do comprehensive testing when the SFTP server is moved to a new platform. This includes moving from to a cloud based service even if the underlying platform remains the same. I have noticed that some cloud platforms can generate unexpected events, possibly related to additional functionality or features associated with the cloud implementation. For example, it appears SFTP servers running under Azure will generate an error event when the connection is closed even when the client has requested the connection be terminated. The same SFTP server running natively on Windows does not appear to exhibit such behaviour.
 
-### Avoid Concurrent Operations<a id="sec-8-1-5"></a>
+
+<a id="org67e5a24"></a>
+
+### Avoid Concurrent Operations
 
 Technically, SFTP should be able to perform multiple operations concurrently. As node is single threaded, what we a really talking about is running multiple execution contexts as a pool where node will switch contexts when each context is blocked due to things like waiting on network data etc. However, I have found this to be extremely unreliable and of very little benefit from a performance perspective. My recommendation is to therefore avoid executing multiple requests over the same connection in parallel (for example, generating multiple `get()` promises and using something like `Promise.all()` to resolve them.
 
 If you are going to try and perform concurrent operations, you need to test extensively and ensure you are using data which is large enough that context switching does occur (i.e. the request is not completed in a single run). Some SFTP servers will handle concurrent operations better than others.
 
-## Debugging Support<a id="sec-8-2"></a>
+
+<a id="org00c676b"></a>
+
+## Debugging Support
 
 You can add a `debug` property to the config object passed in to `connect()` to turn on debugging. This will generate quite a lot of output. The value of the property should be a function which accepts a single string argument. For example;
 
@@ -1314,7 +1475,10 @@ If you just want to see debug messages from `ssh2-sftp-client` and exclude debug
 }
 ```
 
-# Logging Issues<a id="sec-9"></a>
+
+<a id="org6f7f508"></a>
+
+# Logging Issues
 
 Please log an issue for all bugs, questions, feature and enhancement requests. Please ensure you include the module version, node version and platform.
 
@@ -1328,7 +1492,10 @@ I am happy to try and help diagnose and fix any issues you encounter while using
 
 Perhaps the best assistance is a minimal reproducible example of the issue. Once the issue can be readily reproduced, it can usually be fixed very quickly.
 
-# Pull Requests<a id="sec-10"></a>
+
+<a id="org2d2ad0d"></a>
+
+# Pull Requests
 
 Pull requests are always welcomed. However, please ensure your changes pass all tests and if you're adding a new feature, that tests for that feature are included. Likewise, for new features or enhancements, please include any relevant documentation updates.
 
@@ -1340,7 +1507,10 @@ This module will adopt a standard semantic versioning policy. Please indicate in
 -   **Minor:** Minor change, enhancement or new feature which does not change existing API and will not break existing client code.
 -   **Bug Fix:** No change to functionality or features. Simple fix of an existing bug.
 
-# Contributors<a id="sec-11"></a>
+
+<a id="orgba32989"></a>
+
+# Contributors
 
 This module was initially written by jyu213. On August 23rd, 2019, theophilusx took over responsibility for maintaining this module. A number of other people have contributed to this module, but until now, this was not tracked. My intention is to credit anyone who contributes going forward.
 
@@ -1359,4 +1529,4 @@ Thanks to the following for their contributions -
 -   **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.
--   **cakemasher:** Contributed fix for removeTempListeners().
+-   **cakemasher:** Contributed fix for removeTempListeners().

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 *v8.0.0*.
+Current stable release is *v8.1.0*.
 
-Code has been tested against Node versions 14.19.1, 16.14.2 and 17.8.0
+Code has been tested against Node versions 14.19.1, 16.15.0 and 18.1.0
 
 Node versions < 12.x are not supported. However, node v10.x should still work,
 although some tests will fail due to changes in file system functions used in
@@ -44,6 +44,15 @@ test setup and tear down.
     extreme use case which is rare (a use case which wold also have been
     problematic with the old implementation as performance would have been very
     poor).
+
+ - v8.1.0: The ~list()~ method now includes a ~longname~ property in the descriptor
+   object for each file in the listing. The ~longname~ value is a string which
+   resembles the ~ls -l~ listing.
+   
+ - v8.1.0: The ~rmdir()~ method has been further modified to not recurse into
+   directories using async. It was found that on large directories, this could
+   result in too many separate async processes. Only deletion of files is now
+   handled with asynchronous calls. 
     
 * Installation
 
@@ -308,6 +317,7 @@ The objects in the array returned by ~list()~ have the following properties;
     },
     owner: // user ID
     group: // group ID
+    longname: // like ls -l line
   }
 #+end_src
 
@@ -1353,7 +1363,7 @@ This solution was provided by @jmorino.
   const port = 22; // default SSH/SFTP port on remote server
 
   // connect to SOCKS 5 proxy
-  const { socket } = await SocksClient.createConnection({
+  const { socks } = await SocksClient.createConnection({
     proxy: {
       host: 'my.proxy', // proxy hostname
       port: 1080, // proxy port
@@ -1366,7 +1376,7 @@ This solution was provided by @jmorino.
   const client = new SFTPClient();
   client.connect({
     host,
-    sock: socket, // pass the socket to proxy here (see ssh2 doc)
+    sock: socks.socket, // pass the socket to proxy here (see ssh2 doc)
     username: '.....',
     privateKey: '.....'
   })

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "ssh2-sftp-client",
-  "version": "8.0.0",
+  "version": "8.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",
@@ -47,6 +51,6 @@
   "dependencies": {
     "concat-stream": "^2.0.0",
     "promise-retry": "^2.0.1",
-    "ssh2": "^1.9.0"
+    "ssh2": "^1.10.0"
   }
 }

package/src/index.js

@@ -428,6 +428,7 @@ class SftpClient {
                   },
                   owner: item.attrs.uid,
                   group: item.attrs.gid,
+                  longname: item.longname,
                 };
               });
             }
@@ -790,45 +791,63 @@ class SftpClient {
    * @param  {Object} options
    * @return {Promise<String>}
    */
+
   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
-      );
-    }
-    let listeners;
-    return await new Promise((resolve, reject) => {
-      listeners = addTempListeners(this, 'append', reject);
-      if (haveConnection(this, 'append', reject)) {
-        if (typeof input === 'string') {
-          reject(fmtError('Cannot append one file to another', 'append'));
+    const _append = (input, remotePath, options) => {
+      return new Promise((resolve, reject) => {
+        this.debugMsg(`append -> remote: ${remotePath} `, options);
+        options.flags = 'a';
+        let stream = this.sftp.createWriteStream(remotePath, options);
+        stream.on('error', (err) => {
+          this.debugMsg(
+            `append: Error ${err.message} appending to ${remotePath}`
+          );
+          reject(fmtError(`${err.message} ${remotePath}`, 'append', err.code));
+        });
+        stream.on('close', () => {
+          this.debugMsg(`append: data appended to ${remotePath}`);
+          resolve(`Appended data to ${remotePath}`);
+        });
+        if (input instanceof Buffer) {
+          this.debugMsg('append: writing data buffer to remote file');
+          stream.write(input);
+          stream.end();
         } else {
-          this.debugMsg(`append -> remote: ${remotePath} `, options);
-          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 {
-            input.pipe(stream);
-          }
+          this.debugMsg('append: writing stream to remote file');
+          input.pipe(stream);
+        }
+      });
+    };
+
+    let listeners;
+    try {
+      listeners = addTempListeners(this, 'append');
+      if (typeof input === 'string') {
+        this.debugMsg('append: attempt to append two files - throw');
+        throw fmtError(
+          'Cannot append one file to another',
+          'append',
+          errorCode.badPath
+        );
+      }
+      if (haveConnection(this, 'append')) {
+        const fileType = await this.exists(remotePath);
+        if (fileType && fileType === 'd') {
+          this.debugMsg(`append: Error ${remotePath} not a file`);
+          throw fmtError(
+            `Bad path: ${remotePath}: cannot append to a directory`,
+            'append',
+            errorCode.badPath
+          );
         }
+        await _append(input, remotePath, options);
       }
-    }).finally(() => {
+    } catch (e) {
+      throw e.custom ? e : fmtError(e.message, 'append', e.code);
+    } finally {
       removeTempListeners(this, listeners, 'append');
       this._resetEventFlags();
-    });
+    }
   }
 
   /**
@@ -951,15 +970,13 @@ class SftpClient {
             let dirs = list.filter((item) => item.type === 'd');
             this.debugMsg('rmdir contents (files): ', files);
             this.debugMsg('rmdir contents (dirs): ', dirs);
+            for (let d of dirs) {
+              await _dormdir(`${p}${this.remotePathSep}${d.name}`, true);
+            }
             let promiseList = [];
             for (let f of files) {
               promiseList.push(_delete(`${p}${this.remotePathSep}${f.name}`));
             }
-            for (let d of dirs) {
-              promiseList.push(
-                _dormdir(`${p}${this.remotePathSep}${d.name}`, true)
-              );
-            }
             await Promise.all(promiseList);
           }
         }
@@ -1146,8 +1163,7 @@ class SftpClient {
    * server.
    * @param {String} srcDir - local source directory
    * @param {String} dstDir - remote destination directory
-   * @param {RegExp} filter - (Optional) a regular expression used to select
-   *                         files and directories to upload
+   * @param {function(String,Boolean):Boolean} filter - (Optional) The first argument is the full path of the item to be uploaded and the second argument is a boolean, which will be true if the target path is for a directory.  If the function returns true, the item will be uploaded
    * @returns {Promise<String>}
    */
   async uploadDir(srcDir, dstDir, filter) {
@@ -1224,8 +1240,7 @@ class SftpClient {
    * file system.
    * @param {String} srcDir - remote source directory
    * @param {String} dstDir - local destination directory
-   * @param {RegExp} filter - (Optional) a regular expression used to select
-   *                         files and directories to upload
+   * @param {function(String,Boolean):Boolean} filter - (Optional) The first argument is the full path of the item to be downloaded and the second argument is a boolean, which will be true if the target path is for a directory.  If the function returns true, the item will be downloaded
    * @returns {Promise<String>}
    */
   async downloadDir(srcDir, dstDir, filter) {