@open-xchange/soap-client 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.1.6] - 2026-05-26
+
+### Fixed
+
+- Aborting a non-retryable SOAP fault no longer corrupts the error message. p-retry v8 passes `onFailedAttempt` a context object (`{ error, attemptNumber, retriesLeft, ... }`) rather than the error itself; the abort path was passing that context object to `AbortError`, which stored it verbatim as `.message`. p-retry rejects with that `AbortError` as-is (it only unwraps `AbortError`s thrown by the retried function, not by the callback), so consumers received an error whose `.message` was an object and crashed with `error.message.includes is not a function` — masking the real fault. We now pass the inner `context.error`, keeping `.message` a string and letting `wrapSoapFault` recover the fault downstream. Both retry sites (WSDL fetch and per-method calls) share one `handleFailedAttempt` helper.
+
+## [0.1.5] - 2026-05-26
+
+### Fixed
+
+- Retry the WSDL fetch on transient network errors (ECONNRESET / ETIMEDOUT / etc.). The per-method `pRetry` wrapper was already handling SOAP method calls, but `SOAP.createClientAsync()` itself (which fetches the WSDL via axios under the hood) was unretried, so a single TLS hiccup during bootstrap would kill the whole test run.
+
+### Changed
+
+- Retry policy tuned to ride out a recovery window of up to ~3 minutes per call: 10 retries (11 attempts total) with exponential backoff from 1s up to 30s, capped, with jitter. Previous 3-retry / 10s-cap budget was useful for one-packet blips but ran out before a recovering service could come back. The same policy now applies to both the WSDL fetch and per-method SOAP calls (factored into a shared constant). Permanent SOAP faults (already-exists, auth failure, etc.) still abort immediately via `shouldAbortRetry`.
+
 ## [0.1.4] - 2026-05-21
 
 ### Fixed
@@ -103,7 +119,9 @@ All notable changes to this project will be documented in this file.
 
 - Initial release: extract SOAP client into its own library
 
-[unreleased]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.1.4...main
+[unreleased]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.1.6...main
+[0.1.6]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.1.5...soap-client-0.1.6
+[0.1.5]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.1.4...soap-client-0.1.5
 [0.1.4]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.1.3...soap-client-0.1.4
 [0.1.3]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.1.2...soap-client-0.1.3
 [0.1.2]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.1.1...soap-client-0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-xchange/soap-client",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "SOAP client for OX App Suite",
   "main": "index.js",
   "type": "module",
@@ -22,10 +22,10 @@
   "dependencies": {
     "commander": "^14.0.3",
     "p-retry": "^8.0.0",
-    "soap": "^1.9.1"
+    "soap": "^1.9.3"
   },
   "devDependencies": {
-    "vitest": "^4.1.5",
+    "vitest": "^4.1.7",
     "@open-xchange/lint": "0.3.0"
   },
   "scripts": {

package/soap.js

@@ -25,6 +25,21 @@ import pRetry, { AbortError as RetryAbortError } from 'p-retry'
 // Set AbortError correctly
 const AbortError = RetryAbortError
 
+// Shared retry policy for both the WSDL fetch and per-method SOAP calls.
+// Designed to ride out a service recovery window of up to ~3 minutes:
+// fast retries for the first ~30s catch transient blips cheaply, then the
+// schedule settles into 30s polling so a recovering service is picked up
+// within one poll. Note: each pRetry cycle is independent, so back-to-back
+// failures (WSDL + method) can spend up to ~6 minutes total — keep the CI
+// job timeout above that or recovery won't be observable.
+const RETRY_OPTIONS = {
+  retries: 10,        // 11 attempts total
+  factor: 2,          // exponential growth, doubling each attempt
+  minTimeout: 1000,   // first wait = 1s
+  maxTimeout: 30000,  // cap at 30s once growth exceeds it
+  randomize: true     // jitter to avoid thundering herd across parallel shards
+}
+
 for (const envFile of ['.env', '.env.defaults']) {
   try { process.loadEnvFile(envFile) } catch {}
 }
@@ -202,6 +217,31 @@ function shouldAbortRetry (error) {
   }
 }
 
