appium 2.0.0-beta.2 → 2.0.0-beta.20

package/lib/ext-config-io.js

@@ -0,0 +1,287 @@
+// @ts-check
+
+/**
+ * Module containing {@link ExtConfigIO} which handles reading & writing of extension config files.
+ */
+
+import { fs, mkdirp } from '@appium/support';
+import _ from 'lodash';
+import path from 'path';
+import YAML from 'yaml';
+
+const CONFIG_FILE_NAME = 'extensions.yaml';
+
+/**
+ * Current configuration schema revision!
+ */
+const CONFIG_SCHEMA_REV = 2;
+
+export const DRIVER_TYPE = 'driver';
+export const PLUGIN_TYPE = 'plugin';
+
+/**
+ * Set of valid extension types.
+ * @type {Readonly<Set<ExtensionType>>}
+ */
+const VALID_EXT_TYPES = new Set([DRIVER_TYPE, PLUGIN_TYPE]);
+
+const CONFIG_DATA_DRIVER_KEY = `${DRIVER_TYPE}s`;
+const CONFIG_DATA_PLUGIN_KEY = `${PLUGIN_TYPE}s`;
+
+/**
+ * Handles reading & writing of extension config files.
+ *
+ * Only one instance of this class exists per value of `APPIUM_HOME`.
+ */
+class ExtConfigIO {
+  /**
+   * "Dirty" flag. If true, the data has changed since the last write.
+   * @type {boolean}
+   * @private
+   */
+  _dirty;
+
+  /**
+   * The entire contents of a parsed YAML extension config file.
+   * @type {object?}
+   * @private
+   */
+  _data;
+
+  /**
+   * A mapping of extension type to configuration data. Configuration data is
+   * keyed on extension name.
+   *
+   * Consumers get the values of this `Map` (corresponding to the
+   * `extensionType` of the consumer, which will be a subclass of
+   * `ExtensionConfig`) and do not have access to the entire data object.
+   * @private
+   * @type {Map<ExtensionType,object>}
+   */
+  _extDataByType = new Map();
+
+  /**
+   * Path to config file.
+   * @private
+   * @type {Readonly<string>}
+   */
+  _filepath;
+
+  /**
+   * Path to `APPIUM_HOME`
+   * @private
+   * @type {Readonly<string>}
+   */
+  _appiumHome;
+
+  /**
+   * Helps avoid writing multiple times.
+   *
+   * If this is `null`, calling {@link ExtConfigIO.write} will cause it to be
+   * set to a `Promise`. When the call to `write()` is complete, the `Promise`
+   * will resolve and then this value will be set to `null`.  Concurrent calls
+   * made while this value is a `Promise` will return the `Promise` itself.
+   * @private
+   * @type {Promise<boolean>?}
+   */
+  _writing = null;
+
+  /**
+   * Helps avoid reading multiple times.
+   *
+   * If this is `null`, calling {@link ExtConfigIO.read} will cause it to be
+   * set to a `Promise`. When the call to `read()` is complete, the `Promise`
+   * will resolve and then this value will be set to `null`.  Concurrent calls
+   * made while this value is a `Promise` will return the `Promise` itself.
+   * @private
+   * @type {Promise<void>?}
+   */
+  _reading = null;
+
+  /**
+   * @param {string} appiumHome
+   */
+  constructor (appiumHome) {
+    this._filepath = path.resolve(appiumHome, CONFIG_FILE_NAME);
+    this._appiumHome = appiumHome;
+  }
+
+  /**
+   * Creaes a `Proxy` which watches for changes to the extension-type-specific
+   * config data.
+   *
+   * When changes are detected, it sets a `_dirty` flag.  The next call to
+   * {@link ExtConfigIO.write} will check if this flag is `true` before
+   * proceeding.
+   * @param {ExtensionType} extensionType
+   * @param {Record<string,object>} data - Extension config data, keyed by name
+   * @private
+   * @returns {Record<string,object>}
+   */
+  _createProxy (extensionType, data) {
+    return new Proxy(data[`${extensionType}s`], {
+      set: (target, prop, value) => {
+        if (value !== target[prop]) {
+          this._dirty = true;
+        }
+        target[prop] = value;
+        return Reflect.set(target, prop, value);
+      },
+      deleteProperty: (target, prop) => {
+        if (prop in target) {
+          this._dirty = true;
+        }
+        return Reflect.deleteProperty(target, prop);
+      },
+    });
+  }
+
+  /**
+   * Returns the path to the config file.
+   */
+  get filepath () {
+    return this._filepath;
+  }
+
+  /**
+   * Gets data for an extension type.  Reads the config file if necessary.
+   *
+   * Force-reading is _not_ supported, as it's likely to be a source of
+   * bugs--it's easy to mutate the data and then overwrite memory with the file
+   * contents
+   *
+   * Ideally this will only ever read the file _once_.
+   * @param {ExtensionType} extensionType - Which bit of the config data we
+   * want
+   * @returns {Promise<object>} The data
+   */
+  async read (extensionType) {
+    if (this._reading) {
+      await this._reading;
+      return this._extDataByType.get(extensionType);
+    }
+
+    this._reading = (async () => {
+      if (!VALID_EXT_TYPES.has(extensionType)) {
+        throw new TypeError(
+          `Invalid extension type: ${extensionType}. Valid values are: ${[
+            ...VALID_EXT_TYPES,
+          ].join(', ')}`,
+        );
+      }
+      if (this._extDataByType.has(extensionType)) {
+        return;
+      }
+
+      let data;
+      let isNewFile = false;
+      try {
+        await mkdirp(this._appiumHome);
+        const yaml = await fs.readFile(this.filepath, 'utf8');
+        data = YAML.parse(yaml);
+      } catch (err) {
+        if (err.code === 'ENOENT') {
+          data = {
+            [CONFIG_DATA_DRIVER_KEY]: {},
+            [CONFIG_DATA_PLUGIN_KEY]: {},
+            schemaRev: CONFIG_SCHEMA_REV,
+          };
+          isNewFile = true;
+        } else {
+          throw new Error(
+            `Appium had trouble loading the extension installation ` +
+              `cache file (${this.filepath}). Ensure it exists and is ` +
+              `readable. Specific error: ${err.message}`,
+          );
+        }
+      }
+
+      this._data = data;
+      this._extDataByType.set(
+        DRIVER_TYPE,
+        this._createProxy(DRIVER_TYPE, data),
+      );
+      this._extDataByType.set(
+        PLUGIN_TYPE,
+        this._createProxy(PLUGIN_TYPE, data),
+      );
+
+      if (isNewFile) {
+        await this.write(true);
+      }
+    })();
+    try {
+      await this._reading;
+      return this._extDataByType.get(extensionType);
+    } finally {
+      this._reading = null;
+    }
+  }
+
+  /**
+   * Writes the data if it needs writing.
+   *
+   * If the `schemaRev` prop needs updating, the file will be written.
+   * @param {boolean} [force=false] - Whether to force a write even if the data is clean
+   * @returns {Promise<boolean>} Whether the data was written
+   */
+  async write (force = false) {
+    if (this._writing) {
+      return this._writing;
+    }
+    this._writing = (async () => {
+      try {
+        if (!this._dirty && !force) {
+          return false;
+        }
+
+        if (!this._data) {
+          throw new ReferenceError('No data to write. Call `read()` first');
+        }
+
+        const dataToWrite = {
+          ...this._data,
+          [CONFIG_DATA_DRIVER_KEY]: this._extDataByType.get(DRIVER_TYPE),
+          [CONFIG_DATA_PLUGIN_KEY]: this._extDataByType.get(PLUGIN_TYPE),
+        };
+
+        try {
+          await fs.writeFile(
+            this.filepath,
+            YAML.stringify(dataToWrite),
+            'utf8',
+          );
+          this._dirty = false;
+          return true;
+        } catch {
+          throw new Error(
+            `Appium could not parse or write from the Appium Home directory ` +
+              `(${this._appiumHome}). Please ensure it is writable.`,
+          );
+        }
+      } finally {
+        this._writing = null;
+      }
+    })();
+    return await this._writing;
+  }
+}
+
+/**
+ * Factory function for {@link ExtConfigIO}.
+ *
+ * Maintains one instance per value of `APPIUM_HOME`.
+ * @param {string} appiumHome - `APPIUM_HOME`
+ * @returns {ExtConfigIO}
+ */
+export const getExtConfigIOInstance = _.memoize(
+  (appiumHome) => new ExtConfigIO(appiumHome),
+);
+
+/**
+ * @typedef {ExtConfigIO} ExtensionConfigIO
+ */
+
+/**
+ * @typedef {typeof DRIVER_TYPE | typeof PLUGIN_TYPE} ExtensionType
+ */

