feat: implement webinspector shim service (#81)

Author: navin772

package.json

@@ -32,6 +32,7 @@
     "test:image-mounter": "mocha test/integration/mobile-image-mounter-test.ts --exit --timeout 1m",
     "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: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"

src/index.ts

@@ -18,6 +18,7 @@ export type {
   NotificationProxyService,
   MobileConfigService,
   SpringboardService,
+  WebInspectorService,
   SyslogService,
   SocketInfo,
   TunnelResult,
@@ -28,6 +29,7 @@ export type {
   NotificationProxyServiceWithConnection,
   MobileConfigServiceWithConnection,
   SpringboardServiceWithConnection,
+  WebInspectorServiceWithConnection,
 } from './lib/types.js';
 export {
   createUsbmux,

src/lib/types.ts

@@ -312,6 +312,121 @@ export interface MobileConfigServiceWithConnection {
   remoteXPC: RemoteXpcConnection;
 }
 
+/**
+ * Represents the WebInspectorService
+ */
+export interface WebInspectorService extends BaseService {
+  /**
+   * Send a message to the WebInspector service
+   * @param selector The RPC selector (e.g., '_rpc_reportIdentifier:')
+   * @param args The arguments dictionary for the message
+   * @returns Promise that resolves when the message is sent
+   */
+  sendMessage(selector: string, args?: PlistDictionary): Promise<void>;
+
+  /**
+   * Listen to messages from the WebInspector service using async generator
+   * @yields PlistMessage - Messages received from the WebInspector service
+   */
+  listenMessage(): AsyncGenerator<PlistMessage, void, unknown>;
+
+  /**
+   * Stop listening to messages
+   */
+  stopListening(): void;
+
+  /**
+   * Close the connection and clean up resources
+   */
+  close(): Promise<void>;
+
+  /**
+   * Get the connection ID being used for this service
+   * @returns The connection identifier
+   */
+  getConnectionId(): string;
+
+  /**
+   * Request application launch
+   * @param bundleId The bundle identifier of the application to launch
+   */
+  requestApplicationLaunch(bundleId: string): Promise<void>;
+
+  /**
+   * Get connected applications
+   */
+  getConnectedApplications(): Promise<void>;
+
+  /**
+   * Forward get listing for an application
+   * @param appId The application identifier
+   */
+  forwardGetListing(appId: string): Promise<void>;
+
+  /**
+   * Forward automation session request
+   * @param sessionId The session identifier
+   * @param appId The application identifier
+   * @param capabilities Optional session capabilities
+   */
+  forwardAutomationSessionRequest(
+    sessionId: string,
+    appId: string,
+    capabilities?: PlistDictionary,
+  ): Promise<void>;
+
+  /**
+   * Forward socket setup for inspector connection
+   * @param sessionId The session identifier
+   * @param appId The application identifier
+   * @param pageId The page identifier
+   * @param automaticallyPause Whether to automatically pause (defaults to true)
+   */
+  forwardSocketSetup(
+    sessionId: string,
+    appId: string,
+    pageId: number,
+    automaticallyPause?: boolean,
+  ): Promise<void>;
+
+  /**
+   * Forward socket data to a page
+   * @param sessionId The session identifier
+   * @param appId The application identifier
+   * @param pageId The page identifier
+   * @param data The data to send (will be JSON stringified)
+   */
+  forwardSocketData(
+    sessionId: string,
+    appId: string,
+    pageId: number,
+    data: any,
+  ): Promise<void>;
+
+  /**
+   * Forward indicate web view
+   * @param appId The application identifier
+   * @param pageId The page identifier
+   * @param enable Whether to enable indication
+   */
+  forwardIndicateWebView(
+    appId: string,
+    pageId: number,
+    enable: boolean,
+  ): Promise<void>;
+}
+
+/**
+ * Represents a WebInspectorService instance with its associated RemoteXPC connection
+ * This allows callers to properly manage the connection lifecycle
+ */
+export interface WebInspectorServiceWithConnection {
+  /** The WebInspectorService instance */
+  webInspectorService: WebInspectorService;
+  /** The RemoteXPC connection that can be used to close the connection */
+  remoteXPC: RemoteXpcConnection;
+}
+
 /**
  * Options for configuring syslog capture
  */

src/service-connection.ts

@@ -60,6 +60,15 @@ export class ServiceConnection extends BasePlistService {
     return this.sendAndReceive(requestObj, timeout);
   }
 
+  /**
+   * Sends a plist message without waiting for a response
+   * This is useful for fire-and-forget style communication
+   * @param message The message to send
+   */
+  sendPlist(message: PlistDictionary): void {
+    this.send(message);
+  }
+
   /**
    * Gets the underlying socket
    * @returns The socket used by this service

src/services.ts

@@ -10,13 +10,15 @@ import type {
   NotificationProxyServiceWithConnection,
   SpringboardServiceWithConnection,
   SyslogService as SyslogServiceType,
+  WebInspectorServiceWithConnection,
 } from './lib/types.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 { 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';
 
 const APPIUM_XCUITEST_DRIVER_NAME = 'appium-xcuitest-driver';
 const TUNNEL_REGISTRY_PORT = 'tunnelRegistryPort';
@@ -107,6 +109,22 @@ export async function startSyslogService(
   return new SyslogService([tunnelConnection.host, tunnelConnection.port]);
 }
 
+export async function startWebInspectorService(
+  udid: string,
+): Promise<WebInspectorServiceWithConnection> {
+  const { remoteXPC, tunnelConnection } = await createRemoteXPCConnection(udid);
+  const webInspectorService = remoteXPC.findService(
+    WebInspectorService.RSD_SERVICE_NAME,
+  );
+  return {
+    remoteXPC: remoteXPC as RemoteXpcConnection,
+    webInspectorService: new WebInspectorService([
+      tunnelConnection.host,
+      parseInt(webInspectorService.port, 10),
+    ]),
+  };
+}
+
 export async function createRemoteXPCConnection(udid: string) {
   const tunnelConnection = await getTunnelInformation(udid);
   const remoteXPC = await startService(

src/services/index.ts

@@ -6,12 +6,14 @@ import * as diagnostics from './ios/diagnostic-service/index.js';
 import * as mobileImageMounter from './ios/mobile-image-mounter/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';
 
 export {
   diagnostics,
   mobileImageMounter,
   syslog,
   tunnel,
+  webinspector,
   TunnelRegistryServer,
   startTunnelRegistryServer,
 };