appium-ios-remotexpc 0.7.0 → 0.9.0

package/src/services/ios/power-assertion/index.ts

@@ -0,0 +1,100 @@
+import { logger } from '@appium/support';
+
+import type {
+  PlistDictionary,
+  PowerAssertionService as PowerAssertionServiceInterface,
+} from '../../../lib/types.js';
+import { ServiceConnection } from '../../../service-connection.js';
+import { BaseService } from '../base-service.js';
+
+const log = logger.getLogger('PowerAssertionService');
+
+/**
+ * Power assertion types that can be used to prevent system sleep
+ */
+export enum PowerAssertionType {
+  WIRELESS_SYNC = 'AMDPowerAssertionTypeWirelessSync',
+  PREVENT_USER_IDLE_SYSTEM_SLEEP = 'PreventUserIdleSystemSleep',
+  PREVENT_SYSTEM_SLEEP = 'PreventSystemSleep',
+}
+
+/**
+ * Options for power assertion creation
+ */
+export interface PowerAssertionOptions {
+  type: PowerAssertionType;
+  name: string;
+  timeout: number; // timeout in seconds
+  details?: string;
+}
+
+/**
+ * PowerAssertionService provides an API to create power assertions.
+ */
+class PowerAssertionService
+  extends BaseService
+  implements PowerAssertionServiceInterface
+{
+  static readonly RSD_SERVICE_NAME =
+    'com.apple.mobile.assertion_agent.shim.remote';
+
+  private _conn: ServiceConnection | null = null;
+
+  /**
+   * Create a power assertion to prevent system sleep
+   * @param options Options for creating the power assertion
+   * @returns Promise that resolves when the assertion is created
+   */
+  async createPowerAssertion(options: PowerAssertionOptions): Promise<void> {
+    if (!this._conn) {
+      this._conn = await this.connectToPowerAssertionService();
+    }
+
+    const request = this.buildCreateAssertionRequest(options);
+    await this._conn.sendPlistRequest(request);
+    log.info(
+      `Power assertion created: type="${options.type}", name="${options.name}", timeout=${options.timeout}s`,
+    );
+  }
+
+  /**
+   * Close the connection to the power assertion service
+   */
+  async close(): Promise<void> {
+    if (this._conn) {
+      await this._conn.close();
+      this._conn = null;
+      log.debug('Power assertion service connection closed');
+    }
+  }
+
+  private async connectToPowerAssertionService(): Promise<ServiceConnection> {
+    const service = {
+      serviceName: PowerAssertionService.RSD_SERVICE_NAME,
+      port: this.address[1].toString(),
+    };
+    log.debug(
+      `Connecting to power assertion service at ${this.address[0]}:${this.address[1]}`,
+    );
+    return await this.startLockdownService(service);
+  }
+
+  private buildCreateAssertionRequest(
+    options: PowerAssertionOptions,
+  ): PlistDictionary {
+    const request: PlistDictionary = {
+      CommandKey: 'CommandCreateAssertion',
+      AssertionTypeKey: options.type,
+      AssertionNameKey: options.name,
+      AssertionTimeoutKey: options.timeout,
+    };
+
+    if (options.details !== undefined) {
+      request.AssertionDetailKey = options.details;
+    }
+
+    return request;
+  }
+}
+
+export { PowerAssertionService };

package/src/services/ios/webinspector/index.ts

