ssh2-sftp-client 12.0.0 → 12.1.0

package/README.md

@@ -1,68 +1,70 @@
-- [Overview](#org38d065d)
-  - [Version 12.0.0 Changes](#orgaf728c6)
-  - [Background](#org6f33d22)
-- [Installation](#org8439307)
-- [Basic Usage](#orgaf41082)
-- [Documentation](#org5108c1b)
-  - [Specifying Paths](#org72e8719)
-  - [Methods](#orgfe65544)
-    - [new SftpClient(name, callbacks) ===> SFTP client object](#orgc6511be)
-    - [connect(config) ===> SFTP object](#org9fbbaaa)
-    - [list(path, filter) ==> Array[object]](#org73f17ce)
-    - [exists(path) ==> boolean](#org09b5d66)
-    - [stat(path) ==> object](#org91f6b04)
-    - [get(path, dst, options) ==> String|Stream|Buffer](#org78860d7)
-    - [fastGet(remotePath, localPath, options) ===> string](#org075afe7)
-    - [put(src, remotePath, options) ==> string](#org3570f3c)
-    - [fastPut(localPath, remotePath, options) ==> string](#org23d30ed)
-    - [append(input, remotePath, options) ==> string](#org4d3d523)
-    - [mkdir(path, recursive) ==> string](#org7ff954e)
-    - [rmdir(path, recursive) ==> string](#orga241b96)
-    - [delete(path, noErrorOK) ==> string](#org07b0cde)
-    - [rename(fromPath, toPath) ==> string](#org2d695fa)
-    - [posixRename(fromPath, toPath) ==> string](#org54eef84)
-    - [chmod(path, mode) ==> string](#org34c2a04)
-    - [realPath(path) ===> string](#org8e2be15)
-    - [cwd() ==> string](#org2d235d7)
-    - [uploadDir(srcDir, dstDir, options) ==> string](#orgb4585c4)
-    - [downloadDir(srcDir, dstDir, options) ==> string](#orgd2d4371)
-    - [createReadStream(remotePath, options)) ==> stream object](#orgfd916cd)
-    - [createWriteStream(remotePath, options) ==> stream object](#orgbba804d)
-    - [rcopy(srcPath, dstPath) ==> string](#org96b35cc)
-    - [end() ==> boolean](#org7600349)
-    - [Add and Remove Listeners](#orgff68122)
-- [Platform Quirks & Warnings](#orgcd3e52c)
-  - [Server Capabilities](#org44699cb)
-  - [Issues with `fastPut()` and `fastGet()` Methods](#org219edb9)
-  - [Promises, Events & Managing Exceptions](#orgdb50974)
-    - [Adding Custom Handlers](#orge9ed516)
-  - [Windows Based Servers](#org04134c2)
-  - [Don't Re-use SftpClient Objects](#orgb8a3ba1)
-- [FAQ](#org8a8b24b)
-  - [Remote server drops connections with only an end event](#org5de7a15)
-  - [How can I pass writeable stream as dst for get method?](#org21efa6c)
-  - [How can I upload files without having to specify a password?](#orgee1cf34)
-  - [How can I connect through a Socks Proxy](#orga6297a7)
-  - [Timeout while waiting for handshake or handshake errors](#org628c88e)
-  - [How can I limit upload/download speed](#org1116140)
-  - [Connection hangs or fails for larger files](#orgefe495c)
-  - [Typescript definition file out of date](#orgedcb385)
-- [Examples](#org3a23c04)
-- [Troubleshooting](#org888858f)
-  - [Common Errors](#orge820faa)
-    - [Not returning the promise in a `then()` block](#org52515e7)
-    - [Mixing Promise Chains and Async/Await](#org8e86c97)
-    - [Try/catch and Error Handlers](#org55f382c)
-    - [Server Differences](#org76494fa)
-    - [Avoid Concurrent Operations](#orgaedcad8)
-  - [Debugging Support](#orgf7b85d3)
-- [Logging Issues](#orgb243d19)
-- [Pull Requests](#org3d32e62)
-- [Contributors](#org99ba3a6)
-
-
-
-<a id="org38d065d"></a>
+- [Overview](#orge272967)
+  - [Version 12.0.0 Changes](#org9688783)
+  - [Version 12.0.1 Changes](#org6c6cbc7)
+  - [Version 12.1.0 Changes](#org678bfad)
+  - [Background](#org41ff3b3)
+- [Installation](#org64016b3)
+- [Basic Usage](#org0cbc36d)
+- [Documentation](#org161d25d)
+  - [Specifying Paths](#org569c530)
+  - [Methods](#orge938fe1)
+    - [new SftpClient(name, callbacks) ===> SFTP client object](#org87fb7cb)
+    - [connect(config) ===> SFTP object](#org00cd0ef)
+    - [list(path, filter) ==> Array[object]](#org2471bc8)
+    - [exists(path) ==> boolean](#org69f0979)
+    - [stat(path) ==> object](#org70605b0)
+    - [get(path, dst, options) ==> String|Stream|Buffer](#org6ef818c)
+    - [fastGet(remotePath, localPath, options) ===> string](#org4be5f02)
+    - [put(src, remotePath, options) ==> string](#org29892b8)
+    - [fastPut(localPath, remotePath, options) ==> string](#org8b51862)
+    - [append(input, remotePath, options) ==> string](#org60825d3)
+    - [mkdir(path, recursive) ==> string](#orga9278dd)
+    - [rmdir(path, recursive) ==> string](#org49dc87c)
+    - [delete(path, noErrorOK) ==> string](#orgbe8caee)
+    - [rename(fromPath, toPath) ==> string](#orgc525c46)
+    - [posixRename(fromPath, toPath) ==> string](#org72d1dcb)
+    - [chmod(path, mode) ==> string](#org0c71566)
+    - [realPath(path) ===> string](#org7dcfedc)
+    - [cwd() ==> string](#orgdaa63b2)
+    - [uploadDir(srcDir, dstDir, options) ==> string](#orgf47dba2)
+    - [downloadDir(srcDir, dstDir, options) ==> string](#orgc046861)
+    - [createReadStream(remotePath, options)) ==> stream object](#orgbb40821)
+    - [createWriteStream(remotePath, options) ==> stream object](#org5b94858)
+    - [rcopy(srcPath, dstPath) ==> string](#org352c030)
+    - [end() ==> boolean](#org9591ce4)
+    - [Add and Remove Listeners](#org5f4115d)
+- [Platform Quirks & Warnings](#org99f279a)
+  - [Server Capabilities](#org5f13ec7)
+  - [Issues with `fastPut()` and `fastGet()` Methods](#org0580b2e)
+  - [Promises, Events & Managing Exceptions](#org836ad16)
+    - [Adding Custom Handlers](#org7eb04eb)
+  - [Windows Based Servers](#org64d4763)
+  - [Don't Re-use SftpClient Objects](#org4e39c0f)
+- [FAQ](#org55e6f0b)
+  - [Remote server drops connections with only an end event](#orgbba8948)
+  - [How can I pass writeable stream as dst for get method?](#org3380bb0)
+  - [How can I upload files without having to specify a password?](#org144745f)
+  - [How can I connect through a Socks Proxy](#org65cf78c)
+  - [Timeout while waiting for handshake or handshake errors](#orgc1209ba)
+  - [How can I limit upload/download speed](#orgec6bc5b)
+  - [Connection hangs or fails for larger files](#org222771b)
+  - [Typescript definition file out of date](#org64453a9)
+- [Examples](#orge079610)
+- [Troubleshooting](#orgedc17fd)
+  - [Common Errors](#org7756613)
+    - [Not returning the promise in a `then()` block](#orgdf44163)
+    - [Mixing Promise Chains and Async/Await](#org643899f)
+    - [Try/catch and Error Handlers](#orgf1586cd)
+    - [Server Differences](#org57723b9)
+    - [Avoid Concurrent Operations](#org8f56d89)
+  - [Debugging Support](#org4c34184)
+- [Logging Issues](#org63b74c6)
+- [Pull Requests](#org308be7d)
+- [Contributors](#org585b558)
+
+
+
+<a id="orge272967"></a>
 
 # Overview
 
@@ -70,62 +72,80 @@ This package provides the class SftpClient, an SFTP client for node.js. It is a
 
 Documentation on the methods and available options in the underlying modules can be found on the [SSH2](https://github.com/mscdex/ssh2) project pages. As the ssh2-sftp-client package is just a wrapper around the `ssh2` module, you will find lots of useful information, tips and examples in the `ssh2` repository.
 
-Current stable release is \*v12.0.0.
+Current stable release is \*v12.1.0.
 
-Code has been tested against Node versions 20.18.3, 22.14.0 and 23.8.0. Node versions prior to v20.x are not supported.
+Code has been tested against Node versions 24.14.0. Node versions prior to v20.x are not supported.
 
 If you find this module useful and you would like to support the on-going maintenance and support of users, please consider making a small [donation](https://square.link/u/gB2kSdkY?src=embed).
 
 
-<a id="orgaf728c6"></a>
+<a id="org9688783"></a>
 
 ## Version 12.0.0 Changes
 
-The big and breaking change in this version is the removal of the connection retry code. This module no longer supports automatic connection retries when establishing the initial connection. This functionality was removed for a number of reasons. The main reasons are that it significantly complicated the connection handling code and error handling in particular and it was seldom useful. In most cases, if the cvonnection failed on thye first attempt, it would also fail in all subsequent attempts and often resulted in just extending the time to failure as multiple retries were attempted.
+The big and breaking change in this version is the removal of the connection retry code. This module no longer supports automatic connection retries when establishing the initial connection. This functionality was removed for a number of reasons. The main reasons are that it significantly complicated the connection handling code and error handling in particular and it was seldom useful. In most cases, if the connection failed on the first attempt, it would also fail in all subsequent attempts and often resulted in just extending the time to failure as multiple retries were attempted.
 
-The other reason this functionality was removed is because if you really want it, it is fairly straight forward to create your own wrapper around the connect call which uses one of the mnay promise retry packages available. Doing this is significantly easier when you don't need to cater for all the variables available when making a connection i.e. strict host verification, ssh agents, keys, proxies etc.
+Another reason this functionality was removed is because if you really want it, it is straight forward to create your own wrapper around the connect call which uses one of the mnay promise retry packages available. It is much simpler to add a retry mechanism for a specific application than it is to implement a flexible solution which supports all possible combination of connection options, authentication methods, proxies etc.
 
 
-<a id="org6f33d22"></a>
+<a id="org6c6cbc7"></a>
+
+## Version 12.0.1 Changes
+
+Bug Fixes
+
+-   Fix typo error in specification of generic error code in error handler. Typo was causing an undefined symbol error.
+-   Fix bug in stream error handling. Read and write streams had an error handler defined with 'once' rather than 'on'. This caused a bug when an API call caused more than one error. For example, a network connectivity error would cause a stream timeout error followed by a no response from remote host error when the error handler attempted to cleanup and destroy the remote stream. The second error whould not be handled and would bubble up to the parent node process, which would then exit with an unhandled exception error.
+-   Added calls to \_resetEventFlags() to finally clauses to ensure event flags are reset when temp listeners are removed. Without this change, global listeners would not fire when they should after their has been an earlier handled error in the last API call.
+
+
+<a id="org678bfad"></a>
+
+## Version 12.1.0 Changes
+
+The main change in this version is to address an issue with disconnect when accessing Microsoft's SFTP server. Due to the way the Microsoft server implements closing of connections, an exception is thrown even when there has been a legitimate request to end the connection. The fix is to ignore this specific *error* case. Thanks to @rhyswilliamsza for the patch.
+
+
+<a id="org41ff3b3"></a>
 
 ## Background
 
-In basic terms `ssh2-sftp-client` is a simple wrapper around the `ssh2` package which provides a promise base API for interacting with a remote SFTP server . The `ssh2` package provides an event based API for interacting with the `ssh` protocol. The `ssh2-sftp-client` package uses the `sftp` subsystem of this protocol to implement the basic operations typically associated with an `sftp` client.
+In basic terms `ssh2-sftp-client` is a simple wrapper around the `ssh2` package which provides a promise based API for interacting with a remote SFTP server . The `ssh2` package provides an event based API for interacting with the `ssh` protocol. The `ssh2-sftp-client` package uses the `sftp` subsystem of this protocol to implement the basic operations typically associated with an `sftp` client.
 
-Wrapping an event based API with a promised based API comes with a number of challenges. In particular, efficiently and reliably managing events within the context of asynchrounous code execution. This package uses the following strategies;
+Wrapping an event based API with a promise based API comes with a number of challenges. In particular, efficiently and reliably managing events within the context of asynchronous code execution. This package uses the following strategies;
 
--   All direct interactions with the `ssh2` API are wrapped in promise objects. When the API call succeeds, the assoiated promise will be sucessfully resolved. When an error occurs, the promise is rejected.
+-   All direct interactions with the `ssh2` API are wrapped in promise objects. When the API call succeeds, the associated promise will be successfully resolved. When an error occurs, the promise is rejected.
 
 -   An error can either be due to a low level network error, such as a lost connection to the remote server or due to an operational error, such as a file not existing or not having the appropriate permissions for access.
 
--   Each of the available `SftpClient` methods wrap the method call inside a promise. In crwating eacvh promise, the class adds temporary event listenrs for the error, end and close events and links those liseners to the method's promise via it's `reject()` method.
+-   Each of the available `SftpClient` methods wrap the method call inside a promise. In creating each promise, the class adds temporary event listeners for the error, end and close events and links those liseners to the method's promise via its `reject()` method.
 
--   If a promise is waiting to be fulfilled when either of the two types of errors occurs, the error will be communicated back to client code via a rejected promise.
+-   If a promise is waiting to be fulfilled when an error occurs, the error will be communicated back to the client code via the rejected promise.
 
--   When the `ssh2` emitter raises an event outside the context of any promise, that event will be handled by global event handlers. By default, these event handlers will log the event and will invalidate any existing socket connection objects, preventing any further API calls until a new connection is extablished.
+-   When the `ssh2` emitter raises an event outside the context of any promise, that event will be handled by global event handlers. By default, these event handlers will log the event and will invalidate any existing socket connection objects, preventing any further API calls until a new connection is established.
 
--   The `SftpClient` class constructor supports an optoinal second argument which is an objedct whi8ch can have any of three properties representing event callbaqck funct5ions which will be executed for each of the possible events error, end and close.
+-   The `SftpClient` class constructor supports an optoinal second argument which is an object which can have any of the three properties \`error\`, \`end\`, and \`close\`. The values associated with these properties are callback functions that will be run if an error event with the same name as the property is raised and has not been handled by one of the temporary event handlers. The error callback should have a single parameter, the error raised by the event. The other callbacks have no arguments.
 
-The need for both global listeners and temporary promise listeners is because network end, close or error events can occur at any time, including in-betwseen API calls. During an API call, a promise is active and can be used to communicate event information back to the calling code via normal promise communication means i.e. async/await with try/catch or promise chain's then/catch mechanism. However, outside API calls, no promise exists and there is no reliable mechanism to return error and other event information back to calling code. You cannot reliably use try/cdatch to catch errorsx thrown inside event listenrs as you lack control over when the listener code runs. Your try/catch block can easily complete before the error is raised as there is no equivalent *await* type functionality in this situation.
+The need for both global listeners and temporary promise listeners is because network end, close or error events can occur at any time, including in-between API calls. During an API call, a promise is active and can be used to communicate event information back to the calling code via normal promise communication channels i.e. async/await with try/catch or promise chain's then/catch mechanism. However, outside API calls, no promise exists and there is no reliable mechanism to return error and other event information back to calling code. You cannot reliably use try/cdatch to catch errors thrown inside event listenrs as you lack control over when the listener code runs. Your try/catch block can easily complete before the error is raised as there is no equivalent *await* type functionality in this situation.
 
 As there is no simple default way to return error and other event information back to the calling code, `ssh2-sftp-client` doesn't try to. Instead, the default action is to just log the event information and invalidate any existing sftp connections. This strategy is often sufficient for many use cases. For those cases where it isn't, client code can pass in end, close and/or error listener functions when instantiating the `SftpClient` object. If provided, these listners will be executed whenever the default global listeners are executed, which is whenever the `ssh2` event emitter raises an end, close or error event which is not handled by one of the temporary promise linked event listeners.
 
-Version 11 of `ssh2-sftp-client` also changes the behaviour of the temporary promise linked *end* and *close* listeners. Prior to versioln 11, these listeners did not reject promises. They would only invalidate the underlying `ssh` connection object. Only the *error* listener would actually reject the associated promise. This was done because you cannot guarantee the order in which events are responded to.
+Version 11 of `ssh2-sftp-client` also changes the behaviour of the temporary promise linked *end* and *close* listeners. Prior to version 11, these listeners did not reject promises. They would only invalidate the underlying `ssh` connection object. Only the *error* listener would actually reject the associated promise. This was done because you cannot guarantee the order in which events are responded to.
 
-In most cases, events will occur in the order *error*, *end* and then *close*. The error event would contain details about the cause of the error while the end and close events just communicvate that these events have been raised. The normal flow would be
+In most cases, events will occur in the order *error*, *end* and then *close*. The error event would contain details about the cause of the error while the end and close events just communicate that these events have been raised. The normal flow would be
 
--   Error event occurs including error cause description. Listener catches event, creates an error object and calls the associated promises reject function to reject the promise. The calling process receives a rejected promise object.
+-   Error event occurs including error cause description. Listener catches event, creates an error object and calls the associated promise's reject function to reject the promise. The calling process receives a rejected promise object.
 
 -   End event occurs. The end listener catches the event and marks the connection object as invalid as the socket connection has been ended. There is no need to call the reject method of the associated promise as it has already been called by the error listener and you can only call one promise resolution function.
 
--   Close event occurs. This event means the socket connection has been closed. The listener will ensure any connection information has been invalidated. Aga8in, ther is no need to call the reject method of the associated promise as it has already been called by the error listener.
+-   Close event occurs. This event means the socket connection has been closed. The listener will ensure any connection information has been invalidated. Again, there is no need to call the reject method of the associated promise as it has already been called by the error listener.
 
-In some cases, no ende event is raised and you only get an error event followed by a close event. In versions of `ssh2-sftp-client` prior to version 11, neither the end or the close listeners attempted to call the reject method of the associated promise. It was assumed that all sftp servers would raise an error event whenever a connection was unexpectedly ended or closed. Unfortunately, it turns out some sftp servers are not well behaved and will terminate the connection without providing any error information or raising an error event. When this occurred in versions prior to version 11, it could result in either an API call hanging because its associated promise never gets rejected or resolved or the call gets rejected with a timeout error aftrer a significant delay.
+In some cases, no end event is raised and you only get an error event followed by a close event. In versions of `ssh2-sftp-client` prior to version 11, neither the end or the close listeners attempted to call the reject method of the associated promise. It was assumed that all sftp servers would raise an error event whenever a connection was unexpectedly ended or closed. Unfortunately, it turns out some sftp servers are not well behaved and will terminate the connection without providing any error information or raising an error event. When this occurred in versions prior to version 11, it could result in either an API call hanging because its associated promise never gets rejected or resolved or the call gets rejected with a timeout error aftrer a significant delay.
 
-In order to handle the possible hanging issue in version 11, the temporary promise linked end and close listeners have been updated to always call the promise's reject function if they fire. While this works, it can cause a minor issue. As wse cannot gurantee the order in which events are resonded to by listeners, it is possible that either the end or close listener may be executed before the error listener. When this occurs, the promise is rejected, but the only information wse have at that point is that the promise wsas reject due to either an end or close event. We don't yet have any details regarding what error has caused the unexpected end or close event. Furthermore, because only the first promise resolution function call has any effect, calling reject within the error listener (assuming an error event does eventually arrive) has no effect and does not communicate error information back to the caller. This means that in some circumstances, especially when working with some poorly behaved sftp servers, an sftp connection will be lost/closed with no indication as to reason. This can make diagnosis and bug tracking frustrating.
+In order to handle the possible hanging issue in version 11, the temporary promise linked end and close listeners have been updated to always call the promise's reject function if they fire. While this works, it can cause a minor issue. As wse cannot gurantee the order in which events are responded to by listeners, it is possible that either the end or close listener may be executed before the error listener. When this occurs, the promise is rejected, but the only information wse have at that point is that the promise wsas reject due to either an end or close event. We don't yet have any details regarding what error has caused the unexpected end or close event. Furthermore, because only the first promise resolution function call has any effect, calling reject within the error listener (assuming an error event does eventually arrive) has no effect and does not communicate error information back to the caller. This means that in some circumstances, especially when working with some poorly behaved sftp servers, an sftp connection will be lost/closed with no indication as to reason. This can make diagnosis and bug tracking frustrating.
 
 
-<a id="org8439307"></a>
+<a id="org64016b3"></a>
 
 # Installation
 
@@ -134,7 +154,7 @@ npm install ssh2-sftp-client
 ```
 
 
-<a id="orgaf41082"></a>
+<a id="org0cbc36d"></a>
 
 # Basic Usage
 
@@ -157,7 +177,7 @@ sftp.connect({
 ```
 
 
-<a id="org5108c1b"></a>
+<a id="org161d25d"></a>
 
 # Documentation
 
@@ -168,7 +188,7 @@ All the methods will return a Promise, except for `on(), ~removeListener()`, `cr
 Note that I don't use Typescript and I don't maintain any typescript definition files. There are some typescript type definition files for this module, but they are maintained separately and have nothing to do with this project. Therefore, please do not log any issues arising from the use of these definition files with this project. Instead, refer your issues to the maintainers of those modules.
 
 
-<a id="org72e8719"></a>
+<a id="org569c530"></a>
 
 ## Specifying Paths
 
@@ -201,12 +221,12 @@ 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`.
 
 
-<a id="orgfe65544"></a>
+<a id="orge938fe1"></a>
 
 ## Methods
 
 
-<a id="orgc6511be"></a>
+<a id="org87fb7cb"></a>
 
 ### new SftpClient(name, callbacks) ===> SFTP client object
 
@@ -246,7 +266,7 @@ Constructor to create a new `ssh2-sftp-client` object. An optional `name` string
     ```
 
 
-<a id="org9fbbaaa"></a>
+<a id="org00cd0ef"></a>
 
 ### connect(config) ===> SFTP object
 
@@ -310,7 +330,7 @@ Connect to an sftp server. Full documentation for connection options is availabl
     ```
 
 
-<a id="org73f17ce"></a>
+<a id="org2471bc8"></a>
 
 ### list(path, filter) ==> Array[object]
 
@@ -371,7 +391,7 @@ Retrieves a directory listing. This method returns a Promise, which once realise
     ```
 
 
-<a id="org09b5d66"></a>
+<a id="org69f0979"></a>
 
 ### exists(path) ==> boolean
 
@@ -407,7 +427,7 @@ Tests to see if remote file or directory exists. Returns type of remote object i
     ```
 
 
-<a id="org91f6b04"></a>
+<a id="org70605b0"></a>
 
 ### stat(path) ==> object
 
@@ -458,7 +478,7 @@ Returns the attributes associated with the object pointed to by `path`.
     ```
 
 
-<a id="org78860d7"></a>
+<a id="org6ef818c"></a>
 
 ### get(path, dst, options) ==> String|Stream|Buffer
 
@@ -514,7 +534,7 @@ 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'.
 
 
-<a id="org075afe7"></a>
+<a id="org4be5f02"></a>
 
 ### fastGet(remotePath, localPath, options) ===> string
 
@@ -559,7 +579,7 @@ Bottom line, when it works, it tends to work reliably. However, for many servers
     ```
 
 
-<a id="org3570f3c"></a>
+<a id="org29892b8"></a>
 
 ### put(src, remotePath, options) ==> string
 
@@ -609,7 +629,7 @@ 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()`.
 
 
-<a id="org23d30ed"></a>
+<a id="org8b51862"></a>
 
 ### fastPut(localPath, remotePath, options) ==> string
 
@@ -655,7 +675,7 @@ Bottom line, when it works, it tends to work well. However, when it doesn't work
     ```
 
 
-<a id="org4d3d523"></a>
+<a id="org60825d3"></a>
 
 ### append(input, remotePath, options) ==> string
 
@@ -699,7 +719,7 @@ Append the `input` data to an existing remote file. There is no integrity checki
     ```
 
 
-<a id="org7ff954e"></a>
+<a id="orga9278dd"></a>
 
 ### mkdir(path, recursive) ==> string
 
@@ -727,7 +747,7 @@ Create a new directory. If the recursive flag is set to true, the method will cr
     ```
 
 
-<a id="orga241b96"></a>
+<a id="org49dc87c"></a>
 
 ### rmdir(path, recursive) ==> string
 
@@ -757,7 +777,7 @@ Remove a directory. If removing a directory and recursive flag is set to `true`,
     ```
 
 
-<a id="org07b0cde"></a>
+<a id="orgbe8caee"></a>
 
 ### delete(path, noErrorOK) ==> string
 
@@ -786,7 +806,7 @@ Delete a file on the remote server.
     ```
 
 
-<a id="org2d695fa"></a>
+<a id="orgc525c46"></a>
 
 ### rename(fromPath, toPath) ==> string
 
@@ -815,7 +835,7 @@ Rename a file or directory from `fromPath` to `toPath`. You must have the necess
     ```
 
 
-<a id="org54eef84"></a>
+<a id="org72d1dcb"></a>
 
 ### posixRename(fromPath, toPath) ==> string
 
@@ -842,7 +862,7 @@ client.connect(config)
 ```
 
 
-<a id="org34c2a04"></a>
+<a id="org0c71566"></a>
 
 ### chmod(path, mode) ==> string
 
@@ -871,7 +891,7 @@ Change the mode (read, write or execute permissions) of a remote file or directo
     ```
 
 
-<a id="org8e2be15"></a>
+<a id="org7dcfedc"></a>
 
 ### realPath(path) ===> string
 
@@ -882,14 +902,14 @@ 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 '~'.
 
 
-<a id="org2d235d7"></a>
+<a id="orgdaa63b2"></a>
 
 ### cwd() ==> string
 
 Returns what the server believes is the current remote working directory.
 
 
-<a id="orgb4585c4"></a>
+<a id="orgf47dba2"></a>
 
 ### uploadDir(srcDir, dstDir, options) ==> string
 
@@ -958,7 +978,7 @@ The `useFastput` option is a boolean option. If `true`, the method will use the
     ```
 
 
-<a id="orgd2d4371"></a>
+<a id="orgc046861"></a>
 
 ### downloadDir(srcDir, dstDir, options) ==> string
 
@@ -1023,7 +1043,7 @@ If the `useFastget` property is set to `true`, the method will use `fastGet()` t
     ```
 
 
-<a id="orgfd916cd"></a>
+<a id="orgbb40821"></a>
 
 ### createReadStream(remotePath, options)) ==> stream object
 
@@ -1040,7 +1060,7 @@ Returns a read stream object which is attached to the remote file specified by t
     -   **end:** Position to stop reading bytes (inclusive).
 
 
-<a id="orgbba804d"></a>
+<a id="org5b94858"></a>
 
 ### createWriteStream(remotePath, options) ==> stream object
 
@@ -1055,7 +1075,7 @@ Returns a write stream object which is attached to the remote file specified in
     -   **start:** Byte position to start writing from (inclusive). May require changing flag to 'r+'.
 
 
-<a id="org96b35cc"></a>
+<a id="org352c030"></a>
 
 ### rcopy(srcPath, dstPath) ==> string
 
@@ -1065,7 +1085,7 @@ Perform a remote file copy. The file identified by the `srcPath` argument will b
 -   **dstPath:** Path to where the copy will be created specified as a string
 
 
-<a id="org7600349"></a>
+<a id="org9591ce4"></a>
 
 ### end() ==> boolean
 
@@ -1089,7 +1109,7 @@ Ends the current client session, releasing the client socket and associated reso
     ```
 
 
-<a id="orgff68122"></a>
+<a id="org5f4115d"></a>
 
 ### Add and Remove Listeners
 
@@ -1110,12 +1130,12 @@ 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.
 
 
-<a id="orgcd3e52c"></a>
+<a id="org99f279a"></a>
 
 # Platform Quirks & Warnings
 
 
-<a id="org44699cb"></a>
+<a id="org5f13ec7"></a>
 
 ## Server Capabilities
 
@@ -1124,7 +1144,7 @@ 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.
 
 
-<a id="org219edb9"></a>
+<a id="org0580b2e"></a>
 
 ## Issues with `fastPut()` and `fastGet()` Methods
 
@@ -1133,7 +1153,7 @@ The `fastPut()` and `fastGet()` methods are known to be somewhat dependent on SF
 To see an example of the type of issues you can observe with `fastPut()` or `fastGet()`, have a look at [issue 407](https://github.com/theophilusx/ssh2-sftp-client/issues/407), which describes the experiences of one user. Bottom line, when it works, it tends to work well and be significantly faster than using just `get()` or `put()`. However, when developing code to run against different SFTP servers, especially where you are unable to test against each server, you are likely better off just using `get()` and `put()` or structuring your code so that users can select which method to use (this is what `ssh2-sftp-client` does - for example, see the `!downloadDir()` and `uploadDir()` methods.
 
 
-<a id="orgdb50974"></a>
+<a id="org836ad16"></a>
 
 ## Promises, Events & Managing Exceptions
 
@@ -1152,14 +1172,14 @@ 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.
 
 
-<a id="orge9ed516"></a>
+<a id="org7eb04eb"></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.
 
 
-<a id="org04134c2"></a>
+<a id="org64d4763"></a>
 
 ## Windows Based Servers
 
@@ -1168,7 +1188,7 @@ It appears that when the sftp server is running on Windows, a *ECONNRESET* error
 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.
 
 
-<a id="orgb8a3ba1"></a>
+<a id="org4e39c0f"></a>
 
 ## Don't Re-use SftpClient Objects
 
@@ -1177,12 +1197,12 @@ Due to an issue with *ECONNRESET* error signals when connecting to Windows based
 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.
 
 
-<a id="org8a8b24b"></a>
+<a id="org55e6f0b"></a>
 
 # FAQ
 
 
-<a id="org5de7a15"></a>
+<a id="orgbba8948"></a>
 
 ## Remote server drops connections with only an end event
 
@@ -1193,7 +1213,7 @@ Clients first make an unauthenticated connection to the SFTP server to begin neg
 One way to avoid this type of issue is to add a delay between connection attempts. It does not need to be a very long delay - just sufficient to permit the previous connection to be authenticated. In fact, the default setting for openSSH is `10:30:60`, so you really just need to have enough delay to ensure that the 1st connection has completed authentication before the 11th connection is attempted.
 
 
-<a id="org21efa6c"></a>
+<a id="org3380bb0"></a>
 
 ## How can I pass writeable stream as dst for get method?
 
@@ -1252,7 +1272,7 @@ sftp
 ```
 
 
-<a id="orgee1cf34"></a>
+<a id="org144745f"></a>
 
 ## How can I upload files without having to specify a password?
 
@@ -1287,7 +1307,7 @@ sftp.connect({
 ```
 
 
-<a id="orga6297a7"></a>
+<a id="org65cf78c"></a>
 
 ## How can I connect through a Socks Proxy
 
@@ -1324,7 +1344,7 @@ client.connect({
 ```
 
 
-<a id="org628c88e"></a>
+<a id="orgc1209ba"></a>
 
 ## Timeout while waiting for handshake or handshake errors
 
@@ -1333,7 +1353,7 @@ Some users have encountered the error 'Timeout while waiting for handshake' or '
 When encountering this type of problem, one worthwhile approach is to use openSSH's CLI sftp program with the `-v` switch to raise logging 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.
 
 
-<a id="org1116140"></a>
+<a id="orgec6bc5b"></a>
 
 ## How can I limit upload/download speed
 
@@ -1373,7 +1393,7 @@ try {
 ```
 
 
-<a id="orgefe495c"></a>
+<a id="org222771b"></a>
 
 ## Connection hangs or fails for larger files
 
@@ -1384,21 +1404,21 @@ 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).
 
 
-<a id="orgedcb385"></a>
+<a id="org64453a9"></a>
 
 ## Typescript definition file out of date
 
 This project does not use Typescript. However, typescript definition files are provided by other 3rd parties. Sometimes, these definition files have not stayed up-to-date with the current version of this module. If you encounter this issue, you need to report it to the party responsible for the definition file, not this project.
 
 
-<a id="org3a23c04"></a>
+<a id="orge079610"></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.
 
 
-<a id="org888858f"></a>
+<a id="orgedc17fd"></a>
 
 # Troubleshooting
 
@@ -1413,14 +1433,14 @@ 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.
 
 
-<a id="orge820faa"></a>
+<a id="org7756613"></a>
 
 ## Common Errors
 
 There are some common errors people tend to make when using Promises or Async/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.
 
 
-<a id="org52515e7"></a>
+<a id="orgdf44163"></a>
 
 ### Not returning the promise in a `then()` block
 
@@ -1457,7 +1477,7 @@ 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.
 
 
-<a id="org8e86c97"></a>
+<a id="org643899f"></a>
 
 ### Mixing Promise Chains and Async/Await
 
@@ -1517,7 +1537,7 @@ async function doSftp() {
 ```
 
 
-<a id="org55f382c"></a>
+<a id="orgf1586cd"></a>
 
 ### Try/catch and Error Handlers
 
@@ -1528,14 +1548,14 @@ 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.
 
 
-<a id="org76494fa"></a>
+<a id="org57723b9"></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.
 
 
-<a id="orgaedcad8"></a>
+<a id="org8f56d89"></a>
 
 ### Avoid Concurrent Operations
 
@@ -1544,7 +1564,7 @@ Technically, SFTP should be able to perform multiple operations concurrently. As
 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.
 
 
-<a id="orgf7b85d3"></a>
+<a id="org4c34184"></a>
 
 ## Debugging Support
 
@@ -1577,7 +1597,7 @@ If you just want to see debug messages from `ssh2-sftp-client` and exclude debug
 ```
 
 
-<a id="orgb243d19"></a>
+<a id="org63b74c6"></a>
 
 # Logging Issues
 
@@ -1594,7 +1614,7 @@ 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.
 
 
-<a id="org3d32e62"></a>
+<a id="org308be7d"></a>
 
 # Pull Requests
 
@@ -1611,7 +1631,7 @@ This module will adopt a standard semantic versioning policy. Please indicate in
 -   **Bug Fix:** No change to functionality or features. Simple fix of an existing bug.
 
 
-<a id="org99ba3a6"></a>
+<a id="org585b558"></a>
 
 # Contributors
 
@@ -1633,3 +1653,4 @@ Thanks to the following for their contributions -
 -   **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().
+-   **rhyswilliamsza:** Contributed RST-on-END handling fix

package/README.org

@@ -12,10 +12,10 @@ be found on the [[https://github.com/mscdex/ssh2][SSH2]] project pages. As the s
 ~ssh2~ module, you will find lots of useful information, tips and examples in the ~ssh2~
 repository. 
 
-Current stable release is *v12.0.0.
+Current stable release is *v12.1.0.
 
-Code has been tested against Node versions 20.18.3, 22.14.0 and 23.8.0. Node versions
-prior to v20.x are not supported. 
+Code has been tested against Node versions 24.14.0. Node versions prior to v20.x are not
+supported.
 
 If you find this module useful and you would like to support the on-going maintenance and
 support of users, please consider making a small [[https://square.link/u/gB2kSdkY?src=embed][donation]].
@@ -26,30 +26,54 @@ The big and breaking change in this version is the removal of the connection ret
 code. This module no longer supports automatic connection retries when establishing the
 initial connection. This functionality was removed for a number of reasons. The main
 reasons are that it significantly complicated the connection handling code and error
-handling in particular and it was seldom useful. In most cases, if the cvonnection failed
-on thye first attempt, it would also fail in all subsequent attempts and often resulted in
+handling in particular and it was seldom useful. In most cases, if the connection failed
+on the first attempt, it would also fail in all subsequent attempts and often resulted in
 just extending the time to failure as multiple retries were attempted.
 
-The other reason this functionality was removed is because if you really want it, it is
-fairly straight forward to create your own wrapper around the connect call which uses one
-of the mnay promise retry packages available. Doing this is significantly easier when you
-don't need to cater for all the variables available when making a connection i.e. strict
-host verification, ssh agents, keys, proxies etc. 
-
+Another reason this functionality was removed is because if you really want it, it is
+straight forward to create your own wrapper around the connect call which uses one
+of the mnay promise retry packages available. It is much simpler to add a retry mechanism
+for a specific application than it is to implement a flexible solution which supports all
+possible combination of connection options, authentication methods, proxies etc.
+
+** Version 12.0.1 Changes
+
+  Bug Fixes
+
+  - Fix typo error in specification of generic error code in error handler. Typo was
+    causing an undefined symbol error.
+  - Fix bug in stream error handling. Read and write streams had an error handler defined
+    with 'once' rather than 'on'. This caused a bug when an API call caused more than one
+    error. For example, a network connectivity error would cause a stream timeout error
+    followed by a no response from remote host error when the error handler attempted to
+    cleanup and destroy the remote stream. The second error whould not be handled and
+    would bubble up to the  parent node process, which would then exit with an unhandled
+    exception error.
+  - Added calls to _resetEventFlags() to finally clauses to ensure event flags are reset
+    when temp listeners are removed. Without this change, global listeners would not fire
+    when they should after their has been an earlier handled error in the last API call. 
+** Version 12.1.0 Changes
+
+  The main change in this version is to address an issue with disconnect when accessing
+  Microsoft's SFTP server. Due to the way the Microsoft server implements closing of
+  connections, an exception is thrown even when there has been a legitimate request to end
+  the connection. The fix is to ignore this specific /error/ case. Thanks to @rhyswilliamsza
+  for the patch.
+  
 ** Background
 
 In basic terms =ssh2-sftp-client= is a simple wrapper around the =ssh2= package which provides
-a promise base API for interacting with a remote SFTP server . The =ssh2= package provides
+a promise based API for interacting with a remote SFTP server . The =ssh2= package provides
 an event based API for interacting with the ~ssh~ protocol. The ~ssh2-sftp-client~ package
 uses the ~sftp~ subsystem of this protocol to implement the basic operations typically
 associated with an ~sftp~ client.
 
-Wrapping an event based API with a promised based API comes with a number of
+Wrapping an event based API with a promise based API comes with a number of
 challenges. In particular, efficiently and reliably managing events within the context of
-asynchrounous code execution. This package uses the following strategies;
+asynchronous code execution. This package uses the following strategies;
 
     - All direct interactions with the ~ssh2~ API are wrapped in promise objects. When the
-      API call succeeds, the assoiated promise will be sucessfully resolved. When an error occurs,
+      API call succeeds, the associated promise will be successfully resolved. When an error occurs,
       the promise is rejected.
 
     - An error can either be due to a low level network error, such as a lost connection
@@ -57,30 +81,32 @@ asynchrounous code execution. This package uses the following strategies;
       existing or not having the appropriate permissions for access.
 
     - Each of the available ~SftpClient~ methods wrap the method call inside a promise. In
-      crwating eacvh promise, the class adds temporary event listenrs for the error, end
-      and close events and links those liseners to the method's promise via it's ~reject()~
+      creating each promise, the class adds temporary event listeners for the error, end
+      and close events and links those liseners to the method's promise via its ~reject()~
       method. 
 
-    - If a promise is waiting to be fulfilled when either of the two types of errors
-      occurs, the error will be communicated back to client code via a rejected promise.
+    - If a promise is waiting to be fulfilled when an error
+      occurs, the error will be communicated back to the client code via the rejected promise.
 
     - When the ~ssh2~ emitter raises an event outside the context of any promise, that event
       will be handled by global event handlers. By default, these event handlers will log
       the event and will invalidate any existing socket connection objects, preventing any
-      further API calls until a new connection is extablished.
+      further API calls until a new connection is established.
 
     - The ~SftpClient~ class constructor supports an optoinal second argument which is an
-      objedct whi8ch can have any of three properties representing event callbaqck
-      funct5ions which will be executed for each of the possible events error, end and
-      close.
+      object which can have any of the three properties `error`, `end`, and `close`. The values
+      associated with these properties are callback functions that will be run if an error
+      event with the same name as the property is raised and has not been handled by one of
+      the temporary event handlers. The error callback should have a single parameter, the
+      error raised by the event. The other callbacks have no arguments. 
       
 The need for both global listeners and temporary promise listeners is because network end,
-close or error events can occur at any time, including in-betwseen API calls. During an
+close or error events can occur at any time, including in-between API calls. During an
 API call, a promise is active and can be used to communicate event information back to the calling
-code via normal promise communication means i.e. async/await with try/catch or promise chain's then/catch
+code via normal promise communication channels i.e. async/await with try/catch or promise chain's then/catch
 mechanism. However, outside API calls, no promise exists and there is no reliable
 mechanism to return error and other event information back to calling code. You cannot
-reliably use try/cdatch to catch errorsx thrown inside event listenrs as you lack control
+reliably use try/cdatch to catch errors thrown inside event listenrs as you lack control
 over when the listener code runs. Your try/catch block can easily complete before the
 error is raised as there is no equivalent /await/ type functionality in this situation.
 
@@ -95,17 +121,17 @@ close or error event which is not handled by one of the temporary promise linked
 listeners.
 
 Version 11 of ~ssh2-sftp-client~ also changes the behaviour of the temporary promise linked
-/end/ and /close/ listeners. Prior to versioln 11, these listeners did not reject
+/end/ and /close/ listeners. Prior to version 11, these listeners did not reject
 promises. They would only invalidate the underlying ~ssh~ connection object. Only the /error/
 listener would actually reject the associated promise. This was done because you cannot
 guarantee the order in which events are responded to.
 
 In most cases, events will occur in the order /error/, /end/ and then /close/. The error event
 would contain details about the cause of the error while the end and close events just
-communicvate that these events have been raised. The normal flow would be
+communicate that these events have been raised. The normal flow would be
 
     - Error event occurs including error cause description. Listener catches event,
-      creates an error object and calls the associated promises reject function to reject
+      creates an error object and calls the associated promise's reject function to reject
       the promise. The calling process receives a rejected promise object.
 
     - End event occurs. The end listener catches the event and marks the connection object
@@ -114,11 +140,11 @@ communicvate that these events have been raised. The normal flow would be
       listener and you can only call one promise resolution function.
 
     - Close event occurs. This event means the socket connection has been closed. The
-      listener will ensure any connection information has been invalidated. Aga8in, ther
+      listener will ensure any connection information has been invalidated. Again, there
       is no need to call the reject method of the associated promise as it has already
       been called by the error listener.
 
-In some cases, no ende event is raised and you only get an error event followed by a close
+In some cases, no end event is raised and you only get an error event followed by a close
 event. In versions of ~ssh2-sftp-client~ prior to version 11, neither the end or the close
 listeners attempted to call the reject method of the associated promise. It was assumed
 that all sftp servers would raise an error event whenever a connection was unexpectedly
@@ -131,7 +157,7 @@ call gets rejected with a timeout error aftrer a significant delay.
 In order to handle the possible hanging issue in version 11, the temporary promise linked
 end and close listeners have been updated to always call the promise's reject function if
 they fire. While this works, it can cause a minor issue. As wse cannot gurantee the order
-in which events are resonded to by listeners, it is possible that either the end or close
+in which events are responded to by listeners, it is possible that either the end or close
 listener may be executed before the error listener. When this occurs, the promise is
 rejected, but the only information wse have at that point is that the promise wsas reject
 due to either an end or close event. We don't yet have any details regarding what error
@@ -2018,5 +2044,6 @@ Thanks to the following for their contributions -
 - 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().
-  
+- rhyswilliamsza :: Contributed RST-on-END handling fix
+    
   

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ssh2-sftp-client",
-  "version": "12.0.0",
+  "version": "12.1.0",
   "description": "ssh2 sftp client for node",
   "main": "src/index.js",
   "repository": {
@@ -38,7 +38,7 @@
     "chai-as-promised": "^7.1.2",
     "chai-subset": "^1.6.0",
     "checksum": "^1.0.0",
-    "dotenv": "^16.0.0",
+    "dotenv": "^17.3.1",
     "eslint": "^9.6.0",
     "eslint-config-prettier": "^9.0.0",
     "eslint-plugin-mocha": "^10.2.0",

package/src/index.js

@@ -25,7 +25,7 @@ class SftpClient {
       close: () => console.log('Global close listener: close event raised'),
     },
   ) {
-    this.version = '12.0.0';
+    this.version = '12.0.1';
     this.client = new Client();
     this.sftp = undefined;
     this.clientName = clientName;
@@ -169,6 +169,7 @@ class SftpClient {
     }).finally(() => {
       this.removeListener('ready', doReady);
       removeTempListeners(this, listeners, 'getConnection');
+      this._resetEventFlags();
     });
   }
 
@@ -203,6 +204,7 @@ class SftpClient {
     }).finally(() => {
       if (addListeners) {
         removeTempListeners(this, listeners, 'realPath');
+        this._resetEventFlags();
       }
     });
   }
@@ -267,6 +269,7 @@ class SftpClient {
     }).finally(() => {
       if (addListeners) {
         removeTempListeners(this, listeners, '_xstat');
+        this._resetEventFlags();
       }
     });
   }
@@ -397,6 +400,7 @@ class SftpClient {
     }).finally(() => {
       if (addListeners) {
         removeTempListeners(this, listeners, 'list');
+        this._resetEventFlags();
       }
     });
   }
@@ -437,7 +441,7 @@ class SftpClient {
           pipeOptions: { ...options?.pipeOptions, end: true },
         };
         rdr = this.sftp.createReadStream(remotePath, options.readStreamOptions);
-        rdr.once('error', (err) => {
+        rdr.on('error', (err) => {
           if (dst && typeof dst === 'string' && wtr && !wtr.destroyed) {
             wtr.destroy();
           }
@@ -445,13 +449,11 @@ class SftpClient {
         });
         if (dst === undefined) {
           // no dst specified, return buffer of data
-          this.debugMsg('get resolving with buffer of data');
           wtr = concat((buff) => {
             resolve(buff);
           });
         } else if (typeof dst === 'string') {
           // dst local file path
-          this.debugMsg(`get called with file path destination ${dst}`);
           const localCheck = haveLocalCreate(dst);
           if (localCheck.status) {
             wtr = fs.createWriteStream(dst, options.writeStreamOptions);
@@ -465,10 +467,9 @@ class SftpClient {
             );
           }
         } else {
-          this.debugMsg('get called with stream destination');
           wtr = dst;
         }
-        wtr.once('error', (err) => {
+        wtr.on('error', (err) => {
           reject(
             this.fmtError(
               `${err.message} ${typeof dst === 'string' ? dst : '<stream>'}`,
@@ -492,6 +493,7 @@ class SftpClient {
       }
       if (addListeners) {
         removeTempListeners(this, listeners, 'get');
+        this._resetEventFlags();
       }
     });
   }
@@ -527,6 +529,7 @@ class SftpClient {
     }).finally(() => {
       if (addListeners) {
         removeTempListeners(this, listeners, '_fastGet');
+        this._resetEventFlags();
       }
     });
   }
@@ -593,6 +596,7 @@ class SftpClient {
     }).finally(() => {
       if (addListeners) {
         removeTempListeners(this, listeners, '_fastPut');
+        this._resetEventFlags();
       }
     });
   }
@@ -649,7 +653,7 @@ class SftpClient {
       };
       if (haveConnection(this, '_put', reject)) {
         wtr = this.sftp.createWriteStream(rPath, opts.writeStreamOptions);
-        wtr.once('error', (err) => {
+        wtr.on('error', (err) => {
           if (typeof lPath === 'string' && rdr && !rdr.destroyed) {
             rdr.destroy();
           }
@@ -665,17 +669,14 @@ class SftpClient {
           resolve(`Uploaded data stream to ${rPath}`);
         });
         if (lPath instanceof Buffer) {
-          this.debugMsg('put source is a buffer');
           wtr.end(lPath);
         } else {
           if (typeof lPath === 'string') {
-            this.debugMsg('put source is string path');
             rdr = fs.createReadStream(lPath, opts.readStreamOptions);
           } else {
-            this.debugMsg('put source is a stream');
             rdr = lPath;
           }
-          rdr.once('error', (err) => {
+          rdr.on('error', (err) => {
             reject(
               this.fmtError(
                 `Read stream error: ${err.message} ${
@@ -695,6 +696,7 @@ class SftpClient {
       }
       if (addListeners) {
         removeTempListeners(this, listeners, '_put');
+        this._resetEventFlags();
       }
     });
   }
@@ -750,6 +752,7 @@ class SftpClient {
     }).finally(() => {
       if (addListeners) {
         removeTempListeners(this, listeners, '_append');
+        this._resetEventFlags();
       }
     });
   }
@@ -821,6 +824,7 @@ class SftpClient {
     }).finally(() => {
       if (addListeners) {
         removeTempListeners(this, listeners, '_doMkdir');
+        this._resetEventFlags();
       }
     });
   }
@@ -894,6 +898,7 @@ class SftpClient {
         });
       }).finally(() => {
         removeTempListeners(this, listeners, '_rmdir');
+        this._resetEventFlags();
       });
     };
 
@@ -983,6 +988,7 @@ class SftpClient {
     }).finally(() => {
       if (addListeners) {
         removeTempListeners(this, listeners, 'delete');
+        this._resetEventFlags();
       }
     });
   }
@@ -1021,6 +1027,7 @@ class SftpClient {
     }).finally(() => {
       if (addListeners) {
         removeTempListeners(this, listeners, 'rename');
+        this._resetEventFlags();
       }
     });
   }
@@ -1059,6 +1066,7 @@ class SftpClient {
       }
     }).finally(() => {
       removeTempListeners(this, listeners, 'posixRename');
+      this._resetEventFlags();
     });
   }
 
@@ -1090,6 +1098,7 @@ class SftpClient {
     }).finally(() => {
       if (addListeners) {
         removeTempListeners(this, listeners, 'chmod');
+        this._resetEventFlags();
       }
     });
   }
@@ -1175,6 +1184,7 @@ class SftpClient {
         throw this.fmtError(`${e.message} ${srcDir} to ${dstDir}`, 'uploadFiles', e.code);
       } finally {
         removeTempListeners(this, listeners, uploadFiles);
+        this._resetEventFlags();
       }
     };
 
@@ -1300,6 +1310,7 @@ class SftpClient {
         );
       } finally {
         removeTempListeners(this, listeners, 'downloadFiles');
+        this._resetEventFlags();
       }
     };
 
@@ -1347,6 +1358,7 @@ class SftpClient {
       throw err.custom ? err : this.fmtError(err.message, 'createReadStream', err.code);
     } finally {
       removeTempListeners(this, listeners, 'createReadStream');
+      this._resetEventFlags();
     }
   }
 
@@ -1372,6 +1384,7 @@ class SftpClient {
       throw err.custom ? err : this.fmtError(err.message, 'createWriteStream', err.code);
     } finally {
       removeTempListeners(this, listeners, 'createWriteStream');
+      this._resetEventFlags();
     }
   }
 
@@ -1435,6 +1448,7 @@ class SftpClient {
       throw err.custom ? err : this.fmtError(err, 'rcopy');
     } finally {
       removeTempListeners(this, listeners, 'rcopy');
+      this._resetEventFlags();
     }
   }
   /**
@@ -1466,6 +1480,7 @@ class SftpClient {
     }).finally(() => {
       removeTempListeners(this, listeners, 'end');
       this.removeListener('close', endCloseHandler);
+      this._resetEventFlags();
     });
   }
 }

package/src/utils.js

@@ -64,6 +64,11 @@ function errorListener(client, name, reject) {
       client.debugMsg(`${name} errorListener - ignoring handled error ${err.message}`);
       return;
     }
+    // ignore ECONNRESET if end() has been called, as we can be confident that a reset connection is definitely dead
+    if (name === 'end' && client.endCalled && err.code === 'ECONNRESET') {
+      client.debugMsg(`${name} errorListener - ignoring ${err.message} on end`);
+      return;
+    }
     client.debugMsg(`${name} errorListener - handling error ${err.message}`);
     client.errorHandled = true;
     const newError = new Error(`${name}: ${err.message}`);
@@ -88,7 +93,7 @@ function endListener(client, name, reject) {
     client.endHandled = true;
     client.debugMsg(`${name} endListener - handling unexpected end event`);
     const newError = new Error(`${name}: Unexpected end event`);
-    newError.code = errorCode.ERR_GENERIC_CLIENT;
+    newError.code = errorCode.generic;
     if (reject) {
       reject(newError);
     } else {
@@ -109,7 +114,7 @@ function closeListener(client, name, reject) {
     client.closeHandled = true;
     client.debugMsg(`${name} closeListener - handling unexpected close event`);
     const newError = new Error(`${name}: Unexpected close event`);
-    newError.code = errorCode.ERR_GENERIC_CLIENT;
+    newError.code = errorCode.generic;
     if (reject) {
       reject(newError);
     } else {