appium-ios-remotexpc 0.21.2 → 0.23.0

package/src/lib/types.ts

@@ -1495,3 +1495,73 @@ export interface MisagentServiceWithConnection {
   misagentService: MisagentService;
   remoteXPC: RemoteXpcConnection;
 }
+
+/**
+ * Options for pulling crash reports from device to local
+ */
+export interface CrashReportsPullOptions {
+  /**
+   * If true, deletes crash reports from the remote device after pulling to local.
+   * @default false
+   */
+  erase?: boolean;
+  /**
+   * Glob pattern to filter crash reports (e.g., '*.ips', 'Siri*', '**\/*.crash')
+   */
+  match?: string;
+}
+
+/**
+ * CrashReportsService provides an API to manage crash reports on iOS devices
+ */
+export interface CrashReportsService extends BaseService {
+  /**
+   * List files and folders in the crash report's directory
+   *
+   * Crash reports are primarily stored as .ips files, which contain detailed information about
+   * app crashes, including stack traces, thread states, and device information.
+   * In addition to .ips files, the crash reports directory may contain:
+   * - Sysdiagnose tarballs (comprehensive system diagnostic archives)
+   * - Special directories like /Retired, /Cloud, /Assistant, etc.
+   *
+   * For details on the .ips file format, see:
+   * https://developer.apple.com/documentation/xcode/analyzing-a-crash-report
+   *
+   * @param dirPath Path to list, defaults to "/"
+   * @param depth Listing depth: 1 for immediate children, -1 for infinite
+   * @returns List of file paths (e.g., .ips files, sysdiagnose tarballs, directories like /Retired, /Cloud, etc.)
+   */
+  ls(dirPath?: string, depth?: number): Promise<string[]>;
+
+  /**
+   * Pull crash reports from device to local machine
+   * @param out Local directory path
+   * @param entry Remote path on device, defaults to "/"
+   * @param options Pull options (erase, match pattern)
+   */
+  pull(
+    out: string,
+    entry?: string,
+    options?: CrashReportsPullOptions,
+  ): Promise<void>;
+
+  /**
+   * Clear all crash reports from the device
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Flush pending crash reports into CrashReports directory
+   */
+  flush(): Promise<void>;
+
+  /**
+   * Close the service and release resources
+   */
+  close(): void;
+}
+
+export interface CrashReportsServiceWithConnection {
+  crashReportsService: CrashReportsService;
+  remoteXPC: RemoteXpcConnection;
+}

package/src/services/index.ts

@@ -3,6 +3,7 @@ import {
   startTunnelRegistryServer,
 } from '../lib/tunnel/tunnel-registry-server.js';
 import * as afc from './ios/afc/index.js';
+import * as crashReports from './ios/crash-reports/index.js';
 import * as diagnostics from './ios/diagnostic-service/index.js';
 import * as mobileImageMounter from './ios/mobile-image-mounter/index.js';
 import * as powerAssertion from './ios/power-assertion/index.js';
@@ -11,6 +12,7 @@ import * as tunnel from './ios/tunnel-service/index.js';
 import * as webinspector from './ios/webinspector/index.js';
 
 export {
+  crashReports,
   diagnostics,
   mobileImageMounter,
   powerAssertion,

package/src/services/ios/afc/codec.ts

@@ -350,6 +350,40 @@ export async function rsdHandshakeForRawService(
   }
 }
 