@@ -0,0 +1,372 @@
+import { logger } from '@appium/support';
+import { randomUUID } from 'crypto';
+import { EventEmitter } from 'events';
+
+import type { PlistDictionary, PlistMessage } from '../../../lib/types.js';
+import { ServiceConnection } from '../../../service-connection.js';
+import { BaseService } from '../base-service.js';
+
+const log = logger.getLogger('WebInspectorService');
+
+/**
+ * Interface for WebInspector message structure
+ */
+export interface WebInspectorMessage extends PlistDictionary {
+  __selector: string;
+  __argument: PlistDictionary;
+}
+
+/**
+ * WebInspectorService provides an API to:
+ * - Send messages to webinspectord
+ * - Listen to messages from webinspectord
+ * - Communicate with web views and Safari on iOS devices
+ *
+ * This service is used for web automation, inspection, and debugging.
+ */
+export class WebInspectorService extends BaseService {
+  static readonly RSD_SERVICE_NAME = 'com.apple.webinspector.shim.remote';
+
+  // RPC method selectors
+  private static readonly RPC_REPORT_IDENTIFIER = '_rpc_reportIdentifier:';
+  private static readonly RPC_REQUEST_APPLICATION_LAUNCH =
+    '_rpc_requestApplicationLaunch:';
+  private static readonly RPC_GET_CONNECTED_APPLICATIONS =
+    '_rpc_getConnectedApplications:';
+  private static readonly RPC_FORWARD_GET_LISTING = '_rpc_forwardGetListing:';
+  private static readonly RPC_FORWARD_AUTOMATION_SESSION_REQUEST =
+    '_rpc_forwardAutomationSessionRequest:';
+  private static readonly RPC_FORWARD_SOCKET_SETUP = '_rpc_forwardSocketSetup:';
+  private static readonly RPC_FORWARD_SOCKET_DATA = '_rpc_forwardSocketData:';
+  private static readonly RPC_FORWARD_INDICATE_WEB_VIEW =
+    '_rpc_forwardIndicateWebView:';
+
+  private connection: ServiceConnection | null = null;
+  private messageEmitter: EventEmitter = new EventEmitter();
+  private isReceiving: boolean = false;
+  private readonly connectionId: string;
+  private receivePromise: Promise<void> | null = null;
+
+  constructor(address: [string, number]) {
+    super(address);
+    this.connectionId = randomUUID().toUpperCase();
+  }
+
+  /**
+   * Send a message to the WebInspector service
+   * @param selector The RPC selector (e.g., '_rpc_reportIdentifier:')
+   * @param args The arguments dictionary for the message
+   * @returns Promise that resolves when the message is sent
+   */
+  async sendMessage(
+    selector: string,
+    args: PlistDictionary = {},
+  ): Promise<void> {
+    const connection = await this.connectToWebInspectorService();
+
+    // Add connection identifier to all messages
+    const message: WebInspectorMessage = {
+      __selector: selector,
+      __argument: {
+        ...args,
+        WIRConnectionIdentifierKey: this.connectionId,
+      },
+    };
+
+    log.debug(`Sending WebInspector message: ${selector}`);
+
+    connection.sendPlist(message);
+  }
+
+  /**
+   * Listen to messages from the WebInspector service using async generator
+   * @yields PlistMessage - Messages received from the WebInspector service
+   */
+  async *listenMessage(): AsyncGenerator<PlistMessage, void, unknown> {
+    await this.connectToWebInspectorService();
+
+    // Start receiving messages in background if not already started
+    if (!this.isReceiving) {
+      this.startMessageReceiver();
+    }
+
+    const queue: PlistMessage[] = [];
+    let resolveNext: ((value: IteratorResult<PlistMessage>) => void) | null =
+      null;
+    let stopped = false;
+
+    const messageHandler = (message: PlistMessage) => {
+      if (resolveNext) {
+        resolveNext({ value: message, done: false });
+        resolveNext = null;
+      } else {
+        queue.push(message);
+      }
+    };
+
+    const stopHandler = () => {
+      stopped = true;
+      if (resolveNext) {
+        resolveNext({ value: undefined, done: true });
+        resolveNext = null;
+      }
+    };
+
+    this.messageEmitter.on('message', messageHandler);
+    this.messageEmitter.once('stop', stopHandler);
+
+    try {
+      while (!stopped) {
+        if (queue.length > 0) {
+          yield queue.shift()!;
+        } else {
+          const message = await new Promise<PlistMessage | null>((resolve) => {
+            if (stopped) {
+              resolve(null);
+              return;
+            }
+            resolveNext = (result) => {
+              resolve(result.done ? null : result.value);
+            };
+          });
+
+          if (message === null) {
+            break;
+          }
+
+          yield message;
+        }
+      }
+    } finally {
+      this.messageEmitter.off('message', messageHandler);
+      this.messageEmitter.off('stop', stopHandler);
+    }
+  }
+
+  /**
+   * Stop listening to messages
+   */
+  stopListening(): void {
+    this.isReceiving = false;
+    this.messageEmitter.emit('stop');
+  }
+
+  /**
+   * Close the connection and clean up resources
+   */
+  async close(): Promise<void> {
+    this.stopListening();
+
+    if (this.connection) {
+      await this.connection.close();
+      this.connection = null;
+      log.debug('WebInspector connection closed');
+    }
+
+    if (this.receivePromise) {
+      await this.receivePromise;
+    }
+  }
+
+  /**
+   * Get the connection ID being used for this service
+   * @returns The connection identifier
+   */
+  getConnectionId(): string {
+    return this.connectionId;
+  }
+
+  /**
+   * Request application launch
+   * @param bundleId The bundle identifier of the application to launch
+   */
+  async requestApplicationLaunch(bundleId: string): Promise<void> {
+    await this.sendMessage(WebInspectorService.RPC_REQUEST_APPLICATION_LAUNCH, {
+      WIRApplicationBundleIdentifierKey: bundleId,
+    });
+  }
+
+  /**
+   * Get connected applications
+   */
+  async getConnectedApplications(): Promise<void> {
+    await this.sendMessage(
+      WebInspectorService.RPC_GET_CONNECTED_APPLICATIONS,
+      {},
+    );
+  }
+
+  /**
+   * Forward get listing for an application
+   * @param appId The application identifier
+   */
+  async forwardGetListing(appId: string): Promise<void> {
+    await this.sendMessage(WebInspectorService.RPC_FORWARD_GET_LISTING, {
+      WIRApplicationIdentifierKey: appId,
+    });
+  }
+
+  /**
+   * Forward automation session request
+   * @param sessionId The session identifier
+   * @param appId The application identifier
+   * @param capabilities Optional session capabilities
+   */
+  async forwardAutomationSessionRequest(
+    sessionId: string,
+    appId: string,
+    capabilities?: PlistDictionary,
+  ): Promise<void> {
+    const defaultCapabilities: PlistDictionary = {
+      'org.webkit.webdriver.webrtc.allow-insecure-media-capture': true,
+      'org.webkit.webdriver.webrtc.suppress-ice-candidate-filtering': false,
+    };
+
+    await this.sendMessage(
+      WebInspectorService.RPC_FORWARD_AUTOMATION_SESSION_REQUEST,
+      {
+        WIRApplicationIdentifierKey: appId,
+        WIRSessionIdentifierKey: sessionId,
+        WIRSessionCapabilitiesKey: {
+          ...defaultCapabilities,
+          ...(capabilities ?? {}),
+        },
+      },
+    );
+  }
+
+  /**
+   * Forward socket setup for inspector connection
+   * @param sessionId The session identifier
+   * @param appId The application identifier
+   * @param pageId The page identifier
+   * @param automaticallyPause Whether to automatically pause (defaults to true)
+   */
+  async forwardSocketSetup(
+    sessionId: string,
+    appId: string,
+    pageId: number,
+    automaticallyPause: boolean = true,
+  ): Promise<void> {
+    const message: PlistDictionary = {
+      WIRApplicationIdentifierKey: appId,
+      WIRPageIdentifierKey: pageId,
+      WIRSenderKey: sessionId,
+      WIRMessageDataTypeChunkSupportedKey: 0,
+    };
+
+    if (!automaticallyPause) {
+      message.WIRAutomaticallyPause = false;
+    }
+
+    await this.sendMessage(
+      WebInspectorService.RPC_FORWARD_SOCKET_SETUP,
+      message,
+    );
+  }
+
+  /**
+   * Forward socket data to a page
+   * @param sessionId The session identifier
+   * @param appId The application identifier
+   * @param pageId The page identifier
+   * @param data The data to send (will be JSON stringified)
+   */
+  async forwardSocketData(
+    sessionId: string,
+    appId: string,
+    pageId: number,
+    data: any,
+  ): Promise<void> {
+    const socketData = typeof data === 'string' ? data : JSON.stringify(data);
+
+    await this.sendMessage(WebInspectorService.RPC_FORWARD_SOCKET_DATA, {
+      WIRApplicationIdentifierKey: appId,
+      WIRPageIdentifierKey: pageId,
+      WIRSessionIdentifierKey: sessionId,
+      WIRSenderKey: sessionId,
+      WIRSocketDataKey: Buffer.from(socketData, 'utf-8'),
+    });
+  }
+
+  /**
+   * Forward indicate web view
+   * @param appId The application identifier
+   * @param pageId The page identifier
+   * @param enable Whether to enable indication
+   */
+  async forwardIndicateWebView(
+    appId: string,
+    pageId: number,
+    enable: boolean,
+  ): Promise<void> {
+    await this.sendMessage(WebInspectorService.RPC_FORWARD_INDICATE_WEB_VIEW, {
+      WIRApplicationIdentifierKey: appId,
+      WIRPageIdentifierKey: pageId,
+      WIRIndicateEnabledKey: enable,
+    });
+  }
+
+  /**
+   * Connect to the WebInspector service
+   * @returns Promise resolving to the ServiceConnection instance
+   */
+  private async connectToWebInspectorService(): Promise<ServiceConnection> {
+    if (this.connection) {
+      return this.connection;
+    }
+
+    const service = {
+      serviceName: WebInspectorService.RSD_SERVICE_NAME,
+      port: this.address[1].toString(),
+    };
+
+    this.connection = await this.startLockdownService(service);
+
+    // Consume the StartService response from RSDCheckin
+    const startServiceResponse = await this.connection.receive();
+    if (startServiceResponse?.Request !== 'StartService') {
+      log.warn(
+        `Expected StartService response, got: ${JSON.stringify(startServiceResponse)}`,
+      );
+    }
+
+    // Send initial identifier report
+    await this.sendMessage(WebInspectorService.RPC_REPORT_IDENTIFIER, {});
+
+    log.debug('Connected to WebInspector service');
+    return this.connection;
+  }
+
+  /**
+   * Start receiving messages from the WebInspector service in the background
+   */
+  private startMessageReceiver(): void {
+    if (this.isReceiving || !this.connection) {
+      return;
+    }
+
+    this.isReceiving = true;
+
+    this.receivePromise = (async () => {
+      try {
+        while (this.isReceiving && this.connection) {
+          try {
+            const message = await this.connection.receive();
+            this.messageEmitter.emit('message', message);
+          } catch (error) {
+            if (this.isReceiving) {
+              log.error('Error receiving message:', error);
+              this.messageEmitter.emit('error', error);
+            }
+            break;
+          }
+        }
+      } finally {
+        this.isReceiving = false;
+      }
+    })();
+  }
+}
+
+export default WebInspectorService;

