appium-ios-remotexpc 0.0.1

package/src/lib/plist/plist-service.ts

@@ -0,0 +1,231 @@
+import { logger } from '@appium/support';
+import { Socket } from 'net';
+import { TLSSocket } from 'tls';
+
+import type { PlistDictionary } from '../types.js';
+import { LengthBasedSplitter } from './length-based-splitter.js';
+import { PlistServiceDecoder } from './plist-decoder.js';
+import { PlistServiceEncoder } from './plist-encoder.js';
+
+const log = logger.getLogger('Plist');
+const errorLog = logger.getLogger('PlistError');
+
+const config = {
+  verboseErrorLogging: false,
+};
+
+/**
+ * Message type for plist communications
+ */
+type PlistMessage = PlistDictionary;
+
+/**
+ * Options for PlistService
+ */
+export interface PlistServiceOptions {
+  maxFrameLength?: number;
+}
+
+/**
+ * Service for communication using plist protocol
+ */
+export class PlistService {
+  /**
+   * Enable verbose error logging
+   */
+  static enableVerboseErrorLogging(): void {
+    config.verboseErrorLogging = true;
+    errorLog.debug('Verbose plist error logging enabled');
+  }
+
+  /**
+   * Disable verbose error logging
+   */
+  static disableVerboseErrorLogging(): void {
+    config.verboseErrorLogging = false;
+  }
+
+  /**
+   * Check if verbose error logging is enabled
+   * @returns True if verbose error logging is enabled
+   */
+  static isVerboseErrorLoggingEnabled(): boolean {
+    return config.verboseErrorLogging;
+  }
+
+  /**
+   * Gets the underlying socket
+   * @returns The socket used by this service
+   */
+  public getSocket(): Socket | TLSSocket {
+    return this._socket;
+  }
+  private readonly _socket: Socket | TLSSocket;
+  private readonly _splitter: LengthBasedSplitter;
+  private readonly _decoder: PlistServiceDecoder;
+  private _encoder: PlistServiceEncoder;
+  private _messageQueue: PlistMessage[];
+
+  /**
+   * Creates a new PlistService instance
+   * @param socket The socket to use for communication
+   * @param options Configuration options
+   */
+  constructor(socket: Socket, options: PlistServiceOptions = {}) {
+    this._socket = socket;
+
+    // Set up transformers
+    this._splitter = new LengthBasedSplitter({
+      maxFrameLength: options.maxFrameLength ?? 100 * 1024 * 1024, // Default to 100MB
+    });
+    this._decoder = new PlistServiceDecoder();
+    this._encoder = new PlistServiceEncoder();
+
+    // Set up the pipeline
+    this.setupPipeline();
+
+    // Message queue for async receiving
+    this._messageQueue = [];
+    this._decoder.on('data', (data: PlistMessage) =>
+      this._messageQueue.push(data),
+    );
+
+    // Handle errors
+    this.setupErrorHandlers();
+  }
+
+  /**
+   * Send a plist message and receive a response
+   * @param data Message to send
+   * @param timeout Response timeout in ms
+   * @returns Promise resolving to the received message
+   */
+  public async sendPlistAndReceive(
+    data: PlistMessage,
+    timeout = 5000,
+  ): Promise<PlistMessage> {
+    this.sendPlist(data);
+    return this.receivePlist(timeout);
+  }
+
+  /**
+   * Send a plist message
+   * @param data Message to send
+   * @throws Error if data is null or undefined
+   */
+  public sendPlist(data: PlistMessage): void {
+    if (!data) {
+      throw new Error('Cannot send null or undefined data');
+    }
+    this._encoder.write(data);
+  }
+
+  /**
+   * Receive a plist message with timeout
+   * @param timeout Timeout in ms
+   * @returns Promise resolving to the received message
+   * @throws Error if timeout is reached before receiving a message
+   */
+  public async receivePlist(timeout = 5000): Promise<PlistMessage> {
+    return new Promise<PlistMessage>((resolve, reject) => {
+      // Check if we already have a message
+      const message = this._messageQueue.shift();
+      if (message) {
+        return resolve(message);
+      }
+
+      // Set up a check interval
+      const checkInterval = setInterval(() => {
+        const message = this._messageQueue.shift();
+        if (message) {
+          clearInterval(checkInterval);
+          clearTimeout(timeoutId);
+          resolve(message);
+        }
+      }, 50);
+
+      // Set up timeout
+      const timeoutId = setTimeout(() => {
+        clearInterval(checkInterval);
+        reject(
+          new Error(`Timed out waiting for plist response after ${timeout}ms`),
+        );
+      }, timeout);
+    });
+  }
+
+  /**
+   * Close the connection and clean up resources
+   */
+  public close(): void {
+    try {
+      // Remove all data listeners to prevent parsing during close
+      this._splitter.removeAllListeners();
+      this._decoder.removeAllListeners();
+
+      // Clear the message queue to prevent processing during close
+      this._messageQueue = [];
+
+      // Unpipe the transformers to prevent data flow during close
+      try {
+        this._socket.unpipe(this._splitter);
+        this._splitter.unpipe(this._decoder);
+      } catch (unpipeError) {
+        log.debug(
+          `Non-critical error during unpipe: ${unpipeError instanceof Error ? unpipeError.message : String(unpipeError)}`,
+        );
+      }
+
+      // End the socket
+      this._socket.end();
+    } catch (error) {
+      // Log the error but don't rethrow it to ensure cleanup completes
+      log.error(
+        `Error closing socket: ${error instanceof Error ? error.message : String(error)}`,
+      );
+
+      // If ending fails, destroy the socket
+      this._socket.destroy();
+    }
+  }
+
+  /**
+   * Sets up the data pipeline between socket and transformers
+   */
+  private setupPipeline(): void {
+    this._socket.pipe(this._splitter);
+    this._splitter.pipe(this._decoder);
+    this._encoder.pipe(this._socket);
+  }
+
+  /**
+   * Sets up error handlers for socket and transformers
+   */
+  private setupErrorHandlers(): void {
+    this._socket.on('error', this.handleError.bind(this));
+    this._encoder.on('error', this.handleError.bind(this));
+    this._decoder.on('error', this.handleError.bind(this));
+    this._splitter.on('error', this.handleError.bind(this));
+  }
+
+  /**
+   * Handles errors from any component
+   * @param error The error that occurred
+   */
+  private handleError(error: Error): void {
+    // Only log detailed errors if verbose logging is enabled
+    if (!config.verboseErrorLogging) {
+      return;
+    }
+
+    errorLog.debug(`PlistService Error: ${error.message}`);
+
+    // If this is an XML parsing error, it might be a binary plist
+    if (
+      error.message.includes('Invalid XML') ||
+      error.message.includes('XML parsing')
+    ) {
+      errorLog.debug('This might be a binary plist with a non-standard format');
+    }
+  }
+}

