@appium/base-driver 9.16.1 → 9.16.3

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,11 +16,11 @@ 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;
-const COMMAND_WITH_SESSION_ID_MATCHER = pathToRegexMatch('/session/:sessionId{/*command}');
+const COMMAND_WITH_SESSION_ID_MATCHER = pathToRegexMatch('{/*prefix}/session/:sessionId{/*command}');
 
 const {MJSONWP, W3C} = PROTOCOLS;
 
@@ -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,23 +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}'`);
-    }
-    const pathname = this.reqBasePath && parsedUrl.pathname.startsWith(this.reqBasePath)
-      ? parsedUrl.pathname.replace(this.reqBasePath, '')
-      : parsedUrl.pathname;
-    const match = COMMAND_WITH_SESSION_ID_MATCHER(pathname);
-    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,
@@ -172,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();
@@ -246,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
@@ -270,6 +276,11 @@ class JWProxy {
     }
   }
 
+  /**
+   *
+   * @param {Record<string, any>} resObj
+   * @returns {Protocol | undefined}
+   */
   getProtocolFromResBody(resObj) {
     if (_.isInteger(resObj.status)) {
       return MJSONWP;
@@ -280,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
@@ -313,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);
     }
@@ -329,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;
@@ -384,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(
@@ -429,11 +464,57 @@ 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', '');
+      }
+    }
+    let result = pathname;
+    if (match) {
+      result = _.isArray(match.params?.command) ? `/${match.params.command.join('/')}` : '';
+    }
+    return _.trimEnd(result, '/');
+  }
 }
 
