appium-ios-remotexpc 0.13.2 → 0.14.0

package/src/lib/types.ts

@@ -6,6 +6,7 @@ import { EventEmitter } from 'events';
 
 import type { ServiceConnection } from '../service-connection.js';
 import type { BaseService, Service } from '../services/ios/base-service.js';
+import type { LocationCoordinates } from '../services/ios/dvt/instruments/location-simulation.js';
 import { ProvisioningProfile } from '../services/ios/misagent/provisioning-profile.js';
 import type { PowerAssertionOptions } from '../services/ios/power-assertion/index.js';
 import { PowerAssertionType } from '../services/ios/power-assertion/index.js';
@@ -17,8 +18,13 @@ export type { PowerAssertionOptions };
 export { PowerAssertionType };
 
 /**
- * Represents a value that can be stored in a plist
+ * UID (Unique Identifier) interface for plist references
+ * Used in NSKeyedArchiver format
  */
+export interface IPlistUID {
+  value: number;
+}
+
 export type PlistValue =
   | string
   | number
@@ -26,6 +32,7 @@ export type PlistValue =
   | boolean
   | Date
   | Buffer
+  | IPlistUID
   | PlistArray
   | PlistDictionary
   | null;
@@ -347,6 +354,177 @@ export interface PowerAssertionServiceWithConnection {
   remoteXPC: RemoteXpcConnection;
 }
 
