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

package/lib/basedriver/validation.ts

@@ -0,0 +1,145 @@
+import type { Constraint } from '@appium/types';
+import log from './logger';
+import _ from 'lodash';
+
+export class Validator {
+  private readonly _validators: Record<
+    keyof Constraint,
+    (value: any, options?: any, key?: string) => string | null
+  > = {
+    isString: (value: any, options?: any): string | null => {
+      if (_.isUndefined(value) || _.isNil(options)) {
+        return null;
+      }
+
+      if (_.isString(value)) {
+        return options ? null : 'must not be of type string';
+      }
+
+      return options ? 'must be of type string' : null;
+    },
+    isNumber: (value: any, options?: any): string | null => {
+      if (_.isUndefined(value) || _.isNil(options)) {
+        return null;
+      }
+
+      if (_.isNumber(value)) {
+        return options ? null : 'must not be of type number';
+      }
+
+      // allow a string value
+      if (options && _.isString(value) && !isNaN(Number(value))) {
+        log.warn('Number capability passed in as string. Functionality may be compromised.');
+        return null;
+      }
+
+      return options ? 'must be of type number' : null;
+    },
+    isBoolean: (value: any, options?: any): string | null => {
+      if (_.isUndefined(value) || _.isNil(options)) {
+        return null;
+      }
+
+      if (_.isBoolean(value)) {
+        return options ? null : 'must not be of type boolean';
+      }
+
+      // allow a string value
+      if (options && _.isString(value) && ['true', 'false', ''].includes(value)) {
+        return null;
+      }
+
+      return options ? 'must be of type boolean' : null;
+    },
+    isObject: (value: any, options?: any): string | null => {
+      if (_.isUndefined(value) || _.isNil(options)) {
+        return null;
+      }
+
+      if (_.isPlainObject(value)) {
+        return options ? null : 'must not be a plain object';
+      }
+
+      return options ? 'must be a plain object' : null;
+    },
+    isArray: (value: any, options?: any): string | null => {
+      if (_.isUndefined(value) || _.isNil(options)) {
+        return null;
+      }
+
+      if (_.isArray(value)) {
+        return options ? null : 'must not be of type array';
+      }
+
+      return options ? 'must be of type array' : null;
+    },
+    deprecated: (value: any, options?: any, key?: string): string | null => {
+      if (!_.isUndefined(value) && options) {
+        log.warn(
+          `The '${key}' capability has been deprecated and must not be used anymore. ` +
+          `Please check the driver documentation for possible alternatives.`
+        );
+      }
+      return null;
+    },
+    inclusion: (value: any, options?: any): string | null => {
+      if (_.isUndefined(value) || !options) {
+        return null;
+      }
+      const optionsArr = _.isArray(options) ? options : [options];
+      if (optionsArr.some((opt) => opt === value)) {
+        return null;
+      }
+      return `must be contained by ${JSON.stringify(optionsArr)}`;
+    },
+    inclusionCaseInsensitive: (value: any, options?: any): string | null => {
+      if (_.isUndefined(value) || !options) {
+        return null;
+      }
+      const optionsArr = _.isArray(options) ? options : [options];
+      if (optionsArr.some((opt) => _.toLower(opt) === _.toLower(value))) {
+        return null;
+      }
+      return `must be contained by ${JSON.stringify(optionsArr)}`;
+    },
+    presence: (value: any, options?: any): string | null => {
+      if (_.isUndefined(value) && options) {
+        return 'is required to be present';
+      }
+      if (
+        !options?.allowEmpty &&
+        ((!_.isUndefined(value) && _.isEmpty(value)) || (_.isString(value) && !_.trim(value)))
+      ) {
+        return 'must not be empty or blank';
+      }
+      return null;
+    }
+  };
+
+  validate(values: Record<string, any>, constraints: Record<string, Constraint>): Record<string, string[]> | null {
+    const result: Record<string, string[]> = {};
+    for (const [key, constraint] of _.toPairs(constraints)) {
+      const value = values[key];
+      for (const [validatorName, options] of _.toPairs(constraint)) {
+        if (!(validatorName in this._validators)) {
+          continue;
+        }
+
+        const validationError = this._validators[validatorName](value, options, key);
+        if (_.isNil(validationError)) {
+          continue;
+        }
+
+        if (key in result) {
+          result[key].push(validationError);
+        } else {
+          result[key] = [validationError];
+        }
+      }
+    }
+    return _.isEmpty(result) ? null : result;
+  }
+
+}
+
+export const validator = new Validator();

package/lib/express/middleware.js

@@ -5,6 +5,9 @@ export {handleIdempotency} from './idempotency';
 import {match} from 'path-to-regexp';
 import {util} from '@appium/support';
 import {calcSignature} from '../helpers/session';
