appium-ios-remotexpc 0.0.3 → 0.0.5

package/build/src/lib/usbmux/index.d.ts

@@ -0,0 +1,177 @@
+import { Socket } from 'node:net';
+import { BaseSocketService } from '../../base-socket-service.js';
+import { type PairRecord } from '../pair-record/index.js';
+/**
+ * Interface for device properties
+ */
+export interface DeviceProperties {
+    ConnectionSpeed: number;
+    ConnectionType: string;
+    DeviceID: number;
+    LocationID: number;
+    ProductID: number;
+    SerialNumber: string;
+    USBSerialNumber: string;
+}
+/**
+ * Interface for a device
+ */
+export interface Device {
+    DeviceID: number;
+    MessageType: string;
+    Properties: DeviceProperties;
+}
+export declare const USBMUXD_PORT = 27015;
+export declare const DEFAULT_USBMUXD_SOCKET = "/var/run/usbmuxd";
+export declare const DEFAULT_USBMUXD_HOST = "127.0.0.1";
+export declare const MAX_FRAME_SIZE: number;
+export declare const USBMUX_RESULT: {
+    OK: number;
+    BADCOMMAND: number;
+    BADDEV: number;
+    CONNREFUSED: number;
+};
+/**
+ * Function to swap bytes for a 16-bit value
+ * Used for usbmuxd port numbers
+ */
+export declare function byteSwap16(value: number): number;
+/**
+ * Socket options for connecting to usbmuxd
+ */
+export interface SocketOptions {
+    socketPath?: string;
+    socketPort?: number;
+    socketHost?: string;
+    timeout?: number;
+}
+/**
+ * Connects a socket to usbmuxd service
+ * @param opts - Connection options
+ * @returns Promise that resolves with a socket connected to usbmuxd
+ */
+export declare function getDefaultSocket(opts?: Partial<SocketOptions>): Promise<Socket>;
+/**
+ * usbmux class for communicating with usbmuxd
+ */
+export declare class Usbmux extends BaseSocketService {
+    private readonly _decoder;
+    private readonly _splitter;
+    private readonly _encoder;
+    private _tag;
+    private readonly _responseCallbacks;
+    /**
+     * Creates a new usbmux instance
+     * @param socketClient - Connected socket to usbmuxd
+     */
+    constructor(socketClient: Socket);
+    /**
+     * Returns the BUID of the host computer from usbmuxd
+     * @param timeout - Timeout in milliseconds
+     * @returns Promise that resolves with the BUID
+     */
+    readBUID(timeout?: number): Promise<string>;
+    /**
+     * Reads the pair record of a device, checking local cache first
+     * @param udid - Device UDID
+     * @param timeout - Timeout in milliseconds
+     * @returns Promise that resolves with the pair record or null if not found
+     */
+    readPairRecord(udid: string, timeout?: number): Promise<PairRecord | null>;
+    /**
+     * Lists all devices connected to the host
+     * @param timeout - Timeout in milliseconds
+     * @returns Promise that resolves with the device list
+     */
+    listDevices(timeout?: number): Promise<Device[]>;
+    /**
+     * Looks for a device with the passed udid
+     * @param udid - Device UDID
+     * @param timeout - Timeout in milliseconds
+     * @returns Promise that resolves with the device or undefined if not found
+     */
+    findDevice(udid: string, timeout?: number): Promise<Device | undefined>;
+    /**
+     * Connects to a certain port on the device
+     * @param deviceID - Device ID
+     * @param port - Port to connect to
+     * @param timeout - Timeout in milliseconds
+     * @returns Promise that resolves with the connected socket
+     */
+    connect(deviceID: string | number, port: number, timeout?: number): Promise<Socket>;
+    /**
+     * Closes the current USBMUX connection gracefully.
+     * For non-tunnel commands, call this after the operation is complete.
+     * For Connect commands (which consume the connection),
+     * the caller is responsible for closing the returned socket.
+     *
+     * @returns Promise that resolves when the socket is closed.
+     */
+    close(): Promise<void>;
+    /**
+     * Handles incoming data from the decoder
+     * @param data - Decoded data
+     * @private
+     */
+    private _handleData;
+    /**
+     * Sends a plist to usbmuxd
+     * @param json - JSON object with tag and payload
+     * @private
+     */
+    private _sendPlist;
+    /**
+     * Sets up a promise to receive and process a plist response
+     * @param timeout - Timeout in milliseconds
+     * @param responseCallback - Callback to process the response
+     * @returns Object with tag and promise
+     * @private
+     */
+    private _receivePlistPromise;
+}
+/**
+ * Creates a new usbmux instance
+ * @param opts - Socket options
+ * @returns Promise that resolves with a usbmux instance
+ */
+export declare function createUsbmux(opts?: Partial<SocketOptions>): Promise<Usbmux>;
+/**
+ * RelayService class for tunneling connections through a local TCP server
+ */
+export declare class RelayService {
+    private readonly deviceID;
+    private readonly devicePort;
+    private readonly relayPort;
+    private usbmuxClient;
+    private server;
+    /**
+     * Creates a new RelayService instance
+     * @param deviceID - The device ID to connect to
+     * @param devicePort - The port on the device to connect to
+     * @param relayPort - The local port to use for the relay server
+     */
+    constructor(deviceID: string | number, devicePort: number, relayPort?: number);
+    /**
+     * Starts the relay service
+     * @returns Promise that resolves when the relay is set up
+     */
+    start(): Promise<void>;
+    /**
+     * Connects to the relay service
+     * @returns Promise that resolves with a socket connected to the relay
+     */
+    connect(): Promise<Socket>;
+    /**
+     * Stops the relay service
+     */
+    stop(): Promise<void>;
+}
+/**
+ * Connects to a device and sets up a relay service in one operation
+ * @param deviceID - The device ID to connect to
+ * @param port - The port on the device to connect to
+ * @param relayPort - The local port to use for the relay server
+ * @returns Promise that resolves with a connected socket
+ */
+export declare function connectAndRelay(deviceID: string | number, port: number, relayPort?: number): Promise<Socket>;
+//# sourceMappingURL=index.d.ts.map

