appium-ios-remotexpc 2.2.4 → 2.3.0

package/src/services/ios/zipconduit/constants.ts

@@ -0,0 +1,30 @@
+/** Observed Xcode directory permission value (0o755). */
+export const STD_DIR_PERM = 16877;
+
+/** Observed Xcode file permission value (0o644). */
+export const STD_FILE_PERM = -32348;
+
+export const METAINF_FILE_NAME = 'com.apple.ZipMetadata.plist';
+
+/** Fake central directory signature sent after the streaming payload. */
+export const CENTRAL_DIRECTORY_HEADER = Buffer.from([0x50, 0x4b, 0x01, 0x02]);
+
+/**
+ * Fixed 32-byte UT extra field observed in Xcode zip_conduit traffic.
+ * https://commons.apache.org/proper/commons-compress/apidocs/org/apache/commons/compress/archivers/zip/X5455_ExtendedTimestamp.html
+ */
+export const ZIP_EXTRA_BYTES = Buffer.from(
+  '55540D0007F3A2EC60F6A2EC60F3A2EC6075780B000104F50100000414000000',
+  'hex',
+);
+
+export const ZIP_LOCAL_FILE_HEADER_SIGNATURE = 0x04034b50;
+export const ZIP_HEADER_LAST_MODIFIED_TIME = 0xbdef;
+export const ZIP_HEADER_LAST_MODIFIED_DATE = 0x52ec;
+
+export const COPY_BUFFER_SIZE = 32 * 1024;
+
+/** Socket write size while streaming entry payloads (match AFC push chunking). */
+export const TRANSFER_CHUNK_SIZE = 1024 * 1024;
+
+export const DEFAULT_INSTALL_TIMEOUT_MS = 10 * 60 * 1000;

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