+/**
+ * p-retry v8 `onFailedAttempt` handler, shared by both retry sites below.
+ *
+ * IMPORTANT: p-retry v8 invokes `onFailedAttempt` with a *context object*
+ * `{ error, attemptNumber, retriesLeft, retriesConsumed, retryDelay }` — NOT
+ * the error itself (that was the pre-v7 signature). So when we abort, we must
+ * pass `context.error` (the real Error) to `AbortError`, not `context`.
+ *
+ * Why it matters: `new AbortError(nonError)` sets `AbortError.message` to the
+ * value verbatim, and p-retry does not unwrap an AbortError thrown *by this
+ * callback* — it rejects with it as-is. Passing `context` would therefore
+ * reject with an Error whose `.message` is an object, which later blows up
+ * consumers doing `error.message.includes(...)` (appsuite-codeceptjs
+ * contexts.js) with "error.message.includes is not a function", masking the
+ * real SOAP fault. Passing `context.error` keeps `.message` a string and lets
+ * `wrapSoapFault` recover the fault downstream.
+ *
+ * @param {object} context p-retry attempt context.
+ * @param {string} label   Human-readable label for the retry log line.
+ */
+function handleFailedAttempt (context, label) {
+  if (shouldAbortRetry(context)) throw new AbortError(context.error)
+  console.log(`Retrying ${label} in ${context.retriesLeft} attempts (${describeError(context)})`)
+}
+
 /**
  * This function creates a SOAP client for the specified service type.
  * @param {string} type The name of the service type.
@@ -213,13 +253,20 @@ async function createClientAsync (type) {
   performance.mark(startMark)
   const endpoint = `${provisioningUrl}/webservices/${type}`
   const url = `${endpoint}/?wsdl`
-  const client = await SOAP.createClientAsync(url, {
+  // The WSDL fetch itself can hit transient network errors (ECONNRESET,
+  // ETIMEDOUT, ...). Without retry here, a single TLS hiccup during
+  // bootstrap kills the whole job before any per-method pRetry below has
+  // a chance to run.
+  const client = await pRetry(() => SOAP.createClientAsync(url, {
     endpoint,
     suppressStack: true,
     wsdl_options: {
       forever: true
     },
     gzip: true
+  }), {
+    ...RETRY_OPTIONS,
+    onFailedAttempt: context => handleFailedAttempt(context, `WSDL fetch (${type})`)
   })
 
   // https://stackoverflow.com/questions/30740415/namespace-for-array-field-in-node-soap-client-node-js
@@ -246,14 +293,8 @@ async function createClientAsync (type) {
 
           try {
             const result = await pRetry(() => origMethod.apply(this, [soapOptions, { timeout: 30000, ...clientOptions }, ...args]), {
-              retries: 3,
-              minTimeout: 1000,  // Start with 1 second delay between retries
-              maxTimeout: 10000, // Cap retry delay at 10 seconds
-              randomize: true,   // Add jitter to spread out concurrent retries
-              onFailedAttempt: async error => {
-                if (shouldAbortRetry(error)) throw new AbortError(error)
-                console.log(`Retrying ${String(prop)} in ${error.retriesLeft} attempts (${describeError(error)})`)
-              }
+              ...RETRY_OPTIONS,
+              onFailedAttempt: context => handleFailedAttempt(context, String(prop))
             })
 
             performance.mark(endMark)
@@ -272,4 +313,4 @@ async function createClientAsync (type) {
   })
 }
 
-export { createClientAsync, logSoapError, describeError, shouldAbortRetry, wrapSoapFault, unwrapError }
+export { createClientAsync, logSoapError, describeError, shouldAbortRetry, wrapSoapFault, unwrapError, handleFailedAttempt }

package/test/soap.test.js

@@ -7,7 +7,7 @@
 // We don't exercise that path here; set a stub so the import doesn't crash.
 process.env.PROVISIONING_URL = 'http://soap.test/'
 
-const { describeError, shouldAbortRetry, wrapSoapFault } = await import('../soap.js')
+const { describeError, shouldAbortRetry, wrapSoapFault, handleFailedAttempt } = await import('../soap.js')
 
 // Build a SOAP fault object matching the real shape (from soap@1.9.x).
 function soapFault (faultstring, detail = {}) {
@@ -224,3 +224,45 @@ describe('real-world: transient "Could not acquire claim" fault wrapped in { err
     expect(out.body).toMatch(/soap:Envelope/)
   })
 })
+
+describe('handleFailedAttempt (p-retry v8 onFailedAttempt)', () => {
+  // p-retry v8 hands the callback a context object, not the error itself.
+  function attemptContext (faultstring, { retriesLeft = 3 } = {}) {
+    const error = new Error(`soap:Server: ${faultstring}`)
+    Object.assign(error, soapFault(faultstring))
+    return { error, attemptNumber: 1, retriesLeft, retriesConsumed: 0, retryDelay: 0 }
+  }
+
+  it('aborts a blocked fault with a STRING message — the original incident', () => {
+    // Regression: this is the "Mandatory fields in context not set: [id]"
+    // fault that aborts retry. Before the fix, `new AbortError(context)`
+    // stored the context object as `.message`, so downstream
+    // `error.message.includes(...)` threw "includes is not a function".
+    let thrown
+    try {
+      handleFailedAttempt(attemptContext('Mandatory fields in context not set: [id]'), 'create')
+    } catch (e) {
+      thrown = e
+    }
+    expect(thrown).toBeInstanceOf(Error)
+    expect(typeof thrown.message).toBe('string')
+  })
+
+  it('aborts with the inner Error so wrapSoapFault can still recover the fault', () => {
+    let thrown
+    try {
+      handleFailedAttempt(attemptContext('Mandatory fields in context not set: [id]'), 'create')
+    } catch (e) {
+      thrown = e
+    }
+    const recovered = wrapSoapFault(thrown)
+    expect(recovered.message).toContain('Mandatory fields in context not set: [id]')
+    expect(recovered.faultstring).toContain('Mandatory fields in context not set: [id]')
+  })
+
+  it('does not throw for a transient (non-blocked) fault — lets p-retry continue', () => {
+    expect(() =>
+      handleFailedAttempt(attemptContext('Could not acquire claim for context 2572225'), 'create')
+    ).not.toThrow()
+  })
+})