package/lib/extension-config.js

@@ -1,15 +1,15 @@
+// @ts-check
+
 import _ from 'lodash';
-import log from './logger';
-import { fs, mkdirp } from 'appium-support';
+import os from 'os';
 import path from 'path';
-import YAML from 'yaml';
-
-const DRIVER_TYPE = 'driver';
-const PLUGIN_TYPE = 'plugin';
-const DEFAULT_APPIUM_HOME = path.resolve(process.env.HOME, '.appium');
+import resolveFrom from 'resolve-from';
+import { getExtConfigIOInstance } from './ext-config-io';
+import log from './logger';
+import { ALLOWED_SCHEMA_EXTENSIONS, isAllowedSchemaFileExtension, registerSchema } from './schema/schema';
 
-const CONFIG_FILE_NAME = 'extensions.yaml';
-const CONFIG_SCHEMA_REV = 2;
+const DEFAULT_APPIUM_HOME = path.resolve(os.homedir(), '.appium');
+const APPIUM_HOME = process.env.APPIUM_HOME || DEFAULT_APPIUM_HOME;
 
 const INSTALL_TYPE_NPM = 'npm';
 const INSTALL_TYPE_LOCAL = 'local';
@@ -22,27 +22,44 @@ const INSTALL_TYPES = [
   INSTALL_TYPE_NPM
 ];
 
