CHANGELOG.org

Change Logging

v11.0.0

• Fix append() to ensure it returns a value
• Improve consistency in handling streams. Any stream created within the module is managed by the module i.e. will be destroyed when no longer required. Streams passed in via method arguments are left for client code to manage i.e. this module will not destroy them once it is finished with them. The two exceptions to this are streams created via calls to the sftp.createReadStream() and sftp.crweateWriteStream() methods. Streams returned by calls to these methods are left to be managed by client code. This includes ensuring they are destroyed oncve finished with.
• Stripped out most calls to debugMsg() to reduce size and improve performance. As JS is not compiled, adding/removing debugging calls during debug sessions is trivial, so lets not leave them in when not necessary.
• Breaking Change. Global event listeners no longer throw errors. A new mechansm to allow client code to pass in a custom error, end or close event listener has been added in the class constructor. Note that most client code will not need to add custom handlers as the default handlers will often be sufficient. Default handlers will log the event and when necessary invalidate any existing sftp connection object, preventing further API calls until a new connection is established.

v10.0.0

• Add promise limit control for downloadDir/uploadDir
• Bumped to depend on ssh2 1.15.0
• Fix some typos in init parameter names

v9.0.4

• Fix issue with connect promise not handling corrupted private keys in a clean way. Previously, the promise would not resolve and no error would be reported.

v9.0.3

• Fix issue with end() method test for active sftp connection. Previous test was incorrect and could result in trying to call end() when there was no sftp subsystem initialised.
• Fix bug associated with closing destination stream in get() calls. When using the get() method and supplying a destination stream, if the remote file did not exist, the stream was not closed. This could cause a FD resource leak.

v9.0.2

• Change default close and end listeners so that they no longer throw/reject when an unexpected end or close event is seen. Defining expected and unexpected was not reliable and was not adding sufficient value to keep the concept.
• Update to use nullish coalescing instead of or’ing. Allows setting values to 0 without them being overridden by default value.
• Change when event handled flags are reset. Now reset them after adding new set of listeners.
• Don’t raise error/reject when calling end() method if there is no active connection.

v9.0.1

• Minor bug fix. The get() method was not always returning a buffer object when it was supposed to due to a race condition between concat-stream and the reader finish event. Instead of returning the buffer, get() was returning the concat-stream object.

v9.0.0

• New method: rcopy() to perfrom remote file copy
• API Change: The list() method now accepts a filter function instead of a regular expression.
• API Change: The ability to set autoClose to false on read/write streams in calls to get() and put() has been removed. This ability caused confusion for developers and caused significant complication which was hard to justify. If you need low level control over read and write streams, you can now use the createReadStream() and createWriteStream() methods.
• API Change: The ability to set the ‘end’ property for pipe() has been removed in get() and put() methods. This option caused problems in many use cases and was often confusing for developers. If you want low level control over pip() operations, use the createReadStream() and createWriteStream() methods and manage the pip() operation within client code.
• API Change: The 3rd argument to uploadDir() and downloadDir() has been changed from being a filter function to being an object which contains two properties, a filter function and a boolean switch to select fastGet() or fastPut() as the transfer method.
• New option: For uploadDir()/downloadDir() methods, you can now select fastGe()/fastPut() as the file transfer method. While typically faster, not all sftp servers will support fastPut/fastGet.
• New method: createReadStream() method which returns a read stream object connected to a remote file. This is a low level method and client code is responsible for managing the resources involved e.g. ensuring file handles are closed and released, removing listeners etc.
• New method: createWriteStream() method which returns a write stream to a remote file on the sftp server. This is a low level method and client code is responsible for managing all resources used by this method e.g. closing and releasing file descriptors, managing event listeners etc.
• Bump ssh2 version to version 1.11.0
• Internal re-factoring to make temporary listener management more efficient
• Internal re-factoring to exploit asynchronous processing more effectively and speed up some operations
• Re-factored retry code used when establishing connections to improve reliability and ensure it respected retry options correctly.
• Supported version change: Node versions prior to v14 are no longer supported due to use of Javascript ?. syntax which is not supported in node versions prior to v14.

v8.1.0

• Added longname property to object describing files in a list() call.
• Updated to ssh2 v1.10.0
• Modified rmdir() to only do asynchronous calls for file deletion and not for sub-directories.

v8.0.0

• Breaking Change: The uploadDir() and donwloadDir() methods now accept a predicate filter function instead of a regular expression for the 3rd argument. The function is called with 2 arguments - path to each target object (file or directory) and a boolean value which will be true if the target is a directory.
• Performance Enhancement: The rmdir() method has been refactored to enable asynchronous processing of file and directory deletion. This has significantly improved performance when deleting large directory trees, especially broad shallow trees which have lots of files and directories at the same level.
• Bumped ssh2 to latest 1.9.0 version.

v7.2.3

