appium-ios-remotexpc 0.8.0 → 0.10.0

package/build/src/services/ios/power-assertion/index.js

@@ -0,0 +1,64 @@
+import { logger } from '@appium/support';
+import { ServiceConnection } from '../../../service-connection.js';
+import { BaseService } from '../base-service.js';
+const log = logger.getLogger('PowerAssertionService');
+/**
+ * Power assertion types that can be used to prevent system sleep
+ */
+export var PowerAssertionType;
+(function (PowerAssertionType) {
+    PowerAssertionType["WIRELESS_SYNC"] = "AMDPowerAssertionTypeWirelessSync";
+    PowerAssertionType["PREVENT_USER_IDLE_SYSTEM_SLEEP"] = "PreventUserIdleSystemSleep";
+    PowerAssertionType["PREVENT_SYSTEM_SLEEP"] = "PreventSystemSleep";
+})(PowerAssertionType || (PowerAssertionType = {}));
+/**
+ * PowerAssertionService provides an API to create power assertions.
+ */
+class PowerAssertionService extends BaseService {
+    static RSD_SERVICE_NAME = 'com.apple.mobile.assertion_agent.shim.remote';
+    _conn = null;
+    /**
+     * Create a power assertion to prevent system sleep
+     * @param options Options for creating the power assertion
+     * @returns Promise that resolves when the assertion is created
+     */
+    async createPowerAssertion(options) {
+        if (!this._conn) {
+            this._conn = await this.connectToPowerAssertionService();
+        }
+        const request = this.buildCreateAssertionRequest(options);
+        await this._conn.sendPlistRequest(request);
+        log.info(`Power assertion created: type="${options.type}", name="${options.name}", timeout=${options.timeout}s`);
+    }
+    /**
+     * Close the connection to the power assertion service
+     */
+    async close() {
+        if (this._conn) {
+            await this._conn.close();
+            this._conn = null;
+            log.debug('Power assertion service connection closed');
+        }
+    }
+    async connectToPowerAssertionService() {
+        const service = {
+            serviceName: PowerAssertionService.RSD_SERVICE_NAME,
+            port: this.address[1].toString(),
+        };
+        log.debug(`Connecting to power assertion service at ${this.address[0]}:${this.address[1]}`);
+        return await this.startLockdownService(service);
+    }
+    buildCreateAssertionRequest(options) {
+        const request = {
+            CommandKey: 'CommandCreateAssertion',
+            AssertionTypeKey: options.type,
+            AssertionNameKey: options.name,
+            AssertionTimeoutKey: options.timeout,
+        };
+        if (options.details !== undefined) {
+            request.AssertionDetailKey = options.details;
+        }
+        return request;
+    }
+}
+export { PowerAssertionService };

package/build/src/services.d.ts

@@ -1,11 +1,18 @@
 import { RemoteXpcConnection } from './lib/remote-xpc/remote-xpc-connection.js';
-import type { DiagnosticsServiceWithConnection, MobileConfigServiceWithConnection, MobileImageMounterServiceWithConnection, NotificationProxyServiceWithConnection, SpringboardServiceWithConnection, SyslogService as SyslogServiceType, WebInspectorServiceWithConnection } from './lib/types.js';
+import type { DiagnosticsServiceWithConnection, MobileConfigServiceWithConnection, MobileImageMounterServiceWithConnection, NotificationProxyServiceWithConnection, PowerAssertionServiceWithConnection, SpringboardServiceWithConnection, SyslogService as SyslogServiceType, WebInspectorServiceWithConnection } from './lib/types.js';
+import AfcService from './services/ios/afc/index.js';
 export declare function startDiagnosticsService(udid: string): Promise<DiagnosticsServiceWithConnection>;
 export declare function startNotificationProxyService(udid: string): Promise<NotificationProxyServiceWithConnection>;
 export declare function startMobileConfigService(udid: string): Promise<MobileConfigServiceWithConnection>;
 export declare function startMobileImageMounterService(udid: string): Promise<MobileImageMounterServiceWithConnection>;
 export declare function startSpringboardService(udid: string): Promise<SpringboardServiceWithConnection>;
+export declare function startPowerAssertionService(udid: string): Promise<PowerAssertionServiceWithConnection>;
 export declare function startSyslogService(udid: string): Promise<SyslogServiceType>;
