appium-ios-remotexpc 0.0.1

package/src/lib/usbmux/usbmux-encoder.ts

@@ -0,0 +1,55 @@
+import { Transform, type TransformCallback } from 'stream';
+
+import { createPlist } from '../plist/index.js';
+import type { PlistDictionary } from '../types.js';
+
+const HEADER_LENGTH = 16;
+const VERSION = 1;
+const TYPE = 8;
+
+export interface UsbmuxEncodeData {
+  payload: PlistDictionary; // Using PlistDictionary for the payload
+  tag: number;
+}
+
+export class UsbmuxEncoder extends Transform {
+  constructor() {
+    super({ objectMode: true });
+  }
+
+  _transform(
+    data: UsbmuxEncodeData,
+    encoding: BufferEncoding,
+    callback: TransformCallback,
+  ): void {
+    this._encode(data);
+    callback();
+  }
+
+  private _encode(data: UsbmuxEncodeData): void {
+    const plistData = createPlist(data.payload, false);
+    const payloadBuffer = Buffer.isBuffer(plistData)
+      ? plistData
+      : Buffer.from(plistData);
+
+    const header = {
+      length: HEADER_LENGTH + payloadBuffer.length,
+      version: VERSION,
+      type: TYPE,
+      tag: data.tag,
+    };
+
+    const headerBuffer = Buffer.allocUnsafe(HEADER_LENGTH);
+    headerBuffer.writeUInt32LE(header.length, 0);
+    headerBuffer.writeUInt32LE(header.version, 4);
+    headerBuffer.writeUInt32LE(header.type, 8);
+    headerBuffer.writeUInt32LE(header.tag, 12);
+
+    this.push(
+      Buffer.concat(
+        [headerBuffer, payloadBuffer],
+        headerBuffer.length + payloadBuffer.length,
+      ),
+    );
+  }
+}

package/src/service-connection.ts

@@ -0,0 +1,79 @@
+import net from 'node:net';
+
+import { BasePlistService } from './base-plist-service.js';
+import type { PlistServiceOptions } from './lib/plist/plist-service.js';
+import type { PlistDictionary } from './lib/types.js';
+
+export interface ServiceConnectionOptions {
+  keepAlive?: boolean;
+  createConnectionTimeout?: number;
+  plistOptions?: PlistServiceOptions;
+}
+
+/**
+ * ServiceConnection for communicating with Apple device services over TCP
+ */
+export class ServiceConnection extends BasePlistService {
+  constructor(socket: net.Socket, options?: ServiceConnectionOptions) {
+    super(socket, options?.plistOptions);
+  }
+
+  /**
+   * Creates a TCP connection to the specified host and port
+   */
+  static createUsingTCP(
+    hostname: string,
+    port: string,
+    options?: ServiceConnectionOptions,
+  ): Promise<ServiceConnection> {
+    const keepAlive = options?.keepAlive ?? true;
+    const createConnectionTimeout = options?.createConnectionTimeout ?? 30000;
+
+    return new Promise<ServiceConnection>((resolve, reject) => {
+      const socket = net.createConnection(
+        { host: hostname, port: Number(port) },
+        () => {
+          socket.setTimeout(0);
+          if (keepAlive) {
+            socket.setKeepAlive(true);
+          }
+          resolve(new ServiceConnection(socket, options));
+        },
+      );
+
+      socket.setTimeout(createConnectionTimeout, () => {
+        socket.destroy();
+        reject(new Error('Connection timed out'));
+      });
+
+      socket.on('error', (err: Error) => reject(err));
+    });
+  }
+
+  /**
+   * Sends a plist request to the device and returns the response
+   */
+  sendPlistRequest(
+    requestObj: PlistDictionary,
+    timeout = 10000,
+  ): Promise<PlistDictionary> {
+    return this.sendAndReceive(requestObj, timeout);
+  }
+
+  /**
+   * Gets the underlying socket
+   * @returns The socket used by this service
+   */
+  getSocket(): net.Socket {
+    return this.getPlistService().getSocket() as net.Socket;
+  }
+
+  /**
+   * Closes the connection
+   */
+  close(): void {
+    super.close();
+  }
+}
+
+export default ServiceConnection;

package/src/services/index.ts

@@ -0,0 +1,15 @@
+import {
+  TunnelRegistryServer,
+  startTunnelRegistryServer,
+} from '../lib/tunnel/tunnel-registry-server.js';
+import * as diagnostics from './ios/diagnostic-service/index.js';
+import * as syslog from './ios/syslog-service/index.js';
+import * as tunnel from './ios/tunnel-service/index.js';
+
+export {
+  diagnostics,
+  syslog,
+  tunnel,
+  TunnelRegistryServer,
+  startTunnelRegistryServer,
+};

