appium-remote-debugger 12.2.10 → 13.1.0

package/lib/rpc/rpc-client.js

@@ -6,7 +6,7 @@ import B from 'bluebird';
 import RpcMessageHandler from './rpc-message-handler';
 import { util, timing } from '@appium/support';
 import { EventEmitter } from 'node:events';
-import { ON_TARGET_PROVISIONED_EVENT } from './constants';
+import AsyncLock from 'async-lock';
 
 const DATA_LOG_LENGTH = {length: 200};
 const WAIT_FOR_TARGET_TIMEOUT_MS = 10000;
@@ -20,6 +20,8 @@ const NO_TARGET_PRESENT_YET_ERRORS = [
   `some arguments of method`,
   `missing target`,
 ];
+export const NEW_APP_CONNECTED_ERROR = 'New application has connected';
+export const EMPTY_PAGE_DICTIONARY_ERROR = 'Empty page dictionary received';
 
 /**
  * @param {boolean} isSafari
@@ -85,14 +87,14 @@ export class RpcClient {
   /** @type {string[]} */
   _contexts;
 
-  /** @type {import('@appium/types').StringRecord} */
+  /** @type {AppToTargetsMap} */
   _targets;
 
   /** @type {EventEmitter} */
   _targetSubscriptions;
 
-  /** @type {boolean} */
-  _shouldCheckForTarget;
+  /** @type {[import('../types').AppIdKey, import('../types').PageIdKey] | undefined} */
+  _pendingTargetNotification;
 
   /**
    *
@@ -135,7 +137,6 @@ export class RpcClient {
     this._targetSubscriptions = new EventEmitter();
 
     // start with a best guess for the protocol
-    this._shouldCheckForTarget = !!opts.shouldCheckForTarget;
     this.isTargetBased = platformVersion ? isTargetBased(isSafari, platformVersion) : true;
   }
 
@@ -150,27 +151,16 @@ export class RpcClient {
    * @returns {boolean}
    */
   get needsTarget () {
-    return this.shouldCheckForTarget && this.isTargetBased;
+    return this.isTargetBased;
   }
 
   /**
-   * @returns {import('@appium/types').StringRecord}
+   * @returns {AppToTargetsMap}
    */
   get targets () {
     return this._targets;
   }
 
-  /**
-   * @returns {boolean}
-   */
-  get shouldCheckForTarget () {
-    return this._shouldCheckForTarget;
-  }
-
-  set shouldCheckForTarget (shouldCheckForTarget) {
-    this._shouldCheckForTarget = !!shouldCheckForTarget;
-  }
-
   /**
    * @returns {boolean}
    */
