@appium/base-driver 9.16.2 → 10.0.0-beta.0

package/lib/jsonwp-proxy/protocol-converter.js

@@ -43,6 +43,11 @@ const {MJSONWP, W3C} = PROTOCOLS;
 const DEFAULT_LOG = logger.getLogger('Protocol Converter');
 
 class ProtocolConverter {
+  /**
+   *
+   * @param {ProxyFunction} proxyFunc
+   * @param {import('@appium/types').AppiumLogger | null} [log=null]
+   */
   constructor(proxyFunc, log = null) {
     this.proxyFunc = proxyFunc;
     this._downstreamProtocol = null;
@@ -67,7 +72,7 @@ class ProtocolConverter {
    * provided in the request, we need to do 3 proxies and combine the result
    *
    * @param {Object} body Request body
-   * @return {Array} Array of W3C + MJSONWP compatible timeout objects
+   * @return {Object[]} Array of W3C + MJSONWP compatible timeout objects
    */
   getTimeoutRequestObjects(body) {
     if (this.downstreamProtocol === W3C && _.has(body, 'ms') && _.has(body, 'type')) {
@@ -99,9 +104,10 @@ class ProtocolConverter {
 
   /**
    * Proxy an array of timeout objects and merge the result
-   * @param {String} url Endpoint url
-   * @param {String} method Endpoint method
-   * @param {Object} body Request body
+   * @param {string} url Endpoint url
+   * @param {string} method Endpoint method
+   * @param {import('@appium/types').HTTPBody} body Request body
+   * @returns {Promise<[import('@appium/types').ProxyResponse, import('@appium/types').HTTPBody]>}
    */
   async proxySetTimeouts(url, method, body) {
     let response, resBody;
@@ -127,9 +133,16 @@ class ProtocolConverter {
 
       // ...Otherwise, continue to the next timeouts call
     }
-    return [response, resBody];
+    return [/** @type {import('@appium/types').ProxyResponse} */(response), resBody];
   }
 
+  /**
+   *
+   * @param {string} url
+   * @param {string} method
+   * @param {import('@appium/types').HTTPBody} body
+   * @returns {Promise<[import('@appium/types').ProxyResponse, import('@appium/types').HTTPBody]>}
+   */
   async proxySetWindow(url, method, body) {
     const bodyObj = util.safeJsonParse(body);
     if (_.isPlainObject(bodyObj)) {
@@ -160,6 +173,13 @@ class ProtocolConverter {
     return await this.proxyFunc(url, method, body);
   }
 
+  /**
+   *
+   * @param {string} url
+   * @param {string} method
+   * @param {import('@appium/types').HTTPBody} body
+   * @returns {Promise<[import('@appium/types').ProxyResponse, import('@appium/types').HTTPBody]>}
+   */
   async proxySetValue(url, method, body) {
     const bodyObj = util.safeJsonParse(body);
     if (_.isPlainObject(bodyObj) && (util.hasValue(bodyObj.text) || util.hasValue(bodyObj.value))) {
@@ -186,6 +206,13 @@ class ProtocolConverter {
     return await this.proxyFunc(url, method, body);
   }
 
+  /**
+   *
+   * @param {string} url
+   * @param {string} method
+   * @param {import('@appium/types').HTTPBody} body
+   * @returns {Promise<[import('@appium/types').ProxyResponse, import('@appium/types').HTTPBody]>}
+   */
   async proxySetFrame(url, method, body) {
     const bodyObj = util.safeJsonParse(body);
     return _.has(bodyObj, 'id') && _.isPlainObject(bodyObj.id)
@@ -196,6 +223,13 @@ class ProtocolConverter {
       : await this.proxyFunc(url, method, body);
   }
 
+  /**
+   *
+   * @param {string} url
+   * @param {string} method
+   * @param {import('@appium/types').HTTPBody} body
+   * @returns {Promise<[import('@appium/types').ProxyResponse, import('@appium/types').HTTPBody]>}
+   */
   async proxyPerformActions(url, method, body) {
     const bodyObj = util.safeJsonParse(body);
     return _.isPlainObject(bodyObj)
@@ -207,6 +241,12 @@ class ProtocolConverter {
       : await this.proxyFunc(url, method, body);
   }
 
+  /**
+   *
+   * @param {string} url
+   * @param {string} method
+   * @returns {Promise<[import('@appium/types').ProxyResponse, import('@appium/types').HTTPBody]>}
+   */
   async proxyReleaseActions(url, method) {
     return await this.proxyFunc(url, method);
   }
@@ -218,8 +258,8 @@ class ProtocolConverter {
    * @param {string} commandName
    * @param {string} url
    * @param {string} method
-   * @param {?string|object} body
-   * @returns The proxyfying result as [response, responseBody] tuple
+   * @param {import('@appium/types').HTTPBody} [body]
+   * @returns {Promise<[import('@appium/types').ProxyResponse, import('@appium/types').HTTPBody]>}
    */
   async convertAndProxy(commandName, url, method, body) {
     if (!this.downstreamProtocol) {
@@ -272,3 +312,7 @@ class ProtocolConverter {
 }
 
 export default ProtocolConverter;
+
+/**
+ * @typedef {(url: string, method: string, body?: import('@appium/types').HTTPBody) => Promise<[import('@appium/types').ProxyResponse, import('@appium/types').HTTPBody]>} ProxyFunction
+ */

package/lib/jsonwp-proxy/proxy-request.ts

@@ -0,0 +1,52 @@
+import axios from 'axios';
+import { CancellationError } from 'bluebird';
+import EventEmitter from 'node:events';
+
+const CANCEL_EVENT = 'cancel';
+const FINISH_EVENT = 'finish';
+
+export class ProxyRequest {
+  private readonly _requestConfig: axios.RawAxiosRequestConfig;
+  private readonly _ee: EventEmitter;
+  private _resultPromise: Promise<any> | null;
+
+  constructor(requestConfig: axios.RawAxiosRequestConfig<any>) {
+    this._requestConfig = requestConfig;
+    this._ee = new EventEmitter();
+    this._resultPromise = null;
+  }
+
+  async execute(): Promise<axios.AxiosResponse> {
+    if (this._resultPromise) {
+      return await this._resultPromise;
+    }
+
+    try {
+      this._resultPromise = Promise.race([
+        this._makeRacingTimer(),
+        this._makeRequest(),
+      ]);
+      return await this._resultPromise;
+    } finally {
+      this._ee.emit(FINISH_EVENT);
+      this._ee.removeAllListeners();
+    }
+  }
+
+  cancel(): void {
+    this._ee.emit(CANCEL_EVENT);
+  }
+
+  private async _makeRequest(): Promise<axios.AxiosResponse> {
+    return await axios(this._requestConfig);
+  }
+
+  private async _makeRacingTimer(): Promise<void> {
+    return await new Promise((resolve, reject) => {
+      this._ee.once(FINISH_EVENT, resolve);
+      this._ee.once(CANCEL_EVENT, () => reject(new CancellationError(
+        'The request has been cancelled'
+      )));
+    });
+  }
+}

package/lib/jsonwp-proxy/proxy.js

@@ -1,6 +1,5 @@
 import _ from 'lodash';
 import {logger, util} from '@appium/support';
-import axios from 'axios';
 import {getSummaryByCode} from '../jsonwp-status/status';
 import {
   errors,
@@ -17,7 +16,7 @@ import http from 'http';
 import https from 'https';
 import { match as pathToRegexMatch } from 'path-to-regexp';
 import nodeUrl from 'node:url';
-
+import { ProxyRequest } from './proxy-request';
 
 const DEFAULT_LOG = logger.getLogger('WD Proxy');
 const DEFAULT_REQUEST_TIMEOUT = 240000;
@@ -37,7 +36,7 @@ const ALLOWED_OPTS = [
   'keepAlive',
 ];
 
-class JWProxy {
+export class JWProxy {
   /** @type {string} */
   scheme;
   /** @type {string} */
@@ -52,13 +51,20 @@ class JWProxy {
   sessionId;
   /** @type {number} */
   timeout;
+  /** @type {Protocol | null | undefined} */
+  _downstreamProtocol;
+  /** @type {ProxyRequest[]} */
+  _activeRequests;
 
+  /**
+   * @param {import('@appium/types').ProxyOptions} [opts={}]
+   */
   constructor(opts = {}) {
-    opts = _.pick(opts, ALLOWED_OPTS);
-
+    const filteredOpts = _.pick(opts, ALLOWED_OPTS);
     // omit 'log' in the defaults assignment here because 'log' is a getter and we are going to set
     // it to this._log (which lies behind the getter) further down
-    const options = _.defaults(_.omit(opts, 'log'), {
+    /** @type {import('@appium/types').ProxyOptions} */
+    const options = _.defaults(_.omit(filteredOpts, 'log'), {
       scheme: 'http',
       server: 'localhost',
       port: 4444,
@@ -67,7 +73,7 @@ class JWProxy {
       sessionId: null,
       timeout: DEFAULT_REQUEST_TIMEOUT,
     });
-    options.scheme = options.scheme.toLowerCase();
+    options.scheme = /** @type {string} */ (options.scheme).toLowerCase();
     Object.assign(this, options);
 
     this._activeRequests = [];
@@ -81,6 +87,8 @@ class JWProxy {
     this.httpsAgent = new https.Agent(agentOpts);
     this.protocolConverter = new ProtocolConverter(this.proxy.bind(this), opts.log);
     this._log = opts.log;
+
+    this.log.debug(`${this.constructor.name} options: ${JSON.stringify(options)}`);
   }
 
   get log() {
@@ -97,23 +105,32 @@ class JWProxy {
    * @returns {Promise<import('axios').AxiosResponse>}
    */
   async request(requestConfig) {
-    const reqPromise = axios(requestConfig);
-    this._activeRequests.push(reqPromise);
+    const req = new ProxyRequest(requestConfig);
+    this._activeRequests.push(req);
     try {
-      return await reqPromise;
+      return await req.execute();
     } finally {
-      _.pull(this._activeRequests, reqPromise);
+      _.pull(this._activeRequests, req);
     }
   }
 
+  /**
+   * @returns {number}
+   */
   getActiveRequestsCount() {
     return this._activeRequests.length;
   }
 
   cancelActiveRequests() {
+    for (const ar of this._activeRequests) {
+      ar.cancel();
+    }
     this._activeRequests = [];
   }
 
+  /**
+   * @param {Protocol | null | undefined} value
+   */
   set downstreamProtocol(value) {
     this._downstreamProtocol = value;
     this.protocolConverter.downstreamProtocol = value;
@@ -130,32 +147,8 @@ class JWProxy {
    * @returns {string}
    */
   getUrlForProxy(url, method) {
-    const parsedUrl = nodeUrl.parse(url || '/');
-    if (
-      !parsedUrl.href || !parsedUrl.pathname
-      || (parsedUrl.protocol && !['http:', 'https:'].includes(parsedUrl.protocol))
-    ) {
-      throw new Error(`Did not know how to proxy the url '${url}'`);
-    }
-    let pathname = this.reqBasePath && parsedUrl.pathname.startsWith(this.reqBasePath)
-      ? parsedUrl.pathname.replace(this.reqBasePath, '')
-      : parsedUrl.pathname;
-    const match = COMMAND_WITH_SESSION_ID_MATCHER(pathname);
-    // This is needed for the backward compatibility
-    // if drivers don't set reqBasePath properly
-    if (!this.reqBasePath) {
-      if (match && _.isArray(match.params?.prefix)) {
-        pathname = pathname.replace(`/${match.params?.prefix.join('/')}`, '');
-      } else if (_.startsWith(pathname, '/wd/hub')) {
-        pathname = pathname.replace('/wd/hub', '');
-      }
-    }
-    const normalizedPathname = _.trimEnd(
-      match && _.isArray(match.params?.command)
-        ? `/${match.params.command.join('/')}`
-        : pathname,
-      '/'
-    );
+    const parsedUrl = this._parseUrl(url);
+    const normalizedPathname = this._toNormalizedPathname(parsedUrl);
     const commandName = normalizedPathname
       ? routeToCommandName(
         normalizedPathname,
@@ -181,8 +174,8 @@ class JWProxy {
    *
    * @param {string} url
    * @param {string} method
-   * @param {any} body
-   * @returns {Promise<any>}
+   * @param {import('@appium/types').HTTPBody} [body=null]
+   * @returns {Promise<[import('@appium/types').ProxyResponse, import('@appium/types').HTTPBody]>}
    */
   async proxy(url, method, body = null) {
     method = method.toUpperCase();
@@ -255,8 +248,12 @@ class JWProxy {
         // Some servers, like chromedriver may return response code 200 for non-zero JSONWP statuses
         throwProxyError(data);
       }
-      const res = {statusCode: status, headers, body: data};
-      return [res, data];
+      const headersMap = /** @type {import('@appium/types').HTTPHeaders} */ (headers);
+      return [{
+        statusCode: status,
+        headers: headersMap,
+        body: data,
+      }, data];
     } catch (e) {
       // We only consider an error unexpected if this was not
       // an async request module error or if the response cannot be cast to
@@ -279,6 +276,11 @@ class JWProxy {
     }
   }
 
+  /**
+   *
+   * @param {Record<string, any>} resObj
+   * @returns {Protocol | undefined}
+   */
   getProtocolFromResBody(resObj) {
     if (_.isInteger(resObj.status)) {
       return MJSONWP;
@@ -289,6 +291,7 @@ class JWProxy {
   }
 
   /**
+   * @deprecated This method is not used anymore and will be removed
    *
    * @param {string} url
    * @param {import('@appium/types').HTTPMethod} method
@@ -322,10 +325,13 @@ class JWProxy {
    *
    * @param {string} url
    * @param {import('@appium/types').HTTPMethod} method
-   * @param {any?} body
+   * @param {import('@appium/types').HTTPBody} [body=null]
+   * @returns {Promise<[import('@appium/types').ProxyResponse, import('@appium/types').HTTPBody]>}
    */
   async proxyCommand(url, method, body = null) {
-    const commandName = this.requestToCommandName(url, method);
+    const parsedUrl = this._parseUrl(url);
+    const normalizedPathname = this._toNormalizedPathname(parsedUrl);
+    const commandName = normalizedPathname ? routeToCommandName(normalizedPathname, method) : '';
     if (!commandName) {
       return await this.proxy(url, method, body);
     }
@@ -338,8 +344,8 @@ class JWProxy {
    *
    * @param {string} url
    * @param {import('@appium/types').HTTPMethod} method
-   * @param {any?} body
-   * @returns {Promise<unknown>}
+   * @param {import('@appium/types').HTTPBody} [body=null]
+   * @returns {Promise<import('@appium/types').HTTPBody>}
    */
   async command(url, method, body = null) {
     let response;
@@ -393,20 +399,40 @@ class JWProxy {
     );
   }
 
+  /**
+   *
+   * @param {string} url
+   * @returns {string | null}
+   */
   getSessionIdFromUrl(url) {
     const match = url.match(/\/session\/([^/]+)/);
     return match ? match[1] : null;
   }
 
+  /**
+   *
+   * @param {import('express').Request} req
+   * @param {import('express').Response} res
+   */
   async proxyReqRes(req, res) {
     // ! this method must not throw any exceptions
     // ! make sure to call res.send before return
+    /** @type {number} */
     let statusCode;
+    /** @type {import('@appium/types').HTTPBody} */
     let resBodyObj;
     try {
       let response;
-      [response, resBodyObj] = await this.proxyCommand(req.originalUrl, req.method, req.body);
-      res.headers = response.headers;
+      [response, resBodyObj] = await this.proxyCommand(
+        req.originalUrl,
+        /** @type {import('@appium/types').HTTPMethod} */ (req.method),
+        req.body
+      );
+      for (const [name, value] of _.toPairs(response.headers)) {
+        if (!_.isNil(value)) {
+          res.setHeader(name, _.isBoolean(value) ? String(value) : value);
+        }
+      }
       statusCode = response.statusCode;
     } catch (err) {
       [statusCode, resBodyObj] = getResponseForW3CError(
@@ -438,11 +464,58 @@ class JWProxy {
     resBodyObj.value = formatResponseValue(resBodyObj.value);
     res.status(statusCode).send(JSON.stringify(formatStatus(resBodyObj)));
   }
+
+  /**
+   *
+   * @param {string} url
+   * @returns {ParsedUrl}
+   */
+  _parseUrl(url) {
+    const parsedUrl = nodeUrl.parse(url || '/');
+    if (
+      _.isNil(parsedUrl.href) || _.isNil(parsedUrl.pathname)
+      || (parsedUrl.protocol && !['http:', 'https:'].includes(parsedUrl.protocol))
+    ) {
+      throw new Error(`Did not know how to proxy the url '${url}'`);
+    }
+    return parsedUrl;
+  }
+
+  /**
+   *
+   * @param {ParsedUrl} parsedUrl
+   * @returns {string}
+   */
+  _toNormalizedPathname(parsedUrl) {
+    if (!_.isString(parsedUrl.pathname)) {
+      return '';
+    }
+    let pathname = this.reqBasePath && parsedUrl.pathname.startsWith(this.reqBasePath)
+      ? parsedUrl.pathname.replace(this.reqBasePath, '')
+      : parsedUrl.pathname;
+    const match = COMMAND_WITH_SESSION_ID_MATCHER(pathname);
+    // This is needed for the backward compatibility
+    // if drivers don't set reqBasePath properly
+    if (!this.reqBasePath) {
+      if (match && _.isArray(match.params?.prefix)) {
+        pathname = pathname.replace(`/${match.params?.prefix.join('/')}`, '');
+      } else if (_.startsWith(pathname, '/wd/hub')) {
+        pathname = pathname.replace('/wd/hub', '');
+      }
+    }
+    return _.trimEnd(
+      match && _.isArray(match.params?.command)
+        ? `/${match.params.command.join('/')}`
+        : pathname,
+      '/'
+    );
+  }
 }
 
-export {JWProxy};
 export default JWProxy;
 
 /**
  * @typedef {Error & {response: {data: import('type-fest').JsonObject, status: import('http-status-codes').StatusCodes}}} ProxyError
+ * @typedef {nodeUrl.UrlWithStringQuery} ParsedUrl
+ * @typedef {typeof PROTOCOLS[keyof typeof PROTOCOLS]} Protocol
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/base-driver",
-  "version": "9.16.2",
+  "version": "10.0.0-beta.0",
   "description": "Base driver class for Appium drivers",
   "keywords": [
     "automation",
@@ -49,7 +49,7 @@
     "@colors/colors": "1.6.0",
     "async-lock": "1.4.1",
     "asyncbox": "3.0.0",
-    "axios": "1.7.9",
+    "axios": "1.8.1",
     "bluebird": "3.7.2",
     "body-parser": "1.20.3",
     "express": "4.21.2",
@@ -62,7 +62,7 @@
     "path-to-regexp": "8.2.0",
     "serve-favicon": "2.5.0",
     "source-map-support": "0.5.21",
-    "type-fest": "4.35.0",
+    "type-fest": "4.36.0",
     "validate.js": "0.13.1"
   },
   "optionalDependencies": {
@@ -73,9 +73,10 @@
     "npm": ">=8"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "tag": "beta"
   },
-  "gitHead": "e473b05130bb90518a9bdb843c3f93ef74d5b874",
+  "gitHead": "16d16dd0f3bf9829cff2ada7525156c462970932",
   "tsd": {
     "directory": "test/types"
   }