ssh2-sftp-client 11.0.0 → 12.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +160 -153
- package/README.org +78 -70
- package/package.json +3 -4
- package/src/index.js +65 -112
- package/src/utils.js +2 -2
package/README.org
CHANGED
|
@@ -3,56 +3,70 @@
|
|
|
3
3
|
|
|
4
4
|
* Overview
|
|
5
5
|
|
|
6
|
-
This
|
|
7
|
-
based decorator class around the
|
|
8
|
-
Javascript event based ssh2 implementation.
|
|
6
|
+
This package provides the class SftpClient, an SFTP client for node.js. It is a promise
|
|
7
|
+
based decorator class around the excellent [[https://github.com/mscdex/ssh2][SSH2]] package, which provides a pure node
|
|
8
|
+
Javascript event based ssh2 implementation.
|
|
9
9
|
|
|
10
10
|
Documentation on the methods and available options in the underlying modules can
|
|
11
|
-
be found on the [[https://github.com/mscdex/ssh2][SSH2]] project pages. As the ssh2-sftp-client package just a wrapper around the
|
|
11
|
+
be found on the [[https://github.com/mscdex/ssh2][SSH2]] project pages. As the ssh2-sftp-client package is just a wrapper around the
|
|
12
12
|
~ssh2~ module, you will find lots of useful information, tips and examples in the ~ssh2~
|
|
13
13
|
repository.
|
|
14
14
|
|
|
15
|
-
Current stable release is *
|
|
15
|
+
Current stable release is *v12.0.1.
|
|
16
16
|
|
|
17
|
-
Code has been tested against Node versions
|
|
18
|
-
prior to
|
|
19
|
-
using node v22+. This is from the ~ssh2~ package and outside control of this package.
|
|
17
|
+
Code has been tested against Node versions 20.19.2, 22.16.0, 23.11.1 and 24.2.0. Node versions
|
|
18
|
+
prior to v20.x are not supported.
|
|
20
19
|
|
|
21
20
|
If you find this module useful and you would like to support the on-going maintenance and
|
|
22
21
|
support of users, please consider making a small [[https://square.link/u/gB2kSdkY?src=embed][donation]].
|
|
23
22
|
|
|
24
|
-
** Version
|
|
25
|
-
|
|
26
|
-
The
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
23
|
+
** Version 12.0.0 Changes
|
|
24
|
+
|
|
25
|
+
The big and breaking change in this version is the removal of the connection retry
|
|
26
|
+
code. This module no longer supports automatic connection retries when establishing the
|
|
27
|
+
initial connection. This functionality was removed for a number of reasons. The main
|
|
28
|
+
reasons are that it significantly complicated the connection handling code and error
|
|
29
|
+
handling in particular and it was seldom useful. In most cases, if the connection failed
|
|
30
|
+
on the first attempt, it would also fail in all subsequent attempts and often resulted in
|
|
31
|
+
just extending the time to failure as multiple retries were attempted.
|
|
32
|
+
|
|
33
|
+
Another reason this functionality was removed is because if you really want it, it is
|
|
34
|
+
straight forward to create your own wrapper around the connect call which uses one
|
|
35
|
+
of the mnay promise retry packages available. It is much simpler to add a retry mechanism
|
|
36
|
+
for a specific application than it is to implement a flexible solution which supports all
|
|
37
|
+
possible combination of connection options, authentication methods, proxies etc.
|
|
38
|
+
|
|
39
|
+
** Version 12.0.1 Changes
|
|
40
|
+
|
|
41
|
+
Bug Fixes
|
|
42
|
+
|
|
43
|
+
- Fix typo error in specification of generic error code in error handler. Typo was
|
|
44
|
+
causing an undefined symbol error.
|
|
45
|
+
- Fix bug in stream error handling. Read and write streams had an error handler defined
|
|
46
|
+
with 'once' rather than 'on'. This caused a bug when an API call caused more than one
|
|
47
|
+
error. For example, a network connectivity error would cause a stream timeout error
|
|
48
|
+
followed by a no response from remote host error when the error handler attempted to
|
|
49
|
+
cleanup and destroy the remote stream. The second error whould not be handled and
|
|
50
|
+
would bubble up to the parent node process, which would then exit with an unhandled
|
|
51
|
+
exception error.
|
|
52
|
+
- Added calls to _resetEventFlags() to finally clauses to ensure event flags are reset
|
|
53
|
+
when temp listeners are removed. Without this change, global listeners would not fire
|
|
54
|
+
when they should after their has been an earlier handled error in the last API call.
|
|
55
|
+
|
|
42
56
|
** Background
|
|
43
57
|
|
|
44
58
|
In basic terms =ssh2-sftp-client= is a simple wrapper around the =ssh2= package which provides
|
|
45
|
-
a promise
|
|
46
|
-
an event based API for interacting with the ~ssh~
|
|
59
|
+
a promise based API for interacting with a remote SFTP server . The =ssh2= package provides
|
|
60
|
+
an event based API for interacting with the ~ssh~ protocol. The ~ssh2-sftp-client~ package
|
|
47
61
|
uses the ~sftp~ subsystem of this protocol to implement the basic operations typically
|
|
48
62
|
associated with an ~sftp~ client.
|
|
49
63
|
|
|
50
|
-
Wrapping an event based API with a
|
|
64
|
+
Wrapping an event based API with a promise based API comes with a number of
|
|
51
65
|
challenges. In particular, efficiently and reliably managing events within the context of
|
|
52
|
-
|
|
66
|
+
asynchronous code execution. This package uses the following strategies;
|
|
53
67
|
|
|
54
68
|
- All direct interactions with the ~ssh2~ API are wrapped in promise objects. When the
|
|
55
|
-
API call succeeds, the
|
|
69
|
+
API call succeeds, the associated promise will be successfully resolved. When an error occurs,
|
|
56
70
|
the promise is rejected.
|
|
57
71
|
|
|
58
72
|
- An error can either be due to a low level network error, such as a lost connection
|
|
@@ -60,30 +74,32 @@ asynchrounous code execution. This package uses the following strategies;
|
|
|
60
74
|
existing or not having the appropriate permissions for access.
|
|
61
75
|
|
|
62
76
|
- Each of the available ~SftpClient~ methods wrap the method call inside a promise. In
|
|
63
|
-
|
|
64
|
-
and close events and links those liseners to the method's promise via
|
|
77
|
+
creating each promise, the class adds temporary event listeners for the error, end
|
|
78
|
+
and close events and links those liseners to the method's promise via its ~reject()~
|
|
65
79
|
method.
|
|
66
80
|
|
|
67
|
-
- If a promise is waiting to be fulfilled when
|
|
68
|
-
occurs, the error will be communicated back to client code via
|
|
81
|
+
- If a promise is waiting to be fulfilled when an error
|
|
82
|
+
occurs, the error will be communicated back to the client code via the rejected promise.
|
|
69
83
|
|
|
70
84
|
- When the ~ssh2~ emitter raises an event outside the context of any promise, that event
|
|
71
85
|
will be handled by global event handlers. By default, these event handlers will log
|
|
72
86
|
the event and will invalidate any existing socket connection objects, preventing any
|
|
73
|
-
further API calls until a new connection is
|
|
87
|
+
further API calls until a new connection is established.
|
|
74
88
|
|
|
75
89
|
- The ~SftpClient~ class constructor supports an optoinal second argument which is an
|
|
76
|
-
objedct
|
|
77
|
-
|
|
78
|
-
|
|
90
|
+
objedct which can have any of the three properties error, end and close. The values
|
|
91
|
+
associated with these properties are callback functions that will be run if an error
|
|
92
|
+
event with?he same name as the property is raised and has not been handled by one of
|
|
93
|
+
the temporary event handlers. The error callback should have a single parameter, the
|
|
94
|
+
error raised by the event. The other callbacks have no arguments.
|
|
79
95
|
|
|
80
96
|
The need for both global listeners and temporary promise listeners is because network end,
|
|
81
|
-
close or error events can occur at any time, including in-
|
|
97
|
+
close or error events can occur at any time, including in-between API calls. During an
|
|
82
98
|
API call, a promise is active and can be used to communicate event information back to the calling
|
|
83
|
-
code via normal promise communication
|
|
99
|
+
code via normal promise communication channels i.e. async/await with try/catch or promise chain's then/catch
|
|
84
100
|
mechanism. However, outside API calls, no promise exists and there is no reliable
|
|
85
101
|
mechanism to return error and other event information back to calling code. You cannot
|
|
86
|
-
reliably use try/cdatch to catch
|
|
102
|
+
reliably use try/cdatch to catch errors thrown inside event listenrs as you lack control
|
|
87
103
|
over when the listener code runs. Your try/catch block can easily complete before the
|
|
88
104
|
error is raised as there is no equivalent /await/ type functionality in this situation.
|
|
89
105
|
|
|
@@ -98,17 +114,17 @@ close or error event which is not handled by one of the temporary promise linked
|
|
|
98
114
|
listeners.
|
|
99
115
|
|
|
100
116
|
Version 11 of ~ssh2-sftp-client~ also changes the behaviour of the temporary promise linked
|
|
101
|
-
/end/ and /close/ listeners. Prior to
|
|
117
|
+
/end/ and /close/ listeners. Prior to version 11, these listeners did not reject
|
|
102
118
|
promises. They would only invalidate the underlying ~ssh~ connection object. Only the /error/
|
|
103
119
|
listener would actually reject the associated promise. This was done because you cannot
|
|
104
120
|
guarantee the order in which events are responded to.
|
|
105
121
|
|
|
106
122
|
In most cases, events will occur in the order /error/, /end/ and then /close/. The error event
|
|
107
123
|
would contain details about the cause of the error while the end and close events just
|
|
108
|
-
|
|
124
|
+
communicate that these events have been raised. The normal flow would be
|
|
109
125
|
|
|
110
126
|
- Error event occurs including error cause description. Listener catches event,
|
|
111
|
-
creates an error object and calls the associated
|
|
127
|
+
creates an error object and calls the associated promise's reject function to reject
|
|
112
128
|
the promise. The calling process receives a rejected promise object.
|
|
113
129
|
|
|
114
130
|
- End event occurs. The end listener catches the event and marks the connection object
|
|
@@ -117,11 +133,11 @@ communicvate that these events have been raised. The normal flow would be
|
|
|
117
133
|
listener and you can only call one promise resolution function.
|
|
118
134
|
|
|
119
135
|
- Close event occurs. This event means the socket connection has been closed. The
|
|
120
|
-
listener will ensure any connection information has been invalidated.
|
|
136
|
+
listener will ensure any connection information has been invalidated. Again, there
|
|
121
137
|
is no need to call the reject method of the associated promise as it has already
|
|
122
138
|
been called by the error listener.
|
|
123
139
|
|
|
124
|
-
In some cases, no
|
|
140
|
+
In some cases, no end event is raised and you only get an error event followed by a close
|
|
125
141
|
event. In versions of ~ssh2-sftp-client~ prior to version 11, neither the end or the close
|
|
126
142
|
listeners attempted to call the reject method of the associated promise. It was assumed
|
|
127
143
|
that all sftp servers would raise an error event whenever a connection was unexpectedly
|
|
@@ -134,7 +150,7 @@ call gets rejected with a timeout error aftrer a significant delay.
|
|
|
134
150
|
In order to handle the possible hanging issue in version 11, the temporary promise linked
|
|
135
151
|
end and close listeners have been updated to always call the promise's reject function if
|
|
136
152
|
they fire. While this works, it can cause a minor issue. As wse cannot gurantee the order
|
|
137
|
-
in which events are
|
|
153
|
+
in which events are responded to by listeners, it is possible that either the end or close
|
|
138
154
|
listener may be executed before the error listener. When this occurs, the promise is
|
|
139
155
|
rejected, but the only information wse have at that point is that the promise wsas reject
|
|
140
156
|
due to either an end or close event. We don't yet have any details regarding what error
|
|
@@ -173,12 +189,12 @@ with no indication as to reason. This can make diagnosis and bug tracking frustr
|
|
|
173
189
|
|
|
174
190
|
* Documentation
|
|
175
191
|
|
|
176
|
-
The connection options are the same as those offered by the underlying SSH2
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
details relating to setting various key
|
|
181
|
-
part of the ssh2 protocol.
|
|
192
|
+
The connection options are the same as those offered by the underlying SSH2 module, with
|
|
193
|
+
just a couple of additional properties added to add a ~debug~ function and set the
|
|
194
|
+
~promiseLimit~ property. For full details on the other properties, please see
|
|
195
|
+
[[https://github.com/mscdex/ssh2#user-content-client-methods][SSH2 client methods]]. In
|
|
196
|
+
particular, see the ~ssh2~ documentation for details relating to setting various key
|
|
197
|
+
exchange and encryption/signing algorithms used as part of the ssh2 protocol.
|
|
182
198
|
|
|
183
199
|
All the methods will return a Promise, except for ~on(), ~removeListener()~, ~createReadStream~
|
|
184
200
|
and ~createWriteStream~, which are typically only used in special use cases.
|
|
@@ -302,23 +318,18 @@ available [[https://github.com/mscdex/ssh2#user-content-client-methods][here]]
|
|
|
302
318
|
|
|
303
319
|
**** Connection Options
|
|
304
320
|
|
|
305
|
-
This module is based on the excellent [[https://github.com/mscdex/ssh2#client][SSH2]]
|
|
306
|
-
client and server library and provides much more
|
|
307
|
-
connectivity. Many of the connect options provided by that
|
|
308
|
-
relevant for SFTP connections. It is recommended you keep the config
|
|
309
|
-
the minimum needed and stick to the options listed in the ~commonOpts~ below.
|
|
310
|
-
|
|
311
|
-
The ~retries~, ~retry_factor~ and ~retry_minTimeout~ options are not part of the
|
|
312
|
-
SSH2 module. These are part of the configuration for the [[https://www.npmjs.com/package/retry][retry]] package and what
|
|
313
|
-
is used to enable retrying of sftp connection attempts. See the documentation
|
|
314
|
-
for that package for an explanation of these values.
|
|
321
|
+
This module is based on the excellent [[https://github.com/mscdex/ssh2#client][SSH2]]
|
|
322
|
+
module. That module is a general SSH2 client and server library and provides much more
|
|
323
|
+
functionality than just SFTP connectivity. Many of the connect options provided by that
|
|
324
|
+
module are less relevant for SFTP connections. It is recommended you keep the config
|
|
325
|
+
options to the minimum needed and stick to the options listed in the ~commonOpts~ below.
|
|
315
326
|
|
|
316
|
-
The ~promiseLimit~ is
|
|
327
|
+
The ~promiseLimit~ is an option which is not part of the ~ssh2~ module and is specific to
|
|
317
328
|
~ssh2-sftp-client~. It is a property used to limit the maximum number of concurrent promises
|
|
318
329
|
possible when either downloading or uploading a directory tree using the ~downloadDir()~ or
|
|
319
|
-
~uploadDir()~ methods. The default setting for this property is 10. *NOTE*: bigger
|
|
330
|
+
~uploadDir()~ methods. The default setting for this property is 10. *NOTE*: bigger does not
|
|
320
331
|
mean better. Many factors can affect what is the ideal setting for ~promiseLimit~. If it is
|
|
321
|
-
too large, any benefits are lost while node spends time switching contexts and/or
|
|
332
|
+
too large, any benefits are lost while node spends time switching contexts and/or with
|
|
322
333
|
the overheads associated with creating and cleaning up promises. Lots of factors can
|
|
323
334
|
affect what the setting should be, including size of files, number of files, speed of
|
|
324
335
|
network, version of node, capabilities of remote sftp server etc. A setting of 10 seems to
|
|
@@ -343,9 +354,6 @@ work out what is the best maximum size before you begin to see a performance dro
|
|
|
343
354
|
strictVendor: true, // boolean - Performs a strict server vendor check
|
|
344
355
|
debug: myDebug,// function - Set this to a function that receives a single
|
|
345
356
|
// string argument to get detailed (local) debug information.
|
|
346
|
-
retries: 2, // integer. Number of times to retry connecting
|
|
347
|
-
retry_factor: 2, // integer. Time factor used to calculate time between retries
|
|
348
|
-
retry_minTimeout: 2000, // integer. Minimum timeout between attempts
|
|
349
357
|
promiseLimit: 10, // max concurrent promises for downloadDir/uploadDir
|
|
350
358
|
};
|
|
351
359
|
|
package/package.json
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ssh2-sftp-client",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "12.0.1",
|
|
4
4
|
"description": "ssh2 sftp client for node",
|
|
5
5
|
"main": "src/index.js",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
8
|
-
"url": "https://github.com/theophilusx/ssh2-sftp-client"
|
|
8
|
+
"url": "git+https://github.com/theophilusx/ssh2-sftp-client.git"
|
|
9
9
|
},
|
|
10
10
|
"keywords": [
|
|
11
11
|
"sftp",
|
|
@@ -54,7 +54,6 @@
|
|
|
54
54
|
},
|
|
55
55
|
"dependencies": {
|
|
56
56
|
"concat-stream": "^2.0.0",
|
|
57
|
-
"
|
|
58
|
-
"ssh2": "^1.15.0"
|
|
57
|
+
"ssh2": "^1.16.0"
|
|
59
58
|
}
|
|
60
59
|
}
|