package/src/services.ts

@@ -8,15 +8,19 @@ import type {
   MobileConfigServiceWithConnection,
   MobileImageMounterServiceWithConnection,
   NotificationProxyServiceWithConnection,
+  PowerAssertionServiceWithConnection,
   SpringboardServiceWithConnection,
   SyslogService as SyslogServiceType,
+  WebInspectorServiceWithConnection,
 } from './lib/types.js';
 import DiagnosticsService from './services/ios/diagnostic-service/index.js';
 import { MobileConfigService } from './services/ios/mobile-config/index.js';
 import MobileImageMounterService from './services/ios/mobile-image-mounter/index.js';
 import { NotificationProxyService } from './services/ios/notification-proxy/index.js';
+import { PowerAssertionService } from './services/ios/power-assertion/index.js';
 import { SpringBoardService } from './services/ios/springboard-service/index.js';
 import SyslogService from './services/ios/syslog-service/index.js';
+import { WebInspectorService } from './services/ios/webinspector/index.js';
 
 const APPIUM_XCUITEST_DRIVER_NAME = 'appium-xcuitest-driver';
 const TUNNEL_REGISTRY_PORT = 'tunnelRegistryPort';
@@ -100,6 +104,22 @@ export async function startSpringboardService(
   };
 }
 
