@appium/base-driver 10.5.2 → 10.7.0

package/lib/basedriver/helpers.ts

@@ -1,11 +1,10 @@
-import _ from 'lodash';
+import nodeFs from 'node:fs';
 import path from 'node:path';
 import {log as logger} from './logger';
 import {tempDir, fs, util, timing, node} from '@appium/support';
 import {LRUCache} from 'lru-cache';
 import AsyncLock from 'async-lock';
 import axios from 'axios';
-import B from 'bluebird';
 import type {
   ConfigureAppOptions,
   CachedAppInfo,
@@ -15,14 +14,15 @@ import type {
 } from '@appium/types';
 import type {AxiosResponseHeaders, RawAxiosRequestHeaders} from 'axios';
 import type {Readable} from 'node:stream';
+import type {PackageJson} from 'type-fest';
 
 // for compat with running tests transpiled and in-place
-export const {version: BASEDRIVER_VER} = fs.readPackageJsonFrom(__dirname);
+export const BASEDRIVER_VER = readBaseDriverVersion();
 
 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;
-const DEFAULT_REQ_HEADERS = Object.freeze({
+const DEFAULT_REQ_HEADERS: RawAxiosRequestHeaders = Object.freeze({
   'user-agent': `Appium (BaseDriver v${BASEDRIVER_VER})`,
 });
 const AVG_DOWNLOAD_SPEED_MEASUREMENT_THRESHOLD_SEC = 2;
@@ -33,7 +33,7 @@ const APPLICATIONS_CACHE = new LRUCache<string, CachedAppInfoEntry>({
   dispose: ({fullPath}, app) => {
     logger.info(
       `The application '${app}' cached at '${fullPath}' has ` +
-        `expired after ${CACHED_APPS_MAX_AGE_MS}ms`
+        `expired after ${CACHED_APPS_MAX_AGE_MS}ms`,
     );
     if (fullPath) {
       void fs.rimraf(fullPath);
@@ -53,7 +53,7 @@ process.on('exit', () => {
 
   const appPaths = [...APPLICATIONS_CACHE.values()].map(({fullPath}) => fullPath);
   logger.debug(
-    `Performing cleanup of ${util.pluralize('cached application', appPaths.length, true)}`
+    `Performing cleanup of ${util.pluralize('cached application', appPaths.length, true)}`,
   );
   for (const appPath of appPaths) {
     if (!appPath) {
@@ -100,29 +100,29 @@ interface CachedAppInfoEntry extends Omit<CachedAppInfo, 'packageHash'> {
  */
 export async function configureApp(
   app: string,
-  options: string | string[] | ConfigureAppOptions = {} as ConfigureAppOptions
+  options: string | string[] | ConfigureAppOptions = {} as ConfigureAppOptions,
 ): Promise<string> {
-  if (!_.isString(app)) {
+  if (typeof app !== 'string') {
     // immediately shortcircuit if not given an app
     return '';
   }
 
   let supportedAppExtensions: string[];
-  const opts = !_.isString(options) && !_.isArray(options) ? options : undefined;
+  const opts = typeof options !== 'string' && !Array.isArray(options) ? options : undefined;
   const onPostProcess = opts?.onPostProcess;
   const onDownload = opts?.onDownload;
 
-  if (_.isString(options)) {
+  if (typeof options === 'string') {
     supportedAppExtensions = [options];
-  } else if (_.isArray(options)) {
+  } else if (Array.isArray(options)) {
     supportedAppExtensions = options;
-  } else if (_.isPlainObject(options)) {
+  } else if (util.isPlainObject(options)) {
     supportedAppExtensions = options.supportedExtensions ?? [];
   } else {
     supportedAppExtensions = [];
   }
 
-  if (_.isEmpty(supportedAppExtensions)) {
+  if (util.isEmpty(supportedAppExtensions)) {
     throw new Error(`One or more supported app extensions must be provided`);
   }
 
@@ -142,7 +142,7 @@ export async function configureApp(
     newApp = path.resolve(process.cwd(), newApp);
     logger.warn(
       `The current application path '${app}' is not absolute ` +
-      `and has been rewritten to '${newApp}'. Consider using absolute paths rather than relative`
+        `and has been rewritten to '${newApp}'. Consider using absolute paths rather than relative`,
     );
     app = newApp;
   }
@@ -170,7 +170,7 @@ export async function configureApp(
       let {stream, status} = result;
       logger.debug(`Response status: ${status}`);
       try {
-        if (!_.isEmpty(headers)) {
+        if (!util.isEmpty(headers)) {
           if (headers.etag) {
             logger.debug(`Etag: ${headers.etag}`);
             remoteAppProps.etag = headers.etag;
@@ -196,7 +196,7 @@ export async function configureApp(
           }
           logger.info(
             `The application at '${cachedAppInfo.fullPath}' does not exist anymore ` +
-              `or its integrity has been damaged. Deleting it from the internal cache`
+              `or its integrity has been damaged. Deleting it from the internal cache`,
           );
           APPLICATIONS_CACHE.delete(appCacheKey);
 
@@ -212,15 +212,18 @@ export async function configureApp(
         if (onDownload) {
           newApp = await onDownload({
             url: originalAppLink,
-            headers: _.clone(headers) as HTTPHeaders,
+            headers: structuredClone(headers) as HTTPHeaders,
             stream,
           });
         } else {
           const fileName = determineFilename(headers, pathname ?? '', supportedAppExtensions);
-          newApp = await fetchApp(stream, await tempDir.path({
-            prefix: fileName,
-            suffix: '',
-          }));
+          newApp = await fetchApp(
+            stream,
+            await tempDir.path({
+              prefix: fileName,
+              suffix: '',
+            }),
+          );
         }
       } finally {
         if (!stream.closed) {
@@ -233,7 +236,7 @@ export async function configureApp(
     } 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
-      if (_.isString(protocol) && protocol.length > 2) {
+      if (typeof protocol === 'string' && protocol.length > 2) {
         errorMessage =
           `The protocol '${protocol}' used in '${newApp}' is not supported. ` +
           `Only http: and https: protocols are supported`;
@@ -267,12 +270,12 @@ export async function configureApp(
       return appPathToCache;
     };
 
-    if (_.isFunction(onPostProcess)) {
+    if (typeof onPostProcess === 'function') {
       const postProcessArg: PostProcessOptions = {
-        cachedAppInfo: _.clone(cachedAppInfo) as CachedAppInfo | undefined,
+        cachedAppInfo: structuredClone(cachedAppInfo) as CachedAppInfo | undefined,
         isUrl,
         originalAppLink,
-        headers: _.clone(headers) as HTTPHeaders,
+        headers: structuredClone(headers) as HTTPHeaders,
         appPath: newApp,
       };
       const result = await onPostProcess(postProcessArg);
@@ -282,7 +285,8 @@ export async function configureApp(
     }
 
     verifyAppExtension(newApp, supportedAppExtensions);
-    return appCacheKey !== toCacheKey(newApp) && (packageHash || _.values(remoteAppProps).some(Boolean))
+    return appCacheKey !== toCacheKey(newApp) &&
+      (packageHash || Object.values(remoteAppProps).some(Boolean))
       ? await storeAppInCache(newApp)
       : newApp;
   });
@@ -310,14 +314,14 @@ export function isPackageOrBundle(app: string): boolean {
  */
 export function duplicateKeys<T>(input: T, firstKey: string, secondKey: string): T {
   // If array provided, recursively call on all elements
-  if (_.isArray(input)) {
+  if (Array.isArray(input)) {
     return input.map((item) => duplicateKeys(item, firstKey, secondKey)) as T;
   }
 
   // If object, create duplicates for keys and then recursively call on values
-  if (_.isPlainObject(input)) {
+  if (util.isPlainObject(input)) {
     const resultObj: Record<string, unknown> = {};
-    for (const [key, value] of _.toPairs(input as Record<string, unknown>)) {
+    for (const [key, value] of Object.entries(input as Record<string, unknown>)) {
       const recursivelyCalledValue = duplicateKeys(value, firstKey, secondKey);
       if (key === firstKey) {
         resultObj[secondKey] = recursivelyCalledValue;
@@ -342,23 +346,23 @@ export function duplicateKeys<T>(input: T, firstKey: string, secondKey: string):
  * @throws {TypeError} If value is not a string/array or JSON parsing fails for array-like input.
  */
 export function parseCapsArray(capValue: string | string[]): string[] {
-  if (_.isArray(capValue)) {
+  if (Array.isArray(capValue)) {
     return capValue;
   }
 
   try {
     const parsed = JSON.parse(capValue);
-    if (_.isArray(parsed)) {
+    if (Array.isArray(parsed)) {
       return parsed;
     }
   } catch (e) {
     const message = `Failed to parse capability as JSON array: ${(e as Error).message}`;
-    if (_.isString(capValue) && _.startsWith(_.trimStart(capValue), '[')) {
+    if (typeof capValue === 'string' && capValue.trimStart().startsWith('[')) {
       throw new TypeError(message, {cause: e});
     }
     logger.warn(message);
   }
-  if (_.isString(capValue)) {
+  if (typeof capValue === 'string') {
     return [capValue];
   }
   throw new TypeError(`Expected a string or a valid JSON array; received '${capValue}'`);
@@ -382,7 +386,9 @@ export function generateDriverLogPrefix(obj: object | null, _sessionId?: string
 
 // #region Private helpers
 
-function parseAppLink(appLink: string): URL | {protocol?: string; pathname?: string; href?: string; search?: string} {
+function parseAppLink(
+  appLink: string,
+): URL | {protocol?: string; pathname?: string; href?: string; search?: string} {
   try {
     return new URL(appLink);
   } catch {
@@ -392,10 +398,10 @@ function parseAppLink(appLink: string): URL | {protocol?: string; pathname?: str
 
 function isEnvOptionEnabled(optionName: string, defaultValue: boolean | null = null): boolean {
   const value = process.env[optionName];
-  if (!_.isNull(defaultValue) && _.isEmpty(value)) {
+  if (defaultValue !== null && util.isEmpty(value)) {
     return defaultValue;
   }
-  return !_.isEmpty(value) && !['0', 'false', 'no'].includes(_.toLower(value));
+  return !util.isEmpty(value) && !['0', 'false', 'no'].includes(String(value).toLowerCase());
 }
 
 function isSupportedUrl(app: string): boolean {
@@ -432,7 +438,10 @@ function toCacheKey(app: string): string {
   return app;
 }
 
-async function queryAppLink(appLink: string, reqHeaders: RawAxiosRequestHeaders): Promise<RemoteAppData> {
+async function queryAppLink(
+  appLink: string,
+  reqHeaders: RawAxiosRequestHeaders,
+): Promise<RemoteAppData> {
   const url = new URL(appLink);
   // Extract credentials, then remove them from the URL for axios
   const {username, password} = url;
@@ -453,10 +462,9 @@ async function queryAppLink(appLink: string, reqHeaders: RawAxiosRequestHeaders)
     const {data: stream, headers, status} = await axios(requestOpts);
     return {stream, headers, status};
   } catch (err) {
-    throw new Error(
-      `Cannot download the app from ${axiosUrl}: ${(err as Error).message}`,
-      {cause: err}
-    );
+    throw new Error(`Cannot download the app from ${axiosUrl}: ${(err as Error).message}`, {
+      cause: err,
+    });
   }
 }
 
@@ -466,7 +474,7 @@ async function fetchApp(srcStream: Readable, dstPath: string): Promise<string> {
     const writer = fs.createWriteStream(dstPath);
     srcStream.pipe(writer);
 
-    await new B<void>((resolve, reject) => {
+    await new Promise<void>((resolve, reject) => {
       srcStream.once('error', reject);
       writer.once('finish', () => resolve());
       writer.once('error', (e: Error) => {
@@ -482,7 +490,7 @@ async function fetchApp(srcStream: Readable, dstPath: string): Promise<string> {
   const {size} = await fs.stat(dstPath);
   logger.debug(
     `The application (${util.toReadableSizeString(size)}) ` +
-      `has been downloaded to '${dstPath}' in ${secondsElapsed.toFixed(3)}s`
+      `has been downloaded to '${dstPath}' in ${secondsElapsed.toFixed(3)}s`,
   );
   // it does not make much sense to approximate the speed for short downloads
   if (secondsElapsed >= AVG_DOWNLOAD_SPEED_MEASUREMENT_THRESHOLD_SEC) {
@@ -496,13 +504,16 @@ async function fetchApp(srcStream: Readable, dstPath: string): Promise<string> {
 function determineFilename(
   headers: AxiosResponseHeaders | RawAxiosRequestHeaders,
   pathname: string,
-  supportedAppExtensions: string[]
+  supportedAppExtensions: string[],
 ): string {
   const basename = fs.sanitizeName(path.basename(decodeURIComponent(pathname ?? '')), {
     replacement: SANITIZE_REPLACEMENT,
   });
   const extname = path.extname(basename);
-  if (headers['content-disposition'] && /^attachment/i.test(String(headers['content-disposition']))) {
+  if (
+    headers['content-disposition'] &&
+    /^attachment/i.test(String(headers['content-disposition']))
+  ) {
     logger.debug(`Content-Disposition: ${headers['content-disposition']}`);
     const match = /filename="([^"]+)/i.exec(String(headers['content-disposition']));
     if (match) {
@@ -515,24 +526,28 @@ function determineFilename(
     ? basename.substring(0, basename.length - extname.length)
     : DEFAULT_BASENAME;
   let resultingExt = extname;
-  if (!supportedAppExtensions.map(_.toLower).includes(_.toLower(resultingExt))) {
+  if (
+    !supportedAppExtensions.map((ext) => ext.toLowerCase()).includes(resultingExt.toLowerCase())
+  ) {
     logger.info(
       `The current file extension '${resultingExt}' is not supported. ` +
-        `Defaulting to '${_.first(supportedAppExtensions)}'`
+        `Defaulting to '${supportedAppExtensions[0]}'`,
     );
-    resultingExt = _.first(supportedAppExtensions) as string;
+    resultingExt = supportedAppExtensions[0] as string;
   }
   return `${resultingName}${resultingExt}`;
 }
 
 function verifyAppExtension(app: string, supportedAppExtensions: string[]): string {
-  if (supportedAppExtensions.map(_.toLower).includes(_.toLower(path.extname(app)))) {
+  if (
+    supportedAppExtensions.map((ext) => ext.toLowerCase()).includes(path.extname(app).toLowerCase())
+  ) {
     return app;
   }
   throw new Error(
     `New app path '${app}' did not have ` +
       `${util.pluralize('extension', supportedAppExtensions.length, false)}: ` +
-      supportedAppExtensions
+      supportedAppExtensions,
   );
 }
 
@@ -546,7 +561,7 @@ async function calculateFileIntegrity(filePath: string): Promise<string> {
 
 async function isAppIntegrityOk(
   currentPath: string,
-  expectedIntegrity: {file?: string; folder?: number} = {}
+  expectedIntegrity: {file?: string; folder?: number} = {},
 ): Promise<boolean> {
   if (!(await fs.exists(currentPath))) {
     return false;
@@ -565,13 +580,27 @@ async function isAppIntegrityOk(
 }
 
 function toNaturalNumber(defaultValue: number, envVarName?: string): number {
-  if (!envVarName || _.isUndefined(process.env[envVarName])) {
+  if (!envVarName || process.env[envVarName] === undefined) {
     return defaultValue;
   }
   const num = parseInt(`${process.env[envVarName]}`, 10);
   return num > 0 ? num : defaultValue;
 }
 
+function readBaseDriverVersion(): string {
+  const pkgRoot = node.getModuleRootSync('@appium/base-driver', __filename);
+  if (!pkgRoot) {
+    throw new Error('Cannot find the @appium/base-driver package root');
+  }
+  const pkg = JSON.parse(
+    nodeFs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8'),
+  ) as PackageJson;
+  if (typeof pkg.version !== 'string') {
+    throw new Error('Invalid `package.json` for @appium/base-driver');
+  }
+  return pkg.version;
+}
+
 export default {
   configureApp,
   isPackageOrBundle,

package/lib/basedriver/ipc.ts

@@ -0,0 +1,198 @@
+import {log} from './logger';
+import type {
+  StringRecord,
+  IIpcSubscription,
+  IAppiumIpc,
+  IpcMessage,
+  IpcEvent,
+  AppiumLogger,
+  IpcData,
+} from '@appium/types';
+import EventEmitter from 'node:events';
+import {sleep} from 'asyncbox';
+import {node} from '@appium/support';
+
+const DEF_MAX_OBJ_SIZE_BYTES = 1024 * 1024; // 1mb seems like plenty for any plugin to pass a message
+const DEF_MAX_TOPICS = 1000;
+
+export const EVT_MESSAGE = 'message';
+export const EVT_UNSUBSCRIBED = 'unsubscribed';
+
+export type AppiumIpcOpts = {
+  maxObjSize?: number;
+  maxTopics?: number;
+  log?: AppiumLogger;
+};
+
+const ASYNC_ITERATOR_STOP = Symbol('asyncIteratorStop');
+
+export class IpcSubscription<T extends IpcData>
+  extends EventEmitter<IpcEvent<T>>
+  implements IIpcSubscription<T>
+{
+  constructor(
+    public readonly subscriber: string,
+    public readonly topic: string,
+    private readonly ipc: AppiumIpc,
+  ) {
+    super();
+  }
+
+  get isActive() {
+    return this.ipc.subscriptionExists(this.topic, this.subscriber);
+  }
+
+  getMessage(): IpcMessage<T> | undefined {
+    if (!this.isActive) {
+      throw new Error('Cannot get message from subscription after unsubscribing');
+    }
+    return this.ipc.getMessage<T>(this.topic);
+  }
+
+  async publish(data: T): Promise<void> {
+    if (!this.isActive) {
+      throw new Error('Cannot publish data to topic from subscription after unsubscribing');
+    }
+    return await this.ipc.publish<T>(this.topic, this.subscriber, data);
+  }
+
+  unsubscribe(): boolean {
+    if (!this.isActive) {
+      return false;
+    }
+    const unsubscribeRes = this.ipc.unsubscribe(this.topic, this.subscriber);
+    this.emit('unsubscribed');
+    this.removeAllListeners(EVT_MESSAGE);
+    return unsubscribeRes;
+  }
+
+  async *[Symbol.asyncIterator](): AsyncGenerator<IpcMessage<T>> {
+    // yield any messages that are emitted, but keep an eye out for an unsubscribed that happens
+    // while a caller is waiting on the loop, because we want to exit the loop in case of
+    // unsubscription, even if we were already waiting on the next message.
+    while (this.isActive) {
+      const val = await new Promise<IpcMessage<T> | typeof ASYNC_ITERATOR_STOP>((resolve) => {
+        this.once(EVT_MESSAGE, (message: IpcMessage<T>) => {
+          this.removeAllListeners(EVT_UNSUBSCRIBED);
+          resolve(message);
+        });
+        this.once(EVT_UNSUBSCRIBED, () => {
+          // EVT_MESSAGE listeners are already removed in unsubscribe()
+          resolve(ASYNC_ITERATOR_STOP);
+        });
+      });
+      if (val === ASYNC_ITERATOR_STOP) {
+        break;
+      }
+      yield val;
+    }
+  }
+}
+
+export class AppiumIpc implements IAppiumIpc {
+  protected readonly messageByTopic: StringRecord<IpcMessage<any>> = {};
+  protected readonly subs: StringRecord<Array<IpcSubscription<any>>> = {};
+  protected readonly topics = new Set<string>();
+  protected readonly maxObjSize: number;
+  protected readonly maxTopics: number;
+  protected readonly log: AppiumLogger;
+
+  constructor(opts: AppiumIpcOpts = {}) {
+    this.maxObjSize = opts.maxObjSize ?? DEF_MAX_OBJ_SIZE_BYTES;
+    this.maxTopics = opts.maxTopics ?? DEF_MAX_TOPICS;
+    this.log = opts.log ?? log;
+    this.log.debug(
+      `Initialized new IPC object with max object size of ${this.maxObjSize} bytes ` +
+        `and max topics of ${this.maxTopics}`,
+    );
+  }
+
+  subscribe<T extends IpcData>(topic: string, subscriber: string): IpcSubscription<T> {
+    this.log.info(`Subscribing ${subscriber} to topic '${topic}'`);
+    if (this.subscriptionExists(topic, subscriber)) {
+      throw new Error(
+        `Subscription already exists for topic "${topic}" and subscriber "${subscriber}"`,
+      );
+    }
+
+    this.ensureTopic(topic);
+    this.subs[topic] ??= [];
+    const sub = new IpcSubscription<T>(subscriber, topic, this);
+    this.subs[topic].push(sub);
+    return sub;
+  }
+
+  unsubscribe(topic: string, subscriber: string): boolean {
+    this.log.info(`Unsubscribing ${subscriber} from topic '${topic}'`);
+    if (this.subscriptionExists(topic, subscriber)) {
+      this.subs[topic] = this.subs[topic].filter((sub) => sub.subscriber !== subscriber);
+      return true;
+    }
+    return false;
+  }
+
+  async publish<T extends IpcData>(topic: string, publisher: string, data: T): Promise<void> {
+    this.log.debug(`${publisher} is publishing a message to topic ${topic}`);
+
+    this.ensureTopic(topic);
+
+    const messageSize = node.getObjectSize(data);
+    if (messageSize > this.maxObjSize) {
+      throw new Error(
+        `Error when ${publisher} is publishing to topic '${topic}': ` +
+          `Message with size ${messageSize} bytes is bigger than max size of ${this.maxObjSize} bytes`,
+      );
+    }
+
+    let clonedData: T;
+    try {
+      clonedData = structuredClone(data);
+    } catch (e) {
+      throw new Error(`Could not clone data for IPC publish from ${publisher} on topic ${topic}`, {
+        cause: e,
+      });
+    }
+
+    const message: IpcMessage<T> = {publisher, data: clonedData, topic, timestampMs: Date.now()};
+
+    this.messageByTopic[topic] = message;
+
+    const subs = this.subs[topic]
+      ? this.subs[topic].filter((sub) => sub.subscriber !== publisher)
+      : [];
+
+    for (const sub of subs) {
+      sub.emit(EVT_MESSAGE, structuredClone(message));
+    }
+
+    // we don't want to return from publish until the async iterators on subscriptions have had
+    // a chance to observe the emitted value, otherwise some might get lost
+    await sleep(0);
+  }
+
+  getMessage<T extends IpcData>(topic: string): IpcMessage<T> | undefined {
+    if (!this.messageByTopic[topic]) {
+      return;
+    }
+
+    return structuredClone(this.messageByTopic[topic] as IpcMessage<T>);
+  }
+
+  subscriptionExists(topic: string, subscriber: string): boolean {
+    return !!this.subs[topic]?.some((sub) => sub.subscriber === subscriber);
+  }
+
+  protected ensureTopic(topic: string): void {
+    if (this.topics.has(topic)) {
+      return;
+    }
+    if (this.topics.size >= this.maxTopics) {
+      throw new Error(
+        `Cannot create new IPC topic '${topic}': ` +
+          `maximum of ${this.maxTopics} topics per session reached. ` +
+          `Adjust with the --max-ipc-topics server arg.`,
+      );
+    }
+    this.topics.add(topic);
+  }
+}