@@ -265,33 +255,39 @@ export class RpcClient {
    *
    * @param {import('../types').AppIdKey} appIdKey
    * @param {import('../types').PageIdKey} pageIdKey
-   * @returns {Promise<void>}
+   * @returns {Promise<import('../types').TargetId | undefined>}
    */
   async waitForTarget (appIdKey, pageIdKey) {
     if (!this.needsTarget) {
       log.debug(`Target-based communication is not needed, skipping wait for target`);
       return;
     }
-    const target = this.getTarget(appIdKey, pageIdKey);
+    let target = this.getTarget(appIdKey, pageIdKey);
     if (target) {
       log.debug(
         `The target '${target}' for app '${appIdKey}' and page '${pageIdKey}' already exists, no need to wait`
       );
-      return;
+      return target;
     }
 
     // otherwise waiting is necessary to see what the target is
     try {
-      await waitForCondition(() => !_.isEmpty(this.getTarget(appIdKey, pageIdKey)), {
+      await waitForCondition(() => {
+        target = this.getTarget(appIdKey, pageIdKey);
+        return !_.isEmpty(target);
+      }, {
         waitMs: WAIT_FOR_TARGET_TIMEOUT_MS,
         intervalMs: WAIT_FOR_TARGET_INTERVAL_MS,
-        error: 'No targets found, unable to communicate with device',
       });
+      return target;
     } catch (err) {
       if (!err.message.includes('Condition unmet')) {
         throw err;
       }
-      throw new Error('No targets found, unable to communicate with device');
+      throw new Error(
+        `No targets could be matched for the app '${appIdKey}' and page '${pageIdKey}' after ` +
+        `${WAIT_FOR_TARGET_TIMEOUT_MS}ms. This is likely a bug.`
+      );
     }
   }
 
@@ -299,18 +295,18 @@ export class RpcClient {
    *
    * @param {string} command
    * @param {import('../types').RemoteCommandOpts} opts
-   * @param {boolean} [waitForResponse]
+   * @param {boolean} [waitForResponse=true]
    * @returns {Promise<any>}
    */
   async send (command, opts, waitForResponse = true) {
     const timer = new timing.Timer().start();
-    const {
-      appIdKey,
-      pageIdKey
-    } = opts;
     try {
       return await this.sendToDevice(command, opts, waitForResponse);
     } catch (err) {
+      const {
+        appIdKey,
+        pageIdKey
+      } = opts;
       const messageLc = (err.message || '').toLowerCase();
       if (messageLc.includes(NO_TARGET_SUPPORTED_ERROR)) {
         log.info(
@@ -332,11 +328,13 @@ export class RpcClient {
 
   /**
    *
+   * @template {boolean} TWaitForResponse
    * @param {string} command
    * @param {import('../types').RemoteCommandOpts} opts
-   * @param {boolean} [waitForResponse]
-   * @returns {Promise<any>}
+   * @param {TWaitForResponse} [waitForResponse=true]
+   * @returns {Promise<TWaitForResponse extends true ? import('../types').RemoteCommandOpts : any>}
    */
+  // @ts-ignore Compiler issue
   async sendToDevice (command, opts, waitForResponse = true) {
     return await new B(async (resolve, reject) => {
       // promise to be resolved whenever remote debugger
@@ -359,25 +357,41 @@ export class RpcClient {
 
       const appIdKey = opts.appIdKey;
       const pageIdKey = opts.pageIdKey;
-      const targetId = this.getTarget(appIdKey, pageIdKey);
+      const targetId = opts.targetId ?? this.getTarget(appIdKey, pageIdKey);
 
       // retrieve the correct command to send
+      /** @type {import('../types').RemoteCommandOpts} */
       const fullOpts = _.defaults({
         connId: this.connId,
         senderId: this.senderId,
         targetId,
         id: msgId,
       }, opts);
-      // @ts-ignore remoteMessages must be defined
-      const cmd = this.remoteMessages.getRemoteCommand(command, fullOpts);
+      /** @type {import('../types').RawRemoteCommand} */
+      let cmd;
+      try {
+        // @ts-ignore remoteMessages must be defined
+        cmd = this.remoteMessages.getRemoteCommand(command, fullOpts);
+      } catch (err) {
+        log.error(err);
+        return reject(err);
+      }
+
+      /** @type {import('../types').RemoteCommand} */
+      const finalCommand = {
+        __argument: _.omit(cmd.__argument, ['WIRSocketDataKey']),
+        __selector: cmd.__selector,
+      };
 
-      if (cmd?.__argument?.WIRSocketDataKey) {
+      const hasSocketData = _.isPlainObject(cmd.__argument?.WIRSocketDataKey);
+      if (hasSocketData) {
         // make sure the message being sent has all the information that is needed
+        // @ts-ignore We have asserted it's a plain object above
         if (_.isNil(cmd.__argument.WIRSocketDataKey.id)) {
+          // @ts-ignore We have already asserted it's a plain object above
           cmd.__argument.WIRSocketDataKey.id = wrapperMsgId;
         }
-        cmd.__argument.WIRSocketDataKey =
-          Buffer.from(JSON.stringify(cmd.__argument.WIRSocketDataKey));
+        finalCommand.__argument.WIRSocketDataKey = Buffer.from(JSON.stringify(cmd.__argument.WIRSocketDataKey));
       }
 
       let messageHandled = true;
@@ -390,7 +404,10 @@ export class RpcClient {
           if (err) {
             // we are not waiting for this, and if it errors it is most likely
             // a protocol change. Log and check during testing
-            log.error(`Received error from send that is not being waited for (id: ${msgId}): '${_.truncate(JSON.stringify(err), DATA_LOG_LENGTH)}'`);
+            log.error(
+              `Received error from send that is not being waited for (id: ${msgId}): ` +
+              _.truncate(JSON.stringify(err), DATA_LOG_LENGTH)
+            );
             // reject, though it is very rare that this will be triggered, since
             // the promise is resolved directlty after send. On the off chance,
             // though, it will alert of a protocol change.
@@ -405,9 +422,10 @@ export class RpcClient {
             return reject(err);
           }
           log.debug(`Received response from send (id: ${msgId}): '${_.truncate(JSON.stringify(args), DATA_LOG_LENGTH)}'`);
+          // @ts-ignore This is ok
           resolve(args);
         });
-      } else if (cmd?.__argument?.WIRSocketDataKey) {
+      } else if (hasSocketData) {
         // @ts-ignore messageHandler must be defined
         this.messageHandler.once(msgId.toString(), function (err, value) {
           if (err) {
@@ -428,11 +446,12 @@ export class RpcClient {
         ` (id: ${msgId}): '${command}'`;
       log.debug(msg);
       try {
-        const res = await this.sendMessage(cmd);
+        await this.sendMessage(finalCommand);
         if (!messageHandled) {
           // There are no handlers waiting for a response before resolving,
           // and no errors sending the message over the socket, so resolve
-          resolve(res);
+          // @ts-ignore This is ok
+          resolve(fullOpts);
         }
       } catch (err) {
         return reject(err);
@@ -468,53 +487,101 @@ export class RpcClient {
 
   /**
    *
-   * @param {Error?} err
-   * @param {string} app
-   * @param {Record<string, any>} targetInfo
-   * @returns {void}
+   * @param {Error | undefined} err
+   * @param {import('../types').AppIdKey} app
+   * @param {import('../types').TargetInfo} targetInfo
+   * @returns {Promise<void>}
    */
-  addTarget (err, app, targetInfo) {
+  async addTarget (err, app, targetInfo) {
     if (_.isNil(targetInfo?.targetId)) {
-      log.warn(`Received 'Target.targetCreated' event for app '${app}' with no target. Skipping`);
+      log.info(`Received 'Target.targetCreated' event for app '${app}' with no target. Skipping`);
       return;
     }
-    if (_.isEmpty(this.pendingTargetNotification) && !targetInfo.isProvisional) {
-      log.warn(`Received 'Target.targetCreated' event for app '${app}' with no pending request: ${JSON.stringify(targetInfo)}`);
+    if (!this._pendingTargetNotification) {
+      log.info(
+        `Received 'Target.targetCreated' event for app '${app}' with no pending request: ${JSON.stringify(targetInfo)}`
+      );
       return;
     }
 
-    if (targetInfo.isProvisional) {
-      log.debug(`Provisional target created for app '${app}', '${targetInfo.targetId}'. Ignoring until target update event`);
+    const [appIdKey, pageIdKey] = this._pendingTargetNotification;
+    if (appIdKey !== app) {
+      log.info(
+        `Received 'Target.targetCreated' event for app '${app}' with no pending request: ${JSON.stringify(targetInfo)}`
+      );
       return;
     }
 
-    // @ts-ignore this.pendingTargetNotification must be defined here
-    const [appIdKey, pageIdKey] = this.pendingTargetNotification;
+    if (targetInfo.isProvisional) {
+      log.debug(
+        `Provisional target created for app '${appIdKey}' and page '${pageIdKey}': '${targetInfo.targetId}'`
+      );
+      if (!targetInfo.isPaused) {
+        return;
+      }
+
+      log.debug(`The target ${targetInfo.targetId}@${appIdKey} is paused`);
+      const appTargetsMap = this.targets[appIdKey];
+      if (appTargetsMap) {
+        await appTargetsMap.lock.acquire(toLockKey(appIdKey, pageIdKey), async () => {
+          try {
+            await this._initializePage(appIdKey, pageIdKey, targetInfo.targetId);
+          } finally {
+            await this._resumeTarget(appIdKey, pageIdKey, targetInfo.targetId);
+          }
+        });
+      }
+      return;
+    }
 
     log.debug(`Target created for app '${appIdKey}' and page '${pageIdKey}': ${JSON.stringify(targetInfo)}`);
     if (_.has(this.targets[appIdKey], pageIdKey)) {
       log.debug(`There is already a target for this app and page ('${this.targets[appIdKey][pageIdKey]}'). This might cause problems`);
     }
-    this.targets[app] = this.targets[app] || {};
+    const lock = new AsyncLock();
+    this.targets[app] = this.targets[app] || { lock };
     this.targets[appIdKey][pageIdKey] = targetInfo.targetId;
+
+    await lock.acquire(toLockKey(appIdKey, pageIdKey), async () => {
+      try {
+        await this.send('Target.setPauseOnStart', {
+          pauseOnStart: true,
+          appIdKey,
+          pageIdKey,
+        });
+      } catch {}
+      try {
+        await this._initializePage(appIdKey, pageIdKey);
+      } finally {
+        if (targetInfo.isPaused) {
+          await this._resumeTarget(appIdKey, pageIdKey);
+        }
+      }
+    });
   }
 
   /**
    *
-   * @param {Error?} err
-   * @param {string} app
-   * @param {string} oldTargetId
-   * @param {string} newTargetId
-   * @returns {void}
+   * @param {Error | undefined} err
+   * @param {import('../types').AppIdKey} app
+   * @param {import('../types').ProvisionalTargetInfo} targetInfo
+   * @returns {Promise<void>}
    */
-  updateTarget (err, app, oldTargetId, newTargetId) {
+  async updateTarget (err, app, targetInfo) {
+    const {
+      oldTargetId,
+      newTargetId,
+    } = targetInfo;
     log.debug(`Target updated for app '${app}'. Old target: '${oldTargetId}', new target: '${newTargetId}'`);
-    if (!this.targets[app]) {
+
+    const appTargetsMap = this.targets[app];
+    if (!appTargetsMap) {
       log.warn(`No existing target for app '${app}'. Not sure what to do`);
       return;
     }
+
     // save this, to be used if/when the existing target is destroyed
-    this.targets[app].provisional = {
+    appTargetsMap.provisional = {
       oldTargetId,
       newTargetId,
     };
@@ -522,12 +589,12 @@ export class RpcClient {
 
   /**
    *
-   * @param {Error?} err
-   * @param {string} app
-   * @param {Record<string, any>} targetInfo
-   * @returns {void}
+   * @param {Error | undefined} err
+   * @param {import('../types').AppIdKey} app
+   * @param {import('../types').TargetInfo} targetInfo
+   * @returns {Promise<void>}
    */
-  removeTarget (err, app, targetInfo) {
+  async removeTarget (err, app, targetInfo) {
     if (_.isNil(targetInfo?.targetId)) {
       log.debug(`Received 'Target.targetDestroyed' event with no target. Skipping`);
       return;
@@ -541,29 +608,23 @@ export class RpcClient {
       delete this.targets[app].provisional;
 
       // we do not know the page, so go through and find the existing target
-      const targets = this.targets[app];
-      for (const [page, targetId] of _.toPairs(targets)) {
+      const appTargetsMap = this.targets[app];
+      for (const [page, targetId] of _.toPairs(appTargetsMap)) {
         if (targetId === oldTargetId) {
-          log.debug(`Found provisional target for app '${app}'. Old target: '${oldTargetId}', new target: '${newTargetId}'. Updating`);
-          targets[page] = newTargetId;
-          const opts = {appIdKey: app, pageIdKey: parseInt(page, 10)};
-          (async () => {
-            if (this.fullPageInitialization) {
-              await this.initializePageFull(opts.appIdKey, opts.pageIdKey);
-            } else {
-              await this.initializePage(opts.appIdKey, opts.pageIdKey);
-            }
-            this._targetSubscriptions.emit(ON_TARGET_PROVISIONED_EVENT, {
-              ...opts,
-              oldTargetId,
-              targetId: newTargetId,
-            });
-          })();
+          log.debug(
+            `Found provisional target for app '${app}'. ` +
+            `Old target: '${oldTargetId}', new target: '${newTargetId}'. Updating`
+          );
+          appTargetsMap[page] = newTargetId;
           return;
         }
       }
-      log.warn(`Provisional target for app '${app}' found, but no suitable existing target found. This may cause problems`);
-      log.warn(`Old target: '${oldTargetId}', new target: '${newTargetId}'. Existing targets: ${JSON.stringify(targets)}`);
+      log.warn(
+        `Provisional target for app '${app}' found, but no suitable existing target found. This may cause problems`
+      );
+      log.warn(
+        `Old target: '${oldTargetId}', new target: '${newTargetId}'. Existing targets: ${JSON.stringify(appTargetsMap)}`
+      );
     }
 
     // if there is no waiting provisional target, just get rid of the existing one
@@ -595,9 +656,7 @@ export class RpcClient {
    * @returns {Promise<void>}
    */
   async selectPage (appIdKey, pageIdKey) {
-    /** @type {[import('../types').AppIdKey, import('../types').PageIdKey]} */
-    this.pendingTargetNotification = [appIdKey, pageIdKey];
-    this.shouldCheckForTarget = false;
+    this._pendingTargetNotification = [appIdKey, pageIdKey];
 
     // go through the steps that the Desktop Safari system
     // goes through to initialize the Web Inspector session
@@ -617,51 +676,17 @@ export class RpcClient {
     await this.send('setSenderKey', sendOpts);
     log.debug('Sender key set');
 
+    if (!this.isTargetBased) {
+      await this._initializePage(appIdKey, pageIdKey);
+      return;
+    }
+
     if (this.isTargetBased && util.compareVersions(this.platformVersion, '<', MIN_PLATFORM_NO_TARGET_EXISTS)) {
       await this.send('Target.exists', sendOpts, false);
     }
 
-    this.shouldCheckForTarget = true;
-
     await this.waitForTarget(appIdKey, pageIdKey);
-    if (this.fullPageInitialization) {
-      await this.initializePageFull(appIdKey, pageIdKey);
-    } else {
-      await this.initializePage(appIdKey, pageIdKey);
-    }
-  }
-
-  /**
-   * Perform the minimal initialization to get the Web Inspector working
-   * @param {import('../types').AppIdKey} appIdKey
-   * @param {import('../types').PageIdKey} pageIdKey
-   * @returns {Promise<void>}
-   */
-  async initializePage (appIdKey, pageIdKey) {
-    const sendOpts = {
-      appIdKey,
-      pageIdKey,
-    };
-
-    // The sequence of domains is important
-    for (const domain of [
-      'Inspector.enable',
-      'Page.enable',
-      'Runtime.enable',
-
-      'Network.enable',
-      'Heap.enable',
-      'Debugger.enable',
-      'Console.enable',
-
-      'Inspector.initialized',
-    ]) {
-      try {
-        await this.send(domain, sendOpts);
-      } catch (err) {
-        log.info(`Cannot enable domain '${domain}' during initialization: ${err.message}`);
-      }
-    }
+    await this.waitForPageInitialization(appIdKey, pageIdKey);
   }
 
   /**
@@ -670,14 +695,41 @@ export class RpcClient {
    *
    * @param {import('../types').AppIdKey} appIdKey
    * @param {import('../types').PageIdKey} pageIdKey
+   * @param {import('../types').TargetId} [targetId]
    * @returns {Promise<void>}
    */
-  async initializePageFull (appIdKey, pageIdKey) {
+  async _initializePage (appIdKey, pageIdKey, targetId) {
     const sendOpts = {
       appIdKey,
       pageIdKey,
+      targetId,
     };
 
+    log.debug(`Initializing page '${pageIdKey}' for app '${appIdKey}'`);
+    if (!this.fullPageInitialization) {
+      // The sequence of domains is important
+      for (const domain of [
+        'Inspector.enable',
+        'Page.enable',
+        'Runtime.enable',
+
+        'Network.enable',
+        'Heap.enable',
+        'Debugger.enable',
+        'Console.enable',
+
+        'Inspector.initialized',
+      ]) {
+        try {
+          await this.send(domain, sendOpts);
+        } catch (err) {
+          log.info(`Cannot enable domain '${domain}' during initialization: ${err.message}`);
+        }
+      }
+      log.debug(`Simple initialization of page '${pageIdKey}' for app '${appIdKey}' completed`);
+      return;
+    }
+
     // The sequence of commands here is important
     const domainsToOptsMap = {
       'Inspector.enable': sendOpts,
@@ -756,6 +808,7 @@ export class RpcClient {
         log.info(`Cannot enable domain '${domain}' during full initialization: ${err.message}`);
       }
     }
+    log.debug(`Full initialization of page '${pageIdKey}' for app '${appIdKey}' completed`);
   }
 
   /**
@@ -783,7 +836,7 @@ export class RpcClient {
                     `Using id ${correctAppIdKey} instead of ${oldAppIdKey}`);
         }
 
-        reject(new Error('New application has connected'));
+        reject(new Error(NEW_APP_CONNECTED_ERROR));
       };
       this.messageHandler?.prependOnceListener('_rpc_applicationConnected:', onAppChange);
 
@@ -794,7 +847,7 @@ export class RpcClient {
           // sometimes the connect logic happens, but with an empty dictionary
           // which leads to the remote debugger getting disconnected, and into a loop
           if (_.isEmpty(pageDict)) {
-            reject(new Error('Empty page dictionary received'));
+            reject(new Error(EMPTY_PAGE_DICTIONARY_ERROR));
           } else {
             resolve([connectedAppIdKey, pageDict]);
           }
@@ -837,6 +890,56 @@ export class RpcClient {
     // { scriptId: '13', url: '', startLine: 0, startColumn: 0, endLine: 82, endColumn: 3 }
     log.debug(`Script parsed: ${JSON.stringify(scriptInfo)}`);
   }
+
+  /**
+   *
+   * @param {import('../types').AppIdKey} appIdKey
+   * @param {import('../types').PageIdKey} pageIdKey
+   * @param {import('../types').TargetId} [targetId]
+   * @returns {Promise<void>}
+   */
+  async _resumeTarget (appIdKey, pageIdKey, targetId) {
+    try {
+      await this.send('Target.resume', {
+        appIdKey,
+        pageIdKey,
+        targetId,
+      });
+      log.debug(`Successfully resumed the target ${targetId}@${appIdKey}`);
+    } catch {}
+  }
+
+  /**
+   *
+   * @param {import('../types').AppIdKey} appIdKey
+   * @param {import('../types').PageIdKey} pageIdKey
+   */
+  async waitForPageInitialization (appIdKey, pageIdKey) {
+    const appTargetsMap = this.targets[appIdKey];
+    if (!appTargetsMap) {
+      throw new Error(`No targets found for app '${appIdKey}'`);
+    }
+    /** @type {AsyncLock | undefined}  */
+    const lock = appTargetsMap.lock;
+    if (lock?.isBusy()) {
+      const timer = new timing.Timer().start();
+      log.debug(`Waiting until page ${pageIdKey}@${appIdKey} is fully initialized`);
+      await lock.acquire(toLockKey(appIdKey, pageIdKey), async () => await B.delay(0));
+      log.debug(
+        `The initalization of the page ${pageIdKey}@${appIdKey} took ${timer.getDuration().asMilliSeconds}ms`
+      );
+    }
+  }
+}
+
+/**
+ *
+ * @param {import('../types').AppIdKey} appIdKey
+ * @param {import('../types').PageIdKey} pageIdKey
+ * @returns {string}
+ */
+export function toLockKey(appIdKey, pageIdKey) {
+  return `${appIdKey}-${pageIdKey}`;
 }
 
 export default RpcClient;
@@ -852,5 +955,13 @@ export default RpcClient;
  * @property {number} [socketChunkSize]
  * @property {boolean} [fullPageInitialization=false]
  * @property {string} [udid]
- * @property {boolean} [shouldCheckForTarget]
  */
+
+/**
+ * @typedef {{[key: import('../types').PageIdKey]: import('../types').TargetId}} PageDict
+ */
+
+/**
+ * @typedef {PageDict & {provisional?: import('../types').ProvisionalTargetInfo, lock: import('async-lock').default}} PagesToTargets
+ * @typedef {{[key: import('../types').AppIdKey]: PagesToTargets}} AppToTargetsMap
+ */