appium-ios-remotexpc 5.2.2 → 5.3.0

package/src/services/ios/dvt/instruments/device-info.ts

@@ -189,6 +189,52 @@ export class DeviceInfo extends BaseInstrument {
     );
   }
 
+  /**
+   * Get the list of process attribute names supported by the sysmontap
+   * instrument. The returned order matches the per-process value tuples
+   * emitted by the sysmontap service, so it is used to label those values.
+   * @returns Array of process attribute names (e.g. 'pid', 'name', 'cpuUsage')
+   */
+  async sysmonProcessAttributes(): Promise<string[]> {
+    return this.expectStringArrayResult(
+      await this.requestInformation('sysmonProcessAttributes'),
+      'sysmonProcessAttributes',
+    );
+  }
+
+  /**
+   * Get the list of system attribute names supported by the sysmontap
+   * instrument. The returned order matches the system value tuple emitted by
+   * the sysmontap service, so it is used to label those values.
+   * @returns Array of system attribute names (e.g. 'vmPageSize', 'physMemSize')
+   */
+  async sysmonSystemAttributes(): Promise<string[]> {
+    return this.expectStringArrayResult(
+      await this.requestInformation('sysmonSystemAttributes'),
+      'sysmonSystemAttributes',
+    );
+  }
+
+  private expectStringArrayResult(result: unknown, context: string): string[] {
+    if (
+      Array.isArray(result) &&
+      result.every((item) => typeof item === 'string')
+    ) {
+      return result;
+    }
+
+    if (hasNSErrorIndicators(result)) {
+      const description =
+        (result as { NSUserInfo?: { NSLocalizedDescription?: string } })
+          .NSUserInfo?.NSLocalizedDescription ?? JSON.stringify(result);
+      throw new Error(`${context}: ${description}`);
+    }
+
+    throw new Error(
+      `${context}: expected string array, got ${typeof result} (${JSON.stringify(result)})`,
+    );
+  }
+
   private expectStringResult(result: unknown, context: string): string {
     if (typeof result === 'string') {
       return result;

package/src/services/ios/dvt/instruments/sysmontap.ts

@@ -0,0 +1,308 @@
+import { util } from '@appium/support';
+
+import { getLogger } from '../../../../lib/logger.js';
+import type {
+  SysmonProcessInfo,
+  SysmonSample,
+  SysmonSystemInfo,
+  SysmontapOptions,
+} from '../../../../lib/types.js';
+import { MessageAux } from '../dtx-message.js';
+import { BaseInstrument } from './base-instrument.js';
+import { DeviceInfo } from './device-info.js';
+
+const log = getLogger('Sysmontap');
+
+/**
+ * Sysmontap provides real-time sampling of per-process and system resource
+ * usage (CPU, memory, disk, etc.) on iOS devices.
+ *
+ * The instrument is configured with a set of process and system attribute
+ * names (queried from the device via {@link DeviceInfo} unless overridden) and
+ * a sampling interval. Once started, the device streams samples; each sample
+ * carries the raw value tuples that are mapped back to the attribute names.
+ *
+ * @example
+ * ```typescript
+ * const { sysmontap, dvtService } = await Services.startDVTService(udid);
+ * try {
+ *   await sysmontap.configure({ intervalMs: 1000 });
+ *   for await (const processes of sysmontap.iterProcesses()) {
+ *     console.log(processes.length, 'processes');
+ *     break;
+ *   }
+ * } finally {
+ *   await sysmontap.stop();
+ *   await dvtService.close();
+ * }
+ * ```
+ */
+export class Sysmontap extends BaseInstrument {
+  static readonly IDENTIFIER =
+    'com.apple.instruments.server.services.sysmontap';
+
+  /** Default sampling interval in milliseconds. */
+  static readonly DEFAULT_INTERVAL_MS = 500;
+
+  /** Minimum permitted sampling interval in milliseconds. */
+  static readonly MINIMUM_INTERVAL_MS = 1;
+
+  private processAttributes: string[] = [];
+  private systemAttributes: string[] = [];
+  private builtConfig: Record<string, unknown> | null = null;
+  private started = false;
+  private stopRequested = false;
+  private receiveAbortController: AbortController | null = null;
+
+  /**
+   * The process attribute names currently in effect. Empty until
+   * {@link configure} (or {@link start}) has run.
+   */
+  getProcessAttributes(): string[] {
+    return [...this.processAttributes];
+  }
+
+  /**
+   * The system attribute names currently in effect. Empty until
+   * {@link configure} (or {@link start}) has run.
+   */
+  getSystemAttributes(): string[] {
+    return [...this.systemAttributes];
+  }
+
+  /**
+   * Resolve the sampling attributes (querying the device when not overridden)
+   * and build the sampling configuration. This does not start sampling; the
+   * configuration is (re)applied to the device by {@link start}. Safe to call
+   * multiple times; the latest configuration wins.
+   * @param options Optional sampling configuration
+   */
+  async configure(options: SysmontapOptions = {}): Promise<void> {
+    if (options.processAttributes && options.systemAttributes) {
+      this.processAttributes = options.processAttributes;
+      this.systemAttributes = options.systemAttributes;
+    } else {
+      const deviceInfo = new DeviceInfo(this.dvt);
+      this.processAttributes =
+        options.processAttributes ??
+        (await deviceInfo.sysmonProcessAttributes());
+      this.systemAttributes =
+        options.systemAttributes ?? (await deviceInfo.sysmonSystemAttributes());
+    }
+
+    const intervalMs = Math.max(
+      options.intervalMs ?? Sysmontap.DEFAULT_INTERVAL_MS,
+      Sysmontap.MINIMUM_INTERVAL_MS,
+    );
+
+    this.builtConfig = {
+      ur: Sysmontap.MINIMUM_INTERVAL_MS, // Output frequency (ms)
+      bm: 0,
+      procAttrs: this.processAttributes,
+      sysAttrs: this.systemAttributes,
+      cpuUsage: true,
+      physFootprint: true, // Include physical memory footprint
+      sampleInterval: intervalMs * 1_000_000, // Sample interval in nanoseconds
+    };
+
+    log.debug(
+      `sysmontap configured: interval=${intervalMs}ms, ` +
+        `${util.pluralize('process attribute', this.processAttributes.length, true)}, ` +
+        `${util.pluralize('system attribute', this.systemAttributes.length, true)}`,
+    );
+  }
+
+  /**
+   * Begin sampling. Resolves the configuration first (with defaults) when
+   * {@link configure} has not been called.
+   *
+   * A sysmontap instance supports a single sampling session per DVT
+   * connection: once a stream has been {@link stop}ped, the device does not
+   * resume it on the same connection. To sample again, start a new DVT
+   * connection (e.g. via `Services.startDVTService`).
+   */
+  async start(): Promise<void> {
+    if (this.started) {
+      log.debug('sysmontap already sampling; start() is a no-op');
+      return;
+    }
+    if (!this.builtConfig) {
+      await this.configure();
+    }
+    await this.initialize();
+    const channel = this.requireChannel();
+
+    // setConfig must precede start so the device knows which attributes to
+    // sample.
+    const args = new MessageAux().appendObj(this.builtConfig);
+    await channel.call('setConfig_')(args, false);
+
+    this.stopRequested = false;
+    await channel.call('start')(undefined, false);
+    this.started = true;
+    log.debug('sysmontap sampling started');
+  }
+
+  /**
+   * Stop sampling and unblock any in-flight iterator.
+   */
+  async stop(): Promise<void> {
+    this.stopRequested = true;
+    this.receiveAbortController?.abort();
+
+    if (!this.started) {
+      return;
+    }
+    this.started = false;
+
+    if (this.channel) {
+      try {
+        await this.requireChannel().call('stop')(undefined, false);
+      } catch (error) {
+        log.debug(
+          'sysmontap stop() could not notify the device:',
+          error instanceof Error ? error.message : error,
+        );
+      }
+    }
+    log.debug('sysmontap sampling stopped');
+  }
+
+  /**
+   * Async iterator that yields raw sysmontap samples as they arrive. The
+   * device interleaves two kinds of samples: system samples (with `System`,
+   * `SystemAttributes`, CPU usage) and process samples (with `Processes`).
+   * Internal control/heartbeat frames are filtered out.
+   *
+   * Sampling starts automatically on first iteration and stops when iteration
+   * terminates (via break or return), when {@link stop} is called, or when the
+   * underlying DVT connection is closed. The iterator never throws on a read
+   * failure: it ends the stream instead, so a consumer's `for await` does not
+   * have to guard against connection teardown.
+   */
+  async *messages(): AsyncGenerator<SysmonSample, void, unknown> {
+    await this.start();
+
+    try {
+      while (!this.stopRequested) {
+        const channel = this.requireChannel();
+        const receiveAbortController = new AbortController();
+        this.receiveAbortController = receiveAbortController;
+
+        let plist: unknown;
+        try {
+          plist = await channel.receivePlist(receiveAbortController.signal);
+        } catch (err) {
+          // End the stream rather than throwing out of the async iterator
+          if (
+            !this.stopRequested &&
+            !this.isAbortError(err) &&
+            !this.isConnectionClosedError(err)
+          ) {
+            log.warn('sysmontap stream ended due to an unexpected error:', err);
+          }
+          break;
+        } finally {
+          if (this.receiveAbortController === receiveAbortController) {
+            this.receiveAbortController = null;
+          }
+        }
+
+        // Data samples arrive as an array of one or more sample dictionaries.
+        // Other payloads (e.g. `{ DTTapMessagePlist: { k: 8, heart } }` control
+        // and heartbeat frames, or a null parse failure) are not samples and
+        // are skipped.
+        if (!Array.isArray(plist)) {
+          continue;
+        }
+
+        for (const row of plist) {
+          if (row && typeof row === 'object') {
+            yield row as SysmonSample;
+          }
+        }
+      }
+    } finally {
+      await this.stop();
+    }
+  }
+
+  /**
+   * Async iterator that yields labelled per-process snapshots. Each yielded
+   * value is the list of processes contained in a single sample, with the raw
+   * per-process value tuples mapped to objects keyed by the configured process
+   * attribute names.
+   *
+   * Note: the first emitted snapshot typically contains uninitialised
+   * `cpuUsage` values and is commonly skipped by consumers.
+   */
+  async *iterProcesses(): AsyncGenerator<SysmonProcessInfo[], void, unknown> {
+    for await (const sample of this.messages()) {
+      const processes = sample.Processes;
+      if (!processes || typeof processes !== 'object') {
+        continue;
+      }
+
+      const entries: SysmonProcessInfo[] = [];
+      for (const values of Object.values(processes)) {
+        if (Array.isArray(values)) {
+          entries.push(this.zipAttributes(this.processAttributes, values));
+        }
+      }
+      yield entries;
+    }
+  }
+
+  /**
+   * Async iterator that yields labelled system snapshots. Each yielded value is
+   * the device-wide metrics from a single system sample, with the raw value
+   * tuple mapped to an object keyed by the configured system attribute names.
+   *
+   * This is the system-sample counterpart to {@link iterProcesses}.
+   */
+  async *iterSystem(): AsyncGenerator<SysmonSystemInfo, void, unknown> {
+    for await (const sample of this.messages()) {
+      const system = sample.System;
+      if (!Array.isArray(system)) {
+        continue;
+      }
+      yield this.zipAttributes(this.systemAttributes, system);
+    }
+  }
+
+  /**
+   * Zip an ordered list of attribute names with a raw value tuple.
+   */
+  private zipAttributes(
+    attributes: string[],
+    values: unknown[],
+  ): Record<string, unknown> {
+    const result: Record<string, unknown> = {};
+    for (let i = 0; i < attributes.length; i++) {
+      result[attributes[i]] = values[i];
+    }
+    return result;
+  }
+
+  private isAbortError(err: unknown): boolean {
+    return (
+      err instanceof DOMException ||
+      (err instanceof Error && err.name === 'AbortError')
+    );
+  }
+
+  /**
+   * Whether an error indicates the underlying socket/DVT connection was closed,
+   * destroyed, or otherwise torn down (an expected way for the stream to end).
+   * Closing the DVT connection clears its per-channel fragmenters, so a pending
+   * read can surface as "No fragmenter for channel" or "Not connected".
+   */
+  private isConnectionClosedError(err: unknown): boolean {
+    return (
+      err instanceof Error &&
+      /socket|destroyed|closed|not initialized|not available|not connected|no fragmenter|EPIPE|ECONNRESET/i.test(
+        err.message,
+      )
+    );
+  }
+}

package/src/services/ios/dvt/nskeyedarchiver-decoder.ts

@@ -236,8 +236,15 @@ export class NSKeyedArchiverDecoder {
       const key = this.decodeObject(keyRefs[i], visited, depth + 1);
       const value = this.decodeObject(valueRefs[i], visited, depth + 1);
 
-      if (typeof key === 'string') {
-        result[key] = value;
+      // Object keys are strings in JS. Coerce primitive keys (e.g. the integer
+      // pids used by the sysmontap `Processes` map) so they are not dropped.
+      if (
+        typeof key === 'string' ||
+        typeof key === 'number' ||
+        typeof key === 'bigint' ||
+        typeof key === 'boolean'
+      ) {
+        result[String(key)] = value;
       }
     }
 

package/src/services.ts

@@ -22,6 +22,7 @@ import { NetworkMonitor } from './services/ios/dvt/instruments/network-monitor.j
 import { Notifications } from './services/ios/dvt/instruments/notifications.js';
 import { ProcessControl } from './services/ios/dvt/instruments/process-control.js';
 import { Screenshot } from './services/ios/dvt/instruments/screenshot.js';
+import { Sysmontap } from './services/ios/dvt/instruments/sysmontap.js';
 import { HidIndigoService } from './services/ios/hid-indigo/index.js';
 import { HouseArrestService } from './services/ios/house-arrest/index.js';
 import { InstallationProxyService } from './services/ios/installation-proxy/index.js';
@@ -245,6 +246,7 @@ export async function startDVTService(udid: string): Promise<DVTInstruments> {
     notification: new Notifications(dvtService),
     networkMonitor: new NetworkMonitor(dvtService),
     processControl: new ProcessControl(dvtService),
+    sysmontap: new Sysmontap(dvtService),
   };
 }