ssh2-sftp-client 7.0.0 → 7.0.4

package/README.md

@@ -6,7 +6,7 @@
   - [Specifying Paths](#sec-5-1)
   - [Methods](#sec-5-2)
     - [new SftpClient(name) ===> SFTP client object](#sec-5-2-1)
-    - [connect(config) ===> SFTPstream](#sec-5-2-2)
+    - [connect(config) ===> SFTP object](#sec-5-2-2)
     - [list(path, pattern) ==> Array[object]](#sec-5-2-3)
     - [exists(path) ==> boolean](#sec-5-2-4)
     - [stat(path) ==> object](#sec-5-2-5)
@@ -29,7 +29,8 @@
     - [Add and Remove Listeners](#sec-5-2-22)
 - [Platform Quirks & Warnings](#sec-6)
   - [Server Capabilities](#sec-6-1)
-  - [Promises & Events](#sec-6-2)
+  - [Promises, Events & Managing Exceptions](#sec-6-2)
+    - [Adding Custom Handlers](#sec-6-2-1)
   - [Windows Based Servers](#sec-6-3)
   - [Don't Re-use SftpClient Objects](#sec-6-4)
 - [FAQ](#sec-7)
@@ -39,6 +40,7 @@
   - [How can I connect through a Socks Proxy](#sec-7-4)
   - [Timeout while waiting for handshake or handshake errors](#sec-7-5)
   - [How can I limit upload/download speed](#sec-7-6)
+  - [Connection hangs or fails for larger files](#sec-7-7)
 - [Examples](#sec-8)
 - [Troubleshooting](#sec-9)
   - [Common Errors](#sec-9-1)
@@ -59,7 +61,7 @@ an SFTP client for node.js, a wrapper around [SSH2](https://github.com/mscdex/ss
 
 Documentation on the methods and available options in the underlying modules can be found on the [SSH2](https://github.com/mscdex/ssh2) project pages.
 
-Current stable release is **v7.0.0**.
+Current stable release is **v7.0.4**.
 
 Code has been tested against Node versions 12.22.1, 14.17.0 and 16.2.0
 
@@ -93,7 +95,7 @@ sftp.connect({
 
 # Version 7.x Changes<a id="sec-4"></a>
 
--   This version is based on version 1.1.0 of `ssh2`. This version of `ssh2` is a complete re-write of the `ssh2` library. This re-write addresses issues encountered when using node v14 as well as some design weaknesses in the previous 0.8.x version.
+-   This version is based on version 1.x.x of `ssh2`. This version of `ssh2` is a complete re-write of the `ssh2` library. This re-write addresses issues encountered when using node v14 as well as some design weaknesses in the previous 0.8.x version.
 
 -   **Breaking Change** Expanded option handling for `get()` and `put()` methods. A number of use cases were identified where setting specific options on the read and write streams and the pipe operation are necessary. For example, disabling `autoClose` on streams or the `end` event in pipes. The `options` argument for `get()` and `put()` calls now supports properties for `readStreamOptions`, `writeStreamOptions` and `pipeOptions`. Note that options are only applied to streams created by the `get()` and `put()` methods. Streams passed into these methods are under the control of the client code and therefore cannot have options supplied in arguments to those streams (you would apply such options when you create the streams). Options are typically only necessary in special use cases. Most of the time, no options are required. However, if you are currently using options to either `put()` or `get()`, you will need to update your code to map these options to the new structure.
 
@@ -173,7 +175,7 @@ Constructor to create a new `ssh2-sftp-client` object. An optional `name` string
       });
     ```
 
-### connect(config) ===> SFTPstream<a id="sec-5-2-2"></a>
+### connect(config) ===> SFTP object<a id="sec-5-2-2"></a>
 
 Connect to an sftp server. Full documentation for connection options is available [here](https://github.com/mscdex/ssh2#user-content-client-methods)
 
@@ -918,11 +920,13 @@ Although normally not required, you can add and remove custom listeners on the s
 
 -   **error:** An error occurred. Calls listener with an error argument.
 -   **end:** The socket has been disconnected. No argument.
--   **close:** The socket was closed. Boolean argument which is true when the socket was closed due to errors.
+-   **close:** The socket was closed.
 
 1.  on(eventType, listener)
 
-    Adds the specified listener to the specified event type. It the event type is `error`, the listener should accept 1 argument, which will be an Error object. If the event type is `close`, the listener should accept one argument of a boolean type, which will be true when the client connection was closed due to errors.
+    Adds the specified listener to the specified event type. It the event type is `error`, the listener should accept 1 argument, which will be an Error object. The event handlers for `end` and `close` events have no arguments.
+    
+    The handlers will be added to the beginning of the listener's event handlers, so it will be called before any of the `ssh2-sftp-client` listeners.
 
 2.  removeListener(eventType, listener)
 
@@ -936,19 +940,25 @@ All SFTP servers and platforms are not equal. Some facilities provided by `ssh2-
 
 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 & Managing Exceptions<a id="sec-6-2"></a>
+
+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.
+
+Things become even more complicated once you mix in Promises. When you define a promise, you have to methods which can be called to fulfil a promise, `resolve` and `reject`. Only one can be called - once you call `resolve`, you cannot call `reject` (well, you can call it, but it won't have any impact on the fulfilment status of the promise). The problem arises when an event, for exmaple an `error` event is fired either after you have resolved a promise or possibly in-between promises. If you don't catch the `error` event, your script will likely crash with an `uncaught exception` error.
 
-## Promises & Events<a id="sec-6-2"></a>
+To make matters worse, some servers, particularly servers running on a Windows platform, will raise multiple errors for the same error *event*. For example, when you attempt to connect with a bad username or password, you will get a `All authentication methods have failed` exception. However, under Windows, you will also get a `Connection reset by peer` exception. If we reject the connect promise based on the authentication failure exception, what do we do with the `reset by peer` exception? More critically, what will handle that exception given the promise has already been fulfilled and completed? To make matters worse, it seems that Windows based servers also raise an error event for *non-errors*. For example, when you call the `end()` method, the connection is closed. On windows, this also results in a *connection reset by peer* error. While it could be argued that the remote server resetting the connection after receiving a disconnect request is not an error, it doesn't change the fact that one is raised and we need to somehow deal with it.
 
-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.
+To handle this, `ssh2-sftp-client` implements a couple of strategies. Firstly, when you call one of the module's methods, it adds `error`, `end` and `close` event listeners which will call the `reject` moethod on the enclosing promise. It also keeps track of whether an error has been handled and if it has, it ignores any subsequent errors until the promise ends. Typically, the first error caught has the most relevant information and any subsequent error events are less critical or informative, so ignoring them has no negative impact. Provided one of the events is raised before the promise is fulfilled, these handlers will consume the event and deal with it appropriately.
 
-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.
+In testing, it was found that in some situations, particularly during connect operations, subsequent errors fired with a small delay. This prevents the errors from being handled by the event handlers associated with the connect promise. To deal with this, a small 500ms delay has been added to the connect() method, which effectively delays the removal of the event handlers until all events have been caught.
 
-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.
+The other area where additional events are fired is during the end() call. To deal with these events, the `end()` method setus up listeners which will simply ignore additional `error`, `end` and `close` events. It is assumed that once you have called `end()` you really only care about any main error which occurs and no longer care about other errors that may be raised as the connection is terminated.
 
-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).
+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.
 
-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.
+### Adding Custom Handlers<a id="sec-6-2-1"></a>
+
+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-6-3"></a>
 
@@ -1097,6 +1107,8 @@ client.connect({
 
 Some users have encountered the error 'Timeout while waiting for handshake' or 'Handshake failed, no matching client->server ciphers. This is often due to the client not having the correct configuration for the transport layer algorithms used by ssh2. One of the connect options provided by the ssh2 module is `algorithm`, which is an object that allows you to explicitly set the key exchange, ciphers, hmac and compression algorithms as well as server host key used to establish the initial secure connection. See the SSH2 documentation for details. Getting these parameters correct usually resolves the issue.
 
+When encountering this type of problem, one worthwhile approach is to use openSSH's CLI sftp program with the `-v` switch to raise loggin levels. This will show you what algorithms the CLI is using. You can then use this information to match the names with the accepted algorithm names documented in the `ssh2` README to set the properties in the `algorithms` object.
+
 ## How can I limit upload/download speed<a id="sec-7-6"></a>
 
 If you want to limit the amount of bandwidth used during upload/download of data, you can use a stream to limit throughput. The following example was provided by *kennylbj*. Note that there is a caveat that we must set the `autoClose` flag to false to avoid calling an extra `_read()` on a closed stream that may cause \_get Permission Denied error in ssh2-streams.
@@ -1134,6 +1146,14 @@ try {
 }
 ```
 
+## Connection hangs or fails for larger files<a id="sec-7-7"></a>
+
+This was contributed by Ladislav Jacho. Thanks.
+
+A symptom of this issue is that you are able to upload small files, but uploading larger ones fail. You probably have an MTU/fragmentation problem. For each network interface on both client and server set the MTU to 576, e.g. `ifconfig eth0 mtu 576`. If that works, you need to find the largest MTU which will work for your network. An MTU which is too small will adversely affect throughput speed. A common value to use is an MTU of 1400.
+
+For more explanation, see [issue #342](https://github.com/theophilusx/ssh2-sftp-client/issues/342).
+
 # Examples<a id="sec-8"></a>
 
 I have started collecting example scripts in the example directory of the repository. These are mainly scripts I have put together in order to investigate issues or provide samples for users. They are not robust, lack adequate error handling and may contain errors. However, I think they are still useful for helping developers see how the module and API can be used.
@@ -1311,6 +1331,8 @@ Perhaps the best assistance is a minimal reproducible example of the issue. Once
 
 Pull requests are always welcomed. However, please ensure your changes pass all tests and if your adding a new feature, that tests for that feature are included. Likewise, for new features or enhancements, please include any relevant documentation updates.
 
+**Note**: The `README.md` file is generated from the `README.org` file. Therefore, any documentation updates or fixes need to be made to the `README.org` file. This file is *tangled* using `Emacs` org mode. If you don't use Emacs or org-mode, don't be too concerned. The org-mode syntax is straight-forward and similar to *markdown*. I will verify any updates to `README.org` and generate a new `README.md` when necessary. The main point to note is that any changes made directly to `README.md` will not persist and will be lost when a new version is generated, so don't modify that file.
+
 This module will adopt a standard semantic versioning policy. Please indicate in your pull request what level of change it represents i.e.
 
 -   **Major:** Change to API or major change in functionality which will require an increase in major version number.
@@ -1332,3 +1354,5 @@ Thanks to the following for their contributions -
 -   **teenangst:** Contributed fix for error code 4 in stat() method
 -   **kennylbj:** Contributed example of using a throttle stream to limit upload/download bandwidth.
 -   **anton-erofeev:** Documentation fix
+-   **Ladislav Jacho:** Contributed solution explanation for connections hanging when transferring larger files.
+-   **Emma Milner:** Contributed fix for put() bug

package/README.org

@@ -9,7 +9,7 @@ convenience abstraction as well as a Promise based API.
 Documentation on the methods and available options in the underlying modules can
 be found on the [[https://github.com/mscdex/ssh2][SSH2]] project pages.
 
-Current stable release is *v7.0.0*.
+Current stable release is *v7.0.4*.
 
 Code has been tested against Node versions 12.22.1, 14.17.0 and 16.2.0
 
@@ -43,7 +43,7 @@ npm install ssh2-sftp-client
 
 * Version 7.x Changes
 
-- This version is based on version 1.1.0 of ~ssh2~. This version of ~ssh2~ is a
+- This version is based on version 1.x.x of ~ssh2~. This version of ~ssh2~ is a
   complete re-write of the ~ssh2~ library. This re-write addresses issues
   encountered when using node v14 as well as some design weaknesses in the
   previous 0.8.x version.
@@ -175,7 +175,7 @@ client has thrown the error.
     });
 #+end_src
 
-*** connect(config) ===> SFTPstream
+*** connect(config) ===> SFTP object
 
 Connect to an sftp server. Full documentation for connection options is
 available [[https://github.com/mscdex/ssh2#user-content-client-methods][here]]
@@ -1036,15 +1036,16 @@ them have any meaning in the context of SFTP. These are
 
 - error :: An error occurred. Calls listener with an error argument.
 - end :: The socket has been disconnected. No argument.
-- close :: The socket was closed. Boolean argument which is true when the socket
-           was closed due to errors.
+- close :: The socket was closed. 
 
 **** on(eventType, listener)
 
 Adds the specified listener to the specified event type. It the event type is
-~error~, the listener should accept 1 argument, which will be an Error object. If
-the event type is ~close~, the listener should accept one argument of a boolean
-type, which will be true when the client connection was closed due to errors.
+~error~, the listener should accept 1 argument, which will be an Error object.
+The event handlers for =end= and =close= events have no arguments.
+
+The handlers will be added to the beginning of the listener's event handlers, so
+it will be called before any of the =ssh2-sftp-client= listeners.
 
 **** removeListener(eventType, listener)
 
@@ -1072,60 +1073,81 @@ the ~end()~ method automatically removes all listeners from the client object.
    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.
-
+** 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.
+
+   Things become even more complicated once you mix in Promises. When you define
+   a promise, you have to methods which can be called to fulfil a promise,
+   =resolve= and =reject=. Only one can be called - once you call =resolve=, you
+   cannot call =reject= (well, you can call it, but it won't have any impact on
+   the fulfilment status of the promise). The problem arises when an event, for
+   exmaple an =error= event is fired either after you have resolved a promise or
+   possibly in-between promises. If you don't catch the =error= event, your
+   script will likely crash with an =uncaught exception= error.
+
+   To make matters worse, some servers, particularly servers running on a
+   Windows platform, will raise multiple errors for the same error /event/. For
+   example, when you attempt to connect with a bad username or password, you
+   will get a =All authentication methods have failed= exception. However, under
+   Windows, you will also get a =Connection reset by peer= exception. If we
+   reject the connect promise based on the authentication failure exception,
+   what do we do with the =reset by peer= exception? More critically, what will
+   handle that exception given the promise has already been fulfilled and
+   completed? To make matters worse, it seems that Windows based servers also
+   raise an error event for /non-errors/. For example, when you call the =end()=
+   method, the connection is closed. On windows, this also results in a
+   /connection reset by peer/ error. While it could be argued that the remote
+   server resetting the connection after receiving a disconnect request is not
+   an error, it doesn't change the fact that one is raised and we need to
+   somehow deal with it.
+
+   To handle this, =ssh2-sftp-client= implements a couple of strategies.
+   Firstly, when you call one of the module's methods, it adds =error=, =end=
+   and =close= event listeners which will call the =reject= moethod on the
+   enclosing promise. It also keeps track of whether an error has been handled
+   and if it has, it ignores any subsequent errors until the promise ends.
+   Typically, the first error caught has the most relevant information and any
+   subsequent error events are less critical or informative, so ignoring them
+   has no negative impact. Provided one of the events is raised before the
+   promise is fulfilled, these handlers will consume the event and deal with it
+   appropriately.
+
+   In testing, it was found that in some situations, particularly during connect
+   operations, subsequent errors fired with a small delay. This prevents the
+   errors from being handled by the event handlers associated with the connect
+   promise. To deal with this, a small 500ms delay has been added to the
+   connect() method, which effectively delays the removal of the event handlers
+   until all events have been caught.
+
+   The other area where additional events are fired is during the end() call. To
+   deal with these events, the =end()= method setus up listeners which will
+   simply ignore additional =error=, =end= and =close= events. It is assumed
+   that once you have called =end()= you really only care about any main error
+   which occurs and no longer care about other errors that may be raised as the
+   connection is terminated.
+
+   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
+
+    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
 
    It appears that when the sftp server is running on Windows, a /ECONNRESET/
@@ -1333,6 +1355,12 @@ host key used to establish the initial secure connection. See the SSH2
 documentation for details. Getting these parameters correct usually resolves the
 issue.
 
+When encountering this type of problem, one worthwhile approach is to use
+openSSH's CLI sftp program with the =-v= switch to raise loggin levels. This
+will show you what algorithms the CLI is using. You can then use this
+information to match the names with the accepted algorithm names documented in
+the =ssh2= README to set the properties in the =algorithms= object.
+
 ** How can I limit upload/download speed
 
    If you want to limit the amount of bandwidth used during upload/download of
@@ -1374,6 +1402,19 @@ issue.
        await client.end();
      }
    #+end_src
+** Connection hangs or fails for larger files
+
+ This was contributed by Ladislav Jacho. Thanks. 
+
+ A symptom of this issue is that you are able to upload small files, but
+ uploading larger ones fail. You probably have an MTU/fragmentation problem. For
+ each network interface on both client and server set the MTU to 576, e.g.
+ =ifconfig eth0 mtu 576=. If that works, you need to find the largest MTU which
+ will work for your network. An MTU which is too small will adversely affect
+ throughput speed. A common value to use is an MTU of 1400.
+ 
+ For more explanation, see [[https://github.com/theophilusx/ssh2-sftp-client/issues/342][issue #342]].
+ 
 * Examples
 
 I have started collecting example scripts in the example directory of the
@@ -1683,6 +1724,15 @@ tests and if your adding a new feature, that tests for that feature are
 included. Likewise, for new features or enhancements, please include any
 relevant documentation updates.
 
+*Note*: The =README.md= file is generated from the =README.org= file. Therefore,
+any documentation updates or fixes need to be made to the =README.org= file.
+This file is /tangled/ using =Emacs= org mode. If you don't use Emacs or
+org-mode, don't be too concerned. The org-mode syntax is straight-forward and
+similar to /markdown/. I will verify any updates to =README.org= and generate a
+new =README.md= when necessary. The main point to note is that any changes made
+directly to =README.md= will not persist and will be lost when a new version is
+generated, so don't modify that file. 
+
 This module will adopt a standard semantic versioning policy. Please indicate in
 your pull request what level of change it represents i.e.
 
@@ -1712,3 +1762,6 @@ Thanks to the following for their contributions -
 - kennylbj :: Contributed example of using a throttle stream to limit
   upload/download bandwidth.
 - anton-erofeev :: Documentation fix
+- Ladislav Jacho :: Contributed solution explanation for connections hanging
+  when transferring larger files.
+- Emma Milner :: Contributed fix for put() bug

package/package.json

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

package/src/constants.js

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