-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.1",
+  "version": "9.16.3",
   "description": "Base driver class for Appium drivers",
   "keywords": [
     "automation",
@@ -44,12 +44,12 @@
     "test:types": "tsd"
   },
   "dependencies": {
-    "@appium/support": "^6.0.5",
-    "@appium/types": "^0.25.1",
+    "@appium/support": "^6.0.7",
+    "@appium/types": "^0.25.2",
     "@colors/colors": "1.6.0",
     "async-lock": "1.4.1",
     "asyncbox": "3.0.0",
-    "axios": "1.7.9",
+    "axios": "1.8.2",
     "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.37.0",
     "validate.js": "0.13.1"
   },
   "optionalDependencies": {
@@ -75,7 +75,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "715fd03c45d791ef24b28ad915a20ce6430ff946",
+  "gitHead": "7c05f5c213e284b6be0f1ecf5550a40d84e0899e",
   "tsd": {
     "directory": "test/types"
   }

package/lib/basedriver/README.md

@@ -1,36 +0,0 @@
-appium-base-driver
-===================
-This is the parent class that all [appium](appium.io) drivers inherit from. Appium drivers themselves can either be started from the command line as standalone appium servers, or can be included by another module (appium) which then proxies commands to the appropriate driver based on [Desired Capabilities](https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/caps.md).
-
-An appium driver is a module which processes [Mobile Json Wire Protocol](https://code.google.com/p/selenium/source/browse/spec-draft.md?repo=mobile) commands and controls a device accordingly. The commands can either come in over HTTP as json api requests, or they can be passed to the driver object programmatically as already-parsed json object (without the HTTP headers and junk).
-
-The appium Base driver already includes the [mjsonwp](https://github.com/appium/appium-base-driver/blob/master/lib/mjsonwp/README.md) module, which is the HTTP server that converts incoming requests into json objects that get sent to the driver programmatically.
-
-The appium Base driver already has all the REST api routes, validation, and error codes supplied by [mjsonwp](https://github.com/appium/appium-base-driver/blob/master/lib/mjsonwp/README.md).
-
-Appium drivers are designed to have a *single testing session* per instantiation. This means that one Driver object should be attached to a single device and handle commands from a single client. The main appium driver handles multiple sessions and instantiates a new instance of the desired driver for each new session.
-
-## Writing your own appium driver
-
-Writing your own appium driver starts with inheriting and extending this Base driver module.
-
-Appium Base driver has some properties that all drivers share:
-
- - `driver.opts` - these are the options passed into the driver constructor. Your driver's constructor should take an object of options and pass it on the the Base driver by calling `super(opts)` in your constructor.
-
-- `driver.desiredCapConstraints` - Base driver sets this property with a customer `setter` function so that when you create a driver, you can add an object which defines the validation contraints of which desired capabilities your new driver can handle. Of course each driver will have it's own specific desired capabilities. Look for examples on our other drivers.
-
-- `driver.createSession(caps)` - this is the function which gets desired capabilities and creates a session. Make sure to call `super.createSession(caps)` so that things like `this.sessionId` and `this.caps` are populated, and the caps are validated against your `desiredCapConstraints`.
-
-- `driver.caps` - these are the desired capabilities for the current session.
-
-- `driver.sessionId` - this is the ID of the current session. It gets populated automaticall by `baseDriver.createSession`.
-
-- `driver.proxyReqRes()` - used by mjsonwp module for proxying http commands to another process (like chromedriver or selendroid)
-
-- `driver.jwpProxyAvoid` - used by mjsonwp module. You can specify what REST api routes which you want to SKIP the automatic proxy to another server (which is optional) and instead be handled by your driver.
-
-
-Base driver exposes an event called `onUnexpectedShutdown` which is called when the driver is shut down unexpectedly (usually after invocation of the `startUnexpectedShutdown` method).
-
-Your driver should also implement a startUnexpectedShutdown method?

package/lib/express/README.md

@@ -1,59 +0,0 @@
-## appium-express
-
-[Express](http://expressjs.com/) server tuned for to serve [Appium](http://appium.io/).
-
-
-### Configuration
-
-The `appium-express` server comes configured with:
-
-1. appropriate logging formats
-2. service of necessary static assets
-3. allowance of cross-domain requests
-4. default error handling
-5. fix for invalid content types sent by certain clients
-
-To configure routes, a function that takes an Express server is passed into the
-server. This function can add whatever routes are wanted.
-
-
-### Usage
-
-```js
-import { server } from 'appium-base-driver';
-
-
-// configure the routes
-function configureRoutes (app) {
-  app.get('/hello', (req, res) => {
-    res.header['content-type'] = 'text/html';
-    res.status(200).send('Hello');
-  });
-  app.get('/world', (req, res) => {
-    res.header['content-type'] = 'text/html';
-    res.status(200).send('World');
-  });
-}
-
-const port = 5000;
-const host = 'localhost';
-
-const appiumServer = await server({
-  routeConfiguringFunction,
-  port,
-  host,
-});
-```
-
-
-## Watch
-
-```
-npm run watch
-```
-
-## Test
-
-```
-npm test
-```

package/lib/jsonwp-proxy/README.md

@@ -1,52 +0,0 @@
-## appium-jsonwp-proxy
-
-Proxy middleware for the Selenium [JSON Wire Protocol](https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md). Allows
-
-
-### Usage
-
-The proxy is used by instantiating with the details of the Selenium server to which to proxy. The options for the constructor are passed as a hash with the following possible members:
-
-- `scheme` - defaults to 'http'
-- `server` - defaults to 'localhost'
-- `port` - defaults to `4444`
-- `base` - defaults to ''
-- `sessionId` - the session id of the session on the remote server
-- `reqBasePath` - the base path of the server which the request was originally sent to (defaults to '')
-
-Once the proxy is created, there are two `async` methods:
-
-`command (url, method, body)`
-
-Sends a "command" to the proxied server, using the "url", which is the endpoing, with the HTTP method and optional body.
-
-```js
-import { JWProxy } from 'appium-base-driver';
-
-let host = 'my.host.com';
-let port = 4445;
-
-let proxy = new JWProxy({server: host, port: port});
-
-// get the Selenium server status
-let seStatus = await proxy.command('/status', 'GET');
-```
-
-`proxyReqRes (req, res)`
-
-Proxies a request and response to the proxied server. Used to handle the entire conversation of a request/response cycle.
-
-```js
-import { JWProxy } from 'appium-base-driver';
-import http from 'http';
-
-let host = 'my.host.com';
-let port = 4445;
-
-let proxy = new JWProxy({server: host, port: port});
-
-
-http.createServer(function (req, res) {
-  await proxy.proxyReqRes(res, res);
-}).listen(9615);
-```

package/lib/jsonwp-status/README.md

@@ -1,20 +0,0 @@
-## jsonwp-status
-
-Library of status codes for the Selenium [JSON Wire Protocol](https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md).
-
-
-### Usage
-
-```
-import { statusCodes } from 'appium-base-driver';
-
-statusCodes.NoSuchContext;
-// -> {code: 35, summary: 'No such context found'}
-```
-
-```
-import { getSummaryByCode } from 'appium-base-driver';
-
-getSummaryByCode(0);
-// -> 'The command executed successfully.'
-```

package/lib/protocol/README.md

@@ -1,100 +0,0 @@
-## webdriver and mobile-json-wire protocols
-
-An abstraction of the Mobile JSON Wire Protocol ([spec](https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md)) and the W3C Wire Protocol ([spec](https://www.w3.org/TR/webdriver/) with Appium extensions (as specified [here](http://www.w3.org/TR/webdriver/#protocol-extensions)).
-
-### Protocol Detection
-
-In the event that a session is requested, and both MJSONWP _and_ W3C capabilities are provided, like this
-
-```
-{
-  "capabilities: {
-    "alwaysMatch": {...}, 
-    "firstMatch": [{...}, ...]
-  },
-  "desiredCapabilities": {...}
-}
-```
-
-a W3C session will be served _unless_ the W3C Capabilities are incomplete. So if the `"desiredCapabilities"` object has more keys
-then whatever the capabilities were matched for the W3C capabilities, then an MJSONWP session will be served instead
-
-
-### Endpoints in the protocol
-
-The Mobile JSON Wire Protocol package gives access to a number of endpoints documented [here](https://github.com/appium/appium-base-driver/blob/master/docs/mjsonwp/protocol-methods.md).
-
-The W3C WebDriver Protocol package gives access to a number of endpoints documented in the [official documentation](https://www.w3.org/TR/webdriver/) and the 
-[simplified spec](https://github.com/jlipps/simple-wd-spec)
-
-### Protocol
-
-The basic class, subclassed by drivers that will use the protocol.
-
-
-### routeConfiguringFunction (driver)
-
-This function gives drivers access to the protocol routes. It returns a function that itself will take an [Express](http://expressjs.com/) application.
-
-
-### isSessionCommand (command)
-
-Checks if the `command` needs to have a session associated with it.
-
-
-### ALL_COMMANDS
-
-An array of all the commands that will be dispatched to by the Mobile JSON Wire Proxy endpoints.
-
-
-### NO_SESSION_ID_COMMANDS
-
-An array of commands that do not need a session associated with them.
-
-
-### Errors
-
-This package exports a number of classes and methods related to Selenium error handling. There are error classes for each Selenium error type (see [JSONWP Errors](https://code.google.com/p/selenium/wiki/JsonWireProtocol#Response_Status_Codes), as well as the context errors in the [mobile spec](https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md#webviews-and-other-contexts). 
-
-The list of errors, and their meanings, can be found [here for JSONWP](https://github.com/appium/appium-base-driver/blob/master/docs/mjsonwp/errors.md) and
-[here for W3C Errors](https://www.w3.org/TR/webdriver/#handling-errors))
-
-There are, in addition, two helper methods for dealing with errors
-
-`isErrorType (err, type)`
-
-- checks if the `err` object is a Mobile JSON Wire Protocol error of a particular type
-- arguments
-  - `err` - the error object to test
-  - `type` - the error class to test against
-- usage
-  ```js
-  import { errors, isErrorType } from 'mobile-json-wire-protocol';
-
-  try {
-    // do some stuff...
-  } catch (err) {
-    if (isErrorType(err, errors.InvalidCookieDomainError)) {
-      // process...
-    }
-  }
-  ```
-
-`errorFromCode (code, message)`
-
-- retrieve the appropriate error for an error code, with the supplied message.
-- arguments
-  - `code` - the integer error code for a Mobile JSON Wire Protocol error
-  - `message` - the message to be encapsulated in the error
-- usage
-  ```js
-  import { errors, errorFromCode } from 'mobile-json-wire-protocol';
-
-  let error = errorFromCode(6, 'an error has occurred');
-
-  console.log(error instanceof errors.NoSuchDriverError);
-  // => true
-
-  console.log(error.message === 'an error has occurred');
-  // => true
-  ```