+/**
+ * Create a raw socket connection to an RSD service.
+ * Optionally performs RSD handshake if performHandshake is true.
+ * @param host - Hostname to connect to
+ * @param port - Port number
+ * @param options - Connection options
+ * @returns Connected socket (with handshake completed if requested)
+ */
+export async function createRawServiceSocket(
+  host: string,
+  port: number,
+  options: { timeoutMs?: number; performHandshake?: boolean } = {},
+): Promise<net.Socket> {
+  const { timeoutMs = 10000, performHandshake = true } = options;
+
+  const socket = await new Promise<net.Socket>((resolve, reject) => {
+    const conn = net.createConnection({ host, port }, () => {
+      conn.setKeepAlive(true);
+      resolve(conn);
+    });
+    conn.setTimeout(timeoutMs, () => {
+      conn.destroy();
+      reject(new Error('Connection timed out'));
+    });
+    conn.on('error', reject);
+  });
+
+  if (performHandshake) {
+    await rsdHandshakeForRawService(socket);
+  }
+
+  return socket;
+}
+
 export function nextReadChunkSize(left: bigint | number): number {
   const leftNum = typeof left === 'bigint' ? Number(left) : left;
   return leftNum;

package/src/services/ios/afc/index.ts

@@ -1,7 +1,7 @@
 import { minimatch } from 'minimatch';
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
-import net from 'node:net';
+import type net from 'node:net';
 import path from 'node:path';
 import { Readable, Writable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
@@ -11,16 +11,14 @@ import {
   buildClosePayload,
   buildFopenPayload,
   buildMkdirPayload,
-  buildReadPayload,
   buildRemovePayload,
   buildRenamePayload,
   buildStatPayload,
+  createRawServiceSocket,
   nanosecondsToMilliseconds,
-  nextReadChunkSize,
   parseCStringArray,
   parseKeyValueNullList,
   readAfcResponse,
-  rsdHandshakeForRawService,
   sendAfcPacket,
   writeUInt64LE,
 } from './codec.js';
@@ -692,20 +690,9 @@ export class AfcService {
     }
     const [host, rsdPort] = this.address;
 
-    this.socket = await new Promise<net.Socket>((resolve, reject) => {
-      const s = net.createConnection({ host, port: rsdPort }, () => {
-        s.setTimeout(0);
-        s.setKeepAlive(true);
-        resolve(s);
-      });
-      s.once('error', reject);
-      s.setTimeout(30000, () => {
-        s.destroy();
-        reject(new Error('AFC connect timed out'));
-      });
+    this.socket = await createRawServiceSocket(host, rsdPort, {
+      timeoutMs: 30000,
     });
-
-    await rsdHandshakeForRawService(this.socket);
     log.debug('RSD handshake complete; switching to raw AFC');
 
     return this.socket;

package/src/services/ios/afc/stream-utils.ts

@@ -19,7 +19,6 @@ export function createAfcReadStream(
   receive: () => Promise<{ status: AfcError; data: Buffer }>,
 ): Readable {
   let left = size;
-  let totalRead = 0n;
 
   return new Readable({
     async read() {
@@ -39,7 +38,6 @@ export function createAfcReadStream(
           return;
         }
 
-        totalRead += BigInt(data.length);
         left -= BigInt(data.length);
 
         this.push(data);

package/src/services/ios/crash-reports/index.ts

@@ -0,0 +1,180 @@
+import fs from 'node:fs/promises';
+import posixpath from 'node:path/posix';
+
+import { getLogger } from '../../../lib/logger.js';
+import type { CrashReportsPullOptions } from '../../../lib/types.js';
+import { createRawServiceSocket, readExact } from '../afc/codec.js';
+import { AfcService } from '../afc/index.js';
+import { BaseService } from '../base-service.js';
+
+const log = getLogger('CrashReportsService');
+
+/**
+ * Path that is sometimes auto-created after deletion
+ */
+const APPSTORED_PATH = '/com.apple.appstored';
+
+/**
+ * CrashReportsService provides an API to:
+ * - List crash reports on the device (ls)
+ * - Pull crash reports from the device to the local machine (pull)
+ * - Clear all crash reports from the device (clear)
+ * - Flush crash report products into CrashReports directory (flush)
+ *
+ * This service uses the com.apple.crashreportcopymobile.shim.remote for AFC operations
+ * and com.apple.crashreportmover.shim.remote for flush operations.
+ */
+export class CrashReportsService extends BaseService {
+  static readonly RSD_COPY_MOBILE_NAME =
+    'com.apple.crashreportcopymobile.shim.remote';
+  static readonly RSD_CRASH_MOVER_NAME =
+    'com.apple.crashreportmover.shim.remote';
+
+  private readonly afc: AfcService;
+  private readonly crashMoverAddress: [string, number];
+
+  /**
+   * Creates a new CrashReportsService instance
+   * @param afcAddress Tuple containing [host, port] for the AFC service
+   * @param crashMoverAddress Tuple containing [host, port] for the crash mover service
+   */
+  constructor(
+    afcAddress: [string, number],
+    crashMoverAddress: [string, number],
+  ) {
+    super(afcAddress);
+    this.afc = new AfcService(afcAddress, true);
+    this.crashMoverAddress = crashMoverAddress;
+  }
+
+  /**
+   * List files and folders in the crash report's directory.
+   * @param dirPath Path to list, relative to the crash report's directory. Defaults to "/"
+   * @param depth Listing depth. 1 for immediate children, -1 (or any negative number) for infinite depth
+   * @returns List of file paths listed
+   */
+  async ls(dirPath = '/', depth = 1): Promise<string[]> {
+    log.debug(`Listing crash reports at path: ${dirPath}, depth: ${depth}`);
+
+    if (depth === 0) {
+      return [];
+    }
+
+    const results: string[] = [];
+    const entries = await this.afc.listdir(dirPath);
+
+    for (const entry of entries) {
+      const entryPath = posixpath.join(dirPath, entry);
+      results.push(entryPath);
+
+      if (depth !== 1) {
+        try {
+          if (await this.afc.isdir(entryPath)) {
+            const newDepth = depth < 0 ? -1 : depth - 1;
+            const subEntries = await this.ls(entryPath, newDepth);
+            results.push(...subEntries);
+          }
+        } catch {
+          // Skip entries we can't access
+        }
+      }
+    }
+
+    return results;
+  }
+
+  /**
+   * Pull crash reports from the device to the local machine.
+   * @param out Local directory path
+   * @param entry Remote path on device, defaults to "/"
+   * @param options Pull options (erase, match pattern)
+   */
+  async pull(
+    out: string,
+    entry = '/',
+    options?: CrashReportsPullOptions,
+  ): Promise<void> {
+    const { erase = false, match } = options ?? {};
+
+    log.debug(
+      `Pulling crash reports from '${entry}' to '${out}', erase: ${erase}`,
+    );
+
+    await fs.mkdir(out, { recursive: true });
+
+    await this.afc.pull(entry, out, {
+      recursive: true,
+      match,
+      callback: erase
+        ? async (remotePath) => void (await this.afc.rmSingle(remotePath, true))
+        : undefined,
+    });
+  }
+
+  /**
+   * Clear all crash reports from the device.
+   * Removes all files and folders from the crash reports directory.
+   * @throws Error if some items could not be deleted (except for auto-created paths)
+   */
+  async clear(): Promise<void> {
+    log.debug('Clearing all crash reports');
+
+    const entries = await this.afc.listdir('/');
+    const nonDeletedItems: string[] = [];
+
+    for (const entry of entries) {
+      const fullPath = posixpath.join('/', entry);
+      const failedPaths = await this.afc.rm(fullPath, true);
+      nonDeletedItems.push(...failedPaths);
+    }
+
+    // Filter out special paths that are auto-created
+    const realFailures = nonDeletedItems.filter(
+      (item) => item !== APPSTORED_PATH,
+    );
+
+    if (realFailures.length > 0) {
+      throw new Error(
+        `Failed to clear crash reports directory, undeleted items: ${realFailures.join(', ')}`,
+      );
+    }
+
+    log.debug('Successfully cleared all crash reports');
+  }
+
+  /**
+   * Trigger com.apple.crashreportmover to flush all products into CrashReports directory
+   */
+  async flush(): Promise<void> {
+    log.debug('Flushing crash reports');
+
+    const socket = await createRawServiceSocket(
+      this.crashMoverAddress[0],
+      this.crashMoverAddress[1],
+    );
+    try {
+      const ack = await readExact(socket, 5, 10000);
+      const expectedAck = Buffer.from('ping\0', 'utf8');
+      if (!ack.equals(expectedAck)) {
+        throw new Error(
+          `Unexpected flush acknowledgment. Expected: ${expectedAck.toString('hex')}, Got: ${ack.toString('hex')}`,
+        );
+      }
+      log.debug('Successfully flushed crash reports');
+    } finally {
+      socket.destroy();
+    }
+  }
+
+  /**
+   * Close the service and release resources
+   */
+  close(): void {
+    log.debug('Closing CrashReportsService');
+    try {
+      this.afc.close();
+    } catch {}
+  }
+}
+
+export default CrashReportsService;

package/src/services/ios/mobile-config/index.ts

@@ -85,7 +85,7 @@ class MobileConfigService
     // Check if file exists
     try {
       await fs.access(filePath);
-    } catch (error) {
+    } catch {
       throw new Error(`Profile filepath does not exist: ${filePath}`);
     }
 
@@ -163,7 +163,7 @@ class MobileConfigService
       ProfileIdentifier: createPlist(payloadData, true),
     };
 
-    log.info(req);
+    log.debug('Removing profile with request:', req);
 
     await this._sendPlistAndReceive(req);
   }

package/src/services.ts

@@ -4,6 +4,7 @@ import { RemoteXpcConnection } from './lib/remote-xpc/remote-xpc-connection.js';
 import { TunnelManager } from './lib/tunnel/index.js';
 import { TunnelApiClient } from './lib/tunnel/tunnel-api-client.js';
 import type {
+  CrashReportsServiceWithConnection,
   DVTServiceWithConnection,
   DiagnosticsServiceWithConnection,
   MisagentServiceWithConnection,
@@ -16,6 +17,7 @@ import type {
   WebInspectorServiceWithConnection,
 } from './lib/types.js';
 import AfcService from './services/ios/afc/index.js';
+import { CrashReportsService } from './services/ios/crash-reports/index.js';
 import DiagnosticsService from './services/ios/diagnostic-service/index.js';
 import { DVTSecureSocketProxyService } from './services/ios/dvt/index.js';
 import { ApplicationListing } from './services/ios/dvt/instruments/application-listing.js';
@@ -170,6 +172,31 @@ export async function startAfcService(udid: string): Promise<AfcService> {
   ]);
 }
 
+/**
+ * Start CrashReportsService over RemoteXPC shim.
+ * Resolves the crash report copy mobile and crash mover service ports via RemoteXPC.
+ */
+export async function startCrashReportsService(
+  udid: string,
+): Promise<CrashReportsServiceWithConnection> {
+  const { remoteXPC, tunnelConnection } = await createRemoteXPCConnection(udid);
+
+  const copyMobileDescriptor = remoteXPC.findService(
+    CrashReportsService.RSD_COPY_MOBILE_NAME,
+  );
+  const crashMoverDescriptor = remoteXPC.findService(
+    CrashReportsService.RSD_CRASH_MOVER_NAME,
+  );
+
+  return {
+    remoteXPC: remoteXPC as RemoteXpcConnection,
+    crashReportsService: new CrashReportsService(
+      [tunnelConnection.host, parseInt(copyMobileDescriptor.port, 10)],
+      [tunnelConnection.host, parseInt(crashMoverDescriptor.port, 10)],
+    ),
+  };
+}
+
 export async function startWebInspectorService(
   udid: string,
 ): Promise<WebInspectorServiceWithConnection> {