appium-ios-remotexpc 2.2.4 → 2.3.0

package/src/services/ios/zipconduit/zip-reader.ts

@@ -0,0 +1,48 @@
+import type { Readable } from 'node:stream';
+
+import { TRANSFER_CHUNK_SIZE } from './constants.js';
+import { StreamZip, type StreamZipEntry } from './stream-zip.js';
+
+/** Subset of a ZIP central-directory entry used while streaming an IPA. */
+export type IpaZipEntry = StreamZipEntry;
+
+/** Reading surface of an open ZIP archive used by ZipConduit. */
+export type ZipArchive = Pick<StreamZip, 'entries' | 'stream' | 'close'>;
+
+/**
+ * Open an IPA archive, run `fn`, and close the handle when done.
+ */
+export async function withZipFile<T>(
+  ipaPath: string,
+  fn: (zip: ZipArchive) => Promise<T>,
+): Promise<T> {
+  const zip = new StreamZip({
+    file: ipaPath,
+    chunkSize: TRANSFER_CHUNK_SIZE,
+    // Do NOT skip the local header read: an entry's payload offset depends on the
+    // LOCAL header's extra-field length, which the central directory does not record
+    // and which routinely differs from it. Skipping it streams misaligned bytes and
+    // the device fails extraction (ExtractionFailed).
+    verifyEntryCrc: false,
+    skipEntryNameValidation: true,
+  });
+  try {
+    return await fn(zip);
+  } finally {
+    await zip.close();
+  }
+}
+
+/** List all entries from an already-open IPA archive without extracting them. */
+export async function listZipEntries(zip: ZipArchive): Promise<IpaZipEntry[]> {
+  const entries = await zip.entries();
+  return Object.values(entries);
+}
+
+/** Open a decompressed readable stream for one zip entry. */
+export async function openZipEntryStream(
+  zip: ZipArchive,
+  entry: IpaZipEntry,
+): Promise<Readable> {
+  return await zip.stream(entry);
+}

package/src/services/ios/zipconduit/zip-utils.ts

