appium-ios-remotexpc 2.2.1 → 2.2.2

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

@@ -6,6 +6,7 @@ import {
   AFCMAGIC,
   AFC_HEADER_SIZE,
   AFC_OPERATION_TIMEOUT_MS,
+  MAXIMUM_READ_SIZE,
   NULL_BYTE,
 } from './constants.js';
 import { AfcError, AfcFopenMode, AfcOpcode } from './enums.js';
@@ -68,32 +69,35 @@ export function cstr(str: string): Buffer {
   return Buffer.concat([s, NULL_BYTE]);
 }
 /**
- * Build an AFC packet header for the provided operation and payload length.
+ * Build an AFC packet header with explicit entire_length and this_length values.
  */
-export function encodeHeader(
+export function encodeHeaderExplicit(
   op: AfcOpcode,
   packetNum: bigint,
-  payloadLen: number,
-  thisLenOverride?: number,
+  entireLen: number,
+  thisLen: number,
 ): Buffer {
-  const entireLen = BigInt(AFC_HEADER_SIZE + payloadLen);
-  const thisLen = BigInt(thisLenOverride ?? AFC_HEADER_SIZE + payloadLen);
-
   const header = Buffer.alloc(AFC_HEADER_SIZE);
-  // magic
   AFCMAGIC.copy(header, 0);
-  // entire_length
-  writeUInt64LE(entireLen).copy(header, 8);
-  // this_length
-  writeUInt64LE(thisLen).copy(header, 16);
-  // packet_num
+  writeUInt64LE(BigInt(entireLen)).copy(header, 8);
+  writeUInt64LE(BigInt(thisLen)).copy(header, 16);
   writeUInt64LE(packetNum).copy(header, 24);
-  // operation
   writeUInt64LE(BigInt(op)).copy(header, 32);
-
   return header;
 }
 
+/**
+ * Build an AFC packet header for a single contiguous payload after the header.
+ */
+export function encodeHeader(
+  op: AfcOpcode,
+  packetNum: bigint,
+  payloadLen: number,
+): Buffer {
+  const entireLen = AFC_HEADER_SIZE + payloadLen;
+  return encodeHeaderExplicit(op, packetNum, entireLen, entireLen);
+}
+
 const SOCKET_STATES = new WeakMap<net.Socket, SocketState>();
 const FATAL_SOCKETS = new WeakSet<net.Socket>();
 
@@ -201,33 +205,64 @@ export async function readAfcResponse(
 }
 
 /**
- * Send an AFC packet (header and optional payload) to the socket.
+ * Write a buffer to the socket, waiting for drain only when the kernel buffer is full.
+ */
+export async function writeBufferToSocket(
+  socket: net.Socket,
+  data: Buffer,
+): Promise<void> {
+  assertSocketReadable(socket);
+  if (!data.length) {
+    return;
+  }
+  if (socket.write(data)) {
+    return;
+  }
+  await new Promise<void>((resolve, reject) => {
+    const onDrain = () => {
+      cleanup();
+      resolve();
+    };
+    const onError = (err: Error) => {
+      cleanup();
+      reject(err);
+    };
+    const onClosed = () => {
+      cleanup();
+      reject(
+        new AfcConnectionError('AFC socket closed while waiting for drain'),
+      );
+    };
+    const cleanup = () => {
+      socket.off('drain', onDrain);
+      socket.off('error', onError);
+      socket.off('close', onClosed);
+      socket.off('end', onClosed);
+    };
+    socket.once('drain', onDrain);
+    socket.once('error', onError);
+    socket.once('close', onClosed);
+    socket.once('end', onClosed);
+  });
+}
+
+/**
+ * Send an AFC packet as three socket writes: header, optional header payload, optional body.
+ * For FILE_WRITE, headerPayload is the 8-byte handle and content is file bytes (no memcpy).
  */
 export async function sendAfcPacket(
   socket: net.Socket,
   op: AfcOpcode,
   packetNum: bigint,
-  payload: Buffer = Buffer.alloc(0),
-  thisLenOverride?: number,
+  headerPayload: Buffer = Buffer.alloc(0),
+  content: Buffer = Buffer.alloc(0),
 ): Promise<void> {
-  const header = encodeHeader(op, packetNum, payload.length, thisLenOverride);
-  await new Promise<void>((resolve, reject) => {
-    socket.write(header, (err) => {
-      if (err) {
-        return reject(err);
-      }
-      if (payload.length) {
-        socket.write(payload, (err2) => {
-          if (err2) {
-            return reject(err2);
-          }
-          resolve();
-        });
-      } else {
-        resolve();
-      }
-    });
-  });
+  const thisLen = AFC_HEADER_SIZE + headerPayload.length;
+  const entireLen = thisLen + content.length;
+  const header = encodeHeaderExplicit(op, packetNum, entireLen, thisLen);
+  await writeBufferToSocket(socket, header);
+  await writeBufferToSocket(socket, headerPayload);
+  await writeBufferToSocket(socket, content);
 }
 
 /**
@@ -391,6 +426,7 @@ export async function createRawServiceSocket(
   const socket = await new Promise<net.Socket>((resolve, reject) => {
     const conn = net.createConnection({ host, port }, () => {
       conn.setKeepAlive(true);
+      conn.setNoDelay(true);
       resolve(conn);
     });
     conn.setTimeout(timeoutMs, () => {
@@ -415,7 +451,7 @@ export async function createRawServiceSocket(
  */
 export function nextReadChunkSize(left: bigint | number): number {
   const leftNum = typeof left === 'bigint' ? Number(left) : left;
-  return leftNum;
+  return Math.min(leftNum, MAXIMUM_READ_SIZE);
 }
 
 /**

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

@@ -7,8 +7,9 @@ import { AfcFopenMode } from './enums.js';
 // Magic bytes at start of every AFC header
 export const AFCMAGIC = Buffer.from('CFA6LPAA', 'ascii');
 
-// IO chunk sizes
-export const MAXIMUM_READ_SIZE = 4 * 1024 * 1024; // 4 MiB
+// IO chunk sizes (split writes avoid memcpy)
+export const MAXIMUM_READ_SIZE = 1024 * 1024;
+export const MAXIMUM_WRITE_SIZE = 1024 * 1024;
 
 // Mapping of textual fopen modes to AFC modes
 export const AFC_FOPEN_TEXTUAL_MODES: Record<string, AfcFopenMode> = {
@@ -23,10 +24,7 @@ export const AFC_FOPEN_TEXTUAL_MODES: Record<string, AfcFopenMode> = {
 // Header size: magic (8) + entire_length (8) + this_length (8) + packet_num (8) + operation (8)
 export const AFC_HEADER_SIZE = 40;
 
-export const AFC_OPERATION_TIMEOUT_MS = 15_000;
-
-// Override for WRITE packets' this_length
-export const AFC_WRITE_THIS_LENGTH = 48;
+export const AFC_OPERATION_TIMEOUT_MS = 30_000;
 
 export const NULL_BYTE = Buffer.from([0]);
 

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

@@ -0,0 +1,225 @@
+import AsyncLock from 'async-lock';
+import type net from 'node:net';
+
+import { getLogger } from '../../../lib/logger.js';
+import {
+  fatalizeAfcSocket,
+  readAfcHeader,
+  readExact,
+  readUInt64LE,
+  sendAfcPacket,
+} from './codec.js';
+import { AFC_HEADER_SIZE, AFC_OPERATION_TIMEOUT_MS } from './constants.js';
+import { AfcError, AfcOpcode } from './enums.js';
+import { AfcConnectionError } from './errors.js';
+
+const log = getLogger('AfcService');
+
+type PendingResponse = {
+  resolve: (value: { status: AfcError; data: Buffer }) => void;
+  reject: (err: Error) => void;
+};
+
+/**
+ * Routes inbound AFC packets to the matching request by packet_num.
+ * A background reader task demultiplexes responses so callers can overlap
+ * sends while each operation is matched to its reply.
+ */
+export class AfcPacketDemux {
+  private readonly pending = new Map<bigint, PendingResponse>();
+  private packetNum = 0n;
+  private readerSocket: net.Socket | null = null;
+  private readerActive = false;
+  private readonly sendLock = new AsyncLock();
+  private stopped = false;
+
+  constructor(
+    private readonly getSocket: () => Promise<net.Socket>,
+    private readonly onFatalError: (err: Error) => void,
+  ) {}
+
+  ensureReaderStarted(socket: net.Socket): void {
+    if (this.stopped) {
+      throw new AfcConnectionError('AFC demux is stopped');
+    }
+    if (this.readerActive && this.readerSocket === socket) {
+      return;
+    }
+    this.readerSocket = socket;
+    this.readerActive = true;
+    void this._runReaderLoop(socket);
+  }
+
+  /**
+   * Register a waiter, send one packet, then await its response.
+   * packet_num assignment, waiter registration, and send are serialized;
+   * awaiting the response happens outside the send lock.
+   */
+  async sendAndWait(
+    op: AfcOpcode,
+    headerPayload: Buffer = Buffer.alloc(0),
+    content: Buffer = Buffer.alloc(0),
+    timeoutMs = AFC_OPERATION_TIMEOUT_MS,
+  ): Promise<{ status: AfcError; data: Buffer }> {
+    if (this.stopped) {
+      throw new AfcConnectionError('AFC demux is stopped');
+    }
+
+    const socket = await this.getSocket();
+    this.ensureReaderStarted(socket);
+
+    const responsePromise = await this._sendLocked(async () => {
+      const num = this.packetNum++;
+      const waiter = this._registerPending(num, timeoutMs, op);
+      try {
+        await sendAfcPacket(socket, op, num, headerPayload, content);
+      } catch (err) {
+        this._clearPending(num);
+        throw err;
+      }
+      return waiter;
+    });
+
+    return await responsePromise;
+  }
+
+  resetForNewSocket(): void {
+    this._failPending(new AfcConnectionError('AFC socket replaced'), false);
+    this.readerSocket = null;
+    this.readerActive = false;
+    this.stopped = false;
+  }
+
+  /** Graceful shutdown; does not notify the owning service. */
+  stop(): void {
+    this.stopped = true;
+    this._failPending(new AfcConnectionError('AFC demux stopped'), false);
+    this.readerSocket = null;
+    this.readerActive = false;
+  }
+
+  private async _runReaderLoop(socket: net.Socket): Promise<void> {
+    try {
+      await this._readerLoop(socket);
+    } catch (err) {
+      if (!this._isCurrentReader(socket)) {
+        return;
+      }
+      this._failPending(
+        err instanceof Error ? err : new Error(String(err)),
+        true,
+      );
+    } finally {
+      if (this.readerSocket === socket) {
+        this.readerActive = false;
+      }
+    }
+  }
+
+  private _sendLocked<T>(fn: () => Promise<T>): Promise<T> {
+    return this.sendLock.acquire('afc-send', fn);
+  }
+
+  private _registerPending(
+    pktNum: bigint,
+    timeoutMs: number,
+    op: AfcOpcode,
+  ): Promise<{ status: AfcError; data: Buffer }> {
+    return new Promise<{ status: AfcError; data: Buffer }>(
+      (resolve, reject) => {
+        const timer = setTimeout(() => {
+          if (!this.pending.has(pktNum)) {
+            return;
+          }
+          this._clearPending(pktNum);
+          reject(
+            new AfcConnectionError(
+              `AFC operation ${AfcOpcode[op] ?? op} timed out after ${timeoutMs}ms (packet ${pktNum})`,
+            ),
+          );
+        }, timeoutMs);
+
+        this.pending.set(pktNum, {
+          resolve: (value) => {
+            clearTimeout(timer);
+            resolve(value);
+          },
+          reject: (err) => {
+            clearTimeout(timer);
+            reject(err);
+          },
+        });
+      },
+    );
+  }
+
+  private _clearPending(pktNum: bigint): void {
+    this.pending.delete(pktNum);
+  }
+
+  private async _readerLoop(socket: net.Socket): Promise<void> {
+    try {
+      while (!this.stopped && !socket.destroyed) {
+        const header = await readAfcHeader(socket, AFC_OPERATION_TIMEOUT_MS);
+        const payloadLen = Number(
+          header.entireLength - BigInt(AFC_HEADER_SIZE),
+        );
+        const payload =
+          payloadLen > 0
+            ? await readExact(socket, payloadLen, AFC_OPERATION_TIMEOUT_MS)
+            : Buffer.alloc(0);
+
+        let status = AfcError.SUCCESS;
+        let data = payload;
+        const op = Number(header.operation) as AfcOpcode;
+
+        if (op === AfcOpcode.STATUS) {
+          if (payloadLen !== 8) {
+            log.error(`AFC STATUS response length != 8 (${payloadLen})`);
+          }
+          status = Number(readUInt64LE(payload.subarray(0, 8))) as AfcError;
+          data = Buffer.alloc(0);
+        } else if (op !== AfcOpcode.DATA) {
+          log.debug(
+            `Unexpected AFC response opcode ${op} for packet ${header.packetNum}`,
+          );
+        }
+
+        const waiter = this.pending.get(header.packetNum);
+        if (waiter) {
+          this.pending.delete(header.packetNum);
+          waiter.resolve({ status, data });
+        } else {
+          log.warn(
+            `AFC response with no waiter (packet ${header.packetNum}, op ${op})`,
+          );
+        }
+      }
+    } catch (err) {
+      if (!this._isCurrentReader(socket)) {
+        return;
+      }
+      const error =
+        err instanceof Error ? err : new AfcConnectionError(String(err));
+      if (!socket.destroyed) {
+        fatalizeAfcSocket(socket, error);
+      }
+      throw error;
+    }
+  }
+
+  /** True while this socket owns the background reader task. */
+  private _isCurrentReader(socket: net.Socket): boolean {
+    return !this.stopped && this.readerSocket === socket;
+  }
+
+  private _failPending(err: Error, notifyService: boolean): void {
+    for (const [, waiter] of this.pending) {
+      waiter.reject(err);
+    }
+    this.pending.clear();
+    if (notifyService) {
+      this.onFatalError(err);
+    }
+  }
+}

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

@@ -20,16 +20,10 @@ import {
   nanosecondsToMilliseconds,
   parseCStringArray,
   parseKeyValueNullList,
-  readAfcResponse,
-  sendAfcPacket,
   writeUInt64LE,
 } from './codec.js';
-import {
-  AFC_FOPEN_TEXTUAL_MODES,
-  AFC_LOCK_EX,
-  AFC_LOCK_UN,
-  AFC_WRITE_THIS_LENGTH,
-} from './constants.js';
+import { AFC_FOPEN_TEXTUAL_MODES, MAXIMUM_WRITE_SIZE } from './constants.js';
+import { AfcPacketDemux } from './demux.js';
 import { AfcError, AfcFileMode, AfcOpcode } from './enums.js';
 import { AfcConnectionError } from './errors.js';
 import { PullLocalNameAllocator } from './pull-local-name-allocator.js';
@@ -95,7 +89,7 @@ export class AfcService {
   static readonly RSD_SERVICE_NAME = 'com.apple.afc.shim.remote';
 
   private socket: net.Socket | null = null;
-  private packetNum: bigint = 0n;
+  private demux: AfcPacketDemux | null = null;
   private silent: boolean = false;
   /** Set when the AFC byte stream is no longer safe to reuse on this instance. */
   private connectionError: Error | null = null;
@@ -218,19 +212,14 @@ export class AfcService {
   }
 
   createReadStream(handle: bigint, size: bigint): Readable {
-    return createAfcReadStream(
-      handle,
-      size,
-      this._dispatch.bind(this),
-      this._receive.bind(this),
-    );
+    return createAfcReadStream(handle, size, this._sendAndWait.bind(this));
   }
 
   createWriteStream(handle: bigint, chunkSize?: number): Writable {
     return createAfcWriteStream(
       handle,
-      this._dispatch.bind(this),
-      this._receive.bind(this),
+      (handlePayload, content) =>
+        this._sendAndWait(AfcOpcode.WRITE, handlePayload, content),
       chunkSize,
     );
   }
@@ -262,12 +251,11 @@ export class AfcService {
       const chunk = data.subarray(offset, end);
       chunkCount++;
 
-      await this._dispatch(
+      const { status } = await this._sendAndWait(
         AfcOpcode.WRITE,
-        Buffer.concat([writeUInt64LE(handle), chunk]),
-        AFC_WRITE_THIS_LENGTH,
+        writeUInt64LE(handle),
+        chunk,
       );
-      const { status } = await this._receive();
       if (status !== AfcError.SUCCESS) {
         const errorName = AfcError[status] || 'UNKNOWN';
         if (!this.silent) {
@@ -312,15 +300,13 @@ export class AfcService {
   async setFileContents(filePath: string, data: Buffer): Promise<void> {
     log.debug(`Writing ${data.length} bytes to file: ${filePath}`);
     const h = await this.fopen(filePath, 'w');
-    await this._lockFile(h);
     try {
-      await this.fwrite(h, data);
+      await this.fwrite(h, data, MAXIMUM_WRITE_SIZE);
       log.debug(`Successfully wrote file: ${filePath}`);
     } catch (error) {
       await this.rmSingle(filePath, true);
       throw error;
     } finally {
-      await this._unlockFile(h);
       await this.fclose(h);
     }
   }
@@ -345,7 +331,6 @@ export class AfcService {
   async writeFromStream(filePath: string, stream: Readable): Promise<void> {
     log.debug(`Writing stream to file: ${filePath}`);
     const handle = await this.fopen(filePath, 'w');
-    await this._lockFile(handle);
     const writeStream = this.createWriteStream(handle);
     try {
       await pipeline(stream, writeStream);
@@ -354,7 +339,6 @@ export class AfcService {
       await this.rmSingle(filePath, true);
       throw error;
     } finally {
-      await this._unlockFile(handle);
       await this.fclose(handle);
     }
   }
@@ -548,7 +532,9 @@ export class AfcService {
 
   async push(localSrc: string, remoteDst: string): Promise<void> {
     log.debug(`Pushing file from '${localSrc}' to '${remoteDst}'`);
-    const readStream = fs.createReadStream(localSrc);
+    const readStream = fs.createReadStream(localSrc, {
+      highWaterMark: MAXIMUM_WRITE_SIZE,
+    });
     await this.writeFromStream(remoteDst, readStream);
     log.debug(`Successfully pushed file to '${remoteDst}'`);
   }
@@ -580,6 +566,8 @@ export class AfcService {
    */
   close(): void {
     log.debug('Closing AFC service connection');
+    this.demux?.stop();
+    this.demux = null;
     const socket = this.socket;
     this.socket = null;
     this.connectionError = null;
@@ -791,16 +779,48 @@ export class AfcService {
     }
   }
 
+  private _getDemux(): AfcPacketDemux {
+    if (!this.demux) {
+      this.demux = new AfcPacketDemux(
+        async () => await this._connect(),
+        (err) => this._markConnectionDead(err),
+      );
+    }
+    return this.demux;
+  }
+
+  private async _sendAndWait(
+    op: AfcOpcode,
+    headerPayload: Buffer = Buffer.alloc(0),
+    content: Buffer = Buffer.alloc(0),
+  ): Promise<{ status: AfcError; data: Buffer }> {
+    return await this._withAfcConnection(async () =>
+      this._getDemux().sendAndWait(op, headerPayload, content),
+    );
+  }
+
   private async _connect(): Promise<net.Socket> {
     this._assertConnectionAlive();
     if (this.socket && !this.socket.destroyed) {
       return this.socket;
     }
+
+    const previousSocket = this.socket;
+    if (previousSocket) {
+      if (!previousSocket.destroyed) {
+        cleanupServiceSocket(previousSocket);
+        previousSocket.destroy();
+      }
+      this.demux?.resetForNewSocket();
+    }
+    this.socket = null;
+
     const [host, rsdPort] = this.address;
 
     this.socket = await createRawServiceSocket(host, rsdPort, {
       timeoutMs: 30000,
     });
+    this._getDemux().ensureReaderStarted(this.socket);
     log.debug('RSD handshake complete; switching to raw AFC');
 
     return this.socket;
@@ -818,43 +838,6 @@ export class AfcService {
     return filePath;
   }
 
-  private async _lockFile(handle: bigint): Promise<void> {
-    await this._doOperation(
-      AfcOpcode.FILE_LOCK,
-      Buffer.concat([writeUInt64LE(handle), writeUInt64LE(AFC_LOCK_EX)]),
-    );
-  }
-
-  private async _unlockFile(handle: bigint): Promise<void> {
-    try {
-      await this._doOperation(
-        AfcOpcode.FILE_LOCK,
-        Buffer.concat([writeUInt64LE(handle), writeUInt64LE(AFC_LOCK_UN)]),
-      );
-    } catch (error) {
-      log.warn(`Failed to unlock file handle ${handle}:`, error);
-    }
-  }
-
-  private async _dispatch(
-    op: AfcOpcode,
-    payload: Buffer = Buffer.alloc(0),
-    thisLenOverride?: number,
-  ): Promise<void> {
-    return await this._withAfcConnection(async () => {
-      const sock = await this._connect();
-      await sendAfcPacket(sock, op, this.packetNum++, payload, thisLenOverride);
-    });
-  }
-
-  private async _receive(): Promise<{ status: AfcError; data: Buffer }> {
-    return await this._withAfcConnection(async () => {
-      const sock = await this._connect();
-      const res = await readAfcResponse(sock);
-      return { status: res.status, data: res.data };
-    });
-  }
-
   /**
    * Send a single-operation request and parse result.
    * Throws if status != SUCCESS.
@@ -863,10 +846,8 @@ export class AfcService {
   private async _doOperation(
     op: AfcOpcode,
     payload: Buffer = Buffer.alloc(0),
-    thisLenOverride?: number,
   ): Promise<Buffer> {
-    await this._dispatch(op, payload, thisLenOverride);
-    const { status, data } = await this._receive();
+    const { status, data } = await this._sendAndWait(op, payload);
 
     if (status !== AfcError.SUCCESS) {
       const errorName = AfcError[status] || 'UNKNOWN';