@@ -0,0 +1,242 @@
+import fsp from 'node:fs/promises';
+import type net from 'node:net';
+
+import { getLogger } from '../../../lib/logger.js';
+import type { PlistDictionary } from '../../../lib/types.js';
+import {
+  cleanupServiceSocket,
+  createRawServiceSocket,
+  recvOnePlist,
+  sendOnePlist,
+  writeBufferToSocket,
+} from '../afc/codec.js';
+import {
+  CENTRAL_DIRECTORY_HEADER,
+  DEFAULT_INSTALL_TIMEOUT_MS,
+} from './constants.js';
+import {
+  type ZipConduitProgressUpdate,
+  createInitTransfer,
+  evaluateProgress,
+} from './plists.js';
+import {
+  type IpaZipEntry,
+  listZipEntries,
+  openZipEntryStream,
+  withZipFile,
+} from './zip-reader.js';
+import {
+  transferDirectory,
+  transferFile,
+  transferMetaInfDirectory,
+  transferMetaInfFile,
+} from './zip-utils.js';
+
+const log = getLogger('ZipConduitService');
+
+export type ZipConduitProgressCallback = (
+  update: ZipConduitProgressUpdate,
+) => void;
+
+export interface ZipConduitInstallOptions {
+  progress?: ZipConduitProgressCallback;
+  timeoutMs?: number;
+  /** Stop after payload upload; skip waiting for install progress plists. */
+  streamOnly?: boolean;
+}
+
+export interface ZipConduitStreamStats {
+  streamMs: number;
+  payloadBytes: number;
+  entryCount: number;
+}
+
+/**
+ * Streaming zip_conduit client for fast IPA installation over RSD.
+ */
+export class ZipConduitService {
+  static readonly RSD_SERVICE_NAME =
+    'com.apple.streaming_zip_conduit.shim.remote';
+
+  private socket: net.Socket | null = null;
+
+  constructor(private readonly address: [string, number]) {}
+
+  /**
+   * Connect to the zip_conduit service and complete the RSD handshake.
+   */
+  async connect(): Promise<void> {
+    if (this.socket) {
+      return;
+    }
+    this.socket = await createRawServiceSocket(
+      this.address[0],
+      this.address[1],
+    );
+  }
+
+  /**
+   * Install an IPA or app directory using streaming zip_conduit.
+   */
+  async install(
+    appPath: string,
+    options: ZipConduitInstallOptions = {},
+  ): Promise<ZipConduitStreamStats | void> {
+    await this.connect();
+    const socket = this.socket;
+    if (!socket) {
+      throw new Error('ZipConduitService is not connected');
+    }
+
+    const fileStats = await fsp.stat(appPath);
+    if (fileStats.isDirectory()) {
+      throw new Error(
+        'Directory install is not supported yet; provide a path to an .ipa file',
+      );
+    }
+
+    const streamStats = await this.sendIpaFile(socket, appPath);
+    if (options.streamOnly) {
+      return streamStats;
+    }
+    await this.waitForInstallation(socket, options);
+  }
+
+  /**
+   * Close the underlying socket.
+   */
+  close(): void {
+    if (!this.socket) {
+      return;
+    }
+    cleanupServiceSocket(this.socket);
+    this.socket = null;
+  }
+
+  private async sendIpaFile(
+    socket: net.Socket,
+    ipaPath: string,
+  ): Promise<ZipConduitStreamStats> {
+    const streamStart = performance.now();
+    let payloadBytes = 0;
+
+    const init = createInitTransfer(ipaPath);
+    const { entries } = await withZipFile(ipaPath, async (zip) => {
+      const listed = await listZipEntries(zip);
+      const { totalBytes, numFiles } = collectZipStats(listed);
+      log.debug(`Sending InitTransfer for ${init.MediaSubdir}`);
+      await sendOnePlist(socket, init as unknown as PlistDictionary);
+
+      await transferMetaInfDirectory(socket);
+      await transferMetaInfFile(socket, numFiles, totalBytes);
+
+      for (const entry of listed) {
+        if (isDirectoryEntry(entry)) {
+          await transferDirectory(socket, entry.name);
+          continue;
+        }
+
+        const stream = await openZipEntryStream(zip, entry);
+        try {
+          await transferFile(socket, stream, entry.crc, entry.size, entry.name);
+          payloadBytes += entry.size;
+        } finally {
+          stream.destroy();
+        }
+      }
+
+      return { entries: listed };
+    });
+
+    log.debug('IPA payload sent, writing central directory marker');
+    await writeBufferToSocket(socket, CENTRAL_DIRECTORY_HEADER);
+
+    const streamMs = performance.now() - streamStart;
+    const stats: ZipConduitStreamStats = {
+      streamMs,
+      payloadBytes,
+      entryCount: entries.length,
+    };
+    log.debug(
+      `zip_conduit stream finished in ${formatSeconds(streamMs)} ` +
+        `(${formatMiBPerSec(payloadBytes, streamMs)}, ${entries.length} entries)`,
+    );
+    return stats;
+  }
+
+  private async waitForInstallation(
+    socket: net.Socket,
+    options: Pick<ZipConduitInstallOptions, 'progress' | 'timeoutMs'>,
+  ): Promise<void> {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_INSTALL_TIMEOUT_MS;
+    const startTime = performance.now();
+
+    while (performance.now() - startTime <= timeoutMs) {
+      const remaining = timeoutMs - (performance.now() - startTime);
+      const plist = await recvOnePlistWithTimeout(socket, remaining);
+      const { done, percent, status } = evaluateProgress(plist);
+      options.progress?.({ percent, status });
+      if (done) {
+        return;
+      }
+    }
+
+    throw new Error(
+      `Timed out waiting for zip_conduit installation after ${timeoutMs}ms`,
+    );
+  }
+}
+
+function collectZipStats(entries: IpaZipEntry[]): {
+  totalBytes: number;
+  numFiles: number;
+} {
+  const totalBytes = entries.reduce((sum, entry) => sum + entry.size, 0);
+  return { totalBytes, numFiles: entries.length };
+}
+
+function isDirectoryEntry(entry: IpaZipEntry): boolean {
+  return entry.isDirectory || entry.name.endsWith('/');
+}
+
+function formatSeconds(ms: number): string {
+  return `${(ms / 1000).toFixed(2)}s`;
+}
+
+function formatMiBPerSec(bytes: number, ms: number): string {
+  if (ms <= 0) {
+    return 'n/a';
+  }
+  const mibPerSec = bytes / (1024 * 1024) / (ms / 1000);
+  return `${mibPerSec.toFixed(2)} MiB/s`;
+}
+
+async function recvOnePlistWithTimeout(
+  socket: net.Socket,
+  timeoutMs: number,
+): Promise<PlistDictionary> {
+  if (timeoutMs <= 0) {
+    throw new Error('Timed out waiting for zip_conduit progress update');
+  }
+
+  let timeoutId: NodeJS.Timeout | undefined;
+  const timeoutPromise = new Promise<never>((_resolve, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(
+        new Error(
+          `Timed out waiting for zip_conduit progress after ${timeoutMs}ms`,
+        ),
+      );
+    }, timeoutMs);
+  });
+
+  try {
+    return await Promise.race([recvOnePlist(socket), timeoutPromise]);
+  } finally {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+  }
+}
+
+export default ZipConduitService;

