@open-xchange/soap-client 0.1.6 → 0.2.0

package/services/secondaryAccount.js

@@ -1,52 +1,67 @@
-import { createClientAsync } from '../soap.js'
-
-let OXSecondaryAccountService
-function getClient () {
-  if (!OXSecondaryAccountService) OXSecondaryAccountService = createClientAsync('OXSecondaryAccountService')
-  return OXSecondaryAccountService
-}
+import { createClientAsync, memoizeClient } from '../soap.js'
 
 /**
- * Creates a secondary account using the OX Secondary Account Service
- * @async
- * @param {Object} accountData - The data for the secondary account to be created
- * @param {Object} context - The context object where the account will be created
- * @param {Array<Object>} users - Array of users to associate with the secondary account
- * @param {Array<Object>} groups - Array of groups to associate with the secondary account
- * @returns {Promise<Object>} The created secondary account object
- * @throws {Error} If the account creation fails
+ * Build a secondary-account service bound to a SOAP client constructor.
+ * @param {(type: string) => Promise<Object>} createClient
+ * @returns {Object} The secondary account service.
  */
-export async function create (accountData, context, users = [], groups = []) {
-  return (await getClient()).createAsync({
-    accountDataOnCreate: accountData,
-    context: { id: context.id },
-    users: users || [],
-    auth: context.admin
-  })
-}
+export function createSecondaryAccountService (createClient) {
+  const getClient = memoizeClient(createClient, 'OXSecondaryAccountService')
 
-export async function list (context) {
-  return (await getClient()).listAsync({
-    context: { id: context.id },
-    auth: context.admin
-  })
-}
-export async function remove (primaryAddress, context, users, groups) {
-  return (await getClient()).deleteAsync({
-    primaryAddress,
-    context: { id: context.id },
-    users,
-    auth: context.admin
-  })
-}
+  /**
+   * Creates a secondary account using the OX Secondary Account Service
+   * @async
+   * @param {Object} accountData - The data for the secondary account to be created
+   * @param {Object} context - The context object where the account will be created
+   * @param {Array<Object>} users - Array of users to associate with the secondary account
+   * @param {Array<Object>} groups - Array of groups to associate with the secondary account
+   * @returns {Promise<Object>} The created secondary account object
+   * @throws {Error} If the account creation fails
+   */
+  async function create (accountData, context, users = [], groups = []) {
+    return (await getClient()).createAsync({
+      accountDataOnCreate: accountData,
+      context: { id: context.id },
+      users: users || [],
+      auth: context.admin
+    })
+  }
 
-export async function update (primaryAddress, accountData, context, users, groups) {
-  return (await getClient()).updateAsync({
-    primaryAddress,
-    accountDataUpdate: accountData,
-    context: { id: context.id },
-    users,
-    groups,
-    auth: context.admin
-  })
+  async function list (context) {
+    return (await getClient()).listAsync({
+      context: { id: context.id },
+      auth: context.admin
+    })
+  }
+
+  async function remove (primaryAddress, context, users, groups) {
+    return (await getClient()).deleteAsync({
+      primaryAddress,
+      context: { id: context.id },
+      users,
+      auth: context.admin
+    })
+  }
+
+  async function update (primaryAddress, accountData, context, users, groups) {
+    return (await getClient()).updateAsync({
+      primaryAddress,
+      accountDataUpdate: accountData,
+      context: { id: context.id },
+      users,
+      groups,
+      auth: context.admin
+    })
+  }
+
+  return { create, list, remove, update }
 }
+
+// Classic module exports, bound to the env-configured default endpoint.
+let defaultService
+const service = () => (defaultService ??= createSecondaryAccountService(createClientAsync))
+
+export const create = (...args) => service().create(...args)
+export const list = (...args) => service().list(...args)
+export const remove = (...args) => service().remove(...args)
+export const update = (...args) => service().update(...args)

package/services/sharedAccount.js

@@ -18,116 +18,132 @@
  * Any use of the work other than as authorized under this license or copyright law is prohibited.
  */
 
-import { createClientAsync } from '../soap.js'
-
-let OXSharedAccountService
-function getClient () {
-  if (!OXSharedAccountService) OXSharedAccountService = createClientAsync('OXSharedAccountService')
-  return OXSharedAccountService
-}
+import { createClientAsync, memoizeClient } from '../soap.js'
 
 /**
- * Creates a shared account using the OX Shared Account Service
- *
- * @param {Object} context - The context object where the account will be created
- * @param {Object} sharedAccountData - The data for the shared account to be created
- * @returns {Promise<Object>} The created shared account object
- * @throws {Error} If the shared account creation fails
+ * Build a shared-account service bound to a SOAP client constructor.
+ * @param {(type: string) => Promise<Object>} createClient
+ * @returns {Object} The shared account service.
  */
-export async function create (context, sharedAccountData) {
-  return (await getClient()).createAsync({
-    ctx: { id: context.id },
-    sharedAccountData,  // display_name, given_name, imapServer, language, mailenabled, name, sur_name, primaryEmail, email1, smtpServer, timezone, password
-    auth: context.admin
-  })
-}
+export function createSharedAccountService (createClient) {
+  const getClient = memoizeClient(createClient, 'OXSharedAccountService')
 
-/**
- * Converts an existing user to a shared account using the OX Shared Account Service
- *
- * @param {Object} context - The context of the user to be converted
- * @param {number} userId - ID of the user to be converted
- * @param {string} password - The password for the new shared account
- * @returns {Promise<void>}
- * @throws {Error} If the conversion fails
- */
-export async function convertUserToSharedAccount (context, userId, password) {
-  return (await getClient()).convertUserToSharedAccountAsync({
-    ctx: { id: context.id },
-    user: { id: userId },
-    password,
-    auth: context.admin
-  })
-}
+  /**
+   * Creates a shared account using the OX Shared Account Service
+   *
+   * @param {Object} context - The context object where the account will be created
+   * @param {Object} sharedAccountData - The data for the shared account to be created
+   * @returns {Promise<Object>} The created shared account object
+   * @throws {Error} If the shared account creation fails
+   */
+  async function create (context, sharedAccountData) {
+    return (await getClient()).createAsync({
+      ctx: { id: context.id },
+      sharedAccountData, // display_name, given_name, imapServer, language, mailenabled, name, sur_name, primaryEmail, email1, smtpServer, timezone, password
+      auth: context.admin
+    })
+  }
 
-/**
- * Add users and groups with specified permissions and capabilities to an existing shared account using the OX Shared Account Service.
- *
- * @param {Object} context - The context of the users and groups
- * @param {Object} sharedAccountContext - The context of the shared account
- * @param {number} sharedAccountId - ID of the shared account
- * @param {Object} permissions - The users, groups, capabilities, and module-specific permissions.
- * @returns {Promise<Object>} The shared account object
- * @throws {Error} If the creation of the shared account permissions fails
- */
-export async function createSharedAccountPermissions (context, sharedAccountContext, sharedAccountId, permissions) {
-  return (await getClient()).createSharedAccountPermissionsAsync({
-    ctx: { id: context.id },
-    sharedAccountCtx: { id: sharedAccountContext.id },
-    sharedAccount: { id: sharedAccountId },
-    groups: permissions.groups ?? [],
-    users: permissions.users?.map(user => ({ id: user.userdata.id })) ?? [],
-    capabilities: {
-      grantedCapability: permissions.capabilities?.grantedCapability ?? [],
-      deniedCapability: permissions.capabilities?.deniedCapability ?? [],
-    },
-    mailConfig: permissions.mailConfig,
-    calendarConfig: permissions.calendarConfig,
-    auth: context.admin
-  })
-}
+  /**
+   * Converts an existing user to a shared account using the OX Shared Account Service
+   *
+   * @param {Object} context - The context of the user to be converted
+   * @param {number} userId - ID of the user to be converted
+   * @param {string} password - The password for the new shared account
+   * @returns {Promise<void>}
+   * @throws {Error} If the conversion fails
+   */
+  async function convertUserToSharedAccount (context, userId, password) {
+    return (await getClient()).convertUserToSharedAccountAsync({
+      ctx: { id: context.id },
+      user: { id: userId },
+      password,
+      auth: context.admin
+    })
+  }
 
-/**
- * List all shared accounts in the specified context
- *
- * @param {Object} context - The context object whose shared account will be listed
- * @param {*} pattern - An optional search pattern for the contexts
- * @returns {Promise<Object[]>} The list of shared account objects
- */
-export async function list (context, pattern = '*') {
-  return (await getClient()).listAsync({
-    ctx: { id: context.id },
-    search_pattern: pattern,
-    auth: context.admin
-  })
-}
+  /**
+   * Add users and groups with specified permissions and capabilities to an existing shared account using the OX Shared Account Service.
+   *
+   * @param {Object} context - The context of the users and groups
+   * @param {Object} sharedAccountContext - The context of the shared account
+   * @param {number} sharedAccountId - ID of the shared account
+   * @param {Object} permissions - The users, groups, capabilities, and module-specific permissions.
+   * @returns {Promise<Object>} The shared account object
+   * @throws {Error} If the creation of the shared account permissions fails
+   */
+  async function createSharedAccountPermissions (context, sharedAccountContext, sharedAccountId, permissions) {
+    return (await getClient()).createSharedAccountPermissionsAsync({
+      ctx: { id: context.id },
+      sharedAccountCtx: { id: sharedAccountContext.id },
+      sharedAccount: { id: sharedAccountId },
+      groups: permissions.groups ?? [],
+      users: permissions.users?.map(user => ({ id: user.userdata.id })) ?? [],
+      capabilities: {
+        grantedCapability: permissions.capabilities?.grantedCapability ?? [],
+        deniedCapability: permissions.capabilities?.deniedCapability ?? [],
+      },
+      mailConfig: permissions.mailConfig,
+      calendarConfig: permissions.calendarConfig,
+      auth: context.admin
+    })
+  }
 
-/**
- * Get all data of a specified shared account in the specified context
- *
- * @param {*} context - The context where the shared account exists
- * @param {number} sharedAccountId - ID of the requested shared account
- * @returns {Promise<Object>} The shared account object
- */
-export async function getData (context, sharedAccountId) {
-  return (await getClient()).getDataAsync({
-    ctx: { id: context.id },
-    sharedAccount: { id: sharedAccountId },
-    auth: context.admin
-  })
-}
+  /**
+   * List all shared accounts in the specified context
+   *
+   * @param {Object} context - The context object whose shared account will be listed
+   * @param {*} pattern - An optional search pattern for the contexts
+   * @returns {Promise<Object[]>} The list of shared account objects
+   */
+  async function list (context, pattern = '*') {
+    return (await getClient()).listAsync({
+      ctx: { id: context.id },
+      search_pattern: pattern,
+      auth: context.admin
+    })
+  }
 
-/**
- * Remove a specified shared account in the specified context
- *
- * @param {*} context - The context object where the account will be removed
- * @param {number} sharedAccountId - ID of the shared account to be removed
- * @returns {Promise<void>}
- */
-export async function remove (context, sharedAccountId) {
-  return (await getClient()).deleteAsync({
-    ctx: { id: context.id },
-    sharedAccount: { id: sharedAccountId },
-    auth: context.admin
-  })
+  /**
+   * Get all data of a specified shared account in the specified context
+   *
+   * @param {*} context - The context where the shared account exists
+   * @param {number} sharedAccountId - ID of the requested shared account
+   * @returns {Promise<Object>} The shared account object
+   */
+  async function getData (context, sharedAccountId) {
+    return (await getClient()).getDataAsync({
+      ctx: { id: context.id },
+      sharedAccount: { id: sharedAccountId },
+      auth: context.admin
+    })
+  }
+
+  /**
+   * Remove a specified shared account in the specified context
+   *
+   * @param {*} context - The context object where the account will be removed
+   * @param {number} sharedAccountId - ID of the shared account to be removed
+   * @returns {Promise<void>}
+   */
+  async function remove (context, sharedAccountId) {
+    return (await getClient()).deleteAsync({
+      ctx: { id: context.id },
+      sharedAccount: { id: sharedAccountId },
+      auth: context.admin
+    })
+  }
+
+  return { create, convertUserToSharedAccount, createSharedAccountPermissions, list, getData, remove }
 }
+
+// Classic module exports, bound to the env-configured default endpoint.
+let defaultService
+const service = () => (defaultService ??= createSharedAccountService(createClientAsync))
+
+export const create = (...args) => service().create(...args)
+export const convertUserToSharedAccount = (...args) => service().convertUserToSharedAccount(...args)
+export const createSharedAccountPermissions = (...args) => service().createSharedAccountPermissions(...args)
+export const list = (...args) => service().list(...args)
+export const getData = (...args) => service().getData(...args)
+export const remove = (...args) => service().remove(...args)

package/soap.js

@@ -40,12 +40,9 @@ const RETRY_OPTIONS = {
   randomize: true     // jitter to avoid thundering herd across parallel shards
 }
 
-for (const envFile of ['.env', '.env.defaults']) {
-  try { process.loadEnvFile(envFile) } catch {}
-}
-
-// This flag enables debug output including timing information.
-const debug = process.env.DEBUG_SOAP === 'true'
+// This flag enables debug output including timing information. Read lazily so
+// importing the module has no environment-dependent behavior.
+const debug = () => process.env.DEBUG_SOAP === 'true'
 
 /**
  * Walk one layer of common error-wrapper shapes:
@@ -91,44 +88,44 @@ function describeError (err) {
     'unknown'
 }
 
-// Handle specifically timeout-related unhandled promise rejections as fallback
-process.on('unhandledRejection', (reason, promise) => {
-  const r = unwrapError(reason)
-  if (r?.code === 'ECONNABORTED' && (r?.message?.includes('timeout') || r?.message?.includes('exceeded'))) {
-    return
-  }
-
-  // Log other unhandled rejections as they indicate real problems
-  console.error('Unhandled promise rejection:', describeError(reason))
-})
-
-// This URL is used to create the SOAP client.
-const provisioningUrl = String(process.env.PROVISIONING_URL).replace(/\/$/, '')
-
-// This user is used to authenticate against the provisioning API.
-const provisioningAuth = {
-  auth: {
-    login: process.env.E2E_ADMIN_USER,
-    password: process.env.E2E_ADMIN_PW
-  }
+// Swallow specifically timeout-related unhandled promise rejections as
+// fallback; log everything else, as those indicate real problems. Installed
+// on demand (idempotent) — importing the module must not touch process-global
+// state. The env-configured default client installs it for backwards
+// compatibility with the CLI and test-runner consumers; factory clients from
+// createClientFactory never do, so embedding applications keep their own
+// rejection policy.
+let rejectionFilterInstalled = false
+function installTimeoutRejectionFilter () {
+  if (rejectionFilterInstalled) return
+  rejectionFilterInstalled = true
+  process.on('unhandledRejection', (reason, promise) => {
+    const r = unwrapError(reason)
+    if (r?.code === 'ECONNABORTED' && (r?.message?.includes('timeout') || r?.message?.includes('exceeded'))) {
+      return
+    }
+    console.error('Unhandled promise rejection:', describeError(reason))
+  })
 }
 
 /**
- * This code creates a PerformanceObserver instance which asynchronously observes
- * performance measurement events. It logs the name of the event (which is the name
- * of the SOAP method in this context) and the time it took to execute in milliseconds.
- *
- * This is used for performance tracking of the SOAP methods.
+ * Lazily create the PerformanceObserver that logs SOAP method timings when
+ * DEBUG_SOAP is enabled. One observer per process, created on first client
+ * construction rather than at import time.
  * @see https://nodejs.org/api/perf_hooks.html
- * @params {PerformanceObserverEntryList} items The list of performance entries.
  * @returns {void}
  */
-const obs = new PerformanceObserver((items) => {
-  items.getEntries().forEach((entry) => {
-    if (debug) console.log(`${entry.name} took ${Math.round(entry.duration)}ms`)
+let debugObserverInstalled = false
+function ensureDebugObserver () {
+  if (debugObserverInstalled || !debug()) return
+  debugObserverInstalled = true
+  const obs = new PerformanceObserver((items) => {
+    items.getEntries().forEach((entry) => {
+      console.log(`${entry.name} took ${Math.round(entry.duration)}ms`)
+    })
   })
-})
-obs.observe({ entryTypes: ['measure'] })
+  obs.observe({ entryTypes: ['measure'] })
+}
 
 async function logSoapError (e) {
   console.error(describeError(e))
@@ -243,15 +240,109 @@ function handleFailedAttempt (context, label) {
 }
 
 /**
- * This function creates a SOAP client for the specified service type.
+ * @typedef {object} TransportOptions
+ * @property {string} url  Base URL of the provisioning API (e.g. the core-mw
+ *   admin Service), without the `/webservices` suffix.
+ * @property {{login: string, password: string}} auth  Master admin credentials
+ *   injected into every SOAP call unless the call passes its own `auth`.
+ */
+
+/**
+ * Create a per-endpoint SOAP client constructor. Multiple factories coexist in
+ * one process, each bound to its own endpoint and credentials — nothing is
+ * read from the environment and no process-global state is touched.
+ * @param {TransportOptions} options
+ * @returns {(type: string) => Promise<Object>} createClientAsync bound to the endpoint.
+ */
+function createClientFactory ({ url, auth }) {
+  if (!url) throw new TypeError('createClientFactory: url is required')
+  if (!auth?.login || !auth?.password) throw new TypeError('createClientFactory: auth {login, password} is required')
+  const baseUrl = String(url).replace(/\/$/, '')
+  const defaultAuth = { auth: { login: auth.login, password: auth.password } }
+  return (type) => createTypedClientAsync(type, baseUrl, defaultAuth)
+}
+
+/**
+ * Memoize one SOAP client per service type, but only once it resolves.
+ *
+ * A plain `promise ??= createClient(type)` caches a rejection for the lifetime
+ * of the process: if the WSDL fetch exhausts its retry schedule or hits a
+ * non-retryable fault, every later call re-throws that stale error without ever
+ * touching the network again. That is fatal for a long-running embedder, where
+ * one bad startup would poison the service until the process restarts. Clearing
+ * the slot on failure keeps the happy path a single shared client while letting
+ * the next call re-attempt construction.
+ *
+ * @param {(type: string) => Promise<Object>} createClient
+ * @param {string} type The name of the service type.
+ * @returns {() => Promise<Object>} Getter returning the memoized client.
+ */
+function memoizeClient (createClient, type) {
+  let clientPromise
+  return () => (clientPromise ??= createClient(type).catch(e => {
+    clientPromise = undefined
+    throw e
+  }))
+}
+
+// The env-configured default transport behind the classic module exports.
+// Built lazily on first use: loads .env files, installs the timeout-rejection
+// filter (CLI/test-runner compatibility), and binds PROVISIONING_URL +
+// E2E_ADMIN_USER/PW. Factory transports never take this path.
+let defaultCreateClient
+function getDefaultCreateClient () {
+  if (!defaultCreateClient) {
+    for (const envFile of ['.env', '.env.defaults']) {
+      try { process.loadEnvFile(envFile) } catch {}
+    }
+    installTimeoutRejectionFilter()
+    // Report the missing *environment variables*, not createClientFactory's
+    // parameter names: a caller of the classic module exports never touched
+    // that function and would otherwise get an error naming an API it has
+    // never heard of. Note this is stricter than before — calls that carry
+    // their own `auth` (every user/account/reseller method takes
+    // `context.admin`) used to work with the master credentials unset, and
+    // now fail here. See the CHANGELOG entry for 0.2.0.
+    const missing = ['PROVISIONING_URL', 'E2E_ADMIN_USER', 'E2E_ADMIN_PW'].filter(key => !process.env[key])
+    if (missing.length) {
+      throw new TypeError(
+        `@open-xchange/soap-client: missing ${missing.join(', ')}. The module exports bind to the ` +
+        'environment; set these in .env, or use createProvisioningClient({ url, auth }) from ' +
+        "'@open-xchange/soap-client/client' to pass an endpoint and credentials explicitly."
+      )
+    }
+    defaultCreateClient = createClientFactory({
+      url: process.env.PROVISIONING_URL,
+      auth: { login: process.env.E2E_ADMIN_USER, password: process.env.E2E_ADMIN_PW }
+    })
+  }
+  return defaultCreateClient
+}
+
+/**
+ * This function creates a SOAP client for the specified service type, bound to
+ * the env-configured default endpoint (PROVISIONING_URL, E2E_ADMIN_USER/PW).
  * @param {string} type The name of the service type.
  * @returns {Promise<Object>} The SOAP client.
  */
 async function createClientAsync (type) {
+  return getDefaultCreateClient()(type)
+}
+
+/**
+ * Create a SOAP client for the specified service type against a specific
+ * endpoint with specific credentials.
+ * @param {string} type The name of the service type.
+ * @param {string} baseUrl Base URL without trailing slash.
+ * @param {{auth: {login: string, password: string}}} defaultAuth Auth option injected per call.
+ * @returns {Promise<Object>} The SOAP client.
+ */
+async function createTypedClientAsync (type, baseUrl, defaultAuth) {
+  ensureDebugObserver()
   const startMark = `${type}-start`
   const endMark = `${type}-end`
   performance.mark(startMark)
-  const endpoint = `${provisioningUrl}/webservices/${type}`
+  const endpoint = `${baseUrl}/webservices/${type}`
   const url = `${endpoint}/?wsdl`
   // The WSDL fetch itself can hit transient network errors (ECONNRESET,
   // ETIMEDOUT, ...). Without retry here, a single TLS hiccup during
@@ -284,11 +375,19 @@ async function createClientAsync (type) {
           const startMark = `${prop}-start`
           const endMark = `${prop}-end`
           performance.mark(startMark)
-          const soapOptions = { ...provisioningAuth, ...options }
-          if (soapOptions.auth) {
+          // Pull `auth` out before merging. Spreading `options` wholesale made a
+          // present-but-undefined `auth` (every user/account/reseller method
+          // sends `auth: context.admin`, and a context without a resolved admin
+          // makes that undefined) overwrite the endpoint credentials, so the
+          // call went out unauthenticated even though valid ones were
+          // configured. An absent or undefined `auth` now falls back to the
+          // endpoint default; a real one still wins.
+          const { auth, ...rest } = options ?? {}
+          const soapOptions = { ...defaultAuth, ...rest }
+          if (auth) {
             // only send login and password instead of complete admin object.
             // this can fail because of ambiguous namespacing
-            soapOptions.auth = { login: soapOptions.auth.login, password: soapOptions.auth.password }
+            soapOptions.auth = { login: auth.login, password: auth.password }
           }
 
           try {
@@ -313,4 +412,4 @@ async function createClientAsync (type) {
   })
 }
 
-export { createClientAsync, logSoapError, describeError, shouldAbortRetry, wrapSoapFault, unwrapError, handleFailedAttempt }
+export { createClientAsync, createClientFactory, memoizeClient, installTimeoutRejectionFilter, logSoapError, describeError, shouldAbortRetry, wrapSoapFault, unwrapError, handleFailedAttempt }