ssh-client-wrapper 2.11.0 → 2.12.4

package/.github/workflows/coverage_report.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      - uses: actions/download-artifact@v3
+      - uses: actions/download-artifact@v4
         with:
           name: code-coverage-report
       - uses: paambaati/codeclimate-action@v5.0.0

package/.github/workflows/run_test.yml

@@ -21,7 +21,6 @@ jobs:
       TEST_USER: testuser
       TEST_PW: passw0rd
       TEST_PORT: 10022
-      DEBUG: 'ssh*'
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -35,7 +34,9 @@ jobs:
       - run: npm ci
       - run: npm run test
       - run: npm run coverage
-      - uses: actions/upload-artifact@v3
+        if: matrix.node-version == '20.x'
+      - uses: actions/upload-artifact@v4
+        if: matrix.node-version == '20.x'
         with:
           name: code-coverage-report
           path: coverage-report.lcov

package/eslint.config.mjs

@@ -0,0 +1,206 @@
+"use strict";
+import js from "@eslint/js";
+import globals from "globals";
+import stylistic from "@stylistic/eslint-plugin";
+import jsdoc from "eslint-plugin-jsdoc";
+import node from "eslint-plugin-node";
+import chaiFriendly from "eslint-plugin-chai-friendly";
+
+const jsdocRules = {
+  "jsdoc/require-jsdoc": ["warn", { enableFixer: false }],
+  "jsdoc/require-param": ["warn", { enableFixer: false }],
+  "jsdoc/require-param-description": "warn",
+  "jsdoc/require-param-name": "warn",
+  "jsdoc/require-param-type": "warn",
+  "jsdoc/require-hyphen-before-param-description": [
+    "warn",
+    "always",
+  ],
+  "jsdoc/require-returns": "warn",
+  "jsdoc/require-returns-check": "error",
+};
+
+const styleRules = {
+  "@stylistic/arrow-spacing": [
+    "error",
+    {
+      after: false,
+      before: false,
+    }],
+  "@stylistic/comma-dangle": [
+    "error",
+    "never",
+  ],
+  "@stylistic/spaced-comment": [
+    "error",
+    "never",
+  ],
+  "@stylistic/lines-around-comment": [
+    "error",
+    {
+      beforeBlockComment: true,
+      afterBlockComment: false,
+      beforeLineComment: false,
+      afterLineComment: false,
+      allowBlockStart: true,
+    },
+  ],
+  "@stylistic/lines-between-class-members": [
+    "error",
+    "always",
+    {
+      exceptAfterSingleLine: true,
+    },
+  ],
+  "@stylistic/newline-per-chained-call": [
+    "error",
+    {
+      ignoreChainWithDepth: 2,
+    },
+  ],
+  "@stylistic/padded-blocks": [
+    "error",
+    "never",
+  ],
+  "@stylistic/brace-style": [
+    "error",
+    "1tbs",
+    {
+      allowSingleLine: true,
+    },
+  ],
+  "@stylistic/padding-line-between-statements": [
+    "error",
+    {
+      blankLine: "any",
+      prev: [
+        "const",
+        "let",
+        "var",
+      ],
+      next: "*",
+    },
+    {
+      blankLine: "always",
+      prev: "*",
+      next: [
+        "class",
+        "do",
+        "for",
+        "function",
+        "switch",
+        "try",
+        "while",
+      ],
+    },
+    {
+      blankLine: "any",
+      prev: [
+        "const",
+        "let",
+        "var",
+        "for",
+        "while",
+        "do",
+        "block-like",
+        "multiline-block-like",
+      ],
+      next: [
+        "block-like",
+        "do",
+        "for",
+        "multiline-block-like",
+        "switch",
+        "try",
+        "while",
+      ],
+    },
+  ],
+};
+
+export default [
+  js.configs.recommended,
+  jsdoc.configs["flat/recommended"],
+  stylistic.configs["disable-legacy"],
+  stylistic.configs.customize({
+    indent: 2,
+    quotes: "double",
+    semi: true,
+    arrowParens: true,
+  }),
+  {
+    ignores: ["node_modules/"],
+  },
+  {
+    files: ["test/**/*.js"],
+    plugins: {
+      chaiFriendly,
+    },
+    languageOptions: {
+      globals: {
+        ...globals.nodeBuiltin,
+        ...globals.node,
+        it: "readonly",
+        describe: "readonly",
+        before: "readonly",
+        after: "readonly",
+        beforeEach: "readonly",
+        afterEach: "readonly",
+      },
+    },
+  },
+  {
+    files: ["**/*.js"],
+    plugins: {
+      node,
+      "@stylistic": stylistic,
+      jsdoc,
+    },
+    languageOptions: {
+      globals: {
+        ...globals.nodeBuiltin,
+        ...globals.node,
+      },
+      sourceType: "commonjs",
+    },
+    rules: {
+      ...styleRules,
+      ...jsdocRules,
+      "node/exports-style": [
+        "error",
+        "module.exports",
+      ],
+      "no-nested-ternary": "off",
+      "no-param-reassign": "warn",
+      "camelcase": [
+        "error",
+        {
+          properties: "never",
+        },
+      ],
+      "eqeqeq": [
+        "error",
+        "always",
+        {
+          null: "ignore",
+        },
+      ],
+      "func-style": [
+        "error",
+        "declaration",
+        {
+          allowArrowFunctions: true,
+        },
+      ],
+      "no-use-before-define": [
+        "error",
+        {
+          functions: false,
+        },
+      ],
+      "no-warning-comments": "warn",
+      "require-unicode-regexp": "off",
+
+    },
+  },
+];