package/src/services/ios/zipconduit/plists.ts

@@ -0,0 +1,139 @@
+import path from 'node:path';
+
+import type { PlistDictionary } from '../../../lib/types.js';
+import { STD_DIR_PERM, STD_FILE_PERM } from './constants.js';
+
+export const SIGNING_ERROR = 'ApplicationVerificationFailed';
+
+export interface ZipConduitMetadata {
+  StandardDirectoryPerms: number;
+  StandardFilePerms: number;
+  RecordCount: number;
+  TotalUncompressedBytes: number;
+  Version: number;
+}
+
+export interface InitTransferRequest {
+  InstallOptionsDictionary: {
+    DisableDeltaTransfer: number;
+    InstallDeltaTypeKey: string;
+    IsUserInitiated: number;
+    PackageType: string;
+    PreferWifi: number;
+  };
+  InstallTransferredDirectory: number;
+  MediaSubdir: string;
+  UserInitiatedTransfer: number;
+}
+
+export interface ZipConduitProgressUpdate {
+  percent: number;
+  status: string;
+}
+
+/**
+ * Build the InitTransfer plist payload for zip_conduit.
+ * @param fileName Local IPA path used to derive the PublicStaging destination.
+ */
+export function createInitTransfer(fileName: string): InitTransferRequest {
+  const base = path.basename(fileName);
+  return {
+    InstallTransferredDirectory: 1,
+    UserInitiatedTransfer: 0,
+    MediaSubdir: `PublicStaging/${base}`,
+    InstallOptionsDictionary: {
+      InstallDeltaTypeKey: 'InstallDeltaTypeSparseIPAFiles',
+      DisableDeltaTransfer: 1,
+      IsUserInitiated: 1,
+      PreferWifi: 1,
+      PackageType: 'Customer',
+    },
+  };
+}
+
+/**
+ * Build ZipMetadata plist values embedded in the streamed archive.
+ * @param numFiles Number of entries in the source IPA.
+ * @param totalBytes Sum of uncompressed sizes for all IPA entries.
+ */
+export function createMetaInfPlist(
+  numFiles: number,
+  totalBytes: number,
+): ZipConduitMetadata {
+  return {
+    RecordCount: 2 + numFiles,
+    StandardDirectoryPerms: STD_DIR_PERM,
+    StandardFilePerms: STD_FILE_PERM,
+    TotalUncompressedBytes: totalBytes,
+    Version: 2,
+  };
+}
+
+/**
+ * Parse a zip_conduit progress plist into completion state and percentage.
+ * @param progressUpdate Progress plist received from the device.
+ */
+export function evaluateProgress(progressUpdate: PlistDictionary): {
+  done: boolean;
+  percent: number;
+  status: string;
+} {
+  const topStatus = asString(progressUpdate.Status);
+  if (topStatus === 'DataComplete') {
+    return { done: true, percent: 100, status: topStatus };
+  }
+
+  // The device can report a failure as a top-level Error (e.g. ExtractionFailed)
+  // with no InstallProgressDict; surface the real reason instead of a generic
+  // "missing InstallProgressDict".
+  const topError = asString(progressUpdate.Error);
+  if (topError) {
+    const topDescription = asString(progressUpdate.ErrorDescription) ?? '';
+    throw new Error(
+      `Failed installing: '${topError}'${topDescription ? ` errorDescription:'${topDescription}'` : ''}`,
+    );
+  }
+
+  const installProgressDict = progressUpdate.InstallProgressDict;
+  if (!installProgressDict || typeof installProgressDict !== 'object') {
+    throw new Error(
+      `Invalid progress update, missing InstallProgressDict: ${JSON.stringify(progressUpdate)}`,
+    );
+  }
+
+  const progress = installProgressDict as PlistDictionary;
+  const errorMessage = asString(progress.Error);
+  if (errorMessage) {
+    const description = asString(progress.ErrorDescription) ?? '';
+    if (errorMessage === SIGNING_ERROR) {
+      throw new Error(
+        `App is not properly signed for this device. original error: '${errorMessage}' errorDescription:'${description}'`,
+      );
+    }
+    throw new Error(
+      `Failed installing: '${errorMessage}' errorDescription:'${description}'`,
+    );
+  }
+
+  const percent = asNumber(progress.PercentComplete) ?? 0;
+  const status = asString(progress.Status) ?? '';
+  return { done: false, percent, status };
+}
+
+function asNumber(value: unknown): number | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === 'bigint') {
+    return Number(value);
+  }
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}