-
 export default class ExtensionConfig {
-  constructor (appiumHome, extensionType, logFn = null) {
-    if (logFn === null) {
-      logFn = log.error.bind(log);
-    }
+  /**
+   *
+   * @param {string} appiumHome - `APPIUM_HOME`
+   * @param {ExtensionType} extensionType - Type of extension
+   * @param {(...args: any[]) => void} [logFn]
+   */
+  constructor (appiumHome, extensionType, logFn) {
+    const logger = _.isFunction(logFn) ? logFn : log.error.bind(log);
+    /** @type {string} */
     this.appiumHome = appiumHome;
-    this.configFile = path.resolve(this.appiumHome, CONFIG_FILE_NAME);
+    /** @type {Record<string,object>} */
     this.installedExtensions = {};
+    /** @type {import('./ext-config-io').ExtensionConfigIO} */
+    this.io = getExtConfigIOInstance(appiumHome);
+    /** @type {ExtensionType} */
     this.extensionType = extensionType;
-    this.configKey = `${extensionType}s`;
-    this.yamlData = {[`${DRIVER_TYPE}s`]: {}, [`${PLUGIN_TYPE}s`]: {}};
-    this.log = logFn;
+    /** @type {'drivers'|'plugins'} */
+    this.configKey = `${extensionType}s`; // todo use template type
+    /**
+     * @type {(...args: any[])=>void}
+     */
+    this.log = logger;
   }
 
+  /**
+   * Checks extensions for problems
+   * @template ExtData
+   * @param {ExtData[]} exts - Array of extData objects
+   * @returns {ExtData[]}
+   */
   validate (exts) {
     const foundProblems = {};
     for (const [extName, extData] of _.toPairs(exts)) {
       foundProblems[extName] = [
-        ...this.getGenericConfigProblems(extData),
-        ...this.getConfigProblems(extData)
+        ...this.getGenericConfigProblems(extData, extName),
+        ...this.getConfigProblems(extData, extName),
+        ...this.getSchemaProblems(extData, extName)
       ];
     }
 
@@ -63,7 +80,7 @@ export default class ExtensionConfig {
 
     if (!_.isEmpty(problemSummaries)) {
       this.log(`Appium encountered one or more errors while validating ` +
-               `the ${this.configKey} extension file (${this.configFile}):`);
+               `the ${this.configKey} extension file (${this.io.filepath}):`);
       for (const summary of problemSummaries) {
         this.log(summary);
       }
@@ -72,8 +89,52 @@ export default class ExtensionConfig {
     return exts;
   }
 
-  getGenericConfigProblems (ext) {
-    const {version, pkgName, installSpec, installType, installPath, mainClass} = ext;
+  /**
+   * @param {object} extData
+   * @param {string} extName
+   * @returns {Problem[]}
+   */
+  getSchemaProblems (extData, extName) {
+    const problems = [];
+    const {schema: argSchemaPath} = extData;
+    if (argSchemaPath) {
+      if (_.isString(argSchemaPath)) {
+        if (isAllowedSchemaFileExtension(argSchemaPath)) {
+          try {
+            this.readExtensionSchema(extName, extData);
+          } catch (err) {
+            problems.push({err: `Unable to register schema at path ${argSchemaPath}; ${err.message}`, val: argSchemaPath});
+          }
+        } else {
+          problems.push({
+            err: `Schema file has unsupported extension. Allowed: ${[...ALLOWED_SCHEMA_EXTENSIONS].join(', ')}`,
+            val: argSchemaPath
+          });
+        }
+      } else if (_.isPlainObject(argSchemaPath)) {
+        try {
+          this.readExtensionSchema(extName, extData);
+        } catch (err) {
+          problems.push({err: `Unable to register embedded schema; ${err.message}`, val: argSchemaPath});
+        }
+      } else {
+        problems.push({
+          err: 'Incorrectly formatted schema field; must be a path to a schema file or a schema object.',
+          val: argSchemaPath
+        });
+      }
+    }
+    return problems;
+  }
+
+  /**
+   * @param {object} extData
+   * @param {string} extName
+   * @returns {Problem[]}
+   */
+  // eslint-disable-next-line no-unused-vars
+  getGenericConfigProblems (extData, extName) {
+    const {version, pkgName, installSpec, installType, installPath, mainClass} = extData;
     const problems = [];
 
     if (!_.isString(version)) {
@@ -103,62 +164,60 @@ export default class ExtensionConfig {
     return problems;
   }
 
-  getConfigProblems (/*ext*/) {
+  /**
+   * @param {object} extData
+   * @param {string} extName
+   * @returns {Problem[]}
+   */
+  // eslint-disable-next-line no-unused-vars
+  getConfigProblems (extData, extName) {
     // shoud override this method if special validation is necessary for this extension type
     return [];
   }
 
-  applySchemaMigrations () {
-    if (this.yamlData.schemaRev < 2 && _.isUndefined(this.yamlData[PLUGIN_TYPE])) {
-      // at schema revision 2, we started including plugins as well as drivers in the file,
-      // so make sure we at least have an empty section for it
-      this.yamlData[PLUGIN_TYPE] = {};
-    }
-  }
-
+  /**
+   * @returns {Promise<typeof this.installedExtensions>}
+   */
   async read () {
-    await mkdirp(this.appiumHome); // ensure appium home exists
-    try {
-      this.yamlData = YAML.parse(await fs.readFile(this.configFile, 'utf8'));
-      this.applySchemaMigrations();
-
-      // set the list of drivers the user has installed
-      this.installedExtensions = this.validate(this.yamlData[this.configKey]);
-    } catch (err) {
-      if (await fs.exists(this.configFile)) {
-        // if the file exists and we couldn't parse it, that's a problem
-        throw new Error(`Appium had trouble loading the extension installation ` +
-                        `cache file (${this.configFile}). Ensure it exists and is ` +
-                        `readable. Specific error: ${err.message}`);
-      }
-
-      // if the config file doesn't exist, try to write an empty one, to make
-      // sure we actually have write privileges, and complain if we don't
-      try {
-        await this.write();
-      } catch {
-        throw new Error(`Appium could not read or write from the Appium Home directory ` +
-                        `(${this.appiumHome}). Please ensure it is writable.`);
-      }
-    }
+    const extensions = await this.io.read(this.extensionType);
+    this.installedExtensions = this.validate(extensions);
     return this.installedExtensions;
   }
 
-
+  /**
+   * @returns {Promise<boolean>}
+   */
   async write () {
-    const newYamlData = {
-      ...this.yamlData,
-      schemaRev: CONFIG_SCHEMA_REV,
-      [this.configKey]: this.installedExtensions
-    };
-    await fs.writeFile(this.configFile, YAML.stringify(newYamlData), 'utf8');
+    return await this.io.write();
   }
 
+  /**
+   * @param {string} extName
+   * @param {object} extData
+   * @returns {Promise<void>}
+   */
   async addExtension (extName, extData) {
     this.installedExtensions[extName] = extData;
     await this.write();
   }
 
+  /**
+   * @param {string} extName
+   * @param {object} extData
+   * @returns {Promise<void>}
+   */
+  async updateExtension (extName, extData) {
+    this.installedExtensions[extName] = {
+      ...this.installedExtensions[extName],
+      ...extData,
+    };
+    await this.write();
+  }
+
+  /**
+   * @param {string} extName
+   * @returns {Promise<void>}
+   */
   async removeExtension (extName) {
     delete this.installedExtensions[extName];
     await this.write();
@@ -178,31 +237,130 @@ export default class ExtensionConfig {
     }
   }
 
-  extensionDesc () {
-    throw new Error('This must be implemented in a final class');
+  /**
+   * Returns a string describing the extension. Subclasses must implement.
+   * @param {string} extName - Extension name
+   * @param {object} extData - Extension data
+   * @returns {string}
+   * @abstract
+   */
+  // eslint-disable-next-line no-unused-vars
+  extensionDesc (extName, extData) {
+    throw new Error('This must be implemented in a subclass');
   }
 
+  /**
+   * @param {string} extName
+   * @returns {string}
+   */
   getExtensionRequirePath (extName) {
     const {pkgName, installPath} = this.installedExtensions[extName];
     return path.resolve(this.appiumHome, installPath, 'node_modules', pkgName);
   }
 
+  /**
+   * @param {string} extName
+   * @returns {string}
+   */
   getInstallPath (extName) {
     const {installPath} = this.installedExtensions[extName];
     return path.resolve(this.appiumHome, installPath);
   }
 
+  /**
+   * Loads extension and returns its main class
+   * @param {string} extName
+   * @returns {(...args: any[]) => object }
+   */
   require (extName) {
     const {mainClass} = this.installedExtensions[extName];
-    return require(this.getExtensionRequirePath(extName))[mainClass];
+    const reqPath = this.getExtensionRequirePath(extName);
+    const reqResolved = require.resolve(reqPath);
+    if (process.env.APPIUM_RELOAD_EXTENSIONS && require.cache[reqResolved]) {
+      log.debug(`Removing ${reqResolved} from require cache`);
+      delete require.cache[reqResolved];
+    }
+    return require(reqPath)[mainClass];
   }
 
+  /**
+   * @param {string} extName
+   * @returns {boolean}
+   */
   isInstalled (extName) {
     return _.includes(Object.keys(this.installedExtensions), extName);
   }
+
+  /**
+   * Intended to be called by corresponding instance methods of subclass.
+   * @private
+   * @param {string} appiumHome
+   * @param {ExtensionType} extType
+   * @param {string} extName - Extension name (unique to its type)
+   * @param {ExtData} extData - Extension config
+   * @returns {import('ajv').SchemaObject|undefined}
+   */
+  static _readExtensionSchema (appiumHome, extType, extName, extData) {
+    const {installPath, pkgName, schema: argSchemaPath} = extData;
+    if (!argSchemaPath) {
+      throw new TypeError(
+        `No \`schema\` property found in config for ${extType} ${pkgName} -- why is this function being called?`,
+      );
+    }
+    let moduleObject;
+    if (_.isString(argSchemaPath)) {
+      const schemaPath = resolveFrom(
+        path.resolve(appiumHome, installPath),
+        // this path sep is fine because `resolveFrom` uses Node's module resolution
+        path.normalize(`${pkgName}/${argSchemaPath}`),
+      );
+      moduleObject = require(schemaPath);
+    } else {
+      moduleObject = argSchemaPath;
+    }
+    // this sucks. default exports should be destroyed
+    const schema = moduleObject.__esModule
+      ? moduleObject.default
+      : moduleObject;
+    registerSchema(extType, extName, schema);
+    return schema;
+  }
+
+  /**
+   * If an extension provides a schema, this will load the schema and attempt to
+   * register it with the schema registrar.
+   * @param {string} extName - Name of extension
+   * @param {ExtData} extData - Extension data
+   * @returns {import('ajv').SchemaObject|undefined}
+   */
+  readExtensionSchema (extName, extData) {
+    return ExtensionConfig._readExtensionSchema(this.appiumHome, this.extensionType, extName, extData);
+  }
 }
 
+export { DRIVER_TYPE, PLUGIN_TYPE } from './ext-config-io';
 export {
   INSTALL_TYPE_NPM, INSTALL_TYPE_GIT, INSTALL_TYPE_LOCAL, INSTALL_TYPE_GITHUB,
-  INSTALL_TYPES, DEFAULT_APPIUM_HOME, DRIVER_TYPE, PLUGIN_TYPE,
+  INSTALL_TYPES, DEFAULT_APPIUM_HOME, APPIUM_HOME
 };
+
+/**
+ * Config problem
+ * @typedef {Object} Problem
+ * @property {string} err - Error message
+ * @property {any} val - Associated value
+ */
+
+/**
+ * Alias
+ * @typedef {import('./ext-config-io').ExtensionType} ExtensionType
+ */
+
+/**
+ * Extension data (pulled from config YAML)
+ * @typedef {Object} ExtData
+ * @property {string|import('ajv').SchemaObject} [schema] - Optional schema path if the ext defined it
+ * @property {string} pkgName - Package name
+ * @property {string} installPath - Actually looks more like a module identifier? Resolved from `APPIUM_HOME`
+ */
+