ssh-client-wrapper 2.15.0 → 2.17.0

package/README.md

@@ -60,6 +60,10 @@ Creates a new SSH client instance.
     *   `keyFile` (string, optional): The path to the private key file for key-based authentication.
     *   `passphrase` (string | Function, optional): The passphrase for the private key, or a function that returns it.
     *   `noStrictHostKeyChecking` (boolean, optional): If `true`, bypasses strict host key checking.
+    *   `maxRetry` (number, optional): Max number of retries for a retryable error. Defaults to `3`.
+    *   `retryDuration` (number, optional): Time (msec) to wait between each retry. Defaults to `1000`.
+    *   `retryableExitCodes` (number[], optional): Additional rsync exit codes to treat as retryable for `.send()`/`.recv()`. See [Retry behavior for `.send()` / `.recv()`](#retry-behavior-for-send--recv) below.
+    *   `replaceRetryableExitCodes` (boolean, optional): If `true`, `retryableExitCodes` replaces the built-in retryable exit code list instead of adding to it.
     *   And more... see `lib/index.js` for all available options.
 
 ### `.exec(cmd, [timeout], [outputCallback], [rcfile], [prependCmd])`
@@ -82,20 +86,57 @@ Executes a command and interacts with it, similar to the `expect` tool.
 
 *   Returns: `Promise<number>` - The return code of the command.
 
-### `.send(src, dst, [opt], [timeout])`
+### `.send(src, dst, [opt], [timeout], [retryableExitCodes], [replaceRetryableExitCodes])`
 Uploads files or directories to the remote host using `rsync`.
 
 *   `src` (string[]): An array of local paths to send.
 *   `dst` (string): The remote destination path.
+*   `retryableExitCodes` (number[], optional): Per-call override of retryable rsync exit codes for this call only (takes precedence over `hostInfo.retryableExitCodes`). See [Retry behavior for `.send()` / `.recv()`](#retry-behavior-for-send--recv).
+*   `replaceRetryableExitCodes` (boolean, optional): If `true`, `retryableExitCodes` replaces the built-in default instead of adding to it. Defaults to `false`.
 *   Returns: `Promise<void>`
 
-### `.recv(src, dst, [opt], [timeout])`
+### `.recv(src, dst, [opt], [timeout], [retryableExitCodes], [replaceRetryableExitCodes])`
 Downloads files or directories from the remote host using `rsync`.
 
 *   `src` (string[]): An array of remote paths to receive.
 *   `dst` (string): The local destination path.
+*   `retryableExitCodes` (number[], optional): Per-call override of retryable rsync exit codes for this call only (takes precedence over `hostInfo.retryableExitCodes`). See [Retry behavior for `.send()` / `.recv()`](#retry-behavior-for-send--recv).
+*   `replaceRetryableExitCodes` (boolean, optional): If `true`, `retryableExitCodes` replaces the built-in default instead of adding to it. Defaults to `false`.
 *   Returns: `Promise<void>`
 
+### Retry behavior for `.send()` / `.recv()`
+
+`.send()` and `.recv()` automatically retry (up to `hostInfo.maxRetry` times, default `3`, waiting `hostInfo.retryDuration` msec between attempts, default `1000`) when:
+
+*   the underlying `rsync` process exits with one of the built-in retryable exit codes: `10, 11, 12, 13, 14` (I/O and protocol errors that are commonly transient), or
+*   the SSH connection fails with a transient `kex_exchange_identification` error.
+
+If your environment sees other rsync exit codes that should also be retried (for example on a shared HPC filesystem where a "partial transfer" exit code can occur while output files are still being flushed), you can add to or replace the retryable list without changing the library's default, at two levels:
+
+*   **Per instance**, via `hostInfo.retryableExitCodes` / `hostInfo.replaceRetryableExitCodes` — applies to every `.send()`/`.recv()` call made through that `SshClientWrapper`.
+*   **Per call**, via the trailing `retryableExitCodes` / `replaceRetryableExitCodes` arguments on `.send()`/`.recv()` — applies only to that call, and fully overrides the instance-level setting if provided.
+
+By default (`replaceRetryableExitCodes: false`), `retryableExitCodes` is **added** to the built-in list — the common case, since it doesn't require knowing or repeating the built-in codes. Set `replaceRetryableExitCodes: true` to use `retryableExitCodes` verbatim instead (pass `[]` to disable exit-code-based retry entirely).
+
+```javascript
+// add exit codes 23 and 24 to the built-in retryable list, for every send/recv on this instance
+const ssh = new SshClientWrapper({
+  host: 'remote.server.com',
+  user: 'username',
+  password: 'password',
+  retryableExitCodes: [23, 24]
+});
+
+// or, just for a single call:
+await ssh.recv(['/remote/output/*'], './local-output', [], 0, [23, 24]);
+
+// full replace: only retry on 23 for this call
+await ssh.recv(['/remote/output/*'], './local-output', [], 0, [23], true);
+
+// disable exit-code-based retry entirely for this call
+await ssh.recv(['/remote/output/*'], './local-output', [], 0, [], true);
+```
+
 ### `.remoteToRemoteCopy(src, dstHostInfo, dst, [opt], [timeout])`
 Copies files or directories directly from this remote host to another remote host using `rsync` with SSH agent forwarding.
 

package/lib/index.d.ts

@@ -11,6 +11,8 @@ declare module "ssh-client-wrapper" {
     ConnectTimeout?: number;
     maxRetry?: number;
     retryDuration?: number;
+    retryableExitCodes?: number[];
+    replaceRetryableExitCodes?: boolean;
     rcfile?: string;
     prependCmd?: string;
     sshOpt?: string[];
@@ -45,13 +47,17 @@ declare module "ssh-client-wrapper" {
       src: string[],
       dst: string,
       opt?: string[],
-      timeout?: number
+      timeout?: number,
+      retryableExitCodes?: number[],
+      replaceRetryableExitCodes?: boolean
     ): Promise<void>;
     recv(
       src: string[],
       dst: string,
       opt?: string[],
-      timeout?: number
+      timeout?: number,
+      retryableExitCodes?: number[],
+      replaceRetryableExitCodes?: boolean
     ): Promise<void>;
     canConnect(timeout?: number): Promise<boolean>;
     disconnect(): Promise<void>;

package/lib/index.js

@@ -3,7 +3,7 @@ import path from "path";
 import Debug from "debug";
 import * as sshExecModule from "./sshExec.js";
 import * as rsyncExecModule from "./rsyncExec.js";
-import { isArrayOfString, sanityCheck } from "./util.js";
+import { isArrayOfString, isArrayOfInteger, sanityCheck } from "./util.js";
 
 const debug = Debug("sshClientWrapper:debug:interface");
 const debugVerbose = Debug("sshClientWrapper:verbose:interface");
@@ -30,6 +30,8 @@ const debugVerbose = Debug("sshClientWrapper:verbose:interface");
  * @param {Integer} hostInfo.ConnectTimeout - timeout used when connectiong to ths SSH server
  * @param {Integer} hostInfo.maxRetry - max number of retry
  * @param {Integer} hostInfo.retryDuration - duration time (msec) between each retry
+ * @param {number[]} hostInfo.retryableExitCodes - rsync exit codes to treat as retryable for send/recv, in addition to the built-in default (unless hostInfo.replaceRetryableExitCodes is true)
+ * @param {boolean} hostInfo.replaceRetryableExitCodes - if true, hostInfo.retryableExitCodes replaces the built-in default set of retryable rsync exit codes instead of merging with it
  * @param {string} hostInfo.rcfile - rcfile path which will be sourced before executing actual command
  * @param {string} hostInfo.prependCmd - command string which will be executed before executing actual command
  * @param {string[]} hostInfo.sshOpt - additional options for ssh
@@ -149,9 +151,11 @@ class SshClientWrapper {
    * @param {string} dst - Destination path.
    * @param {string[]} opt - option for rsync
    * @param {Integer} timeout - timeout in secconds
+   * @param {number[]} retryableExitCodes - rsync exit codes to treat as retryable for this call (overrides hostInfo.retryableExitCodes)
+   * @param {boolean} replaceRetryableExitCodes - if true, retryableExitCodes replaces the default set instead of merging with it
    * @returns {Promise} - Resolved with undefined when file transfer is done.
    */
-  async send(src, dst, opt = [], timeout = 0) {
+  async send(src, dst, opt = [], timeout = 0, retryableExitCodes = null, replaceRetryableExitCodes = false) {
     debug("send called", src, dst, opt);
 
     if (!isArrayOfString(src)) {
@@ -171,7 +175,13 @@ class SshClientWrapper {
     if (typeof opt !== "undefined" && !isArrayOfString(opt)) {
       return logAndReject("opt must be array of string");
     }
-    return this.deps.send(this.hostInfo, src, dst, opt, timeout);
+    if (retryableExitCodes !== null && !isArrayOfInteger(retryableExitCodes)) {
+      return logAndReject("retryableExitCodes must be array of integer");
+    }
+    if (typeof replaceRetryableExitCodes !== "boolean") {
+      return logAndReject("replaceRetryableExitCodes must be boolean");
+    }
+    return this.deps.send(this.hostInfo, src, dst, opt, timeout, retryableExitCodes, replaceRetryableExitCodes);
   }
 
   /**
@@ -180,9 +190,11 @@ class SshClientWrapper {
    * @param {string} dst - Destination path.
    * @param {string[]} opt - option for rsync
    * @param {Integer} timeout - timeout in secconds
+   * @param {number[]} retryableExitCodes - rsync exit codes to treat as retryable for this call (overrides hostInfo.retryableExitCodes)
+   * @param {boolean} replaceRetryableExitCodes - if true, retryableExitCodes replaces the default set instead of merging with it
    * @returns {Promise} - Resolved with undefined when file transfer is done.
    */
-  async recv(src, dst, opt = [], timeout = 0) {
+  async recv(src, dst, opt = [], timeout = 0, retryableExitCodes = null, replaceRetryableExitCodes = false) {
     debug("recv called", src, dst, opt);
 
     if (!isArrayOfString(src)) {
@@ -202,7 +214,13 @@ class SshClientWrapper {
     if (typeof opt !== "undefined" && !isArrayOfString(opt)) {
       return logAndReject("opt must be array of string");
     }
-    return this.deps.recv(this.hostInfo, src, dst, opt, timeout);
+    if (retryableExitCodes !== null && !isArrayOfInteger(retryableExitCodes)) {
+      return logAndReject("retryableExitCodes must be array of integer");
+    }
+    if (typeof replaceRetryableExitCodes !== "boolean") {
+      return logAndReject("replaceRetryableExitCodes must be boolean");
+    }
+    return this.deps.recv(this.hostInfo, src, dst, opt, timeout, retryableExitCodes, replaceRetryableExitCodes);
   }
 
   /**

package/lib/rsyncExec.js

@@ -6,7 +6,7 @@ import { glob, hasMagic } from "glob";
 import { connect, retryWrapper, sshExec } from "./sshExec.js";
 import { fork } from "./fork.js";
 
-import { sshCmd, rsyncCmd, acceptableRsyncRetrunCodes, getSshOption } from "./util.js";
+import { sshCmd, rsyncCmd, getSshOption, resolveRetryableExitCodes } from "./util.js";
 
 const debug = Debug("sshClientWrapper:debug:rsyncExec");
 const debugVerbose = Debug("sshClientWrapper:verbose:rsyncExec");
@@ -32,10 +32,12 @@ export async function checkRsyncVersion(timeout) {
  * @param {string} dst - Destination path.
  * @param {[string]} rsyncOpt - optional arguments for rsync
  * @param {Integer} timeout - timeout in secconds
+ * @param {number[]} retryableExitCodes - rsync exit codes to treat as retryable for this call (overrides hostInfo-level setting)
+ * @param {boolean} replaceRetryableExitCodes - if true, retryableExitCodes replaces the default instead of merging with it
  *
  * this function execute rsync -avv --copy-unsafe-links  src rsync://[user@]host[:port]/dst
  */
-export async function send(hostInfo, argSrc, dst, rsyncOpt, timeout) {
+export async function send(hostInfo, argSrc, dst, rsyncOpt, timeout, retryableExitCodes, replaceRetryableExitCodes) {
   await connect(hostInfo);
   const promises = await Promise.allSettled(argSrc.map((e)=>{
     return glob(e);
@@ -81,7 +83,8 @@ export async function send(hostInfo, argSrc, dst, rsyncOpt, timeout) {
   }
   debug(`send ${src} to ${hostInfo.host}:${dst}`);
   debugVerbose(`send: ${rsyncCmd} ${args.join(" ")}`);
-  return retryWrapper(fork.bind(null, hostInfo, rsyncCmd, args, timeout, null, acceptableRsyncRetrunCodes), hostInfo);
+  const exitCodes = resolveRetryableExitCodes(hostInfo, retryableExitCodes, replaceRetryableExitCodes);
+  return retryWrapper(fork.bind(null, hostInfo, rsyncCmd, args, timeout, null, exitCodes), hostInfo);
 }
 
 /**
@@ -106,10 +109,12 @@ async function isNewRsync(hostInfo) {
  * @param {string} dst - Destination path.
  * @param {[string]} rsyncOpt - optional arguments for rsync
  * @param {Integer} timeout - timeout in secconds
+ * @param {number[]} retryableExitCodes - rsync exit codes to treat as retryable for this call (overrides hostInfo-level setting)
+ * @param {boolean} replaceRetryableExitCodes - if true, retryableExitCodes replaces the default instead of merging with it
  *
  * this function execute rsync -av --copy-unsafe-links  rsync://[user@]host[:port]/src dst
  */
-export async function recv(hostInfo, argSrc, dst, rsyncOpt, timeout) {
+export async function recv(hostInfo, argSrc, dst, rsyncOpt, timeout, retryableExitCodes, replaceRetryableExitCodes) {
   await connect(hostInfo);
   const src = `${hostInfo.host}:${argSrc.join(" ")}`;
   const sshArgs = getSshOption(hostInfo, true);
@@ -125,7 +130,8 @@ export async function recv(hostInfo, argSrc, dst, rsyncOpt, timeout) {
 
   debug(`recv ${src} to ${dst}`);
   debugVerbose(`recv: ${rsyncCmd} ${args.join(" ")}`);
-  return retryWrapper(fork.bind(null, hostInfo, rsyncCmd, args, timeout, null, acceptableRsyncRetrunCodes), hostInfo);
+  const exitCodes = resolveRetryableExitCodes(hostInfo, retryableExitCodes, replaceRetryableExitCodes);
+  return retryWrapper(fork.bind(null, hostInfo, rsyncCmd, args, timeout, null, exitCodes), hostInfo);
 }
 
 /**

package/lib/util.js

@@ -42,6 +42,11 @@ const hostInfoSchema = {
     ControlPersistDir: { type: "string", pattern: "\\S+", transform: ["trim"] },
     maxRetry: { type: "number", minimum: 0, default: 3 },
     retryDuration: { type: "number", minimum: 0, default: 1000 },
+    retryableExitCodes: {
+      type: "array",
+      items: { type: "integer" }
+    },
+    replaceRetryableExitCodes: { type: "boolean" },
     rcfile: { type: "string", pattern: "\\S+", transform: ["trim"] },
     prependCmd: { type: "string", pattern: "\\S+", transform: ["trim"] },
     sshOpt: {
@@ -235,6 +240,39 @@ export const isArrayOfString = (target)=>{
   });
 };
 
+export const isArrayOfInteger = (target)=>{
+  if (!Array.isArray(target)) {
+    return false;
+  }
+  return !target.some((e)=>{
+    //target has non integer member
+    return !Number.isInteger(e);
+  });
+};
+
+/**
+ * resolve which rsync exit codes should be treated as retryable for a single send/recv call
+ * @param {object} hostInfo - hostinfo object
+ * @param {number[]} methodCodes - retryableExitCodes argument passed directly to send/recv (highest priority)
+ * @param {boolean} methodReplace - replaceRetryableExitCodes argument passed directly to send/recv
+ * @returns {number[]} - exit codes which should be treated as retryable
+ *
+ * precedence: method-level argument (if given) fully supersedes hostInfo-level settings.
+ * at whichever level is used, replace=false (default) merges with acceptableRsyncRetrunCodes,
+ * replace=true uses the given codes verbatim (so [] disables exit-code-based retry entirely).
+ */
+export const resolveRetryableExitCodes = (hostInfo, methodCodes, methodReplace)=>{
+  if (methodCodes != null) {
+    return methodReplace ? methodCodes : [...acceptableRsyncRetrunCodes, ...methodCodes];
+  }
+  if (hostInfo.retryableExitCodes != null) {
+    return hostInfo.replaceRetryableExitCodes
+      ? hostInfo.retryableExitCodes
+      : [...acceptableRsyncRetrunCodes, ...hostInfo.retryableExitCodes];
+  }
+  return acceptableRsyncRetrunCodes;
+};
+
 /**
  * log and send message to pty
  * @param {object} pty - pty object which message will be send to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ssh-client-wrapper",
-  "version": "2.15.0",
+  "version": "2.17.0",
   "description": "wrapper library for open ssh client and rsync",
   "keywords": [
     "ssh",
@@ -34,6 +34,9 @@
   "lint-staged": {
     "*.js": "eslint --fix"
   },
+  "overrides": {
+    "@semantic-release/npm": "^13.1.0"
+  },
   "dependencies": {
     "ajv": "^8.17.1",
     "ajv-keywords": "^5.1.0",
@@ -46,7 +49,7 @@
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^11.0.4",
-    "@semantic-release/npm": "^12.0.2",
+    "@semantic-release/npm": "^13.1.0",
     "@stylistic/eslint-plugin": "^5.2.3",
     "c8": "^10.1.3",
     "chai": "^5.3.1",