package/src/lib/plist/unified-plist-creator.ts

@@ -0,0 +1,19 @@
+import type { PlistDictionary } from '../types.js';
+import { createBinaryPlist } from './binary-plist-creator.js';
+import { createPlist as createXmlPlist } from './plist-creator.js';
+
+/**
+ * Unified plist creator that can create both XML and binary plists
+ * @param obj - The JavaScript object to convert to a plist
+ * @param binary - Whether to create a binary plist (true) or XML plist (false)
+ * @returns The plist data as a string (XML) or Buffer (binary)
+ */
+export function createPlist(
+  obj: PlistDictionary,
+  binary: boolean = false,
+): string | Buffer {
+  if (binary) {
+    return createBinaryPlist(obj);
+  }
+  return createXmlPlist(obj);
+}

package/src/lib/plist/unified-plist-parser.ts

@@ -0,0 +1,25 @@
+import type { PlistValue } from '../types.js';
+import { isBinaryPlist, parseBinaryPlist } from './binary-plist-parser.js';
+import { parsePlist as parseXmlPlist } from './plist-parser.js';
+import { ensureString } from './utils.js';
+
+/**
+ * Unified plist parser that can handle both XML and binary plists
+ * @param data - The plist data as a string or Buffer
+ * @returns The parsed JavaScript object
+ */
+export function parsePlist(data: string | Buffer): PlistValue {
+  try {
+    // Check if it's a binary plist (only if data is a Buffer)
+    if (Buffer.isBuffer(data) && isBinaryPlist(data)) {
+      return parseBinaryPlist(data);
+    } else {
+      // Otherwise, assume it's an XML plist
+      return parseXmlPlist(ensureString(data));
+    }
+  } catch (error) {
+    throw new Error(
+      `Failed to parse plist: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}

package/src/lib/plist/utils.ts

@@ -0,0 +1,376 @@
+import { UTF8_ENCODING } from './constants.js';
+
+/**
+ * Represents a tag position in XML
+ */
+export interface TagPosition {
+  start: number;
+  end: number;
+  isOpening: boolean;
+  tagName: string;
+}
+
+/**
+ * Represents the result of finding tags around a position
+ */
+export interface TagsAroundPosition {
+  beforeTag: TagPosition | null;
+  afterTag: TagPosition | null;
+}
+
+/**
+ * Ensures data is a string for string operations
+ *
+ * @param data - The data to convert, can be a string or Buffer
+ * @returns The data as a string
+ */
+export function ensureString(data: string | Buffer): string {
+  return typeof data === 'string' ? data : data.toString(UTF8_ENCODING);
+}
+
+/**
+ * Finds the position of the first Unicode replacement character in the data.
+ *
+ * @param data - The data to check, can be a string or Buffer
+ * @returns The position of the first replacement character, or -1 if not found
+ */
+export function findFirstReplacementCharacter(data: string | Buffer): number {
+  const strData = ensureString(data);
+  return strData.indexOf('�');
+}
+
+/**
+ * Checks if the provided data contains Unicode replacement characters (�),
+ * which might indicate encoding issues.
+ *
+ * @param data - The data to check, can be a string or Buffer
+ * @returns True if replacement characters are found, false otherwise
+ */
+export function hasUnicodeReplacementCharacter(data: string | Buffer): boolean {
+  const strData = ensureString(data);
+
+  return strData.includes('�');
+}
+
+/**
+ * Finds the XML declaration and trims any preceding content
+ *
+ * @param data - The data to process, can be a string or Buffer
+ * @returns The trimmed data as a string
+ */
+export function trimBeforeXmlDeclaration(data: string | Buffer): string {
+  const strData = ensureString(data);
+  const xmlDeclIndex = strData.indexOf('<?xml');
+
+  if (xmlDeclIndex > 0) {
+    return strData.slice(xmlDeclIndex);
+  }
+
+  return strData;
+}
+
+/**
+ * Checks for multiple XML declarations and fixes the data by keeping only the first one
+ *
+ * @param data - The data to check and fix, can be a string or Buffer
+ * @returns The fixed data as a string, or the original data if no fix was needed
+ */
+export function fixMultipleXmlDeclarations(data: string | Buffer): string {
+  const strData = ensureString(data);
+  const xmlDeclMatches = strData.match(/(<\?xml[^>]*\?>)/g) || [];
+  const xmlDeclCount = xmlDeclMatches.length;
+
+  if (xmlDeclCount > 1) {
+    const firstDeclEnd = strData.indexOf('?>') + 2;
+    const restOfXml = strData.substring(firstDeclEnd);
+    const cleanedRest = restOfXml.replace(/<\?xml[^>]*\?>/g, '');
+    return strData.substring(0, firstDeclEnd) + cleanedRest;
+  }
+
+  return strData;
+}
+
+/**
+ * Removes extra content after the closing plist tag
+ *
+ * @param data - The data to clean, can be a string or Buffer
+ * @returns The cleaned data as a string
+ */
+export function removeExtraContentAfterPlist(data: string | Buffer): string {
+  const strData = ensureString(data);
+
+  const closingPlistIndex = strData.lastIndexOf('</plist>');
+
+  if (closingPlistIndex > 0) {
+    return strData.substring(0, closingPlistIndex + 8);
+  }
+
+  return strData;
+}
+
+/**
+ * Checks if the data is valid XML (contains at least one tag)
+ *
+ * @param data - The data to check, can be a string or Buffer
+ * @returns True if the data is valid XML, false otherwise
+ */
+export function isValidXml(data: string | Buffer): boolean {
+  const strData = ensureString(data);
+  return Boolean(strData) && Boolean(strData.trim()) && strData.includes('<');
+}
+
+/**
+ * Escapes special XML characters in a string
+ *
+ * @param str - The string to escape
+ * @returns The escaped string
+ */
+export function escapeXml(str: string): string {
+  return str.replace(/[<>&"']/g, function (c) {
+    switch (c) {
+      case '<':
+        return '&lt;';
+      case '>':
+        return '&gt;';
+      case '&':
+        return '&amp;';
+      case '"':
+        return '&quot;';
+      // eslint-disable-next-line quotes -- Prettier uses double quotes here to avoid escaping the single quote character
+      case `'`:
+        return '&apos;';
+      default:
+        return c;
+    }
+  });
+}
+
+/**
+ * Checks if the data contains XML plist content by detecting XML declaration or plist tags
+ *
+ * @param data - The data to check, can be a string or Buffer
+ * @returns True if the data contains XML plist content, false otherwise
+ */
+export function isXmlPlistContent(data: string | Buffer): boolean {
+  return (
+    data.toString(UTF8_ENCODING).includes('<?xml') ||
+    data.toString(UTF8_ENCODING).includes('<plist')
+  );
+}
+
+/**
+ * Parses a tag content to extract tag name and determine if it's an opening tag
+ *
+ * @param tagContent - The content between < and > in an XML tag
+ * @returns An object with tag name and whether it's an opening tag
+ */
+function parseTagContent(tagContent: string): {
+  tagName: string;
+  isOpening: boolean;
+} {
+  const isClosing = tagContent.startsWith('/');
+  const tagName = isClosing
+    ? tagContent.substring(1).trim().split(/\s+/)[0]
+    : tagContent.trim().split(/\s+/)[0];
+
+  return {
+    tagName,
+    isOpening: !isClosing,
+  };
+}
+
+/**
+ * Creates a TagPosition object from tag positions and content
+ *
+ * @param startPos - Start position of the tag
+ * @param endPos - End position of the tag
+ * @param tagContent - Content between < and > in the tag
+ * @returns A TagPosition object
+ */
+function createTagPosition(
+  startPos: number,
+  endPos: number,
+  tagContent: string,
+): TagPosition {
+  const { tagName, isOpening } = parseTagContent(tagContent);
+
+  return {
+    start: startPos,
+    end: endPos + 1,
+    isOpening,
+    tagName,
+  };
+}
+
+/**
+ * Finds the tag before a specific position in XML
+ *
+ * @param xmlString - The XML string to search
+ * @param position - The position to search before
+ * @returns The tag position or null if not found
+ */
+function findTagBefore(
+  xmlString: string,
+  position: number,
+): TagPosition | null {
+  const tagEndPos = xmlString.lastIndexOf('>', position);
+  if (tagEndPos < 0) {
+    return null;
+  }
+
+  const tagStartPos = xmlString.lastIndexOf('<', tagEndPos);
+  if (tagStartPos < 0) {
+    return null;
+  }
+
+  const tagContent = xmlString.substring(tagStartPos + 1, tagEndPos);
+  return createTagPosition(tagStartPos, tagEndPos, tagContent);
+}
+
+/**
+ * Finds the tag after a specific position in XML
+ *
+ * @param xmlString - The XML string to search
+ * @param position - The position to search after
+ * @returns The tag position or null if not found
+ */
+function findTagAfter(xmlString: string, position: number): TagPosition | null {
+  const tagStartPos = xmlString.indexOf('<', position);
+  if (tagStartPos < 0) {
+    return null;
+  }
+
+  const tagEndPos = xmlString.indexOf('>', tagStartPos);
+  if (tagEndPos < 0) {
+    return null;
+  }
+
+  const tagContent = xmlString.substring(tagStartPos + 1, tagEndPos);
+  return createTagPosition(tagStartPos, tagEndPos, tagContent);
+}
+
+/**
+ * Finds XML tags around a specific position
+ *
+ * @param xmlString - The XML string to search
+ * @param position - The position to search around
+ * @returns An object with the nearest tags before and after the position
+ */
+export function findTagsAroundPosition(
+  xmlString: string,
+  position: number,
+): TagsAroundPosition {
+  return {
+    beforeTag: findTagBefore(xmlString, position),
+    afterTag: findTagAfter(xmlString, position),
+  };
+}
+
+/**
+ * Removes content between two positions in an XML string
+ *
+ * @param xmlString - The XML string to modify
+ * @param startPos - The start position to remove from
+ * @param endPos - The end position to remove to
+ * @returns The modified XML string
+ */
+function removeContentBetween(
+  xmlString: string,
+  startPos: number,
+  endPos: number,
+): string {
+  return xmlString.substring(0, startPos) + xmlString.substring(endPos);
+}
+
+/**
+ * Handles the case where a replacement character is between complete tags
+ *
+ * @param xmlString - The XML string to clean
+ * @param beforeTag - The tag before the replacement character
+ * @param afterTag - The tag after the replacement character
+ * @returns The cleaned XML string
+ */
+function cleanBetweenTags(
+  xmlString: string,
+  beforeTag: TagPosition,
+  afterTag: TagPosition,
+): string {
+  return removeContentBetween(xmlString, beforeTag.end, afterTag.start);
+}
+
+/**
+ * Handles the case where a replacement character is inside a tag
+ *
+ * @param xmlString - The XML string to clean
+ * @param beforeTag - The tag containing the replacement character
+ * @param afterTag - The tag after the replacement character
+ * @returns The cleaned XML string or null if can't be cleaned
+ */
+function cleanInsideTag(
+  xmlString: string,
+  beforeTag: TagPosition,
+  afterTag: TagPosition,
+): string | null {
+  const prevCompleteTag = xmlString.lastIndexOf('>', beforeTag.start);
+  if (prevCompleteTag < 0) {
+    return null;
+  }
+
+  return removeContentBetween(xmlString, prevCompleteTag + 1, afterTag.start);
+}
+
+/**
+ * Fallback cleaning method when tags aren't available on both sides
+ *
+ * @param xmlString - The XML string to clean
+ * @returns The cleaned XML string
+ */
+function fallbackCleaning(xmlString: string): string {
+  const xmlDeclIndex = xmlString.indexOf('<?xml');
+  if (xmlDeclIndex > 0) {
+    return xmlString.slice(xmlDeclIndex);
+  }
+
+  const plistTagIndex = xmlString.indexOf('<plist');
+  if (plistTagIndex > 0) {
+    return xmlString.slice(plistTagIndex);
+  }
+
+  const anyTagIndex = xmlString.indexOf('<');
+  if (anyTagIndex > 0) {
+    return xmlString.slice(anyTagIndex);
+  }
+
+  return xmlString;
+}
+
+/**
+ * Intelligently cleans XML with Unicode replacement characters
+ *
+ * @param xmlString - The XML string to clean
+ * @param badCharPos - The position of the replacement character
+ * @returns The cleaned XML string
+ */
+export function cleanXmlWithReplacementChar(
+  xmlString: string,
+  badCharPos: number,
+): string {
+  const { beforeTag, afterTag } = findTagsAroundPosition(xmlString, badCharPos);
+
+  if (!beforeTag || !afterTag) {
+    return fallbackCleaning(xmlString);
+  }
+
+  if (beforeTag.end <= badCharPos && badCharPos < afterTag.start) {
+    return cleanBetweenTags(xmlString, beforeTag, afterTag);
+  }
+
+  if (beforeTag.start <= badCharPos && badCharPos < beforeTag.end) {
+    const cleaned = cleanInsideTag(xmlString, beforeTag, afterTag);
+    if (cleaned) {
+      return cleaned;
+    }
+  }
+
+  return removeContentBetween(xmlString, beforeTag.start, afterTag.start);
+}

