ssh2-sftp-client 7.0.0 → 7.0.4

package/src/utils.js

@@ -1,6 +1,8 @@
 'use strict';
 
 const fs = require('fs');
+const path = require('path');
+
 const { errorCode } = require('./constants');
 
 /**
@@ -67,15 +69,19 @@ let tempListeners = [];
  */
 function errorListener(client, name, reject) {
   let fn = (err) => {
-    if (!client.errorHandled) {
+    if (client.endCalled || client.errorHandled) {
+      client.debugMsg(`${name}: Ignoring handled error: ${err.message}`);
+    } else {
+      client.debugMsg(`${name}: Handling error: ${err.message}`);
       client.errorHandled = true;
       if (reject) {
+        client.debugMsg(`${name}: handled error with reject`);
         reject(fmtError(err, name, err.code));
       } else {
+        client.debugMsg(`${name}: handling error with throw`);
         throw fmtError(err, name, err.code);
       }
     }
-    client.debugMsg(`Handled Error: ${err.message} ${err.code}`);
   };
   tempListeners.push(['error', fn]);
   return fn;
@@ -83,12 +89,17 @@ function errorListener(client, name, reject) {
 
 function endListener(client, name, reject) {
   let fn = function () {
-    client.debugMsg(`Handled end event for ${name}`);
-    if (!client.endCalled) {
+    if (client.endCalled || client.endHandled) {
+      client.debugMsg(`${name}: Ignoring expected end event`);
+    } else {
+      client.debugMsg(`${name}: Handling end event`);
       client.sftp = undefined;
+      client.endHandled = true;
       if (reject) {
+        client.debugMsg(`${name}: handling end event with reject'`);
         reject(fmtError('Unexpected end event raised', name));
       } else {
+        client.debugMsg(`${name}: handling end event with throw`);
         throw fmtError('Unexpected end event raised', name);
       }
     }
@@ -99,12 +110,17 @@ function endListener(client, name, reject) {
 
 function closeListener(client, name, reject) {
   let fn = function () {
-    client.debugMsg(`handled close event for ${name}`);
-    if (!client.endCalled) {
+    if (client.endCalled || client.closeHandled) {
+      client.debugMsg(`${name}: ignoring expected close event`);
+    } else {
+      client.debugMsg(`${name}: handling unexpected close event`);
       client.sftp = undefined;
+      client.closeHandled = true;
       if (reject) {
+        client.debugMsg(`${name}: handling close event with reject`);
         reject(fmtError('Unexpected close event raised', name));
       } else {
+        client.debugMsg(`${name}: handling close event with throw`);
         throw fmtError('Unexpected close event raised', name);
       }
     }
@@ -114,73 +130,165 @@ function closeListener(client, name, reject) {
 }
 
 function addTempListeners(obj, name, reject) {
-  obj.debugMsg(`${name}: Adding end listener`);
+  obj.debugMsg(`${name}: Adding temp event listeners`);
   obj.client.prependListener('end', endListener(obj, name, reject));
-  obj.debugMsg(`${name}: Adding close listener`);
   obj.client.prependListener('close', closeListener(obj, name, reject));
-  obj.debugMsg(`${name}: Adding error listener`);
   obj.client.prependListener('error', errorListener(obj, name, reject));
 }
 
-function removeTempListeners(obj) {
+function removeTempListeners(obj, name) {
+  obj.debugMsg(`${name}: Removing temp event listeners`);
   tempListeners.forEach(([e, fn]) => {
-    obj.debugMsg(`${obj.clientName}: Removing ${e} listener`);
     obj.client.removeListener(e, fn);
   });
   tempListeners = [];
 }
 
 /**
- * @async
+ * Checks to verify local object exists. Returns a character string representing the type
+ * type of local object if it exists, false if it doesn't.
  *
- * Tests to see if a path identifies an existing item. Returns either
- * 'd' = directory, 'l' = sym link or '-' regular file if item exists. Returns
- * false if it does not
+ * Return codes: l = symbolic link
+ *               - = regular file
+ *               d = directory
+ *               s = socket
  *
- * @param {String} localPath
- * @returns {Boolean | String}
+ * @param {string} filePath - path to local object
+ * @returns {string | boolean} returns a string for object type if it exists, false otherwise
  */
-function localExists(filePath, writeable = false) {
-  return new Promise((resolve, reject) => {
-    const fileModes = writeable
-      ? fs.constants.F_OK | fs.constants.W_OK
-      : fs.constants.F_OK | fs.constants.R_OK;
-    fs.access(filePath, fileModes, (err) => {
-      if (err) {
-        if (err.code === 'ENOENT') {
-          resolve(false);
-        } else {
-          reject(err);
-        }
-      } else {
-        fs.stat(filePath, (err2, stats) => {
-          if (err2) {
-            reject(err);
-          } else {
-            if (stats.isDirectory()) {
-              resolve('d');
-            } else if (stats.isSymbolicLink()) {
-              resolve('l');
-            } else if (stats.isFile()) {
-              resolve('-');
-            } else {
-              resolve(false);
-            }
-          }
-        });
-      }
-    });
-  });
+function localExists(filePath) {
+  const stats = fs.statSync(filePath, { throwIfNoEntry: false });
+  if (!stats) {
+    return false;
+  } else if (stats.isDirectory()) {
+    return 'd';
+  } else if (stats.isFile()) {
+    return '-';
+  } else {
+    throw fmtError(
+      `Bad path: ${filePath}: target must be a file or directory`,
+      'localExists',
+      errorCode.badPath
+    );
+  }
+}
+
+/**
+ * Verify access to local object. Returns an object with properties for status, type,
+ * details and code.
+ *
+ * return object {
+ *                 status: true if exists and can be accessed, false otherwise
+ *                 type: type of object '-' = file, 'd' = dir, 'l' = link, 's' = socket
+ *                 details: 'access ok' if object can be accessed, 'not found' if
+ *                          object does not exist, 'permission denied' if access denied
+ *                 code: error code if object does not exist or permission denied
+ *              }
+ *
+ * @param {string} filePath = path to local object
+ * @param {string} mode = access mode - either 'r' or 'w'. Defaults to 'r'
+ * @returns {Object} with properties status, type, details and code
+ */
+function haveLocalAccess(filePath, mode = 'r') {
+  const accessMode =
+    fs.constants.F_OK | (mode === 'w') ? fs.constants.W_OK : fs.constants.R_OK;
+
+  try {
+    fs.accessSync(filePath, accessMode);
+    const type = localExists(filePath);
+    return {
+      status: true,
+      type: type,
+      details: 'access OK',
+      code: 0,
+    };
+  } catch (err) {
+    switch (err.errno) {
+      case -2:
+        return {
+          status: false,
+          type: null,
+          details: 'not exist',
+          code: -2,
+        };
+      case -13:
+        return {
+          status: false,
+          type: localExists(filePath),
+          details: 'permission denied',
+          code: -13,
+        };
+      case -20:
+        return {
+          status: false,
+          type: null,
+          details: 'parent not a directory',
+        };
+      default:
+        return {
+          status: false,
+          type: null,
+          details: err.message,
+        };
+    }
+  }
+}
+
+/**
+ * Checks to verify the object specified by filePath can either be written to or created
+ * if it doens't already exist. If it does not exist, checks to see if the parent entry in the
+ * path is a directory and can be written to. Returns an object with the same format as the object
+ * returned by 'haveLocalAccess'.
+ *
+ * @param {string} filePath - path to object to be created or written t
+ * @returns {Object} Object with properties status, type, destils and code
+ */
+function haveLocalCreate(filePath) {
+  const { status, details, type } = haveLocalAccess(filePath, 'w');
+  if (!status && details === 'permission denied') {
+    //throw new Error(`Bad path: ${filePath}: permission denied`);
+    return {
+      status,
+      details,
+      type,
+    };
+  } else if (!status) {
+    const dirPath = path.dirname(filePath);
+    const localCheck = haveLocalAccess(dirPath, 'w');
+    if (localCheck.status && localCheck.type !== 'd') {
+      //throw new Error(`Bad path: ${dirPath}: not a directory`);
+      return {
+        status: false,
+        details: `${dirPath}: not a directory`,
+        type: null,
+      };
+    } else if (!localCheck.status) {
+      //throw new Error(`Bad path: ${dirPath}: ${localCheck.details}`);
+      return {
+        status: localCheck.status,
+        details: `${dirPath}: ${localCheck.details}`,
+        type: null,
+      };
+    } else {
+      return {
+        status: true,
+        details: 'access OK',
+        type: null,
+        code: 0,
+      };
+    }
+  }
+  return { status, details, type };
 }
 
 async function normalizeRemotePath(client, aPath) {
   try {
     if (aPath.startsWith('..')) {
       let root = await client.realPath('..');
-      return root + client.remotePathSep + aPath.substring(3);
+      return root + client.remotePathSep + aPath.slice(3);
     } else if (aPath.startsWith('.')) {
       let root = await client.realPath('.');
-      return root + client.remotePathSep + aPath.substring(2);
+      return root + client.remotePathSep + aPath.slice(2);
     }
     return aPath;
   } catch (err) {
@@ -234,8 +342,10 @@ module.exports = {
   closeListener,
   addTempListeners,
   removeTempListeners,
-  localExists,
+  haveLocalAccess,
+  haveLocalCreate,
   normalizeRemotePath,
+  localExists,
   haveConnection,
   sleep,
 };

package/CHANGELOG.org

@@ -1,232 +0,0 @@
-* Change Logging
-
-** 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. [[https://github.com/jyu213/ssh2-sftp-client#Event][doc]]
-    - add: ~get~ or ~put~ method add extra options [[https://github.com/jyu213/ssh2-sftp-client/pull/52][pr#52]]
-
-*** v2.0.1
-    - add: ~chmod~ method [[https://github.com/jyu213/ssh2-sftp-client/pull/33][pr#33]]
-    - update: upgrade ssh2 to V0.5.0 [[https://github.com/jyu213/ssh2-sftp-client/pull/30][pr#30]]
-    - fix: get method stream error reject unwork [[https://github.com/jyu213/ssh2-sftp-client/issues/22][#22]]
-    - fix: return Error object on promise rejection [[https://github.com/jyu213/ssh2-sftp-client/pull/20][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