@@ -0,0 +1,185 @@
+import type net from 'node:net';
+import type { Readable } from 'node:stream';
+import { Readable as ReadableStream } from 'node:stream';
+import { crc32 } from 'node:zlib';
+
+import { createPlist } from '../../../lib/plist/unified-plist-creator.js';
+import type { PlistDictionary } from '../../../lib/types.js';
+import { writeBufferToSocket } from '../afc/codec.js';
+import {
+  METAINF_FILE_NAME,
+  TRANSFER_CHUNK_SIZE,
+  ZIP_EXTRA_BYTES,
+  ZIP_HEADER_LAST_MODIFIED_DATE,
+  ZIP_HEADER_LAST_MODIFIED_TIME,
+  ZIP_LOCAL_FILE_HEADER_SIGNATURE,
+} from './constants.js';
+import { createMetaInfPlist } from './plists.js';
+
+interface ZipLocalHeader {
+  signature: number;
+  version: number;
+  generalPurposeBitFlags: number;
+  compressionMethod: number;
+  lastModifiedTime: number;
+  lastModifiedDate: number;
+  crc32: number;
+  compressedSize: number;
+  uncompressedSize: number;
+  fileNameLength: number;
+  extraFieldLength: number;
+}
+
+/**
+ * Encode ZipMetadata as XML plist bytes for META-INF/com.apple.ZipMetadata.plist.
+ */
+export function createMetaInfBytes(
+  numFiles: number,
+  totalBytes: number,
+): Buffer {
+  const metadata = createMetaInfPlist(
+    numFiles,
+    totalBytes,
+  ) as unknown as PlistDictionary;
+  const plist = createPlist(metadata, false);
+  return Buffer.isBuffer(plist) ? plist : Buffer.from(plist, 'utf8');
+}
+
+/**
+ * Write a streaming zip_conduit directory entry to the socket.
+ */
+export async function transferDirectory(
+  socket: net.Socket,
+  dstDirPath: string,
+): Promise<void> {
+  await writeBufferToSocket(socket, newZipHeaderDir(dstDirPath));
+}
+
+/**
+ * Write a streaming zip_conduit file entry and its uncompressed payload.
+ */
+export async function transferFile(
+  socket: net.Socket,
+  src: Readable,
+  crc32Value: number,
+  uncompressedSize: number,
+  dstFilePath: string,
+): Promise<void> {
+  await writeBufferToSocket(
+    socket,
+    newZipHeader(uncompressedSize, crc32Value, dstFilePath),
+  );
+  await pipeReadableToSocket(socket, src);
+}
+
+/**
+ * Copy readable data to the socket in large chunks to reduce await/drain overhead.
+ */
+export async function pipeReadableToSocket(
+  socket: net.Socket,
+  src: Readable,
+  chunkSize = TRANSFER_CHUNK_SIZE,
+): Promise<void> {
+  const buf = Buffer.allocUnsafe(chunkSize);
+  let offset = 0;
+
+  for await (const chunk of src) {
+    const data = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    let dataOffset = 0;
+    while (dataOffset < data.length) {
+      const space = chunkSize - offset;
+      const toCopy = Math.min(space, data.length - dataOffset);
+      data.copy(buf, offset, dataOffset, dataOffset + toCopy);
+      offset += toCopy;
+      dataOffset += toCopy;
+      if (offset === chunkSize) {
+        await writeBufferToSocket(socket, buf.subarray(0, chunkSize));
+        offset = 0;
+      }
+    }
+  }
+
+  if (offset > 0) {
+    await writeBufferToSocket(socket, buf.subarray(0, offset));
+  }
+}
+
+/**
+ * Write the META-INF/ directory header expected by zip_conduit.
+ */
+export async function transferMetaInfDirectory(
+  socket: net.Socket,
+): Promise<void> {
+  await transferDirectory(socket, 'META-INF/');
+}
+
+/**
+ * Write the synthetic com.apple.ZipMetadata.plist entry.
+ */
+export async function transferMetaInfFile(
+  socket: net.Socket,
+  numFiles: number,
+  totalBytes: number,
+): Promise<void> {
+  const metaInfBytes = createMetaInfBytes(numFiles, totalBytes);
+  const checksum = crc32(metaInfBytes) >>> 0;
+  await transferFile(
+    socket,
+    ReadableStream.from(metaInfBytes),
+    checksum,
+    metaInfBytes.length,
+    `META-INF/${METAINF_FILE_NAME}`,
+  );
+}
+
+function encodeZipLocalHeader(header: ZipLocalHeader): Buffer {
+  const buf = Buffer.alloc(30);
+  buf.writeUInt32LE(header.signature, 0);
+  buf.writeUInt16LE(header.version, 4);
+  buf.writeUInt16LE(header.generalPurposeBitFlags, 6);
+  buf.writeUInt16LE(header.compressionMethod, 8);
+  buf.writeUInt16LE(header.lastModifiedTime, 10);
+  buf.writeUInt16LE(header.lastModifiedDate, 12);
+  buf.writeUInt32LE(header.crc32 >>> 0, 14);
+  buf.writeUInt32LE(header.compressedSize >>> 0, 18);
+  buf.writeUInt32LE(header.uncompressedSize >>> 0, 22);
+  buf.writeUInt16LE(header.fileNameLength, 26);
+  buf.writeUInt16LE(header.extraFieldLength, 28);
+  return buf;
+}
+
+function newZipHeaderDir(name: string): Buffer {
+  const nameBytes = Buffer.from(name, 'utf8');
+  const header = encodeZipLocalHeader({
+    signature: ZIP_LOCAL_FILE_HEADER_SIGNATURE,
+    version: 20,
+    generalPurposeBitFlags: 0,
+    compressionMethod: 0,
+    lastModifiedTime: ZIP_HEADER_LAST_MODIFIED_TIME,
+    lastModifiedDate: ZIP_HEADER_LAST_MODIFIED_DATE,
+    crc32: 0,
+    compressedSize: 0,
+    uncompressedSize: 0,
+    fileNameLength: nameBytes.length,
+    extraFieldLength: ZIP_EXTRA_BYTES.length,
+  });
+  return Buffer.concat([header, nameBytes, ZIP_EXTRA_BYTES]);
+}
+
+function newZipHeader(size: number, crc32Value: number, name: string): Buffer {
+  const nameBytes = Buffer.from(name, 'utf8');
+  const header = encodeZipLocalHeader({
+    signature: ZIP_LOCAL_FILE_HEADER_SIGNATURE,
+    version: 20,
+    generalPurposeBitFlags: 0,
+    compressionMethod: 0,
+    lastModifiedTime: ZIP_HEADER_LAST_MODIFIED_TIME,
+    lastModifiedDate: ZIP_HEADER_LAST_MODIFIED_DATE,
+    crc32: crc32Value >>> 0,
+    compressedSize: size >>> 0,
+    uncompressedSize: size >>> 0,
+    fileNameLength: nameBytes.length,
+    extraFieldLength: ZIP_EXTRA_BYTES.length,
+  });
+  return Buffer.concat([header, nameBytes, ZIP_EXTRA_BYTES]);
+}

package/src/services.ts

@@ -33,6 +33,7 @@ import { SpringBoardService } from './services/ios/springboard-service/index.js'
 import SyslogService from './services/ios/syslog-service/index.js';
 import { DvtTestmanagedProxyService } from './services/ios/testmanagerd/index.js';
 import { WebInspectorService } from './services/ios/webinspector/index.js';
+import ZipConduitService from './services/ios/zipconduit/index.js';
 
 const log = getLogger('Services');
 
@@ -219,6 +220,24 @@ export async function startAfcService(udid: string): Promise<AfcService> {
   });
 }
 
+/**
+ * Start streaming zip_conduit service over RemoteXPC shim.
+ * Use {@link ZipConduitService.install} for fast IPA installation without AFC upload.
+ */
+export async function startZipConduitService(
+  udid: string,
+): Promise<ZipConduitService> {
+  return withRemoteXpcConnection(udid, (remoteXPC, tunnelConnection) => {
+    const descriptor = remoteXPC.findService(
+      ZipConduitService.RSD_SERVICE_NAME,
+    );
+    return new ZipConduitService([
+      tunnelConnection.host,
+      parseInt(descriptor.port, 10),
+    ]);
+  });
+}
+
 /**
  * Start CrashReportsService over RemoteXPC shim.
  * Resolves the crash report copy mobile and crash mover service ports via RemoteXPC.