@appium/base-driver 9.3.3 → 9.3.5

package/lib/basedriver/helpers.js

@@ -2,16 +2,24 @@ import _ from 'lodash';
 import path from 'path';
 import url from 'url';
 import logger from './logger';
-import {tempDir, fs, util, zip, net, timing, node} from '@appium/support';
+import {tempDir, fs, util, zip, timing, node} from '@appium/support';
 import LRU from 'lru-cache';
 import AsyncLock from 'async-lock';
 import axios from 'axios';
+import B from 'bluebird';
 
+// for compat with running tests transpiled and in-place
+const {version: BASEDRIVER_VER} = fs.readPackageJsonFrom(__dirname);
 const IPA_EXT = '.ipa';
-const ZIP_EXTS = ['.zip', IPA_EXT];
+const ZIP_EXTS = new Set(['.zip', IPA_EXT]);
 const ZIP_MIME_TYPES = ['application/zip', 'application/x-zip-compressed', 'multipart/x-zip'];
 const CACHED_APPS_MAX_AGE = 1000 * 60 * 60 * 24; // ms
 const MAX_CACHED_APPS = 1024;
+const HTTP_STATUS_NOT_MODIFIED = 304;
+const DEFAULT_REQ_HEADERS = Object.freeze({
+  'user-agent': `Appium (BaseDriver v${BASEDRIVER_VER})`,
+});
+const AVG_DOWNLOAD_SPEED_MEASUREMENT_THRESHOLD_SEC = 2;
 const APPLICATIONS_CACHE = new LRU({
   max: MAX_CACHED_APPS,
   ttl: CACHED_APPS_MAX_AGE, // expire after 24 hours
@@ -52,77 +60,6 @@ process.on('exit', () => {
   }
 });
 
-/**
- *
- * @param {string} url
- * @returns {Promise<import('axios').AxiosResponse['headers']>}
- */
-async function retrieveHeaders(url) {
-  try {
-    return (
-      await axios({
-        url,
-        method: 'HEAD',
-        timeout: 5000,
-      })
-    ).headers;
-  } catch (e) {
-    logger.info(`Cannot send HEAD request to '${url}'. Original error: ${e.message}`);
-  }
-  return {};
-}
-
-function getCachedApplicationPath(link, currentAppProps = {}, cachedAppInfo = {}) {
-  const refresh = () => {
-    logger.debug(`A fresh copy of the application is going to be downloaded from ${link}`);
-    return null;
-  };
-
-  if (!_.isPlainObject(cachedAppInfo) || !_.isPlainObject(currentAppProps)) {
-    // if an invalid arg is passed then assume cache miss
-    return refresh();
-  }
-
-  const {
-    lastModified: currentModified,
-    immutable: currentImmutable,
-    // maxAge is in seconds
-    maxAge: currentMaxAge,
-  } = currentAppProps;
-  const {
-    // Date instance
-    lastModified,
-    // boolean
-    immutable,
-    // Unix time in milliseconds
-    timestamp,
-    fullPath,
-  } = cachedAppInfo;
-  if (lastModified && currentModified) {
-    if (currentModified.getTime() <= lastModified.getTime()) {
-      logger.debug(`The application at ${link} has not been modified since ${lastModified}`);
-      return fullPath;
-    }
-    logger.debug(`The application at ${link} has been modified since ${lastModified}`);
-    return refresh();
-  }
-  if (immutable && currentImmutable) {
-    logger.debug(`The application at ${link} is immutable`);
-    return fullPath;
-  }
-  if (currentMaxAge && timestamp) {
-    const msLeft = timestamp + currentMaxAge * 1000 - Date.now();
-    if (msLeft > 0) {
-      logger.debug(
-        `The cached application '${path.basename(fullPath)}' will expire in ${msLeft / 1000}s`
-      );
-      return fullPath;
-    }
-    logger.debug(`The cached application '${path.basename(fullPath)}' has expired`);
-  }
-  return refresh();
-}
-
 function verifyAppExtension(app, supportedAppExtensions) {
   if (supportedAppExtensions.map(_.toLower).includes(_.toLower(path.extname(app)))) {
     return app;
@@ -160,56 +97,14 @@ async function isAppIntegrityOk(currentPath, expectedIntegrity = {}) {
 }
 
 /**
- * @typedef PostProcessOptions
- * @property {?Object} cachedAppInfo The information about the previously cached app instance (if exists):
- *    - packageHash: SHA1 hash of the package if it is a file and not a folder
- *    - lastModified: Optional Date instance, the value of file's `Last-Modified` header
- *    - immutable: Optional boolean value. Contains true if the file has an `immutable` mark
- *                 in `Cache-control` header
- *    - maxAge: Optional integer representation of `maxAge` parameter in `Cache-control` header
- *    - timestamp: The timestamp this item has been added to the cache (measured in Unix epoch
- *                 milliseconds)
- *    - integrity: An object containing either `file` property with SHA1 hash of the file
- *                 or `folder` property with total amount of cached files and subfolders
- *    - fullPath: the full path to the cached app
- * @property {boolean} isUrl Whether the app has been downloaded from a remote URL
- * @property {?Object} headers Optional headers object. Only present if `isUrl` is true and if the server
- * responds to HEAD requests. All header names are normalized to lowercase.
- * @property {string} appPath A string containing full path to the preprocessed application package (either
- * downloaded or a local one)
- */
-
-/**
- * @typedef PostProcessResult
- * @property {string} appPath The full past to the post-processed application package on the
- * local file system (might be a file or a folder path)
- */
-
-/**
- * @typedef ConfigureAppOptions
- * @property {(obj: PostProcessOptions) => (Promise<PostProcessResult|undefined>|PostProcessResult|undefined)} [onPostProcess]
- * Optional function, which should be applied
- * to the application after it is downloaded/preprocessed. This function may be async
- * and is expected to accept single object parameter.
- * The function is expected to either return a falsy value, which means the app must not be
- * cached and a fresh copy of it is downloaded each time. If this function returns an object
- * containing `appPath` property then the integrity of it will be verified and stored into
- * the cache.
- * @property {string[]} supportedExtensions List of supported application extensions (
- * including starting dots). This property is mandatory and must not be empty.
- */
-
-/**
- * Prepares an app to be used in an automated test. The app gets cached automatically
- * if it is an archive or if it is downloaded from an URL.
- * If the downloaded app has `.zip` extension, this method will unzip it.
- * The unzip does not work when `onPostProcess` is provided.
  *
- * @param {string} app Either a full path to the app or a remote URL
- * @param {string|string[]|ConfigureAppOptions} options
- * @returns The full path to the resulting application bundle
+ * @param {string} app
+ * @param {string|string[]|import('@appium/types').ConfigureAppOptions} options
  */
-async function configureApp(app, options = /** @type {ConfigureAppOptions} */ ({})) {
+async function configureApp(
+  app,
+  options = /** @type {import('@appium/types').ConfigureAppOptions} */ ({})
+) {
   if (!_.isString(app)) {
     // immediately shortcircuit if not given an app
     return;
@@ -233,13 +128,14 @@ async function configureApp(app, options = /** @type {ConfigureAppOptions} */ ({
   let newApp = app;
   let shouldUnzipApp = false;
   let packageHash = null;
-  /** @type {import('axios').AxiosResponse['headers']?} */
-  let headers = null;
+  /** @type {import('axios').AxiosResponse['headers']|undefined} */
+  let headers = undefined;
   /** @type {RemoteAppProps} */
   const remoteAppProps = {
     lastModified: null,
     immutable: false,
     maxAge: null,
+    etag: null,
   };
   const {protocol, pathname} = url.parse(newApp);
   const isUrl = protocol === null ? false : ['http:', 'https:'].includes(protocol);
@@ -250,94 +146,121 @@ async function configureApp(app, options = /** @type {ConfigureAppOptions} */ ({
     if (isUrl) {
       // Use the app from remote URL
       logger.info(`Using downloadable app '${newApp}'`);
-      headers = await retrieveHeaders(newApp);
-      if (!_.isEmpty(headers)) {
-        if (headers['last-modified']) {
-          remoteAppProps.lastModified = new Date(headers['last-modified']);
-        }
-        logger.debug(`Last-Modified: ${headers['last-modified']}`);
-        if (headers['cache-control']) {
-          remoteAppProps.immutable = /\bimmutable\b/i.test(headers['cache-control']);
-          const maxAgeMatch = /\bmax-age=(\d+)\b/i.exec(headers['cache-control']);
-          if (maxAgeMatch) {
-            remoteAppProps.maxAge = parseInt(maxAgeMatch[1], 10);
-          }
-        }
-        logger.debug(`Cache-Control: ${headers['cache-control']}`);
+      const reqHeaders = {
+        ...DEFAULT_REQ_HEADERS,
+      };
+      if (cachedAppInfo?.etag) {
+        reqHeaders['if-none-match'] = remoteAppProps.etag;
+      } else if (cachedAppInfo?.lastModified) {
+        reqHeaders['if-modified-since'] = remoteAppProps.lastModified?.toString();
       }
-      const cachedPath = getCachedApplicationPath(app, remoteAppProps, cachedAppInfo);
-      if (cachedPath) {
-        if (await isAppIntegrityOk(cachedPath, cachedAppInfo?.integrity)) {
-          logger.info(`Reusing previously downloaded application at '${cachedPath}'`);
-          return verifyAppExtension(cachedPath, supportedAppExtensions);
+
+      let {headers, stream, status} = await queryAppLink(newApp, reqHeaders);
+      try {
+        if (!_.isEmpty(headers)) {
+          logger.debug(`Etag: ${remoteAppProps?.etag} -> ${headers.etag}`);
+          if (headers.etag) {
+            remoteAppProps.etag = headers.etag;
+          }
+          logger.debug(
+            `Last-Modified: ${remoteAppProps?.['last-modified']} -> ${headers['last-modified']}`
+          );
+          if (headers['last-modified']) {
+            remoteAppProps.lastModified = new Date(headers['last-modified']);
+          }
+          logger.debug(
+            `Cache-Control: ${remoteAppProps?.['cache-control']} -> ${headers['cache-control']}`
+          );
+          if (headers['cache-control']) {
+            remoteAppProps.immutable = /\bimmutable\b/i.test(headers['cache-control']);
+            const maxAgeMatch = /\bmax-age=(\d+)\b/i.exec(headers['cache-control']);
+            if (maxAgeMatch) {
+              remoteAppProps.maxAge = parseInt(maxAgeMatch[1], 10);
+            }
+          }
         }
-        logger.info(
-          `The application at '${cachedPath}' does not exist anymore ` +
-            `or its integrity has been damaged. Deleting it from the internal cache`
-        );
-        APPLICATIONS_CACHE.delete(app);
-      }
+        if (cachedAppInfo && status === HTTP_STATUS_NOT_MODIFIED) {
+          if (await isAppIntegrityOk(cachedAppInfo.fullPath, cachedAppInfo.integrity)) {
+            logger.info(`Reusing previously downloaded application at '${cachedAppInfo.fullPath}'`);
+            return verifyAppExtension(cachedAppInfo.fullPath, supportedAppExtensions);
+          }
+          logger.info(
+            `The application at '${cachedAppInfo.fullPath}' does not exist anymore ` +
+              `or its integrity has been damaged. Deleting it from the internal cache`
+          );
+          APPLICATIONS_CACHE.delete(app);
 
-      let fileName = null;
-      const basename = fs.sanitizeName(path.basename(decodeURIComponent(pathname ?? '')), {
-        replacement: SANITIZE_REPLACEMENT,
-      });
-      const extname = path.extname(basename);
-      // to determine if we need to unzip the app, we have a number of places
-      // to look: content type, content disposition, or the file extension
-      if (ZIP_EXTS.includes(extname)) {
-        fileName = basename;
-        shouldUnzipApp = true;
-      }
-      if (headers['content-type']) {
-        const ct = headers['content-type'];
-        logger.debug(`Content-Type: ${ct}`);
-        // the filetype may not be obvious for certain urls, so check the mime type too
-        if (
-          ZIP_MIME_TYPES.some((mimeType) =>
-            new RegExp(`\\b${_.escapeRegExp(mimeType)}\\b`).test(ct)
-          )
-        ) {
-          if (!fileName) {
-            fileName = `${DEFAULT_BASENAME}.zip`;
+          if (!stream.closed) {
+            stream.destroy();
           }
+          ({stream, headers, status} = await queryAppLink(newApp, {...DEFAULT_REQ_HEADERS}));
+        }
+
+        let fileName = null;
+        const basename = fs.sanitizeName(path.basename(decodeURIComponent(pathname ?? '')), {
+          replacement: SANITIZE_REPLACEMENT,
+        });
+        const extname = path.extname(basename);
+        // to determine if we need to unzip the app, we have a number of places
+        // to look: content type, content disposition, or the file extension
+        if (ZIP_EXTS.has(extname)) {
+          fileName = basename;
           shouldUnzipApp = true;
         }
-      }
-      if (headers['content-disposition'] && /^attachment/i.test(headers['content-disposition'])) {
-        logger.debug(`Content-Disposition: ${headers['content-disposition']}`);
-        const match = /filename="([^"]+)/i.exec(headers['content-disposition']);
-        if (match) {
-          fileName = fs.sanitizeName(match[1], {
-            replacement: SANITIZE_REPLACEMENT,
-          });
-          shouldUnzipApp = shouldUnzipApp || ZIP_EXTS.includes(path.extname(fileName));
+        if (headers['content-type']) {
+          const ct = headers['content-type'];
+          logger.debug(`Content-Type: ${ct}`);
+          // the filetype may not be obvious for certain urls, so check the mime type too
+          if (
+            ZIP_MIME_TYPES.some((mimeType) =>
+              new RegExp(`\\b${_.escapeRegExp(mimeType)}\\b`).test(ct)
+            )
+          ) {
+            if (!fileName) {
+              fileName = `${DEFAULT_BASENAME}.zip`;
+            }
+            shouldUnzipApp = true;
+          }
         }
-      }
-      if (!fileName) {
-        // assign the default file name and the extension if none has been detected
-        const resultingName = basename
-          ? basename.substring(0, basename.length - extname.length)
-          : DEFAULT_BASENAME;
-        let resultingExt = extname;
-        if (!supportedAppExtensions.includes(resultingExt)) {
-          logger.info(
-            `The current file extension '${resultingExt}' is not supported. ` +
-              `Defaulting to '${_.first(supportedAppExtensions)}'`
-          );
-          resultingExt = /** @type {string} */ (_.first(supportedAppExtensions));
+        if (headers['content-disposition'] && /^attachment/i.test(headers['content-disposition'])) {
+          logger.debug(`Content-Disposition: ${headers['content-disposition']}`);
+          const match = /filename="([^"]+)/i.exec(headers['content-disposition']);
+          if (match) {
+            fileName = fs.sanitizeName(match[1], {
+              replacement: SANITIZE_REPLACEMENT,
+            });
+            shouldUnzipApp = shouldUnzipApp || ZIP_EXTS.has(path.extname(fileName));
+          }
+        }
+        if (!fileName) {
+          // assign the default file name and the extension if none has been detected
+          const resultingName = basename
+            ? basename.substring(0, basename.length - extname.length)
+            : DEFAULT_BASENAME;
+          let resultingExt = extname;
+          if (!supportedAppExtensions.includes(resultingExt)) {
+            logger.info(
+              `The current file extension '${resultingExt}' is not supported. ` +
+                `Defaulting to '${_.first(supportedAppExtensions)}'`
+            );
+            resultingExt = /** @type {string} */ (_.first(supportedAppExtensions));
+          }
+          fileName = `${resultingName}${resultingExt}`;
+        }
+        const targetPath = await tempDir.path({
+          prefix: fileName,
+          suffix: '',
+        });
+        newApp = await fetchApp(stream, targetPath);
+      } finally {
+        if (!stream.closed) {
+          stream.destroy();
         }
-        fileName = `${resultingName}${resultingExt}`;
       }
-      const targetPath = await tempDir.path({
-        prefix: fileName,
-        suffix: '',
-      });
-      newApp = await downloadApp(newApp, targetPath);
     } else if (await fs.exists(newApp)) {
       // Use the local app
       logger.info(`Using local app '${newApp}'`);
-      shouldUnzipApp = ZIP_EXTS.includes(path.extname(newApp));
+      shouldUnzipApp = ZIP_EXTS.has(path.extname(newApp));
     } else {
       let errorMessage = `The application at '${newApp}' does not exist or is not accessible`;
       // protocol value for 'C:\\temp' is 'c:', so we check the length as well
@@ -411,12 +334,14 @@ async function configureApp(app, options = /** @type {ConfigureAppOptions} */ ({
     };
 
     if (_.isFunction(onPostProcess)) {
-      const result = await onPostProcess({
-        cachedAppInfo: _.clone(cachedAppInfo),
-        isUrl,
-        headers: _.clone(headers),
-        appPath: newApp,
-      });
+      const result = await onPostProcess(
+        /** @type {import('@appium/types').PostProcessOptions<import('axios').AxiosResponseHeaders>} */ ({
+          cachedAppInfo: _.clone(cachedAppInfo),
+          isUrl,
+          headers: _.clone(headers),
+          appPath: newApp,
+        })
+      );
       return !result?.appPath || app === result?.appPath || !(await fs.exists(result?.appPath))
         ? newApp
         : await storeAppInCache(result.appPath);
@@ -429,16 +354,78 @@ async function configureApp(app, options = /** @type {ConfigureAppOptions} */ ({
   });
 }
 
-async function downloadApp(app, targetPath) {
-  const {href} = url.parse(app);
+/**
+ * Sends a HTTP GET query to fetch the app with caching enabled.
+ * Follows https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching
+ *
+ * @param {string} appLink The URL to download an app from
+ * @param {import('axios').RawAxiosRequestHeaders} reqHeaders Additional HTTP request headers
+ * @returns {Promise<RemoteAppData>}
+ */
+async function queryAppLink(appLink, reqHeaders) {
+  const {href} = url.parse(appLink);
+  /**
+   * @type {import('axios').RawAxiosRequestConfig}
+   */
+  const requestOpts = {
+    url: href,
+    responseType: 'stream',
+    timeout: APP_DOWNLOAD_TIMEOUT_MS,
+    validateStatus: (status) =>
+      (status >= 200 && status < 300) || status === HTTP_STATUS_NOT_MODIFIED,
+    headers: reqHeaders,
+  };
+  try {
+    const {data: stream, headers, status} = await axios(requestOpts);
+    return {
+      stream,
+      headers,
+      status,
+    };
+  } catch (err) {
+    throw new Error(`Cannot download the app from ${href}: ${err.message}`);
+  }
+}
+
+/**
+ * Retrieves app payload from the given stream. Also meters the download performance.
+ *
+ * @param {import('stream').Readable} srcStream The incoming stream
+ * @param {string} dstPath The target file path to be written
+ * @returns {Promise<string>} The same dstPath
+ * @throws {Error} If there was a failure while downloading the file
+ */
+async function fetchApp(srcStream, dstPath) {
+  const timer = new timing.Timer().start();
   try {
-    await net.downloadFile(href, targetPath, {
-      timeout: APP_DOWNLOAD_TIMEOUT_MS,
+    const writer = fs.createWriteStream(dstPath);
+    srcStream.pipe(writer);
+
+    await new B((resolve, reject) => {
+      srcStream.once('error', reject);
+      writer.once('finish', resolve);
+      writer.once('error', (e) => {
+        srcStream.unpipe(writer);
+        reject(e);
+      });
     });
   } catch (err) {
-    throw new Error(`Unable to download the app: ${err.message}`);
+    throw new Error(`Cannot fetch the application: ${err.message}`);
   }
-  return targetPath;
+
+  const secondsElapsed = timer.getDuration().asSeconds;
+  const {size} = await fs.stat(dstPath);
+  logger.debug(
+    `The application (${util.toReadableSizeString(size)}) ` +
+      `has been downloaded to '${dstPath}' in ${secondsElapsed.toFixed(3)}s`
+  );
+  // it does not make much sense to approximate the speed for short downloads
+  if (secondsElapsed >= AVG_DOWNLOAD_SPEED_MEASUREMENT_THRESHOLD_SEC) {
+    const bytesPerSec = Math.floor(size / secondsElapsed);
+    logger.debug(`Approximate download speed: ${util.toReadableSizeString(bytesPerSec)}/s`);
+  }
+
+  return dstPath;
 }
 
 /**
@@ -606,11 +593,26 @@ export default {
   parseCapsArray,
   generateDriverLogPrefix,
 };
-export {configureApp, isPackageOrBundle, duplicateKeys, parseCapsArray, generateDriverLogPrefix};
+export {
+  configureApp,
+  isPackageOrBundle,
+  duplicateKeys,
+  parseCapsArray,
+  generateDriverLogPrefix,
+  BASEDRIVER_VER,
+};
 
 /**
  * @typedef RemoteAppProps
  * @property {Date?} lastModified
  * @property {boolean} immutable
  * @property {number?} maxAge
+ * @property {string?} etag
+ */
+
+/**
+ * @typedef RemoteAppData Properties of the remote application (e.g. GET HTTP response) to be downloaded.
+ * @property {number} status The HTTP status of the response
+ * @property {import('stream').Readable} stream The HTTP response body represented as readable stream
+ * @property {import('axios').RawAxiosResponseHeaders | import('axios').AxiosResponseHeaders} headers HTTP response headers
  */

package/lib/express/server.js

@@ -151,8 +151,10 @@ function configureHttp({httpServer, reject, keepAliveTimeout}) {
     notifier: new EventEmitter(),
     closed: false,
   };
-  // TS does not love monkeypatching.
-  const appiumServer = /** @type {AppiumServer} */ (/** @type {unknown} */ (httpServer));
+  /**
+   * @type {AppiumServer}
+   */
+  const appiumServer = /** @type {any} */ (httpServer);
   appiumServer.addWebSocketHandler = addWebSocketHandler;
   appiumServer.removeWebSocketHandler = removeWebSocketHandler;
   appiumServer.removeAllWebSocketHandlers = removeAllWebSocketHandlers;

package/lib/express/websocket.js

@@ -6,33 +6,21 @@ import B from 'bluebird';
 const DEFAULT_WS_PATHNAME_PREFIX = '/ws';
 
 /**
- * Adds websocket handler to express server instance.
- * It is expected this function is called in Express
- * server instance context.
- *
- * @this {AppiumServer} - An instance of express HTTP server.
- * @param {string} handlerPathname - Web socket endpoint path starting with
- * a single slash character. It is recommended to always add
- * DEFAULT_WS_PATHNAME_PREFIX to all web socket pathnames.
- * @param {import('ws').Server} handlerServer - WebSocket server instance. See
- * https://github.com/websockets/ws/pull/885 for more details
- * on how to configure the handler properly.
- * @returns {Promise<void>}
+ * @this {AppiumServer}
+ * @type {AppiumServer['addWebSocketHandler']}
  */
 async function addWebSocketHandler(handlerPathname, handlerServer) {
-  const server = /** @type {AppiumServer} */ (this);
   if (_.isUndefined(this.webSocketsMapping)) {
-    server.webSocketsMapping = {};
+    this.webSocketsMapping = {};
     // https://github.com/websockets/ws/pull/885
-    server.on('upgrade', (request, socket, head) => {
+    this.on('upgrade', (request, socket, head) => {
       let currentPathname;
       try {
-        // @ts-expect-error
-        currentPathname = new URL(request.url).pathname;
+        currentPathname = new URL(/** @type {string} */ (request.url)).pathname;
       } catch {
         currentPathname = request.url;
       }
-      for (const [pathname, wsServer] of _.toPairs(server.webSocketsMapping)) {
+      for (const [pathname, wsServer] of _.toPairs(this.webSocketsMapping)) {
         if (currentPathname === pathname) {
           wsServer.handleUpgrade(request, socket, head, (ws) => {
             wsServer.emit('connection', ws, request);
@@ -47,17 +35,9 @@ async function addWebSocketHandler(handlerPathname, handlerServer) {
 }
 
 /**
- * Returns web socket handlers registered for the given server
- * instance.
- * It is expected this function is called in Express
- * server instance context.
- *
  * @this {AppiumServer}
- * @param {string?} [keysFilter] - Only include pathnames with given
- * `keysFilter` value if set. All pairs will be included by default.
- * @returns {Promise<Record<string, import('ws').Server>>} pathnames to websocket server instances mapping matching the search criteria or an empty object otherwise.
+ * @type {AppiumServer['getWebSocketHandlers']}
  */
-// eslint-disable-next-line require-await
 async function getWebSocketHandlers(keysFilter = null) {
   if (_.isEmpty(this.webSocketsMapping)) {
     return {};
@@ -72,16 +52,9 @@ async function getWebSocketHandlers(keysFilter = null) {
 }
 
 /**
- * Removes existing websocket handler from express server instance.
- * The call is ignored if the given `handlerPathname` handler
- * is not present in the handlers list.
- * It is expected this function is called in Express
- * server instance context.
  * @this {AppiumServer}
- * @param {string} handlerPathname - Websocket endpoint path.
- * @returns {Promise<boolean>} true if the handlerPathname was found and deleted
+ * @type {AppiumServer['removeWebSocketHandler']}
  */
-// eslint-disable-next-line require-await
 async function removeWebSocketHandler(handlerPathname) {
   const wsServer = this.webSocketsMapping?.[handlerPathname];
   if (!wsServer) {
@@ -103,11 +76,9 @@ async function removeWebSocketHandler(handlerPathname) {
 }
 
 /**
- * Removes all existing websocket handler from express server instance.
- * It is expected this function is called in Express
- * server instance context.
+ *
  * @this {AppiumServer}
- * @returns {Promise<boolean>} true if at least one handler has been deleted
+ * @type {AppiumServer['removeAllWebSocketHandlers']}
  */
 async function removeAllWebSocketHandlers() {
   if (_.isEmpty(this.webSocketsMapping)) {

package/lib/helpers/capabilities.js

@@ -83,7 +83,6 @@ export {isW3cCaps, fixCaps};
  */
 
 /**
- * @template {Constraints} [C=BaseDriverCapConstraints]
- * @template {StringRecord|void} [Extra=void]
- * @typedef {import('@appium/types').Capabilities<C, Extra>} Capabilities
+ * @template {Constraints} C
+ * @typedef {import('@appium/types').Capabilities<C>} Capabilities
  */

package/lib/protocol/protocol.js

@@ -277,7 +277,7 @@ function routeConfiguringFunction(driver) {
           `${basePath}${path}`,
           spec,
           driver,
-          isSessionCommand(spec.command)
+          isSessionCommand(/** @type {import('@appium/types').DriverMethodDef} */ (spec).command)
         );
       }
     }
@@ -454,7 +454,16 @@ function buildHandler(app, method, path, spec, driver, isSessCmd) {
     } catch (err) {
       // if anything goes wrong, figure out what our response should be
       // based on the type of error that we encountered
-      let actualErr = err;
+      let actualErr;
+      if (err instanceof Error || (_.has(err, 'stack') && _.has(err, 'message'))) {
+        actualErr = err;
+      } else {
+        getLogger(driver, req.params.sessionId || newSessionId).warn(
+          'The thrown error object does not seem to be a valid instance of the Error class. This ' +
+            'might be a genuine bug of a driver or a plugin.'
+        );
+        actualErr = new Error(`${err ?? 'unknown'}`);
+      }
 
       currentProtocol =
         currentProtocol || extractProtocol(driver, req.params.sessionId || newSessionId);