+/**
+ * DVT (Developer Tools) service interface
+ */
+export interface DVTSecureSocketProxyService extends BaseService {
+  /**
+   * Connect to the DVT service
+   */
+  connect(): Promise<void>;
+
+  /**
+   * Get supported identifiers (capabilities)
+   * @example
+   * const capabilities = dvtService.getSupportedIdentifiers();
+   * // Example output:
+   * // {
+   * //   "com.apple.instruments.server.services.processcontrol.capability.memorylimits": 1,
+   * //   "com.apple.instruments.server.services.coreml.perfrunner": 4,
+   * //   "com.apple.instruments.server.services.processcontrolbydictionary": 4,
+   * //   "com.apple.instruments.server.services.graphics.coreanimation.immediate": 1,
+   * //   // ... more identifiers
+   * // }
+   */
+  getSupportedIdentifiers(): PlistDictionary;
+
+  /**
+   * Create a channel for a specific identifier
+   * @param identifier The channel identifier
+   * @returns The created channel
+   */
+  makeChannel(identifier: string): Promise<any>;
+
+  /**
+   * Close the DVT service connection
+   */
+  close(): Promise<void>;
+}
+
+/**
+ * Location simulation service interface
+ */
+export interface LocationSimulationService {
+  /**
+   * Set the simulated location
+   * @param latitude The latitude
+   * @param longitude The longitude
+   */
+  setLocation(latitude: number, longitude: number): Promise<void>;
+
+  /**
+   * Set the simulated location using the LocationCoordinates type.
+   * @param coordinates The location coordinates
+   */
+  set(coordinates: LocationCoordinates): Promise<void>;
+
+  /**
+   * Clear/stop location simulation
+   *
+   * Note: This method is safe to call even if no location simulation is currently active.
+   */
+  clear(): Promise<void>;
+}
+
+/**
+ * Condition profile information
+ */
+export interface ConditionProfile {
+  identifier: string;
+  description?: string;
+  [key: string]: any;
+}
+
+/**
+ * Condition group information
+ */
+export interface ConditionGroup {
+  identifier: string;
+  profiles: ConditionProfile[];
+  [key: string]: any;
+}
+
+/**
+ * Condition inducer service interface
+ */
+export interface ConditionInducerService {
+  /**
+   * List all available condition inducers and their profiles
+   *
+   * Each group in the response contains information about whether a condition
+   * is currently active via the `isActive` field and which profile is active
+   * via the `activeProfile` field.
+   *
+   * @returns Array of condition groups with their available profiles
+   *
+   * @example
+   * ```typescript
+   * const groups = await conditionInducer.list();
+   * // Example response:
+   * // [
+   * //   {
+   * //     "profiles": [
+   * //       {
+   * //         "name": "100% packet loss",
+   * //         "identifier": "SlowNetwork100PctLoss",
+   * //         "description": "Name: 100% Loss Scenario\nDownlink Bandwidth: 0 Mbps\nDownlink Latency: 0 ms\nDownlink Packet Loss Ratio: 100%\nUplink Bandwidth: 0 Mbps\nUplink Latency: 0 ms\nUplink Packet Loss Ratio: 100%"
+   * //       },
+   * //       // ... more profiles
+   * //     ],
+   * //     "profilesSorted": true,
+   * //     "identifier": "SlowNetworkCondition",
+   * //     "isDestructive": false,
+   * //     "isInternal": false,
+   * //     "activeProfile": "",
+   * //     "name": "Network Link",
+   * //     "isActive": false
+   * //   },
+   * //   // ... more groups
+   * // ]
+   * ```
+   */
+  list(): Promise<ConditionGroup[]>;
+
+  /**
+   * Set a specific condition profile
+   *
+   * Note: If a condition is already active, attempting to set a new one will
+   * throw an error: {'NSLocalizedDescription': 'A condition is already active.'}
+   * You must call disable() first before setting a different condition.
+   *
+   * Available profile identifiers include (but may vary by iOS version):
+   * - Network profiles: SlowNetwork100PctLoss, SlowNetworkVeryBadNetwork,
+   *   SlowNetworkEdgeBad, SlowNetworkEdgeAverage, SlowNetworkEdgeGood,
+   *   SlowNetworkEdge, SlowNetwork2GRural, SlowNetwork2GUrban,
+   *   SlowNetwork3GAverage, SlowNetwork3GGood, SlowNetwork3G,
+   *   SlowNetworkLTE, SlowNetworkWiFi, SlowNetworkWiFi80211AC,
+   *   SlowNetworkDSL, SlowNetworkHighLatencyDNS
+   * - Thermal profiles: ThermalFair, ThermalSerious, ThermalCritical
+   * - GPU profiles: GPUPerformanceStateMin, GPUPerformanceStateMid, GPUPerformanceStateMax
+   * - And others depending on device capabilities
+   *
+   * Use list() to see all available profiles for your device.
+   *
+   * @param profileIdentifier The identifier of the profile to enable
+   * @throws Error if the profile identifier is not found
+   * @throws Error if a condition is already active
+   */
+  set(profileIdentifier: string): Promise<void>;
+
+  /**
+   * Disable the currently active condition
+   *
+   * Note: This method is idempotent - calling it when no condition is active
+   * will not throw an error.
+   */
+  disable(): Promise<void>;
+}
+
+/**
+ * DVT service with connection
+ * This allows callers to properly manage the connection lifecycle
+ */
+export interface DVTServiceWithConnection {
+  /** The DVTSecureSocketProxyService instance */
+  dvtService: DVTSecureSocketProxyService;
+  /** The LocationSimulation service instance */
+  locationSimulation: LocationSimulationService;
+  /** The ConditionInducer service instance */
+  conditionInducer: ConditionInducerService;
+  /** The RemoteXPC connection that can be used to close the connection */
+  remoteXPC: RemoteXpcConnection;
+}
+
 /**
  * Represents the WebInspectorService
  */

package/src/services/ios/dvt/channel-fragmenter.ts