+import {getResponseForW3CError} from '../protocol/errors';
+
+const SESSION_ID_PATTERN = /\/session\/([^/]+)/;
 
 /**
  *
@@ -14,20 +17,16 @@ import {calcSignature} from '../helpers/session';
  * @returns {any}
  */
 export function allowCrossDomain(req, res, next) {
-  try {
-    res.header('Access-Control-Allow-Origin', '*');
-    res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, OPTIONS, DELETE');
-    res.header(
-      'Access-Control-Allow-Headers',
-      'Cache-Control, Pragma, Origin, X-Requested-With, Content-Type, Accept, User-Agent'
-    );
+  res.header('Access-Control-Allow-Origin', '*');
+  res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, OPTIONS, DELETE');
+  res.header(
+    'Access-Control-Allow-Headers',
+    'Cache-Control, Pragma, Origin, X-Requested-With, Content-Type, Accept, User-Agent'
+  );
 
-    // need to respond 200 to OPTIONS
-    if ('OPTIONS' === req.method) {
-      return res.sendStatus(200);
-    }
-  } catch (err) {
-    log.error(`Unexpected error: ${err.stack}`);
+  // need to respond 200 to OPTIONS
+  if ('OPTIONS' === req.method) {
+    return res.sendStatus(200);
   }
   next();
 }
@@ -50,26 +49,6 @@ export function allowCrossDomainAsyncExecute(basePath) {
   };
 }
 
-/**
- *
- * @param {string} basePath
- * @returns {import('express').RequestHandler}
- */
-export function fixPythonContentType(basePath) {
-  return (req, res, next) => {
-    // hack because python client library gives us wrong content-type
-    if (
-      new RegExp(`^${_.escapeRegExp(basePath)}`).test(req.path) &&
-      /^Python/.test(req.headers['user-agent'] ?? '')
-    ) {
-      if (req.headers['content-type'] === 'application/x-www-form-urlencoded') {
-        req.headers['content-type'] = 'application/json; charset=utf-8';
-      }
-    }
-    next();
-  };
-}
-
 /**
  *
  * @param {import('express').Request} req
@@ -78,12 +57,17 @@ export function fixPythonContentType(basePath) {
  * @returns {any}
  */
 export function handleLogContext(req, res, next) {
-  const requestId = util.uuidV4();
+  const requestId = fetchHeaderValue(req, 'x-request-id') || util.uuidV4();
 
   const sessionId = SESSION_ID_PATTERN.exec(req.url)?.[1];
   const sessionInfo = sessionId ? {sessionId, sessionSignature: calcSignature(sessionId)} : {};
+  const isSensitiveHeaderValue = fetchHeaderValue(req, 'x-appium-is-sensitive');
 
-  log.updateAsyncContext({requestId, ...sessionInfo}, true);
+  log.updateAsyncContext({
+    requestId,
+    ...sessionInfo,
+    isSensitive: ['true', '1', 'yes'].includes(_.toLower(isSensitiveHeaderValue)),
+  }, true);
 
   return next();
 }
@@ -142,19 +126,8 @@ export function catchAllHandler(err, req, res, next) {
   }
 
   log.error(`Uncaught error: ${err.message}`);
-  log.error('Sending generic error response');
-  const error = errors.UnknownError;
-  res.status(error.w3cStatus()).json(
-    patchWithSessionId(req, {
-      status: error.code(),
-      value: {
-        error: error.error(),
-        message: `An unknown server-side error occurred while processing the command: ${err.message}`,
-        stacktrace: err.stack,
-      },
-    })
-  );
-  log.error(err);
+  const [status, body] = getResponseForW3CError(err);
+  res.status(status).json(body);
 }
 
 /**
@@ -163,28 +136,17 @@ export function catchAllHandler(err, req, res, next) {
  */
 export function catch404Handler(req, res) {
   log.debug(`No route found for ${req.url}`);
-  const error = errors.UnknownCommandError;
-  res.status(error.w3cStatus()).json(
-    patchWithSessionId(req, {
-      status: error.code(),
-      value: {
-        error: error.error(),
-        message:
-          'The requested resource could not be found, or a request was ' +
-          'received using an HTTP method that is not supported by the mapped ' +
-          'resource',
-        stacktrace: '',
-      },
-    })
-  );
+  const [status, body] = getResponseForW3CError(new errors.UnknownCommandError());
+  res.status(status).json(body);
 }
 