+/**
+ * Start AFC service over RemoteXPC shim.
+ * Resolves the AFC service port via RemoteXPC and returns a ready-to-use AfcService instance.
+ */
+export declare function startAfcService(udid: string): Promise<AfcService>;
 export declare function startWebInspectorService(udid: string): Promise<WebInspectorServiceWithConnection>;
 export declare function createRemoteXPCConnection(udid: string): Promise<{
     remoteXPC: RemoteXpcConnection;

package/build/src/services.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../../src/services.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAC;AAGhF,OAAO,KAAK,EACV,gCAAgC,EAChC,iCAAiC,EACjC,uCAAuC,EACvC,sCAAsC,EACtC,gCAAgC,EAChC,aAAa,IAAI,iBAAiB,EAClC,iCAAiC,EAClC,MAAM,gBAAgB,CAAC;AAYxB,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gCAAgC,CAAC,CAY3C;AAED,wBAAsB,6BAA6B,CACjD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,sCAAsC,CAAC,CAYjD;AAED,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,iCAAiC,CAAC,CAY5C;AACD,wBAAsB,8BAA8B,CAClD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,uCAAuC,CAAC,CAYlD;AAED,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gCAAgC,CAAC,CAY3C;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,iBAAiB,CAAC,CAG5B;AAED,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,iCAAiC,CAAC,CAY5C;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,MAAM;;;;;;;;GAO3D"}
+{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../../src/services.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAC;AAGhF,OAAO,KAAK,EACV,gCAAgC,EAChC,iCAAiC,EACjC,uCAAuC,EACvC,sCAAsC,EACtC,mCAAmC,EACnC,gCAAgC,EAChC,aAAa,IAAI,iBAAiB,EAClC,iCAAiC,EAClC,MAAM,gBAAgB,CAAC;AACxB,OAAO,UAAU,MAAM,6BAA6B,CAAC;AAarD,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gCAAgC,CAAC,CAY3C;AAED,wBAAsB,6BAA6B,CACjD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,sCAAsC,CAAC,CAYjD;AAED,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,iCAAiC,CAAC,CAY5C;AAED,wBAAsB,8BAA8B,CAClD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,uCAAuC,CAAC,CAYlD;AAED,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gCAAgC,CAAC,CAY3C;AAED,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,mCAAmC,CAAC,CAY9C;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,iBAAiB,CAAC,CAG5B;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAOvE;AAED,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,iCAAiC,CAAC,CAY5C;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,MAAM;;;;;;;;GAO3D"}

package/build/src/services.js

@@ -2,10 +2,12 @@ import { strongbox } from '@appium/strongbox';
 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 AfcService from './services/ios/afc/index.js';
 import DiagnosticsService from './services/ios/diagnostic-service/index.js';
 import { MobileConfigService } from './services/ios/mobile-config/index.js';
 import MobileImageMounterService from './services/ios/mobile-image-mounter/index.js';
 import { NotificationProxyService } from './services/ios/notification-proxy/index.js';
+import { PowerAssertionService } from './services/ios/power-assertion/index.js';
 import { SpringBoardService } from './services/ios/springboard-service/index.js';
 import SyslogService from './services/ios/syslog-service/index.js';
 import { WebInspectorService } from './services/ios/webinspector/index.js';
@@ -66,10 +68,33 @@ export async function startSpringboardService(udid) {
         ]),
     };
 }
+export async function startPowerAssertionService(udid) {
+    const { remoteXPC, tunnelConnection } = await createRemoteXPCConnection(udid);
+    const powerAssertionService = remoteXPC.findService(PowerAssertionService.RSD_SERVICE_NAME);
+    return {
+        remoteXPC: remoteXPC,
+        powerAssertionService: new PowerAssertionService([
+            tunnelConnection.host,
+            parseInt(powerAssertionService.port, 10),
+        ]),
+    };
+}
 export async function startSyslogService(udid) {
     const { tunnelConnection } = await createRemoteXPCConnection(udid);
     return new SyslogService([tunnelConnection.host, tunnelConnection.port]);
 }