• Change uploadDir/downloadDir methods to use put() and get() instead of fastPut() and fastGet() because the latter are not support by all sftp servers.
• Bump ssh2 dependency to 1.8.0
• Refactor the connect method to ensure error messages returned are the main error which caused the connection to fail rather than the last error reported.

v7.2.2

• Bump to ssh2 1.6.0
• bump development dependencies to latest versions
• Fix bug in removeTempListeners() where it tried to reset the hash used to track listeners rather than just reset listeners for a specific method

v7.2.1

• Bugfix. Changed event used to resolve get() requests from being based on the ‘finish’ event emitted by the write stream instead of by the read stream UNLESS autoClose is set to false, in which case, the promise uses the finish event of the read stream. This change was necessary to deal with an edge case which can arise when using slow storage (e.g. a cloud bucket) to avoid errors when client code attempts to access the retrieved file immediately after the get() finishes. Relying on finish event in reader does not allow sufficient time for buffers to be flushed and write stream cleanup, resulting in errors.
• Bumped dev dependency versions to latest

v7.2.0

• Bump ssh2 dependency to 1.5.0
• Fix bug where ssh connection was not correctly terminated when sfrtp channel fails to be established
• Improve efficiency of mkdir() by checking for existence of target directory at beginning of function.
• Move temp listeners tracking to the scope of the client rather than being a global scope. This addresses issues which can arise when using ssh2-sftp-client for multiple concurrent sftp connections.
• Add some additional tests and refactor some existing tests to make them more reliable.
• Bump development dependencies to current version.

v7.1.0

• Bump ssh2 to version 1.5.0
• Fix possible RCE with put() method and use of ‘finish’ to resolve promise by now resolving the promise on ‘close’ events instead. This required removing support for writeStream.autoclose: false, which was not particularly useful anyway.
• Updated function documentation to specify function return value as Promise<type> rather than just Promise. This is not 100% compliant with JSDoc specs, but just stating the function returns a promise is less than useful given that all the functions in this library return promises. Indicating what the resolved data returned will be is more useful.
• Fix bug where connect() failed to return the sftp object as documented.

v7.0.4

• Bump ssh2 dependency to 1.4.0
• Change check for local resources to be consistent across platforms

v7.0.3

• Minor typo bug fix in put()

v7.0.2

• Bump ssh2 dependency to ssh2 v1.3.0
• Minor cleanup to error messages
• Update README

v7.0.1

• New version based on ssh2 version 1.2.0
• Added some additional path checks to deal with poor error messages and unreliable behaviour when connecting to an sftp server on Windows based platforms.
• Added additional tests for local resources (files/directories) to provide better error handling and informative error messages.
• Updated README to provide more info on managing exceptions
• Changed behaviour of global error handler. This error handler now just logs the error to the console and sets the client.sftp property to undefined to ensure any subsequent calls to client methods fail immediately with an error indicating there is no active connection.

V7.0.0

• New version based on new SSH2 version 1.1.0.
• Expand option handling for get() and put() methods Breaking Change
• Re-factored the retry code in the connect() method
• Improve error reporting for adding/removing listeners
• Extend localExists() method to also verify read or write access

V6.0.1

• Fix issue with connect retry not releasing ‘ready’ listeners
• Add finally clauses to all promises to ensure temporary listeners are deleted
• Add nyc module to report on code test coverage
• Add additional utils tests to increase test coverage
• Removed some dead code and unused utility functions to reduce download size
• Cleanup tests and reduce inter-test dependencies

V6.0.0.0

• Update connection retry code to use the promise-retry module instead of plain rety module
• Added optional filter argument for uploadDir/downlDir to select which files and directories are included
• Added an optional boolean argument to delete to turn off raising an error when delete target does not exists
• Reduced/simplified argument verification code to reduce package size and increase performance
• Refactored handling of events and add default close and error listeners to catch connections closed abruptly without an error being raised.

V5.3.2

