ssh2-sftp-client 12.0.1 → 12.1.0
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 +139 -130
- package/README.org +15 -7
- package/package.json +2 -2
- package/src/utils.js +5 -0
package/README.md
CHANGED
|
@@ -1,69 +1,70 @@
|
|
|
1
|
-
- [Overview](#
|
|
2
|
-
- [Version 12.0.0 Changes](#
|
|
3
|
-
- [Version 12.0.1 Changes](#
|
|
4
|
-
- [
|
|
5
|
-
- [
|
|
6
|
-
- [
|
|
7
|
-
- [
|
|
8
|
-
|
|
9
|
-
- [
|
|
10
|
-
|
|
11
|
-
- [
|
|
12
|
-
- [
|
|
13
|
-
- [
|
|
14
|
-
- [
|
|
15
|
-
- [
|
|
16
|
-
- [
|
|
17
|
-
- [
|
|
18
|
-
- [
|
|
19
|
-
- [
|
|
20
|
-
- [
|
|
21
|
-
- [
|
|
22
|
-
- [
|
|
23
|
-
- [
|
|
24
|
-
- [
|
|
25
|
-
- [
|
|
26
|
-
- [
|
|
27
|
-
- [
|
|
28
|
-
- [
|
|
29
|
-
- [
|
|
30
|
-
- [
|
|
31
|
-
- [
|
|
32
|
-
- [
|
|
33
|
-
- [
|
|
34
|
-
- [
|
|
35
|
-
- [
|
|
36
|
-
|
|
37
|
-
- [
|
|
38
|
-
- [
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
- [
|
|
42
|
-
- [
|
|
43
|
-
|
|
44
|
-
- [
|
|
45
|
-
- [How can I
|
|
46
|
-
- [How can I
|
|
47
|
-
- [
|
|
48
|
-
- [
|
|
49
|
-
- [
|
|
50
|
-
- [
|
|
51
|
-
- [
|
|
52
|
-
- [
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
- [
|
|
56
|
-
- [
|
|
57
|
-
- [
|
|
58
|
-
- [
|
|
59
|
-
|
|
60
|
-
- [
|
|
61
|
-
- [
|
|
62
|
-
- [
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
1
|
+
- [Overview](#orge272967)
|
|
2
|
+
- [Version 12.0.0 Changes](#org9688783)
|
|
3
|
+
- [Version 12.0.1 Changes](#org6c6cbc7)
|
|
4
|
+
- [Version 12.1.0 Changes](#org678bfad)
|
|
5
|
+
- [Background](#org41ff3b3)
|
|
6
|
+
- [Installation](#org64016b3)
|
|
7
|
+
- [Basic Usage](#org0cbc36d)
|
|
8
|
+
- [Documentation](#org161d25d)
|
|
9
|
+
- [Specifying Paths](#org569c530)
|
|
10
|
+
- [Methods](#orge938fe1)
|
|
11
|
+
- [new SftpClient(name, callbacks) ===> SFTP client object](#org87fb7cb)
|
|
12
|
+
- [connect(config) ===> SFTP object](#org00cd0ef)
|
|
13
|
+
- [list(path, filter) ==> Array[object]](#org2471bc8)
|
|
14
|
+
- [exists(path) ==> boolean](#org69f0979)
|
|
15
|
+
- [stat(path) ==> object](#org70605b0)
|
|
16
|
+
- [get(path, dst, options) ==> String|Stream|Buffer](#org6ef818c)
|
|
17
|
+
- [fastGet(remotePath, localPath, options) ===> string](#org4be5f02)
|
|
18
|
+
- [put(src, remotePath, options) ==> string](#org29892b8)
|
|
19
|
+
- [fastPut(localPath, remotePath, options) ==> string](#org8b51862)
|
|
20
|
+
- [append(input, remotePath, options) ==> string](#org60825d3)
|
|
21
|
+
- [mkdir(path, recursive) ==> string](#orga9278dd)
|
|
22
|
+
- [rmdir(path, recursive) ==> string](#org49dc87c)
|
|
23
|
+
- [delete(path, noErrorOK) ==> string](#orgbe8caee)
|
|
24
|
+
- [rename(fromPath, toPath) ==> string](#orgc525c46)
|
|
25
|
+
- [posixRename(fromPath, toPath) ==> string](#org72d1dcb)
|
|
26
|
+
- [chmod(path, mode) ==> string](#org0c71566)
|
|
27
|
+
- [realPath(path) ===> string](#org7dcfedc)
|
|
28
|
+
- [cwd() ==> string](#orgdaa63b2)
|
|
29
|
+
- [uploadDir(srcDir, dstDir, options) ==> string](#orgf47dba2)
|
|
30
|
+
- [downloadDir(srcDir, dstDir, options) ==> string](#orgc046861)
|
|
31
|
+
- [createReadStream(remotePath, options)) ==> stream object](#orgbb40821)
|
|
32
|
+
- [createWriteStream(remotePath, options) ==> stream object](#org5b94858)
|
|
33
|
+
- [rcopy(srcPath, dstPath) ==> string](#org352c030)
|
|
34
|
+
- [end() ==> boolean](#org9591ce4)
|
|
35
|
+
- [Add and Remove Listeners](#org5f4115d)
|
|
36
|
+
- [Platform Quirks & Warnings](#org99f279a)
|
|
37
|
+
- [Server Capabilities](#org5f13ec7)
|
|
38
|
+
- [Issues with `fastPut()` and `fastGet()` Methods](#org0580b2e)
|
|
39
|
+
- [Promises, Events & Managing Exceptions](#org836ad16)
|
|
40
|
+
- [Adding Custom Handlers](#org7eb04eb)
|
|
41
|
+
- [Windows Based Servers](#org64d4763)
|
|
42
|
+
- [Don't Re-use SftpClient Objects](#org4e39c0f)
|
|
43
|
+
- [FAQ](#org55e6f0b)
|
|
44
|
+
- [Remote server drops connections with only an end event](#orgbba8948)
|
|
45
|
+
- [How can I pass writeable stream as dst for get method?](#org3380bb0)
|
|
46
|
+
- [How can I upload files without having to specify a password?](#org144745f)
|
|
47
|
+
- [How can I connect through a Socks Proxy](#org65cf78c)
|
|
48
|
+
- [Timeout while waiting for handshake or handshake errors](#orgc1209ba)
|
|
49
|
+
- [How can I limit upload/download speed](#orgec6bc5b)
|
|
50
|
+
- [Connection hangs or fails for larger files](#org222771b)
|
|
51
|
+
- [Typescript definition file out of date](#org64453a9)
|
|
52
|
+
- [Examples](#orge079610)
|
|
53
|
+
- [Troubleshooting](#orgedc17fd)
|
|
54
|
+
- [Common Errors](#org7756613)
|
|
55
|
+
- [Not returning the promise in a `then()` block](#orgdf44163)
|
|
56
|
+
- [Mixing Promise Chains and Async/Await](#org643899f)
|
|
57
|
+
- [Try/catch and Error Handlers](#orgf1586cd)
|
|
58
|
+
- [Server Differences](#org57723b9)
|
|
59
|
+
- [Avoid Concurrent Operations](#org8f56d89)
|
|
60
|
+
- [Debugging Support](#org4c34184)
|
|
61
|
+
- [Logging Issues](#org63b74c6)
|
|
62
|
+
- [Pull Requests](#org308be7d)
|
|
63
|
+
- [Contributors](#org585b558)
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
<a id="orge272967"></a>
|
|
67
68
|
|
|
68
69
|
# Overview
|
|
69
70
|
|
|
@@ -71,14 +72,14 @@ This package provides the class SftpClient, an SFTP client for node.js. It is a
|
|
|
71
72
|
|
|
72
73
|
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.
|
|
73
74
|
|
|
74
|
-
Current stable release is \*v12.0.
|
|
75
|
+
Current stable release is \*v12.1.0.
|
|
75
76
|
|
|
76
|
-
Code has been tested against Node versions
|
|
77
|
+
Code has been tested against Node versions 24.14.0. Node versions prior to v20.x are not supported.
|
|
77
78
|
|
|
78
79
|
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).
|
|
79
80
|
|
|
80
81
|
|
|
81
|
-
<a id="
|
|
82
|
+
<a id="org9688783"></a>
|
|
82
83
|
|
|
83
84
|
## Version 12.0.0 Changes
|
|
84
85
|
|
|
@@ -87,7 +88,7 @@ The big and breaking change in this version is the removal of the connection ret
|
|
|
87
88
|
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.
|
|
88
89
|
|
|
89
90
|
|
|
90
|
-
<a id="
|
|
91
|
+
<a id="org6c6cbc7"></a>
|
|
91
92
|
|
|
92
93
|
## Version 12.0.1 Changes
|
|
93
94
|
|
|
@@ -98,7 +99,14 @@ Bug Fixes
|
|
|
98
99
|
- 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.
|
|
99
100
|
|
|
100
101
|
|
|
101
|
-
<a id="
|
|
102
|
+
<a id="org678bfad"></a>
|
|
103
|
+
|
|
104
|
+
## Version 12.1.0 Changes
|
|
105
|
+
|
|
106
|
+
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.
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
<a id="org41ff3b3"></a>
|
|
102
110
|
|
|
103
111
|
## Background
|
|
104
112
|
|
|
@@ -116,7 +124,7 @@ Wrapping an event based API with a promise based API comes with a number of chal
|
|
|
116
124
|
|
|
117
125
|
- 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.
|
|
118
126
|
|
|
119
|
-
- The `SftpClient` class constructor supports an optoinal second argument which is an
|
|
127
|
+
- 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.
|
|
120
128
|
|
|
121
129
|
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.
|
|
122
130
|
|
|
@@ -137,7 +145,7 @@ In some cases, no end event is raised and you only get an error event followed b
|
|
|
137
145
|
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.
|
|
138
146
|
|
|
139
147
|
|
|
140
|
-
<a id="
|
|
148
|
+
<a id="org64016b3"></a>
|
|
141
149
|
|
|
142
150
|
# Installation
|
|
143
151
|
|
|
@@ -146,7 +154,7 @@ npm install ssh2-sftp-client
|
|
|
146
154
|
```
|
|
147
155
|
|
|
148
156
|
|
|
149
|
-
<a id="
|
|
157
|
+
<a id="org0cbc36d"></a>
|
|
150
158
|
|
|
151
159
|
# Basic Usage
|
|
152
160
|
|
|
@@ -169,7 +177,7 @@ sftp.connect({
|
|
|
169
177
|
```
|
|
170
178
|
|
|
171
179
|
|
|
172
|
-
<a id="
|
|
180
|
+
<a id="org161d25d"></a>
|
|
173
181
|
|
|
174
182
|
# Documentation
|
|
175
183
|
|
|
@@ -180,7 +188,7 @@ All the methods will return a Promise, except for `on(), ~removeListener()`, `cr
|
|
|
180
188
|
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.
|
|
181
189
|
|
|
182
190
|
|
|
183
|
-
<a id="
|
|
191
|
+
<a id="org569c530"></a>
|
|
184
192
|
|
|
185
193
|
## Specifying Paths
|
|
186
194
|
|
|
@@ -213,12 +221,12 @@ client.put('/home/fred/test.txt', '/remote/dir/test-copy.txt');
|
|
|
213
221
|
This will copy the local file `test.txt` to the remote file `test-copy.txt` in the directory `/remote/dir`.
|
|
214
222
|
|
|
215
223
|
|
|
216
|
-
<a id="
|
|
224
|
+
<a id="orge938fe1"></a>
|
|
217
225
|
|
|
218
226
|
## Methods
|
|
219
227
|
|
|
220
228
|
|
|
221
|
-
<a id="
|
|
229
|
+
<a id="org87fb7cb"></a>
|
|
222
230
|
|
|
223
231
|
### new SftpClient(name, callbacks) ===> SFTP client object
|
|
224
232
|
|
|
@@ -258,7 +266,7 @@ Constructor to create a new `ssh2-sftp-client` object. An optional `name` string
|
|
|
258
266
|
```
|
|
259
267
|
|
|
260
268
|
|
|
261
|
-
<a id="
|
|
269
|
+
<a id="org00cd0ef"></a>
|
|
262
270
|
|
|
263
271
|
### connect(config) ===> SFTP object
|
|
264
272
|
|
|
@@ -322,7 +330,7 @@ Connect to an sftp server. Full documentation for connection options is availabl
|
|
|
322
330
|
```
|
|
323
331
|
|
|
324
332
|
|
|
325
|
-
<a id="
|
|
333
|
+
<a id="org2471bc8"></a>
|
|
326
334
|
|
|
327
335
|
### list(path, filter) ==> Array[object]
|
|
328
336
|
|
|
@@ -383,7 +391,7 @@ Retrieves a directory listing. This method returns a Promise, which once realise
|
|
|
383
391
|
```
|
|
384
392
|
|
|
385
393
|
|
|
386
|
-
<a id="
|
|
394
|
+
<a id="org69f0979"></a>
|
|
387
395
|
|
|
388
396
|
### exists(path) ==> boolean
|
|
389
397
|
|
|
@@ -419,7 +427,7 @@ Tests to see if remote file or directory exists. Returns type of remote object i
|
|
|
419
427
|
```
|
|
420
428
|
|
|
421
429
|
|
|
422
|
-
<a id="
|
|
430
|
+
<a id="org70605b0"></a>
|
|
423
431
|
|
|
424
432
|
### stat(path) ==> object
|
|
425
433
|
|
|
@@ -470,7 +478,7 @@ Returns the attributes associated with the object pointed to by `path`.
|
|
|
470
478
|
```
|
|
471
479
|
|
|
472
480
|
|
|
473
|
-
<a id="
|
|
481
|
+
<a id="org6ef818c"></a>
|
|
474
482
|
|
|
475
483
|
### get(path, dst, options) ==> String|Stream|Buffer
|
|
476
484
|
|
|
@@ -526,7 +534,7 @@ In general, if you're going to pass in a string as the destination, you are bett
|
|
|
526
534
|
- **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'.
|
|
527
535
|
|
|
528
536
|
|
|
529
|
-
<a id="
|
|
537
|
+
<a id="org4be5f02"></a>
|
|
530
538
|
|
|
531
539
|
### fastGet(remotePath, localPath, options) ===> string
|
|
532
540
|
|
|
@@ -571,7 +579,7 @@ Bottom line, when it works, it tends to work reliably. However, for many servers
|
|
|
571
579
|
```
|
|
572
580
|
|
|
573
581
|
|
|
574
|
-
<a id="
|
|
582
|
+
<a id="org29892b8"></a>
|
|
575
583
|
|
|
576
584
|
### put(src, remotePath, options) ==> string
|
|
577
585
|
|
|
@@ -621,7 +629,7 @@ Upload data from local system to remote server. If the `src` argument is a strin
|
|
|
621
629
|
- **Tip:** If the src argument is a path string, consider just using `fastPut()`.
|
|
622
630
|
|
|
623
631
|
|
|
624
|
-
<a id="
|
|
632
|
+
<a id="org8b51862"></a>
|
|
625
633
|
|
|
626
634
|
### fastPut(localPath, remotePath, options) ==> string
|
|
627
635
|
|
|
@@ -667,7 +675,7 @@ Bottom line, when it works, it tends to work well. However, when it doesn't work
|
|
|
667
675
|
```
|
|
668
676
|
|
|
669
677
|
|
|
670
|
-
<a id="
|
|
678
|
+
<a id="org60825d3"></a>
|
|
671
679
|
|
|
672
680
|
### append(input, remotePath, options) ==> string
|
|
673
681
|
|
|
@@ -711,7 +719,7 @@ Append the `input` data to an existing remote file. There is no integrity checki
|
|
|
711
719
|
```
|
|
712
720
|
|
|
713
721
|
|
|
714
|
-
<a id="
|
|
722
|
+
<a id="orga9278dd"></a>
|
|
715
723
|
|
|
716
724
|
### mkdir(path, recursive) ==> string
|
|
717
725
|
|
|
@@ -739,7 +747,7 @@ Create a new directory. If the recursive flag is set to true, the method will cr
|
|
|
739
747
|
```
|
|
740
748
|
|
|
741
749
|
|
|
742
|
-
<a id="
|
|
750
|
+
<a id="org49dc87c"></a>
|
|
743
751
|
|
|
744
752
|
### rmdir(path, recursive) ==> string
|
|
745
753
|
|
|
@@ -769,7 +777,7 @@ Remove a directory. If removing a directory and recursive flag is set to `true`,
|
|
|
769
777
|
```
|
|
770
778
|
|
|
771
779
|
|
|
772
|
-
<a id="
|
|
780
|
+
<a id="orgbe8caee"></a>
|
|
773
781
|
|
|
774
782
|
### delete(path, noErrorOK) ==> string
|
|
775
783
|
|
|
@@ -798,7 +806,7 @@ Delete a file on the remote server.
|
|
|
798
806
|
```
|
|
799
807
|
|
|
800
808
|
|
|
801
|
-
<a id="
|
|
809
|
+
<a id="orgc525c46"></a>
|
|
802
810
|
|
|
803
811
|
### rename(fromPath, toPath) ==> string
|
|
804
812
|
|
|
@@ -827,7 +835,7 @@ Rename a file or directory from `fromPath` to `toPath`. You must have the necess
|
|
|
827
835
|
```
|
|
828
836
|
|
|
829
837
|
|
|
830
|
-
<a id="
|
|
838
|
+
<a id="org72d1dcb"></a>
|
|
831
839
|
|
|
832
840
|
### posixRename(fromPath, toPath) ==> string
|
|
833
841
|
|
|
@@ -854,7 +862,7 @@ client.connect(config)
|
|
|
854
862
|
```
|
|
855
863
|
|
|
856
864
|
|
|
857
|
-
<a id="
|
|
865
|
+
<a id="org0c71566"></a>
|
|
858
866
|
|
|
859
867
|
### chmod(path, mode) ==> string
|
|
860
868
|
|
|
@@ -883,7 +891,7 @@ Change the mode (read, write or execute permissions) of a remote file or directo
|
|
|
883
891
|
```
|
|
884
892
|
|
|
885
893
|
|
|
886
|
-
<a id="
|
|
894
|
+
<a id="org7dcfedc"></a>
|
|
887
895
|
|
|
888
896
|
### realPath(path) ===> string
|
|
889
897
|
|
|
@@ -894,14 +902,14 @@ Converts a relative path to an absolute path on the remote server. This method i
|
|
|
894
902
|
- **path:** A file path, either relative or absolute. Can handle '.' and '..', but does not expand '~'.
|
|
895
903
|
|
|
896
904
|
|
|
897
|
-
<a id="
|
|
905
|
+
<a id="orgdaa63b2"></a>
|
|
898
906
|
|
|
899
907
|
### cwd() ==> string
|
|
900
908
|
|
|
901
909
|
Returns what the server believes is the current remote working directory.
|
|
902
910
|
|
|
903
911
|
|
|
904
|
-
<a id="
|
|
912
|
+
<a id="orgf47dba2"></a>
|
|
905
913
|
|
|
906
914
|
### uploadDir(srcDir, dstDir, options) ==> string
|
|
907
915
|
|
|
@@ -970,7 +978,7 @@ The `useFastput` option is a boolean option. If `true`, the method will use the
|
|
|
970
978
|
```
|
|
971
979
|
|
|
972
980
|
|
|
973
|
-
<a id="
|
|
981
|
+
<a id="orgc046861"></a>
|
|
974
982
|
|
|
975
983
|
### downloadDir(srcDir, dstDir, options) ==> string
|
|
976
984
|
|
|
@@ -1035,7 +1043,7 @@ If the `useFastget` property is set to `true`, the method will use `fastGet()` t
|
|
|
1035
1043
|
```
|
|
1036
1044
|
|
|
1037
1045
|
|
|
1038
|
-
<a id="
|
|
1046
|
+
<a id="orgbb40821"></a>
|
|
1039
1047
|
|
|
1040
1048
|
### createReadStream(remotePath, options)) ==> stream object
|
|
1041
1049
|
|
|
@@ -1052,7 +1060,7 @@ Returns a read stream object which is attached to the remote file specified by t
|
|
|
1052
1060
|
- **end:** Position to stop reading bytes (inclusive).
|
|
1053
1061
|
|
|
1054
1062
|
|
|
1055
|
-
<a id="
|
|
1063
|
+
<a id="org5b94858"></a>
|
|
1056
1064
|
|
|
1057
1065
|
### createWriteStream(remotePath, options) ==> stream object
|
|
1058
1066
|
|
|
@@ -1067,7 +1075,7 @@ Returns a write stream object which is attached to the remote file specified in
|
|
|
1067
1075
|
- **start:** Byte position to start writing from (inclusive). May require changing flag to 'r+'.
|
|
1068
1076
|
|
|
1069
1077
|
|
|
1070
|
-
<a id="
|
|
1078
|
+
<a id="org352c030"></a>
|
|
1071
1079
|
|
|
1072
1080
|
### rcopy(srcPath, dstPath) ==> string
|
|
1073
1081
|
|
|
@@ -1077,7 +1085,7 @@ Perform a remote file copy. The file identified by the `srcPath` argument will b
|
|
|
1077
1085
|
- **dstPath:** Path to where the copy will be created specified as a string
|
|
1078
1086
|
|
|
1079
1087
|
|
|
1080
|
-
<a id="
|
|
1088
|
+
<a id="org9591ce4"></a>
|
|
1081
1089
|
|
|
1082
1090
|
### end() ==> boolean
|
|
1083
1091
|
|
|
@@ -1101,7 +1109,7 @@ Ends the current client session, releasing the client socket and associated reso
|
|
|
1101
1109
|
```
|
|
1102
1110
|
|
|
1103
1111
|
|
|
1104
|
-
<a id="
|
|
1112
|
+
<a id="org5f4115d"></a>
|
|
1105
1113
|
|
|
1106
1114
|
### Add and Remove Listeners
|
|
1107
1115
|
|
|
@@ -1122,12 +1130,12 @@ Although normally not required, you can add and remove custom listeners on the s
|
|
|
1122
1130
|
Removes the specified listener from the event specified in eventType. Note that the `end()` method automatically removes all listeners from the client object.
|
|
1123
1131
|
|
|
1124
1132
|
|
|
1125
|
-
<a id="
|
|
1133
|
+
<a id="org99f279a"></a>
|
|
1126
1134
|
|
|
1127
1135
|
# Platform Quirks & Warnings
|
|
1128
1136
|
|
|
1129
1137
|
|
|
1130
|
-
<a id="
|
|
1138
|
+
<a id="org5f13ec7"></a>
|
|
1131
1139
|
|
|
1132
1140
|
## Server Capabilities
|
|
1133
1141
|
|
|
@@ -1136,7 +1144,7 @@ All SFTP servers and platforms are not equal. Some facilities provided by `ssh2-
|
|
|
1136
1144
|
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.
|
|
1137
1145
|
|
|
1138
1146
|
|
|
1139
|
-
<a id="
|
|
1147
|
+
<a id="org0580b2e"></a>
|
|
1140
1148
|
|
|
1141
1149
|
## Issues with `fastPut()` and `fastGet()` Methods
|
|
1142
1150
|
|
|
@@ -1145,7 +1153,7 @@ The `fastPut()` and `fastGet()` methods are known to be somewhat dependent on SF
|
|
|
1145
1153
|
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.
|
|
1146
1154
|
|
|
1147
1155
|
|
|
1148
|
-
<a id="
|
|
1156
|
+
<a id="org836ad16"></a>
|
|
1149
1157
|
|
|
1150
1158
|
## Promises, Events & Managing Exceptions
|
|
1151
1159
|
|
|
@@ -1164,14 +1172,14 @@ The other area where additional events are fired is during the end() call. To de
|
|
|
1164
1172
|
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.
|
|
1165
1173
|
|
|
1166
1174
|
|
|
1167
|
-
<a id="
|
|
1175
|
+
<a id="org7eb04eb"></a>
|
|
1168
1176
|
|
|
1169
1177
|
### Adding Custom Handlers
|
|
1170
1178
|
|
|
1171
1179
|
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.
|
|
1172
1180
|
|
|
1173
1181
|
|
|
1174
|
-
<a id="
|
|
1182
|
+
<a id="org64d4763"></a>
|
|
1175
1183
|
|
|
1176
1184
|
## Windows Based Servers
|
|
1177
1185
|
|
|
@@ -1180,7 +1188,7 @@ It appears that when the sftp server is running on Windows, a *ECONNRESET* error
|
|
|
1180
1188
|
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.
|
|
1181
1189
|
|
|
1182
1190
|
|
|
1183
|
-
<a id="
|
|
1191
|
+
<a id="org4e39c0f"></a>
|
|
1184
1192
|
|
|
1185
1193
|
## Don't Re-use SftpClient Objects
|
|
1186
1194
|
|
|
@@ -1189,12 +1197,12 @@ Due to an issue with *ECONNRESET* error signals when connecting to Windows based
|
|
|
1189
1197
|
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.
|
|
1190
1198
|
|
|
1191
1199
|
|
|
1192
|
-
<a id="
|
|
1200
|
+
<a id="org55e6f0b"></a>
|
|
1193
1201
|
|
|
1194
1202
|
# FAQ
|
|
1195
1203
|
|
|
1196
1204
|
|
|
1197
|
-
<a id="
|
|
1205
|
+
<a id="orgbba8948"></a>
|
|
1198
1206
|
|
|
1199
1207
|
## Remote server drops connections with only an end event
|
|
1200
1208
|
|
|
@@ -1205,7 +1213,7 @@ Clients first make an unauthenticated connection to the SFTP server to begin neg
|
|
|
1205
1213
|
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.
|
|
1206
1214
|
|
|
1207
1215
|
|
|
1208
|
-
<a id="
|
|
1216
|
+
<a id="org3380bb0"></a>
|
|
1209
1217
|
|
|
1210
1218
|
## How can I pass writeable stream as dst for get method?
|
|
1211
1219
|
|
|
@@ -1264,7 +1272,7 @@ sftp
|
|
|
1264
1272
|
```
|
|
1265
1273
|
|
|
1266
1274
|
|
|
1267
|
-
<a id="
|
|
1275
|
+
<a id="org144745f"></a>
|
|
1268
1276
|
|
|
1269
1277
|
## How can I upload files without having to specify a password?
|
|
1270
1278
|
|
|
@@ -1299,7 +1307,7 @@ sftp.connect({
|
|
|
1299
1307
|
```
|
|
1300
1308
|
|
|
1301
1309
|
|
|
1302
|
-
<a id="
|
|
1310
|
+
<a id="org65cf78c"></a>
|
|
1303
1311
|
|
|
1304
1312
|
## How can I connect through a Socks Proxy
|
|
1305
1313
|
|
|
@@ -1336,7 +1344,7 @@ client.connect({
|
|
|
1336
1344
|
```
|
|
1337
1345
|
|
|
1338
1346
|
|
|
1339
|
-
<a id="
|
|
1347
|
+
<a id="orgc1209ba"></a>
|
|
1340
1348
|
|
|
1341
1349
|
## Timeout while waiting for handshake or handshake errors
|
|
1342
1350
|
|
|
@@ -1345,7 +1353,7 @@ Some users have encountered the error 'Timeout while waiting for handshake' or '
|
|
|
1345
1353
|
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.
|
|
1346
1354
|
|
|
1347
1355
|
|
|
1348
|
-
<a id="
|
|
1356
|
+
<a id="orgec6bc5b"></a>
|
|
1349
1357
|
|
|
1350
1358
|
## How can I limit upload/download speed
|
|
1351
1359
|
|
|
@@ -1385,7 +1393,7 @@ try {
|
|
|
1385
1393
|
```
|
|
1386
1394
|
|
|
1387
1395
|
|
|
1388
|
-
<a id="
|
|
1396
|
+
<a id="org222771b"></a>
|
|
1389
1397
|
|
|
1390
1398
|
## Connection hangs or fails for larger files
|
|
1391
1399
|
|
|
@@ -1396,21 +1404,21 @@ A symptom of this issue is that you are able to upload small files, but uploadin
|
|
|
1396
1404
|
For more explanation, see [issue #342](https://github.com/theophilusx/ssh2-sftp-client/issues/342).
|
|
1397
1405
|
|
|
1398
1406
|
|
|
1399
|
-
<a id="
|
|
1407
|
+
<a id="org64453a9"></a>
|
|
1400
1408
|
|
|
1401
1409
|
## Typescript definition file out of date
|
|
1402
1410
|
|
|
1403
1411
|
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.
|
|
1404
1412
|
|
|
1405
1413
|
|
|
1406
|
-
<a id="
|
|
1414
|
+
<a id="orge079610"></a>
|
|
1407
1415
|
|
|
1408
1416
|
# Examples
|
|
1409
1417
|
|
|
1410
1418
|
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.
|
|
1411
1419
|
|
|
1412
1420
|
|
|
1413
|
-
<a id="
|
|
1421
|
+
<a id="orgedc17fd"></a>
|
|
1414
1422
|
|
|
1415
1423
|
# Troubleshooting
|
|
1416
1424
|
|
|
@@ -1425,14 +1433,14 @@ Note also that in the repository there are two useful directories. The first is
|
|
|
1425
1433
|
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.
|
|
1426
1434
|
|
|
1427
1435
|
|
|
1428
|
-
<a id="
|
|
1436
|
+
<a id="org7756613"></a>
|
|
1429
1437
|
|
|
1430
1438
|
## Common Errors
|
|
1431
1439
|
|
|
1432
1440
|
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.
|
|
1433
1441
|
|
|
1434
1442
|
|
|
1435
|
-
<a id="
|
|
1443
|
+
<a id="orgdf44163"></a>
|
|
1436
1444
|
|
|
1437
1445
|
### Not returning the promise in a `then()` block
|
|
1438
1446
|
|
|
@@ -1469,7 +1477,7 @@ Note the `return` statements. These ensure that the Promise returned by the clie
|
|
|
1469
1477
|
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.
|
|
1470
1478
|
|
|
1471
1479
|
|
|
1472
|
-
<a id="
|
|
1480
|
+
<a id="org643899f"></a>
|
|
1473
1481
|
|
|
1474
1482
|
### Mixing Promise Chains and Async/Await
|
|
1475
1483
|
|
|
@@ -1529,7 +1537,7 @@ async function doSftp() {
|
|
|
1529
1537
|
```
|
|
1530
1538
|
|
|
1531
1539
|
|
|
1532
|
-
<a id="
|
|
1540
|
+
<a id="orgf1586cd"></a>
|
|
1533
1541
|
|
|
1534
1542
|
### Try/catch and Error Handlers
|
|
1535
1543
|
|
|
@@ -1540,14 +1548,14 @@ The basic problem is that the try/catch block will have completed execution befo
|
|
|
1540
1548
|
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.
|
|
1541
1549
|
|
|
1542
1550
|
|
|
1543
|
-
<a id="
|
|
1551
|
+
<a id="org57723b9"></a>
|
|
1544
1552
|
|
|
1545
1553
|
### Server Differences
|
|
1546
1554
|
|
|
1547
1555
|
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.
|
|
1548
1556
|
|
|
1549
1557
|
|
|
1550
|
-
<a id="
|
|
1558
|
+
<a id="org8f56d89"></a>
|
|
1551
1559
|
|
|
1552
1560
|
### Avoid Concurrent Operations
|
|
1553
1561
|
|
|
@@ -1556,7 +1564,7 @@ Technically, SFTP should be able to perform multiple operations concurrently. As
|
|
|
1556
1564
|
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.
|
|
1557
1565
|
|
|
1558
1566
|
|
|
1559
|
-
<a id="
|
|
1567
|
+
<a id="org4c34184"></a>
|
|
1560
1568
|
|
|
1561
1569
|
## Debugging Support
|
|
1562
1570
|
|
|
@@ -1589,7 +1597,7 @@ If you just want to see debug messages from `ssh2-sftp-client` and exclude debug
|
|
|
1589
1597
|
```
|
|
1590
1598
|
|
|
1591
1599
|
|
|
1592
|
-
<a id="
|
|
1600
|
+
<a id="org63b74c6"></a>
|
|
1593
1601
|
|
|
1594
1602
|
# Logging Issues
|
|
1595
1603
|
|
|
@@ -1606,7 +1614,7 @@ I am happy to try and help diagnose and fix any issues you encounter while using
|
|
|
1606
1614
|
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.
|
|
1607
1615
|
|
|
1608
1616
|
|
|
1609
|
-
<a id="
|
|
1617
|
+
<a id="org308be7d"></a>
|
|
1610
1618
|
|
|
1611
1619
|
# Pull Requests
|
|
1612
1620
|
|
|
@@ -1623,7 +1631,7 @@ This module will adopt a standard semantic versioning policy. Please indicate in
|
|
|
1623
1631
|
- **Bug Fix:** No change to functionality or features. Simple fix of an existing bug.
|
|
1624
1632
|
|
|
1625
1633
|
|
|
1626
|
-
<a id="
|
|
1634
|
+
<a id="org585b558"></a>
|
|
1627
1635
|
|
|
1628
1636
|
# Contributors
|
|
1629
1637
|
|
|
@@ -1645,3 +1653,4 @@ Thanks to the following for their contributions -
|
|
|
1645
1653
|
- **Witni Davis:** Contributed PR to fix put() RCE when using 'finish' rather than 'close' to resolve promise
|
|
1646
1654
|
- **Maik Marschner:** Contributed fix for connect() not returning sftp object. Also included test to check for this regression in future.
|
|
1647
1655
|
- **cakemasher:** Contributed fix for removeTempListeners().
|
|
1656
|
+
- **rhyswilliamsza:** Contributed RST-on-END handling fix
|
package/README.org
CHANGED
|
@@ -12,10 +12,10 @@ be found on the [[https://github.com/mscdex/ssh2][SSH2]] project pages. As the s
|
|
|
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 *v12.0.
|
|
15
|
+
Current stable release is *v12.1.0.
|
|
16
16
|
|
|
17
|
-
Code has been tested against Node versions
|
|
18
|
-
|
|
17
|
+
Code has been tested against Node versions 24.14.0. Node versions prior to v20.x are not
|
|
18
|
+
supported.
|
|
19
19
|
|
|
20
20
|
If you find this module useful and you would like to support the on-going maintenance and
|
|
21
21
|
support of users, please consider making a small [[https://square.link/u/gB2kSdkY?src=embed][donation]].
|
|
@@ -52,7 +52,14 @@ possible combination of connection options, authentication methods, proxies etc.
|
|
|
52
52
|
- Added calls to _resetEventFlags() to finally clauses to ensure event flags are reset
|
|
53
53
|
when temp listeners are removed. Without this change, global listeners would not fire
|
|
54
54
|
when they should after their has been an earlier handled error in the last API call.
|
|
55
|
-
|
|
55
|
+
** Version 12.1.0 Changes
|
|
56
|
+
|
|
57
|
+
The main change in this version is to address an issue with disconnect when accessing
|
|
58
|
+
Microsoft's SFTP server. Due to the way the Microsoft server implements closing of
|
|
59
|
+
connections, an exception is thrown even when there has been a legitimate request to end
|
|
60
|
+
the connection. The fix is to ignore this specific /error/ case. Thanks to @rhyswilliamsza
|
|
61
|
+
for the patch.
|
|
62
|
+
|
|
56
63
|
** Background
|
|
57
64
|
|
|
58
65
|
In basic terms =ssh2-sftp-client= is a simple wrapper around the =ssh2= package which provides
|
|
@@ -87,9 +94,9 @@ asynchronous code execution. This package uses the following strategies;
|
|
|
87
94
|
further API calls until a new connection is established.
|
|
88
95
|
|
|
89
96
|
- The ~SftpClient~ class constructor supports an optoinal second argument which is an
|
|
90
|
-
|
|
97
|
+
object which can have any of the three properties `error`, `end`, and `close`. The values
|
|
91
98
|
associated with these properties are callback functions that will be run if an error
|
|
92
|
-
event with
|
|
99
|
+
event with the same name as the property is raised and has not been handled by one of
|
|
93
100
|
the temporary event handlers. The error callback should have a single parameter, the
|
|
94
101
|
error raised by the event. The other callbacks have no arguments.
|
|
95
102
|
|
|
@@ -2037,5 +2044,6 @@ Thanks to the following for their contributions -
|
|
|
2037
2044
|
- Maik Marschner :: Contributed fix for connect() not returning sftp object.
|
|
2038
2045
|
Also included test to check for this regression in future.
|
|
2039
2046
|
- cakemasher :: Contributed fix for removeTempListeners().
|
|
2040
|
-
|
|
2047
|
+
- rhyswilliamsza :: Contributed RST-on-END handling fix
|
|
2048
|
+
|
|
2041
2049
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "ssh2-sftp-client",
|
|
3
|
-
"version": "12.0
|
|
3
|
+
"version": "12.1.0",
|
|
4
4
|
"description": "ssh2 sftp client for node",
|
|
5
5
|
"main": "src/index.js",
|
|
6
6
|
"repository": {
|
|
@@ -38,7 +38,7 @@
|
|
|
38
38
|
"chai-as-promised": "^7.1.2",
|
|
39
39
|
"chai-subset": "^1.6.0",
|
|
40
40
|
"checksum": "^1.0.0",
|
|
41
|
-
"dotenv": "^
|
|
41
|
+
"dotenv": "^17.3.1",
|
|
42
42
|
"eslint": "^9.6.0",
|
|
43
43
|
"eslint-config-prettier": "^9.0.0",
|
|
44
44
|
"eslint-plugin-mocha": "^10.2.0",
|
package/src/utils.js
CHANGED
|
@@ -64,6 +64,11 @@ function errorListener(client, name, reject) {
|
|
|
64
64
|
client.debugMsg(`${name} errorListener - ignoring handled error ${err.message}`);
|
|
65
65
|
return;
|
|
66
66
|
}
|
|
67
|
+
// ignore ECONNRESET if end() has been called, as we can be confident that a reset connection is definitely dead
|
|
68
|
+
if (name === 'end' && client.endCalled && err.code === 'ECONNRESET') {
|
|
69
|
+
client.debugMsg(`${name} errorListener - ignoring ${err.message} on end`);
|
|
70
|
+
return;
|
|
71
|
+
}
|
|
67
72
|
client.debugMsg(`${name} errorListener - handling error ${err.message}`);
|
|
68
73
|
client.errorHandled = true;
|
|
69
74
|
const newError = new Error(`${name}: ${err.message}`);
|