+/**
+ * Start AFC service over RemoteXPC shim.
+ * Resolves the AFC service port via RemoteXPC and returns a ready-to-use AfcService instance.
+ */
+export async function startAfcService(udid) {
+    const { remoteXPC, tunnelConnection } = await createRemoteXPCConnection(udid);
+    const afcDescriptor = remoteXPC.findService(AfcService.RSD_SERVICE_NAME);
+    return new AfcService([
+        tunnelConnection.host,
+        parseInt(afcDescriptor.port, 10),
+    ]);
+}
 export async function startWebInspectorService(udid) {
     const { remoteXPC, tunnelConnection } = await createRemoteXPCConnection(udid);
     const webInspectorService = remoteXPC.findService(WebInspectorService.RSD_SERVICE_NAME);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-ios-remotexpc",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "main": "build/src/index.js",
   "types": "build/src/index.d.ts",
   "type": "module",
@@ -33,6 +33,8 @@
     "test:mobile-config": "mocha test/integration/mobile-config-test.ts --exit --timeout 1m",
     "test:springboard": "mocha test/integration/springboard-service-test.ts --exit --timeout 1m",
     "test:webinspector": "mocha test/integration/webinspector-test.ts --exit --timeout 1m",
+    "test:afc": "mocha test/integration/afc-test.ts --exit --timeout 1m",
+    "test:power-assertion": "mocha test/integration/power-assertion-test.ts --exit --timeout 1m",
     "test:unit": "mocha 'test/unit/**/*.ts' --exit --timeout 2m",
     "test:tunnel-creation": "sudo tsx scripts/test-tunnel-creation.ts",
     "test:tunnel-creation:lsof": "sudo tsx scripts/test-tunnel-creation.ts --keep-open"

package/src/index.ts

@@ -17,6 +17,8 @@ export type {
   MobileImageMounterService,
   NotificationProxyService,
   MobileConfigService,
+  PowerAssertionService,
+  PowerAssertionOptions,
   SpringboardService,
   WebInspectorService,
   SyslogService,
@@ -28,9 +30,11 @@ export type {
   MobileImageMounterServiceWithConnection,
   NotificationProxyServiceWithConnection,
   MobileConfigServiceWithConnection,
+  PowerAssertionServiceWithConnection,
   SpringboardServiceWithConnection,
   WebInspectorServiceWithConnection,
 } from './lib/types.js';
+export { PowerAssertionType } from './lib/types.js';
 export {
   createUsbmux,
   Services,

package/src/lib/types.ts

@@ -6,10 +6,15 @@ import { EventEmitter } from 'events';
 
 import type { ServiceConnection } from '../service-connection.js';
 import type { BaseService, Service } from '../services/ios/base-service.js';
+import type { PowerAssertionOptions } from '../services/ios/power-assertion/index.js';
+import { PowerAssertionType } from '../services/ios/power-assertion/index.js';
 import type { InterfaceOrientation } from '../services/ios/springboard-service/index.js';
 import type { RemoteXpcConnection } from './remote-xpc/remote-xpc-connection.js';
 import type { Device } from './usbmux/index.js';
 
+export type { PowerAssertionOptions };
+export { PowerAssertionType };
+
 /**
  * Represents a value that can be stored in a plist
  */
@@ -213,6 +218,24 @@ export interface NotificationProxyService extends BaseService {
   expectNotification(timeout?: number): Promise<PlistMessage>;
 }
 
+/**
+ * Represents the PowerAssertionService for preventing system sleep
+ */
+export interface PowerAssertionService extends BaseService {
+  /**
+   * Create a power assertion to prevent system sleep
+   * @param options Options for creating the power assertion
+   * @returns Promise that resolves when the assertion is created
+   */
+  createPowerAssertion(options: PowerAssertionOptions): Promise<void>;
+
+  /**
+   * Close the connection to the power assertion service
+   * @returns Promise that resolves when the connection is closed
+   */
+  close(): Promise<void>;
+}
+
 /**
  * Represents the static side of MobileConfigService
  */
@@ -312,6 +335,17 @@ export interface MobileConfigServiceWithConnection {
   remoteXPC: RemoteXpcConnection;
 }
 
+/**
+ * Represents a PowerAssertionService instance with its associated RemoteXPC connection
+ * This allows callers to properly manage the connection lifecycle
+ */
+export interface PowerAssertionServiceWithConnection {
+  /** The PowerAssertionService instance */
+  powerAssertionService: PowerAssertionService;
+  /** The RemoteXPC connection that can be used to close the connection */
+  remoteXPC: RemoteXpcConnection;
+}
+
 /**
  * Represents the WebInspectorService
  */

package/src/services/index.ts

@@ -2,8 +2,10 @@ import {
   TunnelRegistryServer,
   startTunnelRegistryServer,
 } from '../lib/tunnel/tunnel-registry-server.js';
+import * as afc from './ios/afc/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';
 import * as syslog from './ios/syslog-service/index.js';
 import * as tunnel from './ios/tunnel-service/index.js';
 import * as webinspector from './ios/webinspector/index.js';
@@ -11,8 +13,10 @@ import * as webinspector from './ios/webinspector/index.js';
 export {
   diagnostics,
   mobileImageMounter,
+  powerAssertion,
   syslog,
   tunnel,
+  afc,
   webinspector,
   TunnelRegistryServer,
   startTunnelRegistryServer,

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

@@ -0,0 +1,365 @@
+import net from 'node:net';
+
+import { createPlist } from '../../../lib/plist/plist-creator.js';
+import { parsePlist } from '../../../lib/plist/unified-plist-parser.js';
+import { AFCMAGIC, AFC_HEADER_SIZE, NULL_BYTE } from './constants.js';
+import { AfcError, AfcFopenMode, AfcOpcode } from './enums.js';
+
+export interface AfcHeader {
+  magic: Buffer;
+  entireLength: bigint;
+  thisLength: bigint;
+  packetNum: bigint;
+  operation: bigint;
+}
+
+export interface AfcResponse {
+  status: AfcError;
+  data: Buffer;
+  operation: AfcOpcode;
+  rawHeader: AfcHeader;
+}
+
+export function writeUInt64LE(value: bigint | number): Buffer {
+  const buf = Buffer.alloc(8);
+  buf.writeBigUInt64LE(BigInt(value), 0);
+  return buf;
+}
+
+export function readUInt64LE(buf: Buffer, offset = 0): bigint {
+  return buf.readBigUInt64LE(offset);
+}
+
+export function cstr(str: string): Buffer {
+  const s = Buffer.from(str, 'utf8');
+  return Buffer.concat([s, NULL_BYTE]);
+}
+
+export function encodeHeader(
+  op: AfcOpcode,
+  packetNum: bigint,
+  payloadLen: number,
+  thisLenOverride?: 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(packetNum).copy(header, 24);
+  // operation
+  writeUInt64LE(BigInt(op)).copy(header, 32);
+
+  return header;
+}
+
+/**
+ * Internal per-socket buffered reader to avoid re-emitting data and race conditions.
+ */
+type SocketWaiter = {
+  n: number;
+  resolve: (buf: Buffer) => void;
+  reject: (err: Error) => void;
+  timer?: NodeJS.Timeout;
+};
+type SocketState = {
+  buffer: Buffer;
+  waiters: SocketWaiter[];
+  onData: (chunk: Buffer) => void;
+  onError: (err: Error) => void;
+  onClose: () => void;
+};
+
+const SOCKET_STATES = new WeakMap<net.Socket, SocketState>();
+
+function cleanupSocketState(socket: net.Socket, error?: Error): void {
+  const state = SOCKET_STATES.get(socket);
+  if (!state) {
+    return;
+  }
+
+  // Remove all event listeners to prevent memory leaks
+  socket.removeListener('data', state.onData);
+  socket.removeListener('error', state.onError);
+  socket.removeListener('close', state.onClose);
+  socket.removeListener('end', state.onClose);
+
+  // Reject any pending waiters
+  const err = error || new Error('Socket closed');
+  while (state.waiters.length) {
+    const w = state.waiters.shift()!;
+    if (w.timer) {
+      clearTimeout(w.timer);
+    }
+    w.reject(err);
+  }
+
+  // Remove from WeakMap
+  SOCKET_STATES.delete(socket);
+}
+
+function ensureSocketState(socket: net.Socket): SocketState {
+  let state = SOCKET_STATES.get(socket);
+  if (state) {
+    return state;
+  }
+
+  state = {
+    buffer: Buffer.alloc(0),
+    waiters: [],
+    onData: (chunk: Buffer) => {
+      const st = SOCKET_STATES.get(socket);
+      if (!st) {
+        return;
+      }
+      st.buffer = Buffer.concat([st.buffer, chunk]);
+
+      while (st.waiters.length && st.buffer.length >= st.waiters[0].n) {
+        const w = st.waiters.shift()!;
+        const out = st.buffer.subarray(0, w.n);
+        st.buffer = st.buffer.subarray(w.n);
+        if (w.timer) {
+          clearTimeout(w.timer);
+        }
+        w.resolve(out);
+      }
+    },
+    onError: (err: Error) => {
+      cleanupSocketState(socket, err);
+    },
+    onClose: () => {
+      cleanupSocketState(socket);
+    },
+  };
+
+  socket.on('data', state.onData);
+  socket.once('error', state.onError);
+  socket.once('close', state.onClose);
+  socket.once('end', state.onClose);
+  SOCKET_STATES.set(socket, state);
+  return state;
+}
+
+export async function readExact(
+  socket: net.Socket,
+  n: number,
+  timeoutMs = 30000,
+): Promise<Buffer> {
+  const state = ensureSocketState(socket);
+
+  if (state.buffer.length >= n) {
+    const out = state.buffer.subarray(0, n);
+    state.buffer = state.buffer.subarray(n);
+    return out;
+  }
+
+  return await new Promise<Buffer>((resolve, reject) => {
+    const waiter: SocketWaiter = { n, resolve, reject };
+    state.waiters.push(waiter);
+    waiter.timer = setTimeout(() => {
+      const idx = state.waiters.indexOf(waiter);
+      if (idx >= 0) {
+        state.waiters.splice(idx, 1);
+        reject(new Error(`readExact timeout after ${timeoutMs}ms`));
+      }
+    }, timeoutMs);
+  });
+}
+
+export async function readAfcHeader(socket: net.Socket): Promise<AfcHeader> {
+  const buf = await readExact(socket, AFC_HEADER_SIZE);
+  const magic = buf.subarray(0, 8);
+  if (!magic.equals(AFCMAGIC)) {
+    throw new Error(`Invalid AFC magic: ${magic.toString('hex')}`);
+  }
+  const entireLength = readUInt64LE(buf, 8);
+  const thisLength = readUInt64LE(buf, 16);
+  const packetNum = readUInt64LE(buf, 24);
+  const operation = readUInt64LE(buf, 32);
+  return {
+    magic,
+    entireLength,
+    thisLength,
+    packetNum,
+    operation,
+  };
+}
+
+export async function readAfcResponse(
+  socket: net.Socket,
+): Promise<AfcResponse> {
+  const header = await readAfcHeader(socket);
+  const payloadLen = Number(header.entireLength - BigInt(AFC_HEADER_SIZE));
+  const payload =
+    payloadLen > 0 ? await readExact(socket, payloadLen) : Buffer.alloc(0);
+  const op = Number(header.operation) as AfcOpcode;
+
+  if (op === AfcOpcode.STATUS) {
+    const status = Number(readUInt64LE(payload.subarray(0, 8))) as AfcError;
+    return { status, data: Buffer.alloc(0), operation: op, rawHeader: header };
+  }
+
+  return {
+    status: AfcError.SUCCESS,
+    data: payload,
+    operation: op,
+    rawHeader: header,
+  };
+}
+
+export async function sendAfcPacket(
+  socket: net.Socket,
+  op: AfcOpcode,
+  packetNum: bigint,
+  payload: Buffer = Buffer.alloc(0),
+  thisLenOverride?: number,
+): 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();
+      }
+    });
+  });
+}
+
+export function parseCStringArray(buf: Buffer): string[] {
+  const parts: string[] = [];
+  let start = 0;
+  for (let i = 0; i < buf.length; i++) {
+    if (buf[i] === 0x00) {
+      const slice = buf.subarray(start, i);
+      parts.push(slice.toString('utf8'));
+      start = i + 1;
+    }
+  }
+  if (start < buf.length) {
+    parts.push(buf.subarray(start).toString('utf8'));
+  }
+  while (parts.length && parts[parts.length - 1] === '') {
+    parts.pop();
+  }
+  return parts;
+}
+
+export function parseKeyValueNullList(buf: Buffer): Record<string, string> {
+  const arr = parseCStringArray(buf);
+  if (arr.length % 2 !== 0) {
+    throw new Error('Invalid key/value AFC list (odd number of entries)');
+  }
+  return Object.fromEntries(
+    Array.from({ length: arr.length / 2 }, (_, i) => [
+      arr[i * 2],
+      arr[i * 2 + 1],
+    ]),
+  );
+}
+
+export function buildFopenPayload(mode: AfcFopenMode, path: string): Buffer {
+  return Buffer.concat([writeUInt64LE(mode), cstr(path)]);
+}
+
+export function buildReadPayload(
+  handle: bigint | number,
+  size: bigint | number,
+): Buffer {
+  return Buffer.concat([writeUInt64LE(handle), writeUInt64LE(BigInt(size))]);
+}
+
+export function buildClosePayload(handle: bigint | number): Buffer {
+  return writeUInt64LE(handle);
+}
+
+export function buildRemovePayload(path: string): Buffer {
+  return cstr(path);
+}
+
+export function buildMkdirPayload(path: string): Buffer {
+  return cstr(path);
+}
+
+export function buildStatPayload(path: string): Buffer {
+  return cstr(path);
+}
+
+export function buildRenamePayload(src: string, dst: string): Buffer {
+  return Buffer.concat([cstr(src), cstr(dst)]);
+}
+
+export function buildLinkPayload(
+  type: number,
+  target: string,
+  source: string,
+): Buffer {
+  return Buffer.concat([writeUInt64LE(type), cstr(target), cstr(source)]);
+}
+
+/**
+ * Receive a single length-prefixed plist from the socket
+ */
+export async function recvOnePlist(socket: net.Socket): Promise<any> {
+  const lenBuf = await readExact(socket, 4);
+  const respLen = lenBuf.readUInt32BE(0);
+  const respBody = await readExact(socket, respLen);
+  return parsePlist(respBody);
+}
+
+export async function rsdHandshakeForRawService(
+  socket: net.Socket,
+): Promise<void> {
+  const request = {
+    Label: 'appium-internal',
+    ProtocolVersion: '2',
+    Request: 'RSDCheckin',
+  };
+  const xml = createPlist(request);
+  const body = Buffer.from(xml, 'utf8');
+  const header = Buffer.alloc(4);
+  header.writeUInt32BE(body.length, 0);
+  await new Promise<void>((resolve, reject) => {
+    socket.write(Buffer.concat([header, body]), (err) =>
+      err ? reject(err) : resolve(),
+    );
+  });
+
+  const first = await recvOnePlist(socket);
+  if (!first || first.Request !== 'RSDCheckin') {
+    throw new Error(`Invalid RSDCheckin response: ${JSON.stringify(first)}`);
+  }
+
+  const second = await recvOnePlist(socket);
+  if (!second || second.Request !== 'StartService') {
+    throw new Error(`Invalid StartService response: ${JSON.stringify(second)}`);
+  }
+}
+
+export function nextReadChunkSize(left: bigint | number): number {
+  const leftNum = typeof left === 'bigint' ? Number(left) : left;
+  return leftNum;
+}
+
+/**
+ * Convert nanoseconds to milliseconds for Date construction
+ * @param nanoseconds - Time value in nanoseconds as a string
+ * @returns Time value in milliseconds
+ */
+export function nanosecondsToMilliseconds(nanoseconds: string): number {
+  return Number(BigInt(nanoseconds) / 1000000n);
+}

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

@@ -0,0 +1,29 @@
+import { AfcFopenMode } from './enums.js';
+
+/**
+ * AFC protocol constants
+ */
+
+// 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
+
+// Mapping of textual fopen modes to AFC modes
+export const AFC_FOPEN_TEXTUAL_MODES: Record<string, AfcFopenMode> = {
+  r: AfcFopenMode.RDONLY,
+  'r+': AfcFopenMode.RW,
+  w: AfcFopenMode.WRONLY,
+  'w+': AfcFopenMode.WR,
+  a: AfcFopenMode.APPEND,
+  'a+': AfcFopenMode.RDAPPEND,
+};
+
+// Header size: magic (8) + entire_length (8) + this_length (8) + packet_num (8) + operation (8)
+export const AFC_HEADER_SIZE = 40;
+
+// Override for WRITE packets' this_length
+export const AFC_WRITE_THIS_LENGTH = 48;
+
+export const NULL_BYTE = Buffer.from([0]);