package/src/services/ios/base-service.ts

@@ -0,0 +1,81 @@
+import { logger } from '@appium/support';
+
+import { ServiceConnection } from '../../service-connection.js';
+
+const log = logger.getLogger('BaseService');
+
+/**
+ * Interface for service information
+ */
+export interface Service {
+  serviceName: string;
+  port: string;
+}
+
+/**
+ * Base class for iOS services that provides common functionality
+ */
+export class BaseService {
+  protected readonly address: [string, number];
+
+  /**
+   * Creates a new BaseService instance
+   * @param address Tuple containing [host, port]
+   */
+  constructor(address: [string, number]) {
+    this.address = address;
+  }
+
+  /**
+   * Starts a lockdown service without sending a check-in message
+   * @param service Service information
+   * @param options Additional options for the connection
+   * @returns Promise resolving to a ServiceConnection
+   */
+  public async startLockdownWithoutCheckin(
+    service: Service,
+    options: Record<string, any> = {},
+  ): Promise<ServiceConnection> {
+    // Get the port for the requested service
+    const port = service.port;
+    return ServiceConnection.createUsingTCP(this.address[0], port, options);
+  }
+
+  /**
+   * Starts a lockdown service with proper check-in
+   * @param service Service information
+   * @param options Additional options for the connection
+   * @returns Promise resolving to a ServiceConnection
+   */
+  public async startLockdownService(
+    service: Service,
+    options: Record<string, any> = {},
+  ): Promise<ServiceConnection> {
+    try {
+      const connection = await this.startLockdownWithoutCheckin(
+        service,
+        options,
+      );
+      const checkin = {
+        Label: 'appium-internal',
+        ProtocolVersion: '2',
+        Request: 'RSDCheckin',
+      };
+
+      const response = await connection.sendPlistRequest(checkin);
+      log.debug(
+        `Service check-in response: ${JSON.stringify(response, null, 2)}`,
+      );
+      return connection;
+    } catch (error: unknown) {
+      log.error('Error during check-in:', error);
+      if (error instanceof Error) {
+        log.error('Error message:', error.message);
+        log.error('Error stack:', error.stack);
+      }
+      throw error;
+    }
+  }
+}
+
+export default BaseService;

package/src/services/ios/diagnostic-service/index.ts