@@ -0,0 +1,42 @@
+import type { DTXMessageHeader } from './dtx-message.js';
+
+/**
+ * Handles message fragmentation for DTX channels
+ * Assembles fragmented messages and queues complete messages for retrieval
+ */
+export class ChannelFragmenter {
+  private readonly messages: Buffer[] = [];
+  private packetData: Buffer = Buffer.alloc(0);
+  private streamPacketData: Buffer = Buffer.alloc(0);
+
+  /**
+   * Get the next complete message from the queue
+   */
+  get(): Buffer | null {
+    return this.messages.shift() || null;
+  }
+
+  /**
+   * Add a message fragment and assemble if complete
+   * @param header The message header
+   * @param chunk The message data chunk
+   */
+  addFragment(header: DTXMessageHeader, chunk: Buffer): void {
+    // Handle positive vs negative channel codes (regular vs stream data)
+    if (header.channelCode >= 0) {
+      this.packetData = Buffer.concat([this.packetData, chunk]);
+
+      if (header.fragmentId === header.fragmentCount - 1) {
+        this.messages.push(this.packetData);
+        this.packetData = Buffer.alloc(0);
+      }
+    } else {
+      this.streamPacketData = Buffer.concat([this.streamPacketData, chunk]);
+
+      if (header.fragmentId === header.fragmentCount - 1) {
+        this.messages.push(this.streamPacketData);
+        this.streamPacketData = Buffer.alloc(0);
+      }
+    }
+  }
+}

package/src/services/ios/dvt/channel.ts

@@ -0,0 +1,58 @@
+import type { MessageAux } from './dtx-message.js';
+import type { DVTSecureSocketProxyService } from './index.js';
+
+export type ChannelMethodCall = (
+  args?: MessageAux,
+  expectsReply?: boolean,
+) => Promise<void>;
+
+/**
+ * Represents a DTX communication channel for a specific instrument service
+ */
+export class Channel {
+  constructor(
+    private readonly channelCode: number,
+    private readonly service: DVTSecureSocketProxyService,
+  ) {}
+
+  /**
+   * Receive a plist response from the channel
+   */
+  async receivePlist(): Promise<any> {
+    const [data] = await this.service.recvPlist(this.channelCode);
+    return data;
+  }
+
+  /**
+   * Call a method on this channel with automatic ObjectiveC selector conversion
+   *
+   * Converts method names to ObjectiveC selector format:
+   * - 'methodName' -> 'methodName'
+   * - 'method_name' -> 'method:name:'
+   * - '_method_name' -> '_method:name:'
+   *
+   * @param methodName The method name
+   * @returns A function that sends the message with optional arguments
+   */
+  call(methodName: string): ChannelMethodCall {
+    const selector = this.convertToSelector(methodName);
+    return (async (args, expectsReply = true) => {
+      await this.service.sendMessage(
+        this.channelCode,
+        selector,
+        args,
+        expectsReply,
+      );
+    }) as ChannelMethodCall;
+  }
+
+  /**
+   * Convert method name to ObjectiveC selector format
+   */
+  private convertToSelector(name: string): string {
+    if (name.startsWith('_')) {
+      return '_' + name.substring(1).replace(/_/g, ':');
+    }
+    return name.replace(/_/g, ':');
+  }
+}

package/src/services/ios/dvt/dtx-message.ts