• Minor README typo fixes
• Fix error in local file path checks (#294)

V5.3.1

• Fix bug in handling of relative local paths
• Change handling of stream closures in get() and put() methods

v5.3.0

• Refine event handler management
• Fix path processing for win32 based sftp servers
• Update documentation

v5.2.2

• Bug fix release. Add error code 4 check to stat() method.
• bump Mocha version for tests

v5.2.1

• Move some dependencies into dev-Dependencies

v5.2.0

• Add new method posixRename() which uses the openSSH POSIX rename extension.

v5.1.3

• Fix bug when writing to root directory and failure due to not being able to determine parent
• Refactor some tests to eliminate need to have artificial delays between tests
• Bumped some dependency versions to latest version

v5.1.2

• Added back global close handler
• Added dumpListeners() method

v5.1.1

• Added separate close handlers to each method.
• Added missing return statement in connect method
• Added additional troubleshooting documentation for common errors.

v5.1.0

• Fix bug in checkRemotePath() relating to handling of badly specified paths (issue #213)
• Added additional debugging support
• Add missing test for valid connection in end() method.
• Bump ssh2 version to v0.8.8

v5.0.2

• Fix bugs related to win32 platform and local tests for valid directories
• Fix problem with parsing of file paths

v5.0.1

• Turn down error checking to be less stringent and handle situations where user does not have read permission on parent directory.

v5.0.0

• Added two new methods uploadDir() and downloadDir()
• Removed deprecated auxList() method
• Improved error message consistency
• Added additional error checking to enable more accurate and useful error messages.
• Added default error handler to deal with event errors which fire outside of active SftpClient methods (i.e. connection unexpectedly reset by remote host).
• Modified event handlers to ensure that only event handlers added by the module are removed by the module (users now responsible for removing any custom event handlers they add).
• Module error handlers added using prependListener to ensure they are called before any additional custom handlers added by client code.
• Any error events fired during an end() call are now ignored.

v4.3.1

• Updated end() method to resolve once close event fires
• Added errorListener to error event in each promise to catch error events and reject the promise. This should resolve the issue of some error events causing uncaughtException erros and causing the process to exit.

v4.3.0

• Ensure errors include an err.code property and pass through the error code from the originating error
• Change tests for error type to use error.code instead of matching on error.message.

v4.2.4

• Bumped ssh2 to v0.8.6
• Added exists() usage example to examples directory
• Clarify documentation on get() method

v4.2.3

• Fix bug in exist() where tests on root directory returned false
• Minor documentation fixes
• Clean up mkdir example

v4.2.2

• Minor documentation fixes
• Added additional examples in the example directory

v4.2.1

• Remove default close listener. changes in ssh2 API removed the utility of a default close listener
• Fix path handling. Under mixed environments (where client platform and server platform were different i.e. one windows the other unix), path handling was broken due tot he use of path.join().
• Ensure error messages include path details. Instead of errors such as “No such file” now report “No such file /path/to/missing/file” to help with debugging

v4.2.0

• Work-around for SSH2 end event bug
• Added ability to set client name in constructor method
• Added additional error checking to prevent connect() being called on already connected client
• Added additional examples in example directory

v4.1.0

• move end() call to resolve into close hook
• Prevent put() and get() from creating empty files in destination when unable to read source
• Expand tests for operations when lacking required permissions
• Add additional data checks for append()
  • Verify file exists
  • Verify file is writeable
  • Verify file is a regular file
• Fix handling of relative paths
• Add realPath() method
• Add cwd() method

v4.0.4

• Minor documentation fix
• Fix return value from get()

v4.0.3

• Fix bug in mkdir() relating to handling of relative paths
• Modify exists() to always return ‘d’ if path is ‘.’

v4.0.2

• Fix some minor packaging issues

v4.0.0

• Remove support for node < 8.x
• Fix connection retry feature
• sftp connection object set to null when ‘end’ signal is raised
• Removed ‘connectMethod’ argument from connect method.
• Refined adding/removing of listeners in connect() and end() methods to enable errors to be adequately caught and reported.
• Deprecate auxList() and add pattern/regexp filter option to list()
• Refactored handling of event signals to provide better feedback to clients
• Removed pointless ‘permissions’ property from objects returned by stat() (same as mode property). Added additional properties describing the type of object.
• Added the removeListener() method to compliment the existing on() method.

Older Versions

v2.5.2

• Repository transferred to theophilusx
• Fix error in package.json pointing to wrong repository

v2.5.1

• Apply 4 pull requests to address minor issues prior to transfer

v2.5.0

• ???

v2.4.3

• merge #108, #110
  • fix connect promise if connection ends

v2.4.2

• merge #105
  • fix windows path

v2.4.1

• merge pr #99, #100
  • bug fix

v2.4.0

• Requires node.js v7.5.0 or above.
• merge pr #97, thanks for @theophilusx
  • Remove emitter.maxListener warnings
  • Upgraded ssh2 dependency from 0.5.5 to 0.6.1
  • Enhanced error messages to provide more context and to be more consistent
  • re-factored test
  • Added new ‘exists’ method and re-factored mkdir/rmdir

v2.3.0

• add: stat method
• add fastGet and fastPut method.
• fix: mkdir file exists decision logic

v3.0.0 – deprecate this version

• change: sftp.get will return chunk not stream anymore
• fix: get readable not emitting data events in node 10.0.0

v2.1.1

• add: event listener. doc
• add: get or put method add extra options pr#52

v2.0.1

• add: chmod method pr#33
• update: upgrade ssh2 to V0.5.0 pr#30
• fix: get method stream error reject unwork #22
• fix: return Error object on promise rejection pr#20

v1.1.0

• fix: add encoding control support for binary stream

v1.0.5:

• fix: multi image upload
• change: remove this.client.sftp to connect function