appium-remote-debugger 12.2.9 → 13.0.0

package/lib/rpc/rpc-message-handler.js

@@ -107,18 +107,17 @@ export default class RpcMessageHandler extends EventEmitters {
   /**
    * Dispatch a data message.
    *
-   * @param {string | undefined} msgId
-   * @param {string} method
-   * @param {import('@appium/types').StringRecord} params
+   * @param {string} msgId If not empty then the following event is going to be emitted:
+   * - <msgId, error, result>
+   * If empty then the following event is going to be emitted:
+   * - <name, error, ..args>
+   * @param {string | undefined} method
+   * @param {import('@appium/types').StringRecord | undefined} params
    * @param {any} result
-   * @param {Error} [error]
+   * @param {Error | undefined} error
    * @returns {Promise<void>}
    */
   async dispatchDataMessage (msgId, method, params, result, error) {
-    if (!_.isEmpty(msgId)) {
-      log.debug(`Handling message (id: '${msgId}')`);
-    }
-
     if (msgId) {
       if (this.listenerCount(msgId)) {
         if (_.has(result?.result, 'value')) {
@@ -134,7 +133,7 @@ export default class RpcMessageHandler extends EventEmitters {
       return;
     }
 
-    /** @type {string[]} */
+    /** @type {any[]} */
     const eventNames = [method];
     /** @type {any[]} */
     let args = [params];
@@ -152,10 +151,10 @@ export default class RpcMessageHandler extends EventEmitters {
         args = [params || params.record];
         break;
       case 'Console.messageAdded':
-        args = [params.message];
+        args = [params?.message];
         break;
       case 'Runtime.executionContextCreated':
-        args = [params.context];
+        args = [params?.context];
         break;
       default:
         // pass
@@ -190,67 +189,65 @@ export default class RpcMessageHandler extends EventEmitters {
     let result = dataKey.result;
 
     let method = dataKey.method;
-    let params;
+    let params = dataKey.params;
 
-    if (method === 'Target.targetCreated') {
-      // this is in response to a `_rpc_forwardSocketSetup:` call
-      // targetInfo: { targetId: 'page-1', type: 'page' }
-      const app = plist.__argument.WIRApplicationIdentifierKey;
-      const targetInfo = dataKey.params.targetInfo;
-      this.emit('Target.targetCreated', null, app, targetInfo);
-      return;
-    } else if (method === 'Target.didCommitProvisionalTarget') {
-      const app = plist.__argument.WIRApplicationIdentifierKey;
-      const oldTargetId = dataKey.params.oldTargetId;
-      const newTargetId = dataKey.params.newTargetId;
-      this.emit('Target.didCommitProvisionalTarget', null, app, oldTargetId, newTargetId);
-      return;
-    } else if (method === 'Target.targetDestroyed') {
-      const app = plist.__argument.WIRApplicationIdentifierKey;
-      const targetInfo = dataKey.params.targetInfo || {targetId: dataKey.params.targetId};
-      this.emit('Target.targetDestroyed', null, app, targetInfo);
-      return;
-    }
+    const parseError = () => {
+      const defaultMessage = 'Error occurred in handling data message';
+      if (result?.wasThrown) {
+        const message = (result?.result?.value || result?.result?.description)
+          ? (result?.result?.value || result?.result?.description)
+          : (dataKey.error ?? defaultMessage);
+        return new Error(message);
+      }
+      if (dataKey.error) {
+        if (_.isPlainObject(dataKey.error)) {
+          const dataKeyError = /** @type {DataErrorMessage} */ (dataKey.error);
+          let error = new Error(defaultMessage);
+          for (const key of Object.keys(dataKeyError)) {
+            error[key] = dataKeyError[key];
+          }
+          return error;
+        }
+        return new Error(String(dataKey.error || defaultMessage));
+      }
+      return undefined;
+    };
 
-    if (!dataKey.error && this.isTargetBased) {
-      if (dataKey.method !== 'Target.dispatchMessageFromTarget') {
-        // this sort of message, at this point, is just an acknowledgement
-        // that the original message was received
+    switch (method) {
+      case 'Target.targetCreated':
+      case 'Target.targetDestroyed':
+      case 'Target.didCommitProvisionalTarget': {
+        const app = plist.__argument.WIRApplicationIdentifierKey;
+        const args = method === 'Target.didCommitProvisionalTarget'
+          ? params
+          : (params.targetInfo ?? {targetId: params.targetId});
+        this.emit(method, null, app, args);
         return;
       }
+      case 'Target.dispatchMessageFromTarget': {
+        if (!dataKey.error && this.isTargetBased) {
+          try {
+            const message = JSON.parse(dataKey.params.message);
+            msgId = _.isUndefined(message.id) ? '' : String(message.id);
+            method = message.method;
+            result = message.result || message;
+            params = result.params;
+          } catch (err) {
+            // if this happens then some aspect of the protocol is missing to us
+            // so print the entire message to get visibiity into what is going on
+            log.error(`Unexpected message format from Web Inspector: ${util.jsonStringify(plist, null)}`);
+            throw err;
+          }
+        }
 
-      // at this point, we have a Target-based message wrapping a protocol message
-      let message;
-      try {
-        message = JSON.parse(dataKey.params.message);
-        msgId = message.id;
-        method = message.method;
-        result = message.result || message;
-        params = result.params;
-      } catch (err) {
-        // if this happens then some aspect of the protocol is missing to us
-        // so print the entire message to get visibiity into what is going on
-        log.error(`Unexpected message format from Web Inspector:`);
-        log.warn(util.jsonStringify(plist, null));
-        throw err;
+        await this.dispatchDataMessage(msgId, method, params, result, parseError());
+        return;
       }
-    } else {
-      params = dataKey.params;
-    }
-
-    // we can get an error, or we can get a response that is an error
-    let error;
-    if (result?.wasThrown) {
-      const message = (result?.result?.value || result?.result?.description)
-        ? (result?.result?.value || result?.result?.description)
-        : (dataKey.error ?? 'Error occurred in handling data message');
-      error = new Error(message);
-    } else if (dataKey.error) {
-      error = new Error(dataKey.error);
-    }
-
-    await this.dispatchDataMessage(msgId, method, params, result, error);
-  }
+      default: {
+        await this.dispatchDataMessage(msgId, method, params, result, parseError());
+      }
+    } // switch
+  } // function
 }
 
 /**
@@ -259,5 +256,12 @@ export default class RpcMessageHandler extends EventEmitters {
  * @property {string} method
  * @property {import('@appium/types').StringRecord} params
  * @property {any} result
- * @property {string} [error]
+ * @property {string | DataErrorMessage} [error]
+ */
+
+/**
+ * @typedef {Object} DataErrorMessage
+ * @property {string} message
+ * @property {number} code
+ * @property {any} data
  */

package/lib/types.ts

@@ -83,6 +83,7 @@ export type RemoteDebuggerRealDeviceOptions = RemoteDebuggerRealDeviceSpecificOp
 
 export type AppIdKey = string | number;
 export type PageIdKey = string | number;
+export type TargetId = string;
 
 export interface RemoteCommandOpts {
   appIdKey?: AppIdKey;
@@ -90,7 +91,7 @@ export interface RemoteCommandOpts {
   id?: string;
   connId?: string;
   senderId?: string;
-  targetId?: string;
+  targetId?: TargetId;
   bundleId?: string;
   enabled?: boolean;
   [key: string]: any;
@@ -102,7 +103,36 @@ export interface ProtocolCommandOpts {
   params: StringRecord;
 }
 
-export interface RemoteCommand {
-  __argument: StringRecord;
+type SocketDataKey = Buffer | StringRecord;
+
+interface RemoteCommandArgument<T extends SocketDataKey> {
+  WIRSocketDataKey?: T;
+  WIRConnectionIdentifierKey?: string;
+  WIRSenderKey?: string;
+  WIRApplicationIdentifierKey?: AppIdKey;
+  WIRPageIdentifierKey?: PageIdKey;
+  WIRMessageDataTypeKey?: string;
+  WIRDestinationKey?: string;
+  WIRMessageDataKey?: string;
+  [key: string]: any;
+}
+
+interface RemoteCommandTemplated<T extends SocketDataKey> {
+  __argument: RemoteCommandArgument<T>;
   __selector: string;
 }
+
+export type RawRemoteCommand = RemoteCommandTemplated<StringRecord>;
+export type RemoteCommand = RemoteCommandTemplated<Buffer>;
+
+export interface TargetInfo {
+  targetId: string;
+  type: 'page' | 'service-worker' | 'worker';
+  isProvisional: boolean;
+  isPaused: boolean;
+}
+
+export interface ProvisionalTargetInfo {
+  oldTargetId: string;
+  newTargetId: string;
+}

package/lib/utils.js

@@ -96,8 +96,9 @@ export function appIdsForBundle (bundleId, appDict) {
 }
 
 /**
- * @param {import('@appium/types').StringRecord} params
- * @returns {void}
+ * @template {import('@appium/types').StringRecord} T
+ * @param {T} params
+ * @returns {T}
  */
 export function checkParams (params) {
   // check if all parameters have a value
@@ -107,6 +108,7 @@ export function checkParams (params) {
   if (errors.length) {
     throw new Error(`Missing ${util.pluralize('parameter', errors.length)}: ${errors.join(', ')}`);
   }
+  return params;
 }
 
 /**

package/package.json

@@ -4,7 +4,7 @@
   "keywords": [
     "appium"
   ],
-  "version": "12.2.9",
+  "version": "13.0.0",
   "author": "Appium Contributors",
   "license": "Apache-2.0",
   "repository": {
@@ -37,6 +37,7 @@
     "@appium/support": "^6.0.0",
     "appium-ios-device": "^2.0.0",
     "asyncbox": "^3.0.0",
+    "async-lock": "^1.4.1",
     "bluebird": "^3.4.7",
     "glob": "^10.3.3",
     "lodash": "^4.17.11",

package/build/lib/rpc/constants.d.ts

@@ -1,2 +0,0 @@
-export const ON_TARGET_PROVISIONED_EVENT: "onTargetProvisioned";
-//# sourceMappingURL=constants.d.ts.map

package/build/lib/rpc/constants.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../lib/rpc/constants.js"],"names":[],"mappings":"AAAA,0CAA2C,qBAAqB,CAAC"}

package/build/lib/rpc/constants.js

@@ -1,5 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ON_TARGET_PROVISIONED_EVENT = void 0;
-exports.ON_TARGET_PROVISIONED_EVENT = 'onTargetProvisioned';
-//# sourceMappingURL=constants.js.map

package/build/lib/rpc/constants.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../lib/rpc/constants.js"],"names":[],"mappings":";;;AAAa,QAAA,2BAA2B,GAAG,qBAAqB,CAAC"}

package/lib/rpc/constants.js

@@ -1 +0,0 @@
-export const ON_TARGET_PROVISIONED_EVENT = 'onTargetProvisioned';