@@ -0,0 +1,162 @@
+/**
+ * DTX Message Header structure
+ */
+export interface DTXMessageHeader {
+  magic: number;
+  cb: number;
+  fragmentId: number;
+  fragmentCount: number;
+  length: number;
+  identifier: number;
+  conversationIndex: number;
+  channelCode: number;
+  expectsReply: number;
+}
+
+/**
+ * DTX Message Payload Header structure
+ */
+export interface DTXMessagePayloadHeader {
+  flags: number;
+  auxiliaryLength: number;
+  totalLength: bigint;
+}
+
+/**
+ * Message auxiliary value structure
+ */
+export interface MessageAuxValue {
+  type: number;
+  value: any;
+}
+
+/**
+ * DTX Protocol constants
+ */
+export const DTX_CONSTANTS = {
+  MESSAGE_HEADER_MAGIC: 0x1f3d5b79,
+  MESSAGE_HEADER_SIZE: 32,
+  PAYLOAD_HEADER_SIZE: 16,
+  MESSAGE_AUX_MAGIC: 0x1f0,
+  EMPTY_DICTIONARY: 0xa,
+
+  // Message types
+  INSTRUMENTS_MESSAGE_TYPE: 2,
+  EXPECTS_REPLY_MASK: 0x1000,
+
+  // Auxiliary value types
+  AUX_TYPE_OBJECT: 2,
+  AUX_TYPE_INT32: 3,
+  AUX_TYPE_INT64: 6,
+} as const;
+
+/**
+ * DTX Message utilities for encoding and decoding protocol messages
+ */
+export class DTXMessage {
+  /**
+   * Parse DTX message header from buffer
+   */
+  static parseMessageHeader(buffer: Buffer): DTXMessageHeader {
+    if (buffer.length < DTX_CONSTANTS.MESSAGE_HEADER_SIZE) {
+      throw new Error('Buffer too small for DTX message header');
+    }
+
+    return {
+      magic: buffer.readUInt32LE(0),
+      cb: buffer.readUInt32LE(4),
+      fragmentId: buffer.readUInt16LE(8),
+      fragmentCount: buffer.readUInt16LE(10),
+      length: buffer.readUInt32LE(12),
+      identifier: buffer.readUInt32LE(16),
+      conversationIndex: buffer.readUInt32LE(20),
+      channelCode: buffer.readInt32LE(24),
+      expectsReply: buffer.readUInt32LE(28),
+    };
+  }
+
+  /**
+   * Build DTX message header buffer
+   */
+  static buildMessageHeader(header: DTXMessageHeader): Buffer {
+    const buffer = Buffer.alloc(DTX_CONSTANTS.MESSAGE_HEADER_SIZE);
+
+    buffer.writeUInt32LE(header.magic, 0);
+    buffer.writeUInt32LE(header.cb, 4);
+    buffer.writeUInt16LE(header.fragmentId, 8);
+    buffer.writeUInt16LE(header.fragmentCount, 10);
+    buffer.writeUInt32LE(header.length, 12);
+    buffer.writeUInt32LE(header.identifier, 16);
+    buffer.writeUInt32LE(header.conversationIndex, 20);
+    buffer.writeInt32LE(header.channelCode, 24);
+    buffer.writeUInt32LE(header.expectsReply, 28);
+
+    return buffer;
+  }
+
+  /**
+   * Parse DTX payload header from buffer
+   */
+  static parsePayloadHeader(buffer: Buffer): DTXMessagePayloadHeader {
+    if (buffer.length < DTX_CONSTANTS.PAYLOAD_HEADER_SIZE) {
+      throw new Error('Buffer too small for DTX payload header');
+    }
+
+    return {
+      flags: buffer.readUInt32LE(0),
+      auxiliaryLength: buffer.readUInt32LE(4),
+      totalLength: buffer.readBigUInt64LE(8),
+    };
+  }
+
+  /**
+   * Build DTX payload header buffer
+   */
+  static buildPayloadHeader(header: DTXMessagePayloadHeader): Buffer {
+    const buffer = Buffer.alloc(DTX_CONSTANTS.PAYLOAD_HEADER_SIZE);
+
+    buffer.writeUInt32LE(header.flags, 0);
+    buffer.writeUInt32LE(header.auxiliaryLength, 4);
+    buffer.writeBigUInt64LE(header.totalLength, 8);
+
+    return buffer;
+  }
+}
+
+/**
+ * Message auxiliary builder for DTX protocol parameters
+ */
+export class MessageAux {
+  private readonly values: MessageAuxValue[] = [];
+
+  /**
+   * Append a 32-bit integer
+   */
+  appendInt(value: number): MessageAux {
+    this.values.push({ type: DTX_CONSTANTS.AUX_TYPE_INT32, value });
+    return this;
+  }
+
+  /**
+   * Append a 64-bit integer (bigint)
+   */
+  appendLong(value: bigint): MessageAux {
+    this.values.push({ type: DTX_CONSTANTS.AUX_TYPE_INT64, value });
+    return this;
+  }
+
+  /**
+   * Append an object (will be archived as NSKeyedArchiver plist)
+   */
+  appendObj(value: any): MessageAux {
+    this.values.push({ type: DTX_CONSTANTS.AUX_TYPE_OBJECT, value });
+    return this;
+  }
+
+  /**
+   * Get raw values for encoding
+   */
+  getValues(): MessageAuxValue[] {
+    return this.values;
+  }
+}