@appium/base-driver 10.5.1 → 10.6.0

package/lib/basedriver/driver.ts

@@ -17,8 +17,6 @@ import {
   type SingularSessionData,
   type SessionCapabilities,
 } from '@appium/types';
-import B from 'bluebird';
-import _ from 'lodash';
 import {fixCaps, isW3cCaps} from '../helpers/capabilities';
 import {getLevenshteinSuggestion} from '../helpers/levenshtein-match';
 import {calcSignature} from '../helpers/session';
@@ -27,6 +25,7 @@ import {processCapabilities, validateCaps} from './capabilities';
 import {DriverCore} from './core';
 import * as helpers from './helpers';
 import {resolveExecuteExtensionName} from '../helpers/extension-command-name';
+import {mergePlainObjects} from '../utils';
 
 const EVENT_SESSION_INIT = 'newSessionRequested';
 const EVENT_SESSION_START = 'newSessionStarted';
@@ -69,7 +68,9 @@ export class BaseDriver<
    * @see {@link https://github.com/appium/appium/issues/new}
    */
   protected get _desiredCapConstraints(): Readonly<BaseDriverCapConstraints & C> {
-    return Object.freeze(_.merge({}, BASE_DESIRED_CAP_CONSTRAINTS, this.desiredCapConstraints));
+    return Object.freeze(
+      mergePlainObjects({}, BASE_DESIRED_CAP_CONSTRAINTS, this.desiredCapConstraints) as BaseDriverCapConstraints & C
+    );
   }
 
   /**
@@ -113,11 +114,11 @@ export class BaseDriver<
         unexpectedShutdownRejecter?.(e);
       };
       try {
-        return await B.race([
+        return await Promise.race([
           this[cmd](...args),
           // This promise is needed to monitor if the session has been
           // shut down unexpectedly while the command was running
-          new B((resolve, reject) => {
+          new Promise((resolve, reject) => {
             unexpectedShutdownResolver = resolve;
             unexpectedShutdownRejecter = reject;
             this.eventEmitter.once(ON_UNEXPECTED_SHUTDOWN_EVENT, onUnexpectedShutdown);
@@ -180,7 +181,7 @@ export class BaseDriver<
   clarifyCommandName(cmd: string, args: string[]): string {
     if (cmd === 'execute') {
       const firstArg = args?.[0];
-      if (_.isString(firstArg) && firstArg.trim().length > 0) {
+      if (typeof firstArg === 'string' && firstArg.trim().length > 0) {
         return resolveExecuteExtensionName.call(this, firstArg);
       }
     }
@@ -257,7 +258,7 @@ export class BaseDriver<
       await this.createSession(this.originalCaps);
     } finally {
       // always restore state.
-      for (const [key, value] of _.toPairs(currentConfig)) {
+      for (const [key, value] of Object.entries(currentConfig)) {
         this[key] = value;
       }
     }
@@ -286,7 +287,7 @@ export class BaseDriver<
 
     this.log.debug();
 
-    const originalCaps = _.cloneDeep(
+    const originalCaps = structuredClone(
       [w3cCapabilities, w3cCapabilities1, w3cCapabilities2].find(isW3cCaps),
     );
     if (!originalCaps) {
@@ -321,7 +322,7 @@ export class BaseDriver<
     this.sessionCreationTimestampMs = Date.now();
     this.caps = caps;
     // merge caps onto opts so we don't need to worry about what's where
-    this.opts = {..._.cloneDeep(this.initialOpts), ...this.caps};
+    this.opts = {...structuredClone(this.initialOpts), ...this.caps};
 
     // deal with resets
     // some people like to do weird things by setting noReset and fullReset
@@ -347,7 +348,7 @@ export class BaseDriver<
       delete this.opts.app;
     }
 
-    if (!_.isUndefined(this.caps.newCommandTimeout)) {
+    if (this.caps.newCommandTimeout !== undefined) {
       this.newCommandTimeoutMs = (this.caps.newCommandTimeout as number) * 1000;
     }
 
@@ -388,7 +389,7 @@ export class BaseDriver<
       // simple hack to release pending commands if they exist
       // @ts-expect-error private API
       const queues = this.commandsQueueGuard.queues;
-      for (const key of _.keys(queues)) {
+      for (const key of Object.keys(queues)) {
         queues[key] = [];
       }
     }
@@ -396,8 +397,9 @@ export class BaseDriver<
   }
 
   logExtraCaps(caps: Capabilities<C>) {
-    const knownCaps = _.keys(this._desiredCapConstraints);
-    const extraCaps = _.difference(_.keys(caps), knownCaps);
+    const knownCaps = Object.keys(this._desiredCapConstraints);
+    const knownCapsSet = new Set(knownCaps);
+    const extraCaps = Object.keys(caps).filter((cap) => !knownCapsSet.has(cap));
     if (extraCaps.length) {
       this.log.warn(`The following provided capabilities were not recognized by this driver:`);
       for (const cap of extraCaps) {

package/lib/basedriver/extension-core.ts

@@ -1,9 +1,12 @@
-import {logger} from '@appium/support';
+import {logger, util} from '@appium/support';
 import {EventEmitter} from 'node:events';
 import type {
   AppiumLogger,
   BidiModuleMap,
   BiDiResultData,
+  IAppiumIpc,
+  IIpcSubscription,
+  IpcData,
   StringRecord,
 } from '@appium/types';
 import {
@@ -11,7 +14,6 @@ import {
 } from '../constants';
 import {errors} from '../protocol';
 import {BIDI_COMMANDS} from '../protocol/bidi-commands';
-import _ from 'lodash';
 import {generateDriverLogPrefix} from './helpers';
 
 export class ExtensionCore {
@@ -21,6 +23,7 @@ export class ExtensionCore {
   // used to handle driver events
   readonly eventEmitter: NodeJS.EventEmitter;
   protected _log: AppiumLogger;
+  private ipc?: IAppiumIpc;
 
 
   constructor(logPrefix?: string) {
@@ -41,7 +44,7 @@ export class ExtensionCore {
   }
 
   updateBidiCommands(cmds: BidiModuleMap): void {
-    const overlappingKeys = _.intersection(Object.keys(cmds), Object.keys(this.bidiCommands));
+    const overlappingKeys = Object.keys(cmds).filter((key) => key in this.bidiCommands);
     if (overlappingKeys.length) {
       this.log.warn(`Overwriting existing bidi modules: ${JSON.stringify(overlappingKeys)}. This may not be intended!`);
     }
@@ -98,7 +101,7 @@ export class ExtensionCore {
     const args: any[] = [];
     if (params?.required?.length) {
       for (const requiredParam of params.required) {
-        if (_.isUndefined(bidiParams[requiredParam])) {
+        if (bidiParams[requiredParam] === undefined) {
           throw new errors.InvalidArgumentError(
             `The ${requiredParam} parameter was required but you omitted it`,
           );
@@ -111,18 +114,41 @@ export class ExtensionCore {
         args.push(bidiParams[optionalParam]);
       }
     }
-    const logParams = _.truncate(JSON.stringify(bidiParams), {length: MAX_LOG_BODY_LENGTH});
+    const logParams = util.truncateString(JSON.stringify(bidiParams), {length: MAX_LOG_BODY_LENGTH});
     this.log.debug(
       `Executing bidi command '${bidiCmd}' with params ${logParams} by passing to ${handlerType} ` +
         `method '${command}'`,
     );
     // call the handler with the signature appropriate to extension type (plugin or driver)
     const response = (next && driver) ? await this[command](next, driver, ...args) : await this[command](...args);
-    const finalResponse = _.isUndefined(response) ? {} : response;
+    const finalResponse = response === undefined ? {} : response;
     this.log.debug(
       `Responding to bidi command '${bidiCmd}' with ` +
-      `${_.truncate(JSON.stringify(finalResponse), {length: MAX_LOG_BODY_LENGTH})}`
+      `${util.truncateString(JSON.stringify(finalResponse), {length: MAX_LOG_BODY_LENGTH})}`
     );
     return finalResponse;
   }
+
+  /**
+   * @internal Used by AppiumDriver to wire session IPC; extension authors should use {@link onIpcInit} instead.
+   */
+  async assignIpc(ipc: IAppiumIpc): Promise<void> {
+    this.ipc = ipc;
+    try {
+      await this.onIpcInit();
+    } catch (e) {
+      this.log.error(`Error running onIpcInit: `, e);
+    }
+  }
+
+  async onIpcInit(): Promise<void> {}
+
+  ipcSubscribe<T extends IpcData>(topic: string): IIpcSubscription<T> {
+    if (!this.ipc) {
+      throw new Error(`Cannot subscribe to an IPC topic without an IPC object assigned. ` +
+                      `This is likely a programming error. ipcSubscribe should be called in the ` +
+                      `onIpcInit handler or after you are certain that createSession has completed successfully.`);
+    }
+    return this.ipc.subscribe<T>(topic, generateDriverLogPrefix(this));
+  }
 }

package/lib/basedriver/helpers.ts

@@ -1,11 +1,9 @@
-import _ from 'lodash';
 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,
@@ -102,27 +100,27 @@ export async function configureApp(
   app: string,
   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`);
   }
 
@@ -170,7 +168,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;
@@ -212,7 +210,7 @@ export async function configureApp(
         if (onDownload) {
           newApp = await onDownload({
             url: originalAppLink,
-            headers: _.clone(headers) as HTTPHeaders,
+            headers: structuredClone(headers) as HTTPHeaders,
             stream,
           });
         } else {
@@ -233,7 +231,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 +265,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 +280,7 @@ 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 +308,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 +340,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}'`);
@@ -392,10 +390,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 {
@@ -466,7 +464,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) => {
@@ -515,18 +513,18 @@ 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(
@@ -565,7 +563,7 @@ 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);

package/lib/basedriver/ipc.ts

@@ -0,0 +1,179 @@
+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);
+  }
+}