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

package/lib/basedriver/helpers.js

@@ -2,7 +2,7 @@ import _ from 'lodash';
 import path from 'path';
 import url from 'url';
 import logger from './logger';
-import {tempDir, fs, util, zip, timing, node} from '@appium/support';
+import {tempDir, fs, util, timing, node} from '@appium/support';
 import { LRUCache } from 'lru-cache';
 import AsyncLock from 'async-lock';
 import axios from 'axios';
@@ -10,9 +10,6 @@ import B from 'bluebird';
 
 // for compat with running tests transpiled and in-place
 export const {version: BASEDRIVER_VER} = fs.readPackageJsonFrom(__dirname);
-const IPA_EXT = '.ipa';
-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_MS = 1000 * 60 * toNaturalNumber(60 * 24, 'APPIUM_APPS_CACHE_MAX_AGE');
 const MAX_CACHED_APPS = toNaturalNumber(1024, 'APPIUM_APPS_CACHE_MAX_ITEMS');
 const HTTP_STATUS_NOT_MODIFIED = 304;
@@ -62,9 +59,17 @@ process.on('exit', () => {
 });
 
 /**
+ * Perform inital application package configuration
+ * to prepare it for the further consumption by a driver:
+ *
+ * - Manages caching logic
+ * - Downloads the app from a remote URL to the local filesystem
+ * - Determines package name
+ * - Checks basic requiremenets on the application package
  *
  * @param {string} app
  * @param {string|string[]|import('@appium/types').ConfigureAppOptions} options
+ * @returns {Promise<string>}
  */
 export async function configureApp(
   app,
@@ -72,9 +77,10 @@ export async function configureApp(
 ) {
   if (!_.isString(app)) {
     // immediately shortcircuit if not given an app
-    return;
+    return '';
   }
 
+  /** @type {string[]} */
   let supportedAppExtensions;
   const onPostProcess = !_.isString(options) && !_.isArray(options) ? options.onPostProcess : undefined;
   const onDownload = !_.isString(options) && !_.isArray(options) ? options.onDownload : undefined;
@@ -86,13 +92,13 @@ export async function configureApp(
   } else if (_.isPlainObject(options)) {
     supportedAppExtensions = options.supportedExtensions;
   }
+  // @ts-ignore this is OK
   if (_.isEmpty(supportedAppExtensions)) {
     throw new Error(`One or more supported app extensions must be provided`);
   }
 
   let newApp = app;
   const originalAppLink = app;
-  let shouldUnzipApp = false;
   let packageHash = null;
   /** @type {import('axios').AxiosResponse['headers']|undefined} */
   let headers = undefined;
@@ -172,67 +178,19 @@ export async function configureApp(
           ({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-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 (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}`;
-        }
-        newApp = onDownload
-          ? await onDownload({
+        if (onDownload) {
+          newApp = await onDownload({
             url: originalAppLink,
             headers: /** @type {import('@appium/types').HTTPHeaders} */ (_.clone(headers)),
             stream,
-          })
-          : await fetchApp(stream, await tempDir.path({
+          });
+        } else {
+          const fileName = determineFilename(headers, pathname, supportedAppExtensions);
+          newApp = await fetchApp(stream, await tempDir.path({
             prefix: fileName,
             suffix: '',
           }));
+        }
       } finally {
         if (!stream.closed) {
           stream.destroy();
@@ -241,7 +199,6 @@ export async function configureApp(
     } else if (await fs.exists(newApp)) {
       // Use the local app
       logger.info(`Using local app '${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
@@ -258,34 +215,7 @@ export async function configureApp(
       packageHash = await calculateFileIntegrity(newApp);
     }
 
-    if (isPackageAFile && shouldUnzipApp && !_.isFunction(onPostProcess)) {
-      const archivePath = newApp;
-      if (packageHash === cachedAppInfo?.packageHash) {
-        const fullPath = cachedAppInfo?.fullPath;
-        if (await isAppIntegrityOk(/** @type {string} */ (fullPath), cachedAppInfo?.integrity)) {
-          if (archivePath !== app) {
-            await fs.rimraf(archivePath);
-          }
-          logger.info(`Will reuse previously cached application at '${fullPath}'`);
-          return verifyAppExtension(/** @type {string} */ (fullPath), supportedAppExtensions);
-        }
-        logger.info(
-          `The application at '${fullPath}' does not exist anymore ` +
-            `or its integrity has been damaged. Deleting it from the cache`
-        );
-        APPLICATIONS_CACHE.delete(appCacheKey);
-      }
-      const tmpRoot = await tempDir.openDir();
-      try {
-        newApp = await unzipApp(archivePath, tmpRoot, supportedAppExtensions);
-      } finally {
-        if (newApp !== archivePath && archivePath !== app) {
-          await fs.rimraf(archivePath);
-        }
-      }
-      logger.info(`Unzipped local app to '${newApp}'`);
-    }
-
+    /** @type {(appPathToCache: string) => Promise<string>} */
     const storeAppInCache = async (appPathToCache) => {
       const cachedFullPath = cachedAppInfo?.fullPath;
       if (cachedFullPath && cachedFullPath !== appPathToCache) {
@@ -496,83 +426,6 @@ async function fetchApp(srcStream, dstPath) {
   return dstPath;
 }
 
-/**
- * Extracts the bundle from an archive into the given folder
- *
- * @param {string} zipPath Full path to the archive containing the bundle
- * @param {string} dstRoot Full path to the folder where the extracted bundle
- * should be placed
- * @param {Array<string>|string} supportedAppExtensions The list of extensions
- * the target application bundle supports, for example ['.apk', '.apks'] for
- * Android packages
- * @returns {Promise<string>} Full path to the bundle in the destination folder
- * @throws {Error} If the given archive is invalid or no application bundles
- * have been found inside
- */
-async function unzipApp(zipPath, dstRoot, supportedAppExtensions) {
-  await zip.assertValidZip(zipPath);
-
-  if (!_.isArray(supportedAppExtensions)) {
-    supportedAppExtensions = [supportedAppExtensions];
-  }
-
-  const tmpRoot = await tempDir.openDir();
-  try {
-    logger.debug(`Unzipping '${zipPath}'`);
-    const timer = new timing.Timer().start();
-    const useSystemUnzip = isEnvOptionEnabled('APPIUM_PREFER_SYSTEM_UNZIP', true);
-    /**
-     * Attempt to use use the system `unzip` (e.g., `/usr/bin/unzip`) due
-     * to the significant performance improvement it provides over the native
-     * JS "unzip" implementation.
-     * @type {import('@appium/support/lib/zip').ExtractAllOptions}
-     */
-    const extractionOpts = {useSystemUnzip};
-    // https://github.com/appium/appium/issues/14100
-    if (path.extname(zipPath) === IPA_EXT) {
-      logger.debug(
-        `Enforcing UTF-8 encoding on the extracted file names for '${path.basename(zipPath)}'`
-      );
-      extractionOpts.fileNamesEncoding = 'utf8';
-    }
-    await zip.extractAllTo(zipPath, tmpRoot, extractionOpts);
-    const globPattern = `**/*.+(${supportedAppExtensions
-      .map((ext) => ext.replace(/^\./, ''))
-      .join('|')})`;
-    const sortedBundleItems = (
-      await fs.glob(globPattern, {
-        cwd: tmpRoot,
-        // Get the top level match
-      })
-    ).sort((a, b) => a.split(path.sep).length - b.split(path.sep).length);
-    if (_.isEmpty(sortedBundleItems)) {
-      throw logger.errorWithException(
-        `App unzipped OK, but we could not find any '${supportedAppExtensions}' ` +
-          util.pluralize('bundle', supportedAppExtensions.length, false) +
-          ` in it. Make sure your archive contains at least one package having ` +
-          `'${supportedAppExtensions}' ${util.pluralize(
-            'extension',
-            supportedAppExtensions.length,
-            false
-          )}`
-      );
-    }
-    logger.debug(
-      `Extracted ${util.pluralize('bundle item', sortedBundleItems.length, true)} ` +
-        `from '${zipPath}' in ${Math.round(
-          timer.getDuration().asMilliSeconds
-        )}ms: ${sortedBundleItems}`
-    );
-    const matchedBundle = /** @type {string} */ (_.first(sortedBundleItems));
-    logger.info(`Assuming '${matchedBundle}' is the correct bundle`);
-    const dstPath = path.resolve(dstRoot, path.basename(matchedBundle));
-    await fs.mv(path.resolve(tmpRoot, matchedBundle), dstPath, {mkdirp: true});
-    return dstPath;
-  } finally {
-    await fs.rimraf(tmpRoot);
-  }
-}
-
 /**
  * Transforms the given app link to the cache key.
  * This is necessary to properly cache apps
@@ -614,6 +467,47 @@ function parseAppLink(appLink) {
   }
 }
 
+/**
+ * Tries to determine the file name of the payload that is going
+ * to be downloaded from an URL
+ *
+ * @param {import('axios').RawAxiosRequestHeaders} headers
+ * @param {string} pathname
+ * @param {string[]} supportedAppExtensions
+ * @returns {string}
+ */
+function determineFilename(headers, pathname, supportedAppExtensions) {
+  const basename = fs.sanitizeName(path.basename(decodeURIComponent(pathname ?? '')), {
+    replacement: SANITIZE_REPLACEMENT,
+  });
+  const extname = path.extname(basename);
+  if (headers['content-disposition'] && /^attachment/i.test(
+    /** @type {string} */ (headers['content-disposition']
+  ))) {
+    logger.debug(`Content-Disposition: ${headers['content-disposition']}`);
+    const match = /filename="([^"]+)/i.exec(/** @type {string} */ (headers['content-disposition']));
+    if (match) {
+      return fs.sanitizeName(match[1], {
+        replacement: SANITIZE_REPLACEMENT,
+      });
+    }
+  }
+
+  // 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.map(_.toLower).includes(_.toLower(resultingExt))) {
+    logger.info(
+      `The current file extension '${resultingExt}' is not supported. ` +
+        `Defaulting to '${_.first(supportedAppExtensions)}'`
+    );
+    resultingExt = /** @type {string} */ (_.first(supportedAppExtensions));
+  }
+  return `${resultingName}${resultingExt}`;
+}
+
 /**
  * Checks whether we can threat the given app link
  * as a URL,

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
  */