package/lib/fork.js

@@ -1,7 +1,7 @@
 "use strict";
 const debug = require("debug")("sshClientWrapper:debug:fork");
 const debugVerbose = require("debug")("sshClientWrapper:verbose:fork");
-const debugSendPty = require("debug")("sshClientWrapperInsecure:fork_sendpty");
+const debugSendPty = require("debug")("sshClientWrapper:insecure:fork");
 const { spawn } = require("node-pty");
 
 const { rePwPrompt, rePhPrompt, reNewHostPrompt, reRemoteHostIdentificationHasChanged, buff2String, sendPty, watchDogTimer } = require("./util.js");
@@ -11,8 +11,8 @@ const nodePtyOpt = {
   windowsHide: true
 };
 
-function sshLoginCallback (output, ptyProcess, pw, ph, logger = debugSendPty) {
-  return new Promise((resolve, reject) => {
+function sshLoginCallback(output, ptyProcess, pw, ph, logger = debugSendPty) {
+  return new Promise((resolve, reject)=>{
     if (reRemoteHostIdentificationHasChanged.test(output)) {
       debug("REMOTE HOST IDENTIFICATION HAS CHANGED");
       const rt = /known_hosts:(\d+)/.exec(output);
@@ -38,10 +38,10 @@ function sshLoginCallback (output, ptyProcess, pw, ph, logger = debugSendPty) {
       if (typeof pw === "function") {
         debug("call password callback function");
         pw()
-          .then((v) => {
+          .then((v)=>{
             sendPty(ptyProcess, `${v}\n`, logger, 30);
           })
-          .catch((e) => {
+          .catch((e)=>{
             reject(e);
           });
         resolve();
@@ -56,10 +56,10 @@ function sshLoginCallback (output, ptyProcess, pw, ph, logger = debugSendPty) {
       if (typeof ph === "function") {
         debug("call passphrase callback function");
         ph()
-          .then((v) => {
+          .then((v)=>{
             sendPty(ptyProcess, `${v}\n`, logger, 45);
           })
-          .catch((e) => {
+          .catch((e)=>{
             reject(e);
           });
       }
@@ -70,7 +70,7 @@ function sshLoginCallback (output, ptyProcess, pw, ph, logger = debugSendPty) {
 /**
  * create pty for master ssh session and store to hostInfo.masterPty
  */
-function createMasterPty (hostInfo) {
+function createMasterPty(hostInfo) {
   debug("fork pty for master connection");
 
   if (hostInfo.masterPty) {
@@ -81,13 +81,13 @@ function createMasterPty (hostInfo) {
   hostInfo.masterPty = ptyProcess;
 }
 
-async function fork (hostInfo, cmd, args, timeout, outputCallback, retryableExitCodes = []) {
-  return new Promise((resolve, reject) => {
+async function fork(hostInfo, cmd, args, timeout, outputCallback, retryableExitCodes = [], expects = []) {
+  return new Promise((resolve, reject)=>{
     debug(`cmd=${cmd}: args=${args}`);
     const ptyProcess = spawn(cmd, args, nodePtyOpt);
     let ac = null;
     if (timeout > 0) {
-      ac = watchDogTimer(timeout, cmd, () => {
+      ac = watchDogTimer(timeout, cmd, ()=>{
         ptyProcess.kill();
         const err = new Error(`watchdog timer expired ${timeout}`);
         err.code = "TIMEEXPIRE";
@@ -97,7 +97,7 @@ async function fork (hostInfo, cmd, args, timeout, outputCallback, retryableExit
     ptyProcess.onData(buff2String.bind(null, debugVerbose));
 
     if (hostInfo !== null) {
-      ptyProcess.onData(async (data) => {
+      ptyProcess.onData((data)=>{
         const output = data.toString();
         sshLoginCallback(output, ptyProcess, hostInfo.password, hostInfo.passphrase)
           .catch(reject);
@@ -108,13 +108,25 @@ async function fork (hostInfo, cmd, args, timeout, outputCallback, retryableExit
           err.retryable = true;
           reject(err);
         }
+
+        if (Array.isArray(expects) && expects.length > 0) {
+          const { reExpect, send, numKeep } = expects.shift();
+          if (reExpect.test(output)) {
+            sendPty(ptyProcess, `${send}\n`, debugSendPty, "userDefinedHandler").catch(reject);
+            if (numKeep > 0) {
+              expects.unshift({ reExpect, send, numKeep: numKeep - 1 });
+            }
+          } else {
+            expects.unshift({ reExpect, send, numKeep });
+          }
+        }
       });
     }
 
     if (typeof outputCallback === "function") {
       ptyProcess.onData(buff2String.bind(null, outputCallback));
     }
-    ptyProcess.onExit(({ exitCode, signal }) => {
+    ptyProcess.onExit(({ exitCode, signal })=>{
       debug("onExit", exitCode, signal);
 
       if (ac !== null) {

package/lib/index.js

@@ -1,22 +1,23 @@
 "use strict";
 const fs = require("fs");
 const path = require("path");
-const debug = require("debug")("sshClientWrapper:interface");
+const debug = require("debug")("sshClientWrapper:debug:interface");
 const debugVerbose = require("debug")("sshClientWrapper:verbose:interface");
-const { sshExec, canConnect, disconnect, ls } = require("./sshExec.js");
+const { sshExec, canConnect, disconnect, expect } = require("./sshExec.js");
 const { send, recv } = require("./rsyncExec.js");
 const { isArrayOfString, sanityCheck } = require("./util.js");
 
 /**
  * Integer means integer number but it is defined as Object for now
  * workaround for eslint-plugin-jsdoc's no-undefined-types rule bug.
- * @typedef {Object} Integer
+ * @typedef {object} Integer
+ * @property
  */
 
 /**
  * host info object which contain all settings for 1 remote host
  * it will be (shallow) copied in constructor.
- * @param {Object} hostInfo - option object
+ * @param {object} hostInfo - option object
  * @param {string} hostInfo.host - destination
  * @param {string} hostInfo.user - login name
  * @param {number} hostInfo.port - port number
@@ -33,17 +34,17 @@ const { isArrayOfString, sanityCheck } = require("./util.js");
  * @param {string[]} hostInfo.sshOpt - additional options for ssh
  */
 
-const logAndReject = (message) => {
+const logAndReject = (message)=>{
   debug(message);
   return Promise.reject(new Error(message));
 };
 
 /**
  * Facade class.
- * @constructor
+ * @class
  */
 class SshClientWrapper {
-  constructor (hostInfo) {
+  constructor(hostInfo) {
     debug("constructor called for", hostInfo.host);
     debugVerbose("hostInfo=", hostInfo);
     this.hostInfo = { ...hostInfo };
@@ -73,7 +74,7 @@ class SshClientWrapper {
    *
    * note rcfile and prependCmd override hostInfo.rcfile and hostInfo.prependCmd respectively
    */
-  async exec (cmd, timeout = 0, outputCallback = null, rcfile = null, prependCmd = null) {
+  async exec(cmd, timeout = 0, outputCallback = null, rcfile = null, prependCmd = null) {
     debug("exec called", cmd);
 
     if (typeof cmd !== "string" || cmd === "") {
@@ -82,6 +83,39 @@ class SshClientWrapper {
     return sshExec(this.hostInfo, cmd, timeout, outputCallback, rcfile, prependCmd);
   }
 
+  /**
+   * execute command on remote host and get output text
+   * @param {string} cmd - Cmdline which will be executed.
+   * @param {Integer} timeout - timeout in secconds
+   * @param {string} rcfile - rcfile path which will be sourced before executing actual command
+   * @param {string} prependCmd - command string which will be executed before executing actual command
+   * @returns {object} - output test array (output) and return value of cmd (rt)
+   */
+  async execAndGetOutput(cmd, timeout = 0, rcfile = null, prependCmd = null) {
+    debug("execAndGetOutput called", cmd);
+    const outputArray = [];
+    const cb = (data)=>{
+      outputArray.push(data);
+    };
+    let rt = null;
+    try {
+      rt = await sshExec(this.hostInfo, cmd, timeout, cb, rcfile, prependCmd);
+    } catch (e) {
+    //non-zero retrun should be allowed
+      if (typeof e.rt === "undefined" || e.rt < 0) {
+        throw e;
+      }
+    }
+    const output = outputArray.length === 0
+      ? []
+      : outputArray
+          .join("\n")
+          .replace(/\n+/g, "\n")
+          .replace(/\n$/, "")
+          .split("\n");
+    return { output, rt };
+  }
+
   /**
    * execute ls command and return output
    * @param {string} target - file or directory path to watch
@@ -89,9 +123,22 @@ class SshClientWrapper {
    * @param {Integer} timeout - timeout in secconds
    * @returns {string[]} - output from ls
    */
-  async ls (target, lsOpt = [], timeout = 0) {
+  async ls(target, lsOpt = [], timeout = 0) {
     debug("ls called", target, lsOpt);
-    return ls(this.hostInfo, target, lsOpt, timeout);
+    const { output, rt } = await this.execAndGetOutput(`ls ${lsOpt.join(" ")} ${target}`, timeout);
+    return rt === 0 ? output : rt;
+  }
+
+  /**
+   * execute series of comands like expect(3)
+   * @param {string} cmd - Cmdline which will be executed.
+   * @param {Array} expects - array of expect and send string pairs
+   * @param {Integer} timeout - timeout in secconds
+   * @returns {Integer} - Return code of cmd.
+   */
+  async expect(cmd, expects, timeout = 180) {
+    debug("expect called", expects);
+    return expect(this.hostInfo, cmd, expects, timeout);
   }
 
   /**
@@ -102,13 +149,13 @@ class SshClientWrapper {
    * @param {Integer} timeout - timeout in secconds
    * @returns {Promise} - Resolved with undefined when file transfer is done.
    */
-  async send (src, dst, opt = [], timeout = 0) {
+  async send(src, dst, opt = [], timeout = 0) {
     debug("send called", src, dst, opt);
 
     if (!isArrayOfString(src)) {
       return logAndReject("src must be array of string");
     }
-    if (!src.some((e) => {
+    if (!src.some((e)=>{
       return e !== "";
     })) {
       return logAndReject("src must contain non-empty string");
@@ -133,13 +180,13 @@ class SshClientWrapper {
    * @param {Integer} timeout - timeout in secconds
    * @returns {Promise} - Resolved with undefined when file transfer is done.
    */
-  async recv (src, dst, opt = [], timeout = 0) {
+  async recv(src, dst, opt = [], timeout = 0) {
     debug("recv called", src, dst, opt);
 
     if (!isArrayOfString(src)) {
       return logAndReject("src must be array of string");
     }
-    if (!src.some((e) => {
+    if (!src.some((e)=>{
       return e !== "";
     })) {
       return logAndReject("src must contain non-empty string");
@@ -161,7 +208,7 @@ class SshClientWrapper {
    * @param {Integer} timeout - timeout in secconds
    * @returns {Promise} - Resolved with true on success, otherwise rejected with Error.
    */
-  async canConnect (timeout = 60) {
+  async canConnect(timeout = 60) {
     debug("canConnect called with timeout=", timeout);
     debugVerbose("hostInfo=", this.hostInfo);
 
@@ -174,7 +221,7 @@ class SshClientWrapper {
   /**
    * Disconnect master session
    */
-  async disconnect () {
+  async disconnect() {
     debug(`disconnect from ${this.hostInfo.host} called`);
     disconnect(this.hostInfo);
   }

package/lib/rsyncExec.js

@@ -10,9 +10,9 @@ const { fork } = require("./fork.js");
 
 const { sshCmd, rsyncCmd, acceptableRsyncRetrunCodes, getSshOption } = require("./util.js");
 
-async function checkRsyncVersion (timeout) {
+async function checkRsyncVersion(timeout) {
   const rt = {};
-  await fork(null, rsyncCmd, ["--version"], timeout, (output) => {
+  await fork(null, rsyncCmd, ["--version"], timeout, (output)=>{
     const result = /^rsync *version *(\d+)\.(\d+)\.(\d+).*$/m.exec(output);
 
     if (result) {
@@ -26,7 +26,7 @@ async function checkRsyncVersion (timeout) {
 
 /**
  * Send file or directory and its child to server.
- * @param {Object} hostInfo - hostinfo object
+ * @param {object} hostInfo - hostinfo object
  * @param {[string]} argSrc - File or directory name which to be send.
  * @param {string} dst - Destination path.
  * @param {[string]} rsyncOpt - optional arguments for rsync
@@ -34,13 +34,13 @@ async function checkRsyncVersion (timeout) {
  *
  * this function execute rsync -avv --copy-unsafe-links  src rsync://[user@]host[:port]/dst
  */
-async function send (hostInfo, argSrc, dst, rsyncOpt, timeout) {
+async function send(hostInfo, argSrc, dst, rsyncOpt, timeout) {
   await connect(hostInfo);
-  const promises = await Promise.allSettled(argSrc.map((e) => {
+  const promises = await Promise.allSettled(argSrc.map((e)=>{
     return glob(e);
   }));
   const src = promises
-    .map((e, i) => {
+    .map((e, i)=>{
       if (e.status !== "fulfilled") {
         return null;
       }
@@ -49,10 +49,10 @@ async function send (hostInfo, argSrc, dst, rsyncOpt, timeout) {
       }
       return e.value;
     })
-    .filter((e) => {
+    .filter((e)=>{
       return e !== null;
     })
-    .flatMap((e) => {
+    .flatMap((e)=>{
       return e;
     });
 
@@ -85,14 +85,14 @@ async function send (hostInfo, argSrc, dst, rsyncOpt, timeout) {
 
 /**
  * format src array to src string for recv
- * @param {Object} hostInfo - hostinfo object
+ * @param {object} hostInfo - hostinfo object
  * @returns {boolean} - rsync command version is higher than 3.2.4 or not
  */
-async function isNewRsync (hostInfo) {
-  if (!hostInfo.rsyncVersion ||
-    !Number.isInteger(hostInfo.rsyncVersion.major) ||
-    !Number.isInteger(hostInfo.rsyncVersion.minor) ||
-    !Number.isInteger(hostInfo.rsyncVersion.patch)) {
+async function isNewRsync(hostInfo) {
+  if (!hostInfo.rsyncVersion
+    || !Number.isInteger(hostInfo.rsyncVersion.major)
+    || !Number.isInteger(hostInfo.rsyncVersion.minor)
+    || !Number.isInteger(hostInfo.rsyncVersion.patch)) {
     hostInfo.rsyncVersion = await checkRsyncVersion(3);
   }
   return hostInfo.rsyncVersion.major >= 3 && hostInfo.rsyncVersion.minor >= 2 && hostInfo.rsyncVersion.patch >= 4;
@@ -100,7 +100,7 @@ async function isNewRsync (hostInfo) {
 
 /**
  * Send file or directory and its child to server.
- * @param {Object} hostInfo - hostinfo object
+ * @param {object} hostInfo - hostinfo object
  * @param {[string]} argSrc - File or directory name which to be send.
  * @param {string} dst - Destination path.
  * @param {[string]} rsyncOpt - optional arguments for rsync
@@ -108,7 +108,7 @@ async function isNewRsync (hostInfo) {
  *
  * this function execute rsync -av --copy-unsafe-links  rsync://[user@]host[:port]/src dst
  */
-async function recv (hostInfo, argSrc, dst, rsyncOpt, timeout) {
+async function recv(hostInfo, argSrc, dst, rsyncOpt, timeout) {
   await connect(hostInfo);
   const src = `${hostInfo.host}:${argSrc.join(" ")}`;
   const sshArgs = getSshOption(hostInfo, true);
@@ -118,7 +118,7 @@ async function recv (hostInfo, argSrc, dst, rsyncOpt, timeout) {
     args.unshift("--old-args");
   }
 
-  // make destination directory
+  //make destination directory
   const dstDir = argSrc.len > 1 || hasMagic(argSrc[0]) ? dst : path.dirname(dst);
   await fs.mkdir(dstDir, { recursive: true });