+export async function startPowerAssertionService(
+  udid: string,
+): Promise<PowerAssertionServiceWithConnection> {
+  const { remoteXPC, tunnelConnection } = await createRemoteXPCConnection(udid);
+  const powerAssertionService = remoteXPC.findService(
+    PowerAssertionService.RSD_SERVICE_NAME,
+  );
+  return {
+    remoteXPC: remoteXPC as RemoteXpcConnection,
+    powerAssertionService: new PowerAssertionService([
+      tunnelConnection.host,
+      parseInt(powerAssertionService.port, 10),
+    ]),
+  };
+}
+
 export async function startSyslogService(
   udid: string,
 ): Promise<SyslogServiceType> {
@@ -107,6 +127,22 @@ export async function startSyslogService(
   return new SyslogService([tunnelConnection.host, tunnelConnection.port]);
 }
 
+export async function startWebInspectorService(
+  udid: string,
+): Promise<WebInspectorServiceWithConnection> {
+  const { remoteXPC, tunnelConnection } = await createRemoteXPCConnection(udid);
+  const webInspectorService = remoteXPC.findService(
+    WebInspectorService.RSD_SERVICE_NAME,
+  );
+  return {
+    remoteXPC: remoteXPC as RemoteXpcConnection,
+    webInspectorService: new WebInspectorService([
+      tunnelConnection.host,
+      parseInt(webInspectorService.port, 10),
+    ]),
+  };
+}
+
 export async function createRemoteXPCConnection(udid: string) {
   const tunnelConnection = await getTunnelInformation(udid);
   const remoteXPC = await startService(