ssh2-sftp-client 6.0.1 → 7.0.0

package/CHANGELOG.org

@@ -1,6 +1,13 @@
 * Change Logging
 
-** Version 6.0.1
+** V7.0.0
+   - New version based on new SSH2 version 1.1.0.
+   - Expand option handling for get() and put() methods *Breaking Change*
+   - Re-factored the retry code in the connect() method
+   - Improve error reporting for adding/removing listeners
+   - Extend localExists() method to also verify read or write access
+       
+** V6.0.1
    - Fix issue with connect retry not releasing 'ready' listeners
    - Add finally clauses to all promises to ensure temporary listeners are deleted
    - Add nyc module to report on code test coverage

package/README.md

@@ -1,9 +1,7 @@
 - [Overview](#sec-1)
 - [Installation](#sec-2)
 - [Basic Usage](#sec-3)
-- [Version 6.x Changes](#sec-4)
-  - [Version 6.0.1](#sec-4-1)
-  - [Version 6.0.0 Changes](#sec-4-2)
+- [Version 7.x Changes](#sec-4)
 - [Documentation](#sec-5)
   - [Specifying Paths](#sec-5-1)
   - [Methods](#sec-5-2)
@@ -59,24 +57,14 @@
 
 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.
+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 **v5.3.2**.
+Current stable release is **v7.0.0**.
 
-Code has been tested against Node versions 12.18.2 and 13.14.0
+Code has been tested against Node versions 12.22.1, 14.17.0 and 16.2.0
 
 Node versions < 10.x are not supported.
 
-<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>
 
 ```shell
@@ -103,23 +91,13 @@ sftp.connect({
 });
 ```
 
-# Version 6.x Changes<a id="sec-4"></a>
+# Version 7.x Changes<a id="sec-4"></a>
 
-## Version 6.0.1<a id="sec-4-1"></a>
+-   This version is based on version 1.1.0 of `ssh2`. This version of `ssh2` is a complete re-write of the `ssh2` library. This re-write addresses issues encountered when using node v14 as well as some design weaknesses in the previous 0.8.x version.
 
--   Fix issue with connect retry not releasing 'ready' listener.
--   Add finally clauses to all promises to ensure release of temporary listeners.
--   Add nyc module to improve test coverage
--   Added additional utils tests to improve test coverage
--   Removed some unnecessary util functions to reduce code size
+-   **Breaking Change** Expanded option handling for `get()` and `put()` methods. A number of use cases were identified where setting specific options on the read and write streams and the pipe operation are necessary. For example, disabling `autoClose` on streams or the `end` event in pipes. The `options` argument for `get()` and `put()` calls now supports properties for `readStreamOptions`, `writeStreamOptions` and `pipeOptions`. Note that options are only applied to streams created by the `get()` and `put()` methods. Streams passed into these methods are under the control of the client code and therefore cannot have options supplied in arguments to those streams (you would apply such options when you create the streams). Options are typically only necessary in special use cases. Most of the time, no options are required. However, if you are currently using options to either `put()` or `get()`, you will need to update your code to map these options to the new structure.
 
-## Version 6.0.0 Changes<a id="sec-4-2"></a>
-
--   Added new optional argument *notFoundOK* to `delete()` method. If true, no error is thrown when trying to delete a file which does not exist. Default is false.
--   Added new filter argument to `uploadDir()` and `downloadDir()` methods. The filter argument is a regular expression used to match the files and directories to be included in the upload or download. Defaults to match all files and directories.
--   New event handling approach. Have standardised the adding and removing of event handlers as well as added event handlers for *close* and *end* events. Some sftp servers appear to abruptly terminate connections without issuing an *error* event. This could result in failing to resolve the promise associated with the action being performed. Adding *close* and *end* listeners to reject a promise should prevent the scripts from hanging when the remote server does not return either a status or an error.
--   Replace the `retry` library module with the `promise-retry` library module. This module also uses the `retry` library, but at a higher level abstracted for use with Promises. As a result, the number of failed retries is no longer returned as part of the error message when all attempted connection retries fail.
--   Reduced argument verification code. Version 5.x added a lot of additional argument verification code in an attempt to provide more meaningful error messages. While this goal was achieved, it did have a significant performance impact, especially with respect to small file transfers. This additional argument verification has now been removed in favour of faster code. The downside is that some error messages have changed and in some cases, will not be as meaningful or will be more generic in nature. This seems as a reasonable compromise. It may result in increased difficulty tracking down why a script is failing, but once a script is working, it should be more efficient. If your code relies on the text in error messages, you will need to verify whether the text is still the same in any testing and adjust where necessary.
+-   Improved event handling. A listener for a global error event is now defined to catch errors which occur in-between method calls i.e. connection lost in-between calls to the library methods. A new mechanism has also been added for removal of listeners when no longer required.
 
 # Documentation<a id="sec-5"></a>
 
@@ -129,7 +107,7 @@ 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.
+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.
 
@@ -171,17 +149,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();
@@ -202,12 +180,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.
@@ -226,9 +204,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,
@@ -269,16 +247,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');
@@ -297,7 +275,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)
@@ -318,11 +296,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>
@@ -333,16 +311,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');
@@ -367,7 +345,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
@@ -390,7 +368,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');
@@ -418,28 +396,33 @@ 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.
-
+    The `options` argument can be used to pass options to the underlying streams and pipe call used by this method. The argument is an object with three possible properties, `readStreamOptions`, `writeStreamOptions` and `pipeOptions`. The values for each of these properties should be an object containing the required options. For example, possible read stream and pipe options could be defined as
+    
     ```javascript
-    {
-      flags: 'r',
-      encoding: null,
-      handle: null,
-      mode: 0o666,
-      autoClose: true
-    }
+    let options = {
+      readStreamOptions: {
+        flags: 'r',
+        encoding: null,
+        handle: null,
+        mode: 0o666,
+        autoClose: true
+      },
+      pipeOptions: {
+        end: false
+      }};
+    
     ```
-
+    
     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);
@@ -451,7 +434,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>
@@ -472,7 +455,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
@@ -481,7 +464,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);
@@ -500,31 +483,32 @@ Upload data from local system to remote server. If the `src` argument is a strin
 
 -   **src:** string | buffer | readable stream. Data source for data to copy to the remote server.
 -   **remotePath:** string. Path to the remote file to be created on the server.
--   **options:** object. Options which can be passed to adjust the write stream used in sending the data to the remote server (see below).
+-   **options:** object. Options which can be passed to adjust the read and write stream used in sending the data to the remote server or the pipe call used to make the data transfer (see below).
 
 1.  Options
 
-    The following options are supported;
-
+    The options object supports three properties, `readStreamOptions`, `writeStreamOptions` and `pipeOptions`. The value for each property should be an object with options as properties and their associated values representing the option value. For example, you might use the following to set `writeStream` options.
+    
     ```javascript
     {
-      flags: 'w',  // w - write and a - append
-      encoding: null, // use null for binary files
-      mode: 0o666, // mode to use for created file (rwx)
-      autoClose: true // automatically close the write stream when finished
-    }
+      writeStreamOptions: {
+        flags: 'w',  // w - write and a - append
+        encoding: null, // use null for binary files
+        mode: 0o666, // mode to use for created file (rwx)
+        autoClose: true // automatically close the write stream when finished
+    }}
     ```
-
+    
     The most common options to use are mode and encoding. The values shown above are the defaults. You do not have to set encoding to utf-8 for text files, null is fine for all file types. However, using utf-8 encoding for binary files will often result in data corruption.
 
 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);
@@ -536,7 +520,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>
@@ -558,7 +542,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
@@ -567,7 +551,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);
@@ -591,7 +575,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
@@ -600,7 +584,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
@@ -608,7 +592,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);
@@ -633,7 +617,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);
@@ -660,7 +644,7 @@ Remove a directory. If removing a directory and recursive flag is set to `true`,
     ```javascript
     let remoteDir = '/path/to/remote/dir';
     let client = new Client();
-
+    
     client.connect(config)
       .then(() => {
         return client.rmdir(remoteDir, true);
@@ -686,7 +670,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);
@@ -712,7 +696,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);
@@ -762,7 +746,7 @@ Change the mode (read, write or execute permissions) of a remote file or directo
     let path = '/path/to/remote/file.txt';
     let newMode = 0o644;  // rw-r-r
     let client = new Client();
-
+    
     client.connect(config)
       .then(() => {
         return client.chmod(path, newMode);
@@ -803,28 +787,28 @@ The optionsl *filter* argument is a regular expression which can be used to sele
 
     ```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 => {
@@ -836,7 +820,7 @@ The optionsl *filter* argument is a regular expression which can be used to sele
       client.end();
     }
         }
-
+    
         main()
     .then(msg => {
       console.log(msg);
@@ -844,7 +828,7 @@ The optionsl *filter* argument is a regular expression which can be used to sele
     .catch(err => {
       console.log(`main error: ${err.message}`);
     });
-
+    
     ```
 
 ### downloadDir(srcDir, dstDir, filter) ==> string<a id="sec-5-2-20"></a>
@@ -863,28 +847,28 @@ The optional *filter* argument is a regular expression which can be used to sele
 
     ```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 => {
@@ -896,7 +880,7 @@ The optional *filter* argument is a regular expression which can be used to sele
         client.end();
       }
     }
-
+    
     main()
       .then(msg => {
         console.log(msg);
@@ -904,7 +888,7 @@ The optional *filter* argument is a regular expression which can be used to sele
       .catch(err => {
         console.log(`main error: ${err.message}`);
       });
-
+    
     ```
 
 ### end() ==> boolean<a id="sec-5-2-21"></a>
@@ -915,7 +899,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
@@ -948,7 +932,7 @@ Although normally not required, you can add and remove custom listeners on the s
 
 ## 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.
+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.