-const SESSION_ID_PATTERN = /\/session\/([^/]+)/;
-
-function patchWithSessionId(req, body) {
-  const match = SESSION_ID_PATTERN.exec(req.url);
-  if (match) {
-    body.sessionId = match[1];
-  }
-  return body;
+/**
+ * @param {import('express').Request} req
+ * @param {string} name
+ * @returns {string | undefined}
+ */
+function fetchHeaderValue(req, name) {
+  return _.isArray(req.headers[name])
+    ? req.headers[name][0]
+    : req.headers[name];
 }

package/lib/express/server.js

@@ -9,7 +9,6 @@ import log from './logger';
 import {startLogFormatter, endLogFormatter} from './express-logging';
 import {
   allowCrossDomain,
-  fixPythonContentType,
   defaultToJSONContentType,
   catchAllHandler,
   allowCrossDomainAsyncExecute,
@@ -172,7 +171,6 @@ export function configureServer({
     app.use(allowCrossDomainAsyncExecute(basePath));
   }
   app.use(handleIdempotency);
-  app.use(fixPythonContentType(basePath));
   app.use(defaultToJSONContentType);
   app.use(bodyParser.urlencoded({extended: true}));
   app.use(methodOverride());

package/lib/helpers/capabilities.js

@@ -2,7 +2,14 @@
 
 import _ from 'lodash';
 
-function isW3cCaps(caps) {
+/**
+ * Determine whether the given agument is valid
+ * W3C capabilities instance.
+ *
+ * @param {any} caps
+ * @returns {caps is import('@appium/types').W3CCapabilities}
+ */
+export function isW3cCaps(caps) {
   if (!_.isPlainObject(caps)) {
     return false;
   }
@@ -32,7 +39,7 @@ function isW3cCaps(caps) {
  * @param {AppiumLogger} log
  * @returns {Capabilities<C>}
  */
-function fixCaps(oldCaps, desiredCapConstraints, log) {
+export function fixCaps(oldCaps, desiredCapConstraints, log) {
   let caps = _.clone(oldCaps);
 
   // boolean capabilities can be passed in as strings 'false' and 'true'
@@ -73,8 +80,6 @@ function fixCaps(oldCaps, desiredCapConstraints, log) {
   return caps;
 }
 
-export {isW3cCaps, fixCaps};
-
 /**
  * @typedef {import('@appium/types').Constraints} Constraints
  * @typedef {import('@appium/types').AppiumLogger} AppiumLogger

package/lib/index.js

@@ -54,6 +54,8 @@ export {BIDI_COMMANDS} from './protocol/bidi-commands';
 
 export {generateDriverLogPrefix} from './basedriver/helpers';
 
+export {isW3cCaps} from './helpers/capabilities';
+
 /**
  * @typedef {import('./express/server').ServerOpts} ServerOpts
  */

package/lib/jsonwp-proxy/proxy.js

@@ -11,7 +11,7 @@ import {
 import {isSessionCommand, routeToCommandName} from '../protocol';
 import {MAX_LOG_BODY_LENGTH, DEFAULT_BASE_PATH, PROTOCOLS} from '../constants';
 import ProtocolConverter from './protocol-converter';
-import {formatResponseValue, formatStatus} from '../protocol/helpers';
+import {formatResponseValue, ensureW3cResponse} from '../protocol/helpers';
 import http from 'http';
 import https from 'https';
 import { match as pathToRegexMatch } from 'path-to-regexp';
@@ -290,37 +290,6 @@ export class JWProxy {
     }
   }
 
-  /**
-   * @deprecated This method is not used anymore and will be removed
-   *
-   * @param {string} url
-   * @param {import('@appium/types').HTTPMethod} method
-   * @returns {string|undefined}
-   */
-  requestToCommandName(url, method) {
-    /**
-     *
-     * @param {RegExp} pattern
-     * @returns {string|undefined}
-     */
-    const extractCommandName = (pattern) => {
-      const pathMatch = pattern.exec(url);
-      if (pathMatch) {
-        return routeToCommandName(pathMatch[1], method, this.reqBasePath);
-      }
-    };
-    let commandName = routeToCommandName(url, method, this.reqBasePath);
-    if (!commandName && _.includes(url, `${this.reqBasePath}/session/`)) {
-      commandName = extractCommandName(
-        new RegExp(`${_.escapeRegExp(this.reqBasePath)}/session/[^/]+(.+)`)
-      );
-    }
-    if (!commandName && _.includes(url, this.reqBasePath)) {
-      commandName = extractCommandName(new RegExp(`${_.escapeRegExp(this.reqBasePath)}(/.+)`));
-    }
-    return commandName;
-  }
-
   /**
    *
    * @param {string} url
@@ -428,18 +397,13 @@ export class JWProxy {
         /** @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(
         isErrorType(err, errors.ProxyRequestError) ? err.getActualError() : err
       );
     }
-    res.set('content-type', 'application/json; charset=utf-8');
+    res.setHeader('content-type', 'application/json; charset=utf-8');
     if (!_.isPlainObject(resBodyObj)) {
       const error = new errors.UnknownError(
         `The downstream server response with the status code ${statusCode} is not a valid JSON object: ` +
@@ -462,7 +426,7 @@ export class JWProxy {
       }
     }
     resBodyObj.value = formatResponseValue(resBodyObj.value);
-    res.status(statusCode).send(JSON.stringify(formatStatus(resBodyObj)));
+    res.status(statusCode).json(ensureW3cResponse(resBodyObj));
   }
 
   /**
@@ -503,12 +467,11 @@ export class JWProxy {
         pathname = pathname.replace('/wd/hub', '');
       }
     }
-    return _.trimEnd(
-      match && _.isArray(match.params?.command)
-        ? `/${match.params.command.join('/')}`
-        : pathname,
-      '/'
-    );
+    let result = pathname;
+    if (match) {
+      result = _.isArray(match.params?.command) ? `/${match.params.command.join('/')}` : '';
+    }
+    return _.trimEnd(result, '/');
   }
 }