appium-ios-remotexpc 0.0.1

package/src/lib/plist/length-based-splitter.ts

@@ -0,0 +1,326 @@
+import { logger } from '@appium/support';
+import { Transform, type TransformCallback } from 'stream';
+
+import {
+  BINARY_PLIST_HEADER_LENGTH,
+  BINARY_PLIST_MAGIC,
+  IBINARY_PLIST_MAGIC,
+  LENGTH_FIELD_1_BYTE,
+  LENGTH_FIELD_2_BYTES,
+  LENGTH_FIELD_4_BYTES,
+  LENGTH_FIELD_8_BYTES,
+  PLIST_CLOSING_TAG,
+  UINT32_HIGH_MULTIPLIER,
+  UTF8_ENCODING,
+  XML_DECLARATION,
+} from './constants.js';
+import { isXmlPlistContent } from './utils.js';
+
+const log = logger.getLogger('Plist');
+
+// Constants
+const DEFAULT_MAX_FRAME_LENGTH = 100 * 1024 * 1024; // 100MB default for large IORegistry responses
+const DEFAULT_LENGTH_FIELD_OFFSET = 0;
+const DEFAULT_LENGTH_FIELD_LENGTH = 4;
+const DEFAULT_LENGTH_ADJUSTMENT = 0;
+const MAX_PREVIEW_LENGTH = 100; // Maximum number of bytes to preview for content type detection
+
+/**
+ * Options for LengthBasedSplitter
+ */
+export interface LengthBasedSplitterOptions {
+  readableStream?: NodeJS.ReadableStream;
+  littleEndian?: boolean;
+  maxFrameLength?: number;
+  lengthFieldOffset?: number;
+  lengthFieldLength?: number;
+  lengthAdjustment?: number;
+}
+
+/**
+ * Splits incoming data into length-prefixed chunks
+ */
+export class LengthBasedSplitter extends Transform {
+  private buffer: Buffer;
+  private readonly littleEndian: boolean;
+  private readonly maxFrameLength: number;
+  private readonly lengthFieldOffset: number;
+  private readonly lengthFieldLength: number;
+  private readonly lengthAdjustment: number;
+  private isXmlMode: boolean = false;
+
+  /**
+   * Creates a new LengthBasedSplitter
+   * @param options Configuration options
+   */
+  constructor(options: LengthBasedSplitterOptions = {}) {
+    super();
+    this.buffer = Buffer.alloc(0);
+    this.littleEndian = options.littleEndian ?? false;
+    this.maxFrameLength = options.maxFrameLength ?? DEFAULT_MAX_FRAME_LENGTH;
+    this.lengthFieldOffset =
+      options.lengthFieldOffset ?? DEFAULT_LENGTH_FIELD_OFFSET;
+    this.lengthFieldLength =
+      options.lengthFieldLength ?? DEFAULT_LENGTH_FIELD_LENGTH;
+    this.lengthAdjustment =
+      options.lengthAdjustment ?? DEFAULT_LENGTH_ADJUSTMENT;
+
+    // If readableStream is provided, pipe it to this
+    if (options.readableStream) {
+      options.readableStream.pipe(this);
+    }
+  }
+
+  /**
+   * Shutdown the splitter and remove all listeners
+   */
+  shutdown(): void {
+    // Reset internal state
+    this.buffer = Buffer.alloc(0);
+    this.isXmlMode = false;
+
+    // Remove all listeners
+    this.removeAllListeners();
+    log.debug('LengthBasedSplitter shutdown complete');
+  }
+
+  _transform(
+    chunk: Buffer,
+    encoding: BufferEncoding,
+    callback: TransformCallback,
+  ): void {
+    try {
+      // Add the new chunk to our buffer
+      this.buffer = Buffer.concat([this.buffer, chunk]);
+
+      // Check if this is XML data or binary plist before doing any other processing
+      const bufferString = this.buffer.toString(
+        UTF8_ENCODING,
+        0,
+        Math.min(MAX_PREVIEW_LENGTH, this.buffer.length),
+      );
+
+      // Check for XML format
+      if (isXmlPlistContent(bufferString) || this.isXmlMode) {
+        // This is XML data, set XML mode
+        this.isXmlMode = true;
+        this.processXmlData(callback);
+        return;
+      }
+
+      // Check for binary plist format (bplist00 or Ibplist00)
+      if (this.buffer.length >= BINARY_PLIST_HEADER_LENGTH) {
+        const possibleBplistHeader = this.buffer.toString(
+          UTF8_ENCODING,
+          0,
+          BINARY_PLIST_HEADER_LENGTH,
+        );
+
+        if (
+          possibleBplistHeader === BINARY_PLIST_MAGIC ||
+          possibleBplistHeader.includes(BINARY_PLIST_MAGIC)
+        ) {
+          log.debug('Detected standard binary plist format');
+          this.push(this.buffer);
+          this.buffer = Buffer.alloc(0);
+          return callback();
+        }
+
+        if (
+          possibleBplistHeader === IBINARY_PLIST_MAGIC ||
+          possibleBplistHeader.includes(IBINARY_PLIST_MAGIC)
+        ) {
+          log.debug('Detected non-standard Ibplist00 format');
+          this.push(this.buffer);
+          this.buffer = Buffer.alloc(0);
+          return callback();
+        }
+      }
+      // Process as many complete messages as possible for binary data
+      this.processBinaryData(callback);
+    } catch (err) {
+      callback(err as Error);
+    }
+  }
+
+  /**
+   * Process data as XML
+   */
+  private processXmlData(callback: TransformCallback): void {
+    const fullBufferString = this.buffer.toString(UTF8_ENCODING);
+
+    let startIndex = 0;
+    if (!fullBufferString.startsWith(XML_DECLARATION)) {
+      const declIndex = fullBufferString.indexOf(XML_DECLARATION);
+      if (declIndex >= 0) {
+        startIndex = declIndex;
+      } else {
+        return callback();
+      }
+    }
+
+    // Now search for the closing tag in the string starting at startIndex.
+    const plistEndIndex = fullBufferString.indexOf(
+      PLIST_CLOSING_TAG,
+      startIndex,
+    );
+
+    if (plistEndIndex >= 0) {
+      const endPos = plistEndIndex + PLIST_CLOSING_TAG.length;
+
+      const xmlData = this.buffer.slice(0, endPos);
+
+      // Push the complete XML document downstream.
+      this.push(xmlData);
+
+      // Remove the processed data from the buffer.
+      this.buffer = this.buffer.slice(endPos);
+
+      // If there's remaining data, check if it still looks XML.
+      if (this.buffer.length === 0) {
+        this.isXmlMode = false;
+      } else {
+        const remainingData = this.buffer.toString(
+          UTF8_ENCODING,
+          0,
+          Math.min(MAX_PREVIEW_LENGTH, this.buffer.length),
+        );
+
+        this.isXmlMode = isXmlPlistContent(remainingData);
+      }
+    }
+
+    callback();
+  }
+
+  /**
+   * Process data as binary with length prefix
+   */
+  private processBinaryData(callback: TransformCallback): void {
+    while (
+      this.buffer.length >=
+      this.lengthFieldOffset + this.lengthFieldLength
+    ) {
+      let messageLength: number;
+
+      // Read the length prefix according to configuration
+      if (this.lengthFieldLength === LENGTH_FIELD_4_BYTES) {
+        messageLength = this.littleEndian
+          ? this.buffer.readUInt32LE(this.lengthFieldOffset)
+          : this.buffer.readUInt32BE(this.lengthFieldOffset);
+      } else if (this.lengthFieldLength === LENGTH_FIELD_2_BYTES) {
+        messageLength = this.littleEndian
+          ? this.buffer.readUInt16LE(this.lengthFieldOffset)
+          : this.buffer.readUInt16BE(this.lengthFieldOffset);
+      } else if (this.lengthFieldLength === LENGTH_FIELD_1_BYTE) {
+        messageLength = this.buffer.readUInt8(this.lengthFieldOffset);
+      } else if (this.lengthFieldLength === LENGTH_FIELD_8_BYTES) {
+        const high = this.littleEndian
+          ? this.buffer.readUInt32LE(
+              this.lengthFieldOffset + LENGTH_FIELD_4_BYTES,
+            )
+          : this.buffer.readUInt32BE(this.lengthFieldOffset);
+        const low = this.littleEndian
+          ? this.buffer.readUInt32LE(this.lengthFieldOffset)
+          : this.buffer.readUInt32BE(
+              this.lengthFieldOffset + LENGTH_FIELD_4_BYTES,
+            );
+        messageLength = high * UINT32_HIGH_MULTIPLIER + low;
+      } else {
+        throw new Error(
+          `Unsupported lengthFieldLength: ${this.lengthFieldLength}`,
+        );
+      }
+
+      // Apply adjustment
+      messageLength += this.lengthAdjustment;
+
+      // Check if the extracted message length seems suspicious
+      if (messageLength < 0 || messageLength > this.maxFrameLength) {
+        let alternateLength: number;
+        if (this.lengthFieldLength === LENGTH_FIELD_4_BYTES) {
+          alternateLength = this.littleEndian
+            ? this.buffer.readUInt32BE(this.lengthFieldOffset)
+            : this.buffer.readUInt32LE(this.lengthFieldOffset);
+
+          if (alternateLength > 0 && alternateLength <= this.maxFrameLength) {
+            messageLength = alternateLength;
+          } else {
+            // If length is still invalid, check if this might actually be XML
+            const suspiciousData = this.buffer.toString(
+              UTF8_ENCODING,
+              0,
+              Math.min(MAX_PREVIEW_LENGTH, this.buffer.length),
+            );
+
+            if (isXmlPlistContent(suspiciousData)) {
+              this.isXmlMode = true;
+              // Process as XML on next iteration
+              return callback();
+            }
+
+            // Invalid length - skip one byte and try again
+            this.buffer = this.buffer.slice(1);
+            continue;
+          }
+        } else {
+          // For non-4-byte length fields, just use the original approach
+          // If length is invalid, check if this might actually be XML
+          const suspiciousData = this.buffer.toString(
+            UTF8_ENCODING,
+            0,
+            Math.min(MAX_PREVIEW_LENGTH, this.buffer.length),
+          );
+
+          if (isXmlPlistContent(suspiciousData)) {
+            this.isXmlMode = true;
+            // Process as XML on next iteration
+            return callback();
+          }
+
+          // Invalid length - skip one byte and try again
+          this.buffer = this.buffer.slice(1);
+          continue;
+        }
+      }
+
+      // Total length of frame = lengthFieldOffset + lengthFieldLength + messageLength
+      const totalLength =
+        this.lengthFieldOffset + this.lengthFieldLength + messageLength;
+
+      // If we don't have the complete message yet, wait for more data
+      if (this.buffer.length < totalLength) {
+        break;
+      }
+
+      // Extract the message
+      try {
+        // Extract the complete message
+        const message = this.buffer.slice(0, totalLength);
+
+        // Check if this message is actually XML
+        const messageStart = message.toString(
+          UTF8_ENCODING,
+          0,
+          Math.min(MAX_PREVIEW_LENGTH, message.length),
+        );
+
+        if (isXmlPlistContent(messageStart)) {
+          // Switch to XML mode
+          this.isXmlMode = true;
+          return callback();
+        }
+
+        // Push the message
+        this.push(message);
+
+        // Remove the processed message from the buffer
+        this.buffer = this.buffer.slice(totalLength);
+      } catch {
+        // move forward by 1 byte and try again
+        this.buffer = this.buffer.slice(1);
+      }
+    }
+    callback();
+  }
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Creates an XML plist string from a JavaScript object
+ * @param obj - The JavaScript object to convert
+ * @returns - XML plist string
+ */
+import type { PlistDictionary, PlistValue } from '../types.js';
+import { escapeXml } from './utils.js';
+
+export function createPlist(obj: PlistDictionary): string {
+  function convert(value: PlistValue): string {
+    if (typeof value === 'number') {
+      return `<integer>${value}</integer>`;
+    }
+    if (typeof value === 'boolean') {
+      return value ? '<true/>' : '<false/>';
+    }
+    if (typeof value === 'string') {
+      return `<string>${escapeXml(value)}</string>`;
+    }
+    if (Array.isArray(value)) {
+      return `<array>${value.map((item) => convert(item)).join('')}</array>`;
+    }
+    if (typeof value === 'object' && value !== null) {
+      const entries = Object.entries(value)
+        .map(([k, v]) => `<key>${escapeXml(k)}</key>${convert(v)}`)
+        .join('');
+      return `<dict>${entries}</dict>`;
+    }
+    return '<string></string>';
+  }
+
+  const body = Object.entries(obj)
+    .map(([key, val]) => `<key>${escapeXml(key)}</key>${convert(val)}`)
+    .join('');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" 
+"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>${body}</dict>
+</plist>`;
+}

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

@@ -0,0 +1,135 @@
+import { logger } from '@appium/support';
+import { Transform, type TransformCallback } from 'stream';
+
+import { UTF8_ENCODING } from './constants.js';
+import { parsePlist } from './plist-parser.js';
+import {
+  ensureString,
+  findFirstReplacementCharacter,
+  fixMultipleXmlDeclarations,
+  hasUnicodeReplacementCharacter,
+} from './utils.js';
+
+const log = logger.getLogger('Plist');
+
+/**
+ * Decodes plist format data with length prefix to JavaScript objects
+ */
+export class PlistServiceDecoder extends Transform {
+  // Static property to store the last decoded result
+  static lastDecodedResult: any = null;
+  constructor() {
+    super({ objectMode: true });
+  }
+
+  _transform(
+    data: Buffer,
+    encoding: BufferEncoding,
+    callback: TransformCallback,
+  ): void {
+    try {
+      // Get the plist data without the 4-byte header
+      let plistData = data.slice(4);
+
+      // Skip empty data
+      if (plistData.length === 0) {
+        return callback();
+      }
+
+      // Check if this is XML data with potential binary header and trim content before XML declaration
+      const dataStr = plistData.toString(
+        UTF8_ENCODING,
+        0,
+        Math.min(100, plistData.length),
+      );
+      const xmlIndex = dataStr.indexOf('<?xml');
+
+      if (xmlIndex > 0) {
+        // There's content before the XML declaration, remove it
+        log.debug(
+          `Found XML declaration at position ${xmlIndex}, trimming preceding content`,
+        );
+        plistData = plistData.slice(xmlIndex);
+      }
+
+      // Check for multiple XML declarations which can cause parsing errors
+      const fullDataStr = ensureString(plistData);
+
+      // Check for potential corruption indicators and handle them
+      if (hasUnicodeReplacementCharacter(plistData)) {
+        log.debug(
+          'Detected Unicode replacement characters in plist data, which may indicate encoding issues',
+        );
+
+        // Try to find and clean the corrupted data
+        const firstReplacementPos = findFirstReplacementCharacter(fullDataStr);
+        if (firstReplacementPos >= 0) {
+          log.debug(
+            `Found replacement character at position ${firstReplacementPos}, attempting to clean data`,
+          );
+        }
+      }
+      const xmlDeclMatches = fullDataStr.match(/(<\?xml[^>]*\?>)/g) || [];
+      if (xmlDeclMatches.length > 1) {
+        log.debug(
+          `Found ${xmlDeclMatches.length} XML declarations, which may cause parsing errors`,
+        );
+        // Fix multiple XML declarations
+        plistData = Buffer.from(fixMultipleXmlDeclarations(plistData));
+      }
+
+      try {
+        // Parse the plist
+        this._parseAndProcess(plistData, callback);
+      } catch (error) {
+        // If parsing fails, try to recover by cleaning up the data more aggressively
+        const parseError = error as Error;
+
+        try {
+          // Find the first valid XML tag
+          const firstTagIndex = fullDataStr.indexOf('<');
+          if (firstTagIndex > 0) {
+            const cleanedData = plistData.slice(firstTagIndex);
+            this._parseAndProcess(cleanedData, callback);
+          } else {
+            // If we can't find a valid starting point, propagate the original error
+            throw parseError;
+          }
+        } catch (error) {
+          // If recovery also fails, propagate the original error
+          callback(error as Error);
+        }
+      }
+    } catch (err) {
+      callback(err as Error);
+    }
+  }
+
+  /**
+   * Parse plist data and process the result
+   *
+   * @param data - The plist data to parse
+   * @param callback - The transform callback
+   */
+  private _parseAndProcess(data: Buffer, callback: TransformCallback): void {
+    const result = parsePlist(data);
+    this._processResult(result, callback);
+  }
+
+  /**
+   * Process a successfully parsed result
+   * Stores the result in the static property and pushes it to the stream
+   *
+   * @param result - The parsed plist result
+   * @param callback - The transform callback
+   */
+  private _processResult(result: any, callback: TransformCallback): void {
+    // Store the result in the static property for later access
+    if (typeof result === 'object' && result !== null) {
+      PlistServiceDecoder.lastDecodedResult = result;
+    }
+
+    this.push(result);
+    callback();
+  }
+}

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

@@ -0,0 +1,36 @@
+import { Transform, type TransformCallback } from 'stream';
+
+import type { PlistDictionary } from '../types.js';
+import { UTF8_ENCODING } from './constants.js';
+import { createPlist } from './plist-creator.js';
+
+/**
+ * Encodes JavaScript objects to plist format with length prefix
+ */
+export class PlistServiceEncoder extends Transform {
+  constructor() {
+    super({ objectMode: true });
+  }
+
+  _transform(
+    data: PlistDictionary,
+    encoding: BufferEncoding,
+    callback: TransformCallback,
+  ): void {
+    try {
+      // Convert object to plist
+      const plist = createPlist(data);
+      const plistBuffer = Buffer.from(plist, UTF8_ENCODING);
+
+      // Create length header (4 bytes, big endian)
+      const header = Buffer.alloc(4);
+      header.writeUInt32BE(plistBuffer.length, 0);
+
+      // Send header + plist
+      this.push(Buffer.concat([header, plistBuffer]));
+      callback();
+    } catch (err) {
+      callback(err as Error);
+    }
+  }
+}

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

@@ -0,0 +1,144 @@
+import { logger } from '@appium/support';
+import { DOMParser, Element, Node } from '@xmldom/xmldom';
+
+import type { PlistArray, PlistDictionary, PlistValue } from '../types.js';
+import { PlistService } from './plist-service.js';
+import {
+  cleanXmlWithReplacementChar,
+  ensureString,
+  findFirstReplacementCharacter,
+  fixMultipleXmlDeclarations,
+  hasUnicodeReplacementCharacter,
+  isValidXml,
+  removeExtraContentAfterPlist,
+  trimBeforeXmlDeclaration,
+} from './utils.js';
+
+const errorLog = logger.getLogger('PlistError');
+
+/**
+ * Parses an XML plist string into a JavaScript object
+ *
+ * @param xmlData - XML plist data as string or Buffer
+ * @returns Parsed JavaScript object
+ */
+export function parsePlist(xmlData: string | Buffer): PlistDictionary {
+  let xmlStr = ensureString(xmlData);
+
+  xmlStr = trimBeforeXmlDeclaration(xmlStr);
+
+  if (hasUnicodeReplacementCharacter(xmlStr)) {
+    const badCharPos = findFirstReplacementCharacter(xmlStr);
+    xmlStr = cleanXmlWithReplacementChar(xmlStr, badCharPos);
+  }
+
+  if (!isValidXml(xmlStr)) {
+    if (PlistService.isVerboseErrorLoggingEnabled()) {
+      errorLog.debug(
+        `Invalid XML: missing root element - XML content: ${xmlStr.substring(0, 200)}...`,
+      );
+    }
+    throw new Error('Invalid XML: missing root element or malformed XML');
+  }
+
+  xmlStr = fixMultipleXmlDeclarations(xmlStr);
+
+  xmlStr = removeExtraContentAfterPlist(xmlStr);
+
+  const parser = new DOMParser({
+    errorHandler(level, message) {
+      if (level === 'fatalError') {
+        throw new Error(`Fatal XML parsing error: ${message}`);
+      }
+      return true;
+    },
+  });
+
+  const doc = parser.parseFromString(xmlStr, 'text/xml');
+
+  if (!doc) {
+    throw new Error('Invalid XML response');
+  }
+
+  const plistElements = doc.getElementsByTagName('plist');
+  if (plistElements.length === 0) {
+    throw new Error('No plist element found in XML');
+  }
+
+  const rootDict = doc.getElementsByTagName('dict')[0];
+  if (!rootDict) {
+    return {};
+  }
+
+  return parseDict(rootDict);
+
+  function parseNode(node: Element): PlistValue {
+    if (!node) {
+      return null;
+    }
+
+    switch (node.nodeName) {
+      case 'dict':
+        return parseDict(node);
+      case 'array':
+        return parseArray(node);
+      case 'string':
+        return node.textContent || '';
+      case 'integer':
+        return parseInt(node.textContent || '0', 10);
+      case 'real':
+        return parseFloat(node.textContent || '0');
+      case 'true':
+        return true;
+      case 'false':
+        return false;
+      case 'date':
+        return new Date(node.textContent || '');
+      case 'data':
+        if (!node.textContent) {
+          return null;
+        }
+        try {
+          return Buffer.from(node.textContent, 'base64');
+        } catch {
+          return node.textContent;
+        }
+      default:
+        return node.textContent || null;
+    }
+  }
+
+  function parseDict(dictNode: Element): PlistDictionary {
+    const obj: PlistDictionary = {};
+    const keys = dictNode.getElementsByTagName('key');
+
+    for (let i = 0; i < keys.length; i++) {
+      const keyName = keys[i].textContent || '';
+      let valueNode = keys[i].nextSibling;
+
+      while (valueNode && valueNode.nodeType !== Node.ELEMENT_NODE) {
+        valueNode = valueNode.nextSibling;
+      }
+
+      if (valueNode) {
+        obj[keyName] = parseNode(valueNode as Element);
+      }
+    }
+
+    return obj;
+  }
+
+  function parseArray(arrayNode: Element): PlistArray {
+    const result: PlistArray = [];
+    let childNode = arrayNode.firstChild;
+
+    while (childNode) {
+      if (childNode.nodeType === Node.ELEMENT_NODE) {
+        result.push(parseNode(childNode as Element));
+      }
+      childNode = childNode.nextSibling;
+    }
+
+    return result;
+  }
+}