package/build/src/lib/usbmux/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/usbmux/index.ts"],"names":[],"mappings":"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"}

package/build/src/lib/usbmux/index.js

@@ -0,0 +1,490 @@
+import { logger } from '@appium/support';
+import { Server, Socket, createConnection, createServer } from 'node:net';
+import { release } from 'node:os';
+import { BaseSocketService } from '../../base-socket-service.js';
+import { processPlistResponse } from '../pair-record/index.js';
+import {} from '../pair-record/pair-record.js';
+import { LengthBasedSplitter, parsePlist } from '../plist/index.js';
+import { UsbmuxDecoder } from '../usbmux/usbmux-decoder.js';
+import { UsbmuxEncoder } from '../usbmux/usbmux-encoder.js';
+const log = logger.getLogger('Usbmux');
+export const USBMUXD_PORT = 27015;
+export const DEFAULT_USBMUXD_SOCKET = '/var/run/usbmuxd';
+export const DEFAULT_USBMUXD_HOST = '127.0.0.1';
+export const MAX_FRAME_SIZE = 100 * 1024 * 1024; // 1MB
+// Result codes from usbmuxd
+export const USBMUX_RESULT = {
+    OK: 0,
+    BADCOMMAND: 1,
+    BADDEV: 2,
+    CONNREFUSED: 3,
+};
+// Package info for client identification
+const PROG_NAME = 'appium-internal';
+const CLIENT_VERSION_STRING = 'appium-internal-1.0.0';
+/**
+ * Function to swap bytes for a 16-bit value
+ * Used for usbmuxd port numbers
+ */
+export function byteSwap16(value) {
+    return ((value & 0xff) << 8) | ((value >> 8) & 0xff);
+}
+/**
+ * Helper function to check if a file exists
+ * @param path - Path to check
+ * @returns Boolean indicating if the file exists
+ */
+async function fileExists(path) {
+    try {
+        await import('fs').then((fs) => fs.promises.access(path));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Connects a socket to usbmuxd service
+ * @param opts - Connection options
+ * @returns Promise that resolves with a socket connected to usbmuxd
+ */
+export async function getDefaultSocket(opts = {}) {
+    const defaults = {
+        socketPath: DEFAULT_USBMUXD_SOCKET,
+        socketPort: USBMUXD_PORT,
+        socketHost: DEFAULT_USBMUXD_HOST,
+        timeout: 5000,
+    };
+    if (process.env.USBMUXD_SOCKET_ADDRESS &&
+        !opts.socketPath &&
+        !opts.socketPort &&
+        !opts.socketHost) {
+        log.debug(`Using USBMUXD_SOCKET_ADDRESS environment variable as default socket: ${process.env.USBMUXD_SOCKET_ADDRESS}`);
+        // "unix:" or "UNIX:" prefix is optional for unix socket paths.
+        const usbmuxdSocketAddress = process.env.USBMUXD_SOCKET_ADDRESS.replace(/^(unix):/i, '');
+        const [ip, port] = usbmuxdSocketAddress.split(':');
+        if (ip && port) {
+            defaults.socketHost = ip;
+            defaults.socketPort = parseInt(port, 10);
+        }
+        else {
+            defaults.socketPath = usbmuxdSocketAddress;
+        }
+    }
+    const { socketPath, socketPort, socketHost, timeout } = {
+        ...defaults,
+        ...opts,
+    };
+    let socket;
+    if (await fileExists(socketPath ?? '')) {
+        socket = createConnection(socketPath ?? '');
+    }
+    else if (process.platform === 'win32' ||
+        (process.platform === 'linux' && /microsoft/i.test(release()))) {
+        // Connect to usbmuxd when running on WSL1
+        socket = createConnection({
+            port: socketPort,
+            host: socketHost,
+        });
+    }
+    else {
+        throw new Error(`The usbmuxd socket at '${socketPath}' does not exist or is not accessible`);
+    }
+    return await new Promise((resolve, reject) => {
+        const timeoutId = setTimeout(() => {
+            socket.removeAllListeners();
+            reject(new Error(`Connection timed out after ${timeout}ms`));
+        }, timeout ?? 5000);
+        socket.once('error', (err) => {
+            clearTimeout(timeoutId);
+            reject(err);
+        });
+        socket.once('connect', () => {
+            clearTimeout(timeoutId);
+            resolve(socket);
+        });
+    });
+}
+/**
+ * usbmux class for communicating with usbmuxd
+ */
+export class Usbmux extends BaseSocketService {
+    _decoder;
+    _splitter;
+    _encoder;
+    _tag;
+    _responseCallbacks;
+    /**
+     * Creates a new usbmux instance
+     * @param socketClient - Connected socket to usbmuxd
+     */
+    constructor(socketClient) {
+        super(socketClient);
+        this._decoder = new UsbmuxDecoder();
+        this._splitter = new LengthBasedSplitter({
+            readableStream: socketClient,
+            littleEndian: true,
+            maxFrameLength: MAX_FRAME_SIZE,
+            lengthFieldOffset: 0,
+            lengthFieldLength: 4,
+            lengthAdjustment: 0,
+        });
+        this._socketClient.pipe(this._decoder);
+        this._encoder = new UsbmuxEncoder();
+        this._encoder.pipe(this._socketClient);
+        this._assignClientFailureHandlers(this._encoder);
+        this._tag = 0;
+        this._responseCallbacks = {};
+        this._decoder.on('data', this._handleData.bind(this));
+    }
+    /**
+     * Returns the BUID of the host computer from usbmuxd
+     * @param timeout - Timeout in milliseconds
+     * @returns Promise that resolves with the BUID
+     */
+    async readBUID(timeout = 5000) {
+        const { tag, receivePromise } = this._receivePlistPromise(timeout, (data) => {
+            if (data.payload.BUID) {
+                return data.payload.BUID;
+            }
+            throw new Error(`Unexpected data: ${JSON.stringify(data)}`);
+        });
+        this._sendPlist({
+            tag,
+            payload: {
+                MessageType: 'ReadBUID',
+                ProgName: PROG_NAME,
+                ClientVersionString: CLIENT_VERSION_STRING,
+            },
+        });
+        return await receivePromise;
+    }
+    /**
+     * Reads the pair record of a device, checking local cache first
+     * @param udid - Device UDID
+     * @param timeout - Timeout in milliseconds
+     * @returns Promise that resolves with the pair record or null if not found
+     */
+    async readPairRecord(udid, timeout = 5000) {
+        // Request from usbmuxd if not found in cache
+        const { tag, receivePromise } = this._receivePlistPromise(timeout, (data) => {
+            if (!data.payload.PairRecordData) {
+                return null;
+            }
+            try {
+                // Parse the pair record and assert the type
+                return processPlistResponse(parsePlist(data.payload.PairRecordData));
+            }
+            catch (e) {
+                throw new Error(`Failed to parse pair record data: ${e}`);
+            }
+        });
+        this._sendPlist({
+            tag,
+            payload: {
+                MessageType: 'ReadPairRecord',
+                PairRecordID: udid,
+                ProgName: PROG_NAME,
+                ClientVersionString: CLIENT_VERSION_STRING,
+            },
+        });
+        return await receivePromise;
+    }
+    /**
+     * Lists all devices connected to the host
+     * @param timeout - Timeout in milliseconds
+     * @returns Promise that resolves with the device list
+     */
+    async listDevices(timeout = 5000) {
+        const { tag, receivePromise } = this._receivePlistPromise(timeout, (data) => {
+            if (data.payload.DeviceList) {
+                return data.payload.DeviceList;
+            }
+            throw new Error(`Unexpected data: ${JSON.stringify(data)}`);
+        });
+        this._sendPlist({
+            tag,
+            payload: {
+                MessageType: 'ListDevices',
+                ProgName: PROG_NAME,
+                ClientVersionString: CLIENT_VERSION_STRING,
+            },
+        });
+        return await receivePromise;
+    }
+    /**
+     * Looks for a device with the passed udid
+     * @param udid - Device UDID
+     * @param timeout - Timeout in milliseconds
+     * @returns Promise that resolves with the device or undefined if not found
+     */
+    async findDevice(udid, timeout = 5000) {
+        const devices = await this.listDevices(timeout);
+        return devices.find((device) => device.Properties.SerialNumber === udid);
+    }
+    /**
+     * Connects to a certain port on the device
+     * @param deviceID - Device ID
+     * @param port - Port to connect to
+     * @param timeout - Timeout in milliseconds
+     * @returns Promise that resolves with the connected socket
+     */
+    async connect(deviceID, port, timeout = 5000) {
+        const { tag, receivePromise } = this._receivePlistPromise(timeout, (data) => {
+            if (data.payload.MessageType !== 'Result') {
+                throw new Error(`Unexpected data: ${JSON.stringify(data)}`);
+            }
+            if (data.payload.Number === USBMUX_RESULT.OK) {
+                this._splitter.shutdown();
+                this._socketClient.unpipe(this._splitter);
+                this._splitter.unpipe(this._decoder);
+                return this._socketClient;
+            }
+            else if (data.payload.Number === USBMUX_RESULT.CONNREFUSED) {
+                throw new Error(`Connection was refused to port ${port}`);
+            }
+            else {
+                throw new Error(`Connection failed with code ${data.payload.Number}`);
+            }
+        });
+        this._sendPlist({
+            tag,
+            payload: {
+                MessageType: 'Connect',
+                ProgName: PROG_NAME,
+                ClientVersionString: CLIENT_VERSION_STRING,
+                DeviceID: deviceID,
+                PortNumber: byteSwap16(port),
+            },
+        });
+        return await receivePromise;
+    }
+    /**
+     * Closes the current USBMUX connection gracefully.
+     * For non-tunnel commands, call this after the operation is complete.
+     * For Connect commands (which consume the connection),
+     * the caller is responsible for closing the returned socket.
+     *
+     * @returns Promise that resolves when the socket is closed.
+     */
+    close() {
+        return new Promise((resolve, reject) => {
+            // If the socket is still open, end it gracefully.
+            if (!this._socketClient.destroyed) {
+                // End the connection and then destroy it once closed.
+                this._socketClient.end((err) => {
+                    if (err) {
+                        log.error(`Error closing usbmux socket: ${err}`);
+                        this._socketClient.destroy();
+                        reject(err);
+                    }
+                    else {
+                        this._socketClient.destroy();
+                        resolve();
+                    }
+                });
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+    /**
+     * Handles incoming data from the decoder
+     * @param data - Decoded data
+     * @private
+     */
+    _handleData(data) {
+        const cb = this._responseCallbacks[data.header.tag];
+        if (cb) {
+            cb(data);
+        }
+    }
+    /**
+     * Sends a plist to usbmuxd
+     * @param json - JSON object with tag and payload
+     * @private
+     */
+    _sendPlist(json) {
+        this._encoder.write(json);
+    }
+    /**
+     * Sets up a promise to receive and process a plist response
+     * @param timeout - Timeout in milliseconds
+     * @param responseCallback - Callback to process the response
+     * @returns Object with tag and promise
+     * @private
+     */
+    _receivePlistPromise(timeout = 5000, responseCallback) {
+        const tag = this._tag++;
+        let timeoutId;
+        const receivePromise = new Promise((resolve, reject) => {
+            this._responseCallbacks[tag] = (data) => {
+                try {
+                    // Clear the timeout to prevent it from triggering
+                    if (timeoutId) {
+                        clearTimeout(timeoutId);
+                    }
+                    // Process the response
+                    resolve(responseCallback(data));
+                }
+                catch (e) {
+                    reject(e);
+                }
+                finally {
+                    delete this._responseCallbacks[tag];
+                }
+            };
+            // Set the timeout handler
+            timeoutId = setTimeout(() => {
+                if (this._responseCallbacks[tag]) {
+                    delete this._responseCallbacks[tag];
+                    log.warn(`Timeout waiting for response with tag ${tag} after ${timeout}ms`);
+                    reject(new Error(`Failed to receive any data within the timeout: ${timeout}ms - The device might be busy or unresponsive`));
+                }
+            }, timeout);
+        });
+        // Add cleanup handler when promise is settled
+        receivePromise
+            .catch(() => { })
+            .finally(() => {
+            if (this._responseCallbacks[tag]) {
+                delete this._responseCallbacks[tag];
+            }
+        });
+        return { tag, receivePromise };
+    }
+}
+/**
+ * Creates a new usbmux instance
+ * @param opts - Socket options
+ * @returns Promise that resolves with a usbmux instance
+ */
+export async function createUsbmux(opts = {}) {
+    const socket = await getDefaultSocket(opts);
+    return new Usbmux(socket);
+}
+/**
+ * RelayService class for tunneling connections through a local TCP server
+ */
+export class RelayService {
+    deviceID;
+    devicePort;
+    relayPort;
+    usbmuxClient;
+    server;
+    /**
+     * Creates a new RelayService instance
+     * @param deviceID - The device ID to connect to
+     * @param devicePort - The port on the device to connect to
+     * @param relayPort - The local port to use for the relay server
+     */
+    constructor(deviceID, devicePort, relayPort = 2222) {
+        this.deviceID = deviceID;
+        this.devicePort = devicePort;
+        this.relayPort = relayPort;
+        this.usbmuxClient = null;
+        this.server = null;
+    }
+    /**
+     * Starts the relay service
+     * @returns Promise that resolves when the relay is set up
+     */
+    async start() {
+        log.info(`Starting relay to device ${this.deviceID} on port ${this.devicePort}...`);
+        // Create a usbmux instance and connect to the device
+        const usbmux = await createUsbmux();
+        this.usbmuxClient = await usbmux.connect(this.deviceID, this.devicePort);
+        // Set up the relay server
+        this.server = createServer((localSocket) => {
+            log.debug('🔌 Local client connected to relay!');
+            // Set up the bidirectional pipe between local socket and usbmux connection
+            if (this.usbmuxClient) {
+                localSocket.pipe(this.usbmuxClient).pipe(localSocket);
+            }
+            // Handle socket events
+            localSocket.on('close', () => {
+                log.debug('Local connection closed (tunnel remains open).');
+            });
+            localSocket.on('error', (err) => {
+                log.error(`Local socket error: ${err}`);
+            });
+        });
+        // Start the server
+        await new Promise((resolve, reject) => {
+            if (!this.server) {
+                return reject(new Error('Server not initialized'));
+            }
+            this.server.listen(this.relayPort, () => {
+                log.info(`Relay server running on localhost:${this.relayPort}`);
+                resolve();
+            });
+            this.server.on('error', (err) => {
+                reject(err);
+            });
+        });
+    }
+    /**
+     * Connects to the relay service
+     * @returns Promise that resolves with a socket connected to the relay
+     */
+    async connect() {
+        return new Promise((resolve, reject) => {
+            const socket = createConnection({ host: '127.0.0.1', port: this.relayPort }, () => {
+                log.debug('Connected to service via local relay.');
+                resolve(socket);
+            });
+            socket.on('error', (err) => {
+                reject(err);
+            });
+        });
+    }
+    /**
+     * Stops the relay service
+     */
+    async stop() {
+        return new Promise((resolve, reject) => {
+            if (this.server) {
+                this.server.close((err) => {
+                    if (err) {
+                        log.error(`Error stopping relay server: ${err}`);
+                        reject(err);
+                    }
+                    else {
+                        log.info('Relay server stopped');
+                        resolve();
+                    }
+                });
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+}
+/**
+ * Connects to a device and sets up a relay service in one operation
+ * @param deviceID - The device ID to connect to
+ * @param port - The port on the device to connect to
+ * @param relayPort - The local port to use for the relay server
+ * @returns Promise that resolves with a connected socket
+ */
+export async function connectAndRelay(deviceID, port, relayPort = 2222) {
+    // Create and start the relay service
+    const relay = new RelayService(deviceID, port, relayPort);
+    let socket;
+    try {
+        // Start the relay
+        await relay.start();
+        // Connect to the relay
+        socket = await relay.connect();
+        return socket;
+    }
+    finally {
+        if (!socket) {
+            await relay
+                .stop()
+                .catch((err) => log.error(`Error stopping relay: ${err}`));
+        }
+    }
+}

package/build/src/lib/usbmux/usbmux-decoder.d.ts

@@ -0,0 +1,19 @@
+import { Transform, type TransformCallback } from 'stream';
+import type { PlistDictionary } from '../types.js';
+export interface UsbmuxHeader {
+    length: number;
+    version: number;
+    type: number;
+    tag: number;
+}
+export interface DecodedUsbmux {
+    header: UsbmuxHeader;
+    payload: PlistDictionary;
+}
+export declare class UsbmuxDecoder extends Transform {
+    private _buffer;
+    constructor();
+    _transform(chunk: Buffer, encoding: BufferEncoding, callback: TransformCallback): void;
+    private _decode;
+}
+//# sourceMappingURL=usbmux-decoder.d.ts.map

package/build/src/lib/usbmux/usbmux-decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usbmux-decoder.d.ts","sourceRoot":"","sources":["../../../../src/lib/usbmux/usbmux-decoder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AAG3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAInD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,eAAe,CAAC;CAC1B;AAED,qBAAa,aAAc,SAAQ,SAAS;IAC1C,OAAO,CAAC,OAAO,CAA2B;;IAM1C,UAAU,CACR,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,iBAAiB,GAC1B,IAAI;IAwBP,OAAO,CAAC,OAAO;CAWhB"}