@@ -0,0 +1,241 @@
+import { logger } from '@appium/support';
+
+import { PlistServiceDecoder } from '../../../lib/plist/plist-decoder.js';
+import type {
+  DiagnosticsService as DiagnosticsServiceInterface,
+  PlistDictionary,
+} from '../../../lib/types.js';
+import { BaseService } from '../base-service.js';
+
+const log = logger.getLogger('DiagnosticService');
+
+/**
+ * DiagnosticsService provides an API to:
+ * - Query MobileGestalt & IORegistry keys
+ * - Reboot, shutdown or put the device in sleep mode
+ * - Get WiFi information
+ */
+class DiagnosticsService
+  extends BaseService
+  implements DiagnosticsServiceInterface
+{
+  static readonly RSD_SERVICE_NAME =
+    'com.apple.mobile.diagnostics_relay.shim.remote';
+
+  constructor(address: [string, number]) {
+    super(address);
+  }
+
+  /**
+   * Restart the device
+   * @returns Promise that resolves when the restart request is sent
+   */
+  async restart(): Promise<PlistDictionary> {
+    try {
+      const request: PlistDictionary = {
+        Request: 'Restart',
+      };
+
+      return await this.sendRequest(request);
+    } catch (error) {
+      log.error(`Error restarting device: ${error}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Shutdown the device
+   * @returns Promise that resolves when the shutdown request is sent
+   */
+  async shutdown(): Promise<PlistDictionary> {
+    try {
+      const request: PlistDictionary = {
+        Request: 'Shutdown',
+      };
+
+      return await this.sendRequest(request);
+    } catch (error) {
+      log.error(`Error shutting down device: ${error}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Put the device in sleep mode
+   * @returns Promise that resolves when the sleep request is sent
+   */
+  async sleep(): Promise<PlistDictionary> {
+    try {
+      const request: PlistDictionary = {
+        Request: 'Sleep',
+      };
+
+      return await this.sendRequest(request);
+    } catch (error) {
+      log.error(`Error putting device to sleep: ${error}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Query IORegistry
+   * @returns Object containing the IORegistry information
+   * @param options
+   */
+  async ioregistry(options?: {
+    plane?: string;
+    name?: string;
+    ioClass?: string;
+    returnRawJson?: boolean;
+    timeout?: number;
+  }): Promise<PlistDictionary[] | Record<string, any>> {
+    try {
+      const request: PlistDictionary = {
+        Request: 'IORegistry',
+      };
+
+      if (options?.plane) {
+        request.CurrentPlane = options.plane;
+      }
+      if (options?.name) {
+        request.EntryName = options.name;
+      }
+      if (options?.ioClass) {
+        request.EntryClass = options.ioClass;
+      }
+
+      PlistServiceDecoder.lastDecodedResult = null;
+
+      const timeout = options?.timeout || 3000;
+
+      log.debug('Sending IORegistry request...');
+
+      const conn = await this.connectToDiagnosticService();
+      const response = await conn.sendPlistRequest(request, timeout);
+
+      log.debug(
+        `IORegistry response size: ${JSON.stringify(response).length} bytes`,
+      );
+
+      if (options?.returnRawJson) {
+        return await this.handleMultipartIORegistryResponse(
+          conn,
+          response,
+          timeout,
+        );
+      }
+
+      return this.processIORegistryResponse(response);
+    } catch (error) {
+      log.error(`Error querying IORegistry: ${error}`);
+      throw error;
+    }
+  }
+
+  private getServiceConfig() {
+    return {
+      serviceName: DiagnosticsService.RSD_SERVICE_NAME,
+      port: this.address[1].toString(),
+    };
+  }
+
+  private async connectToDiagnosticService() {
+    const service = this.getServiceConfig();
+    return await this.startLockdownService(service);
+  }
+
+  private async sendRequest(
+    request: PlistDictionary,
+    timeout?: number,
+  ): Promise<PlistDictionary> {
+    const conn = await this.connectToDiagnosticService();
+    const response = await conn.sendPlistRequest(request, timeout);
+
+    log.debug(`${request.Request} response received`);
+
+    if (!response) {
+      return {};
+    }
+
+    if (Array.isArray(response)) {
+      return response.length > 0 ? (response[0] as PlistDictionary) : {};
+    }
+
+    return response as PlistDictionary;
+  }
+
+  private processIORegistryResponse(
+    response: any,
+  ): PlistDictionary[] | Record<string, any> {
+    if (PlistServiceDecoder.lastDecodedResult) {
+      if (Array.isArray(PlistServiceDecoder.lastDecodedResult)) {
+        return PlistServiceDecoder.lastDecodedResult as PlistDictionary[];
+      }
+      return [PlistServiceDecoder.lastDecodedResult as PlistDictionary];
+    }
+
+    if (!response) {
+      throw new Error('Invalid response from IORegistry');
+    }
+
+    if (Array.isArray(response)) {
+      if (response.length === 0 && typeof response === 'object') {
+        log.debug('Received empty array response');
+        return [{ IORegistryResponse: 'No data found' } as PlistDictionary];
+      }
+      return response as PlistDictionary[];
+    }
+
+    if (
+      typeof response === 'object' &&
+      !Buffer.isBuffer(response) &&
+      !(response instanceof Date)
+    ) {
+      const responseObj = response as Record<string, any>;
+
+      if (
+        responseObj.Diagnostics &&
+        typeof responseObj.Diagnostics === 'object'
+      ) {
+        return [responseObj.Diagnostics as PlistDictionary];
+      }
+
+      return [responseObj as PlistDictionary];
+    }
+
+    return [{ value: response } as PlistDictionary];
+  }
+
+  private async handleMultipartIORegistryResponse(
+    conn: any,
+    initialResponse: any,
+    timeout: number,
+  ): Promise<Record<string, any>> {
+    await new Promise((resolve) => setTimeout(resolve, 500));
+
+    const emptyRequest: PlistDictionary = {
+      Request: 'Status',
+    };
+
+    log.debug('Sending follow-up request for additional data');
+
+    const additionalResponse = await conn.sendPlistRequest(
+      emptyRequest,
+      timeout,
+    );
+    log.debug('Additional response: ', additionalResponse);
+    const hasDiagnostics =
+      'Diagnostics' in additionalResponse &&
+      typeof additionalResponse.Diagnostics === 'object' &&
+      additionalResponse.Diagnostics !== null &&
+      'IORegistry' in additionalResponse.Diagnostics;
+    if (additionalResponse.Status !== 'Success' && hasDiagnostics) {
+      throw new Error(`Error getting diagnostic data: ${additionalResponse}`);
+    }
+
+    log.debug('Using additional response with IORegistry data');
+    return additionalResponse.Diagnostics.IORegistry as Record<string, any>;
+  }
+}
+
+export default DiagnosticsService;