package/src/lib/remote-xpc/constants.ts

@@ -0,0 +1,22 @@
+// HTTP/2 Constants
+export const Http2Constants = {
+  HTTP2_MAGIC: Buffer.from('PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n', 'ascii'),
+  FRAME_HEADER_SIZE: 9,
+  ROOT_CHANNEL: 1,
+  REPLY_CHANNEL: 3,
+  FLAG_END_HEADERS: 0x4,
+  FLAG_ACK: 0x1,
+  DEFAULT_SETTINGS_MAX_CONCURRENT_STREAMS: 100,
+  DEFAULT_SETTINGS_INITIAL_WINDOW_SIZE: 1048576,
+  DEFAULT_WIN_SIZE_INCR: 983041,
+  SETTINGS_MAX_CONCURRENT_STREAMS: 0x03,
+  SETTINGS_INITIAL_WINDOW_SIZE: 0x04,
+} as const;
+
+// XPC Constants
+export const XpcConstants = {
+  XPC_FLAGS_INIT_HANDSHAKE: 0x00400000,
+  XPC_FLAGS_ALWAYS_SET: 0x00000001,
+  XPC_FLAGS_DATA_PRESENT: 0x00000100,
+  XPC_FLAGS_WANTING_REPLY: 0x00010000,
+} as const;