fix: add new command to get proxy state (#84)

- Add new entry in executeMethodMap (plugin.ts)
- Implement new function getProxyState (plugin.ts) : it returns a json object containing the proxy server state + the current proxy conf on the adb device
- Add new function getAdbReverseTunnels (adb.ts) that allow to list active reverse tunnels
- Update readme

Author: vdanti

docs/commands.md

@@ -398,3 +398,36 @@ Below code shows how to add the mock and get the id
                         new HashMap() {{put("config", config); }});
 
 ```
+
+### interceptor: getProxyState
+
+Returns the current health and configuration state of both the interceptor proxy and the ADB device under test. This is useful for diagnostic purposes to verify if the proxy is running correctly and if the device is properly connected via ADB reverse tunnels. It can be used to monitor proxy state on client side.
+
+#### Example:
+
+```javascript
+  const state = await driver.execute("interceptor: getProxyState");
+  console.log(JSON.parse(state));
+```
+
+#### Returns:
+
+getProxyState will return a JSON string containing details about the proxy server and the ADB device status.
+  
+```json
+{
+  "proxyServerStatus": {
+    "isRegistered": true, // Indicates if the proxy exists in the internal cache
+    "isStarted": true, // Indicates if the proxy server is currently running
+    "deviceUDID": "R5CY127XBWB",
+    "sessionId": "8e902882-ce19-44f6-90ca-975b167f94ca",
+    "certificatePath": "/var/folders/.../8e902882-ce19-44f6-90ca-975b167f94ca",
+    "port": 59046,
+    "ip": "localhost"
+  },
+  "adbDeviceStatus": {
+    "udid": "R5CY127XBWB",
+    "activeAdbReverseTunnels": "UsbFfs tcp:56982 tcp:56982" // Current active reverse tunnels on the device
+  }
+}
+```

src/plugin.ts

@@ -4,7 +4,7 @@ import { Application } from 'express';
 import { CliArg, ISessionCapability, MockConfig, RecordConfig, RequestInfo, ReplayConfig, SniffConfig } from './types';
 import { DefaultPluginArgs, IPluginArgs } from './interfaces';
 import _ from 'lodash';
-import { configureWifiProxy, isRealDevice, getGlobalProxyValue } from './utils/adb';
+import { configureWifiProxy, isRealDevice, getGlobalProxyValue, getAdbReverseTunnels } from './utils/adb';
 import { cleanUpProxyServer, sanitizeMockConfig, setupProxyServer } from './utils/proxy';
 import proxyCache from './proxy-cache';
 import logger from './logger';
@@ -67,6 +67,10 @@ export class AppiumInterceptorPlugin extends BasePlugin {
       command: 'stopReplaying',
       params: { optional: ['id'] },
     },
+
+    'interceptor: getProxyState': {
+      command: 'getProxyState',
+    },
   };
 
   constructor(name: string, cliArgs: CliArg) {
@@ -251,6 +255,39 @@ export class AppiumInterceptorPlugin extends BasePlugin {
     proxy.getRecordingManager().stopReplay(id);
   }
 
+  /**
+   * Aggregates the current health and configuration state of the proxy system.
+   * * This method performs a dual-layer diagnostic:
+   * 1. Host Layer: Checks if the proxy instance exists in the cache and verifies its execution status.
+   * 2. Transport Layer: Queries the physical device via ADB to list active reverse tunnels.
+   * * It is primarily used to determine if a connectivity issue originates from the
+   * Node.js server (Host) or the ADB bridge/USB connection (Device).
+   *
+   * @param next - The next middleware or handler in the execution chain (if applicable).
+   * @param driver - The Appium driver instance containing the ADB controller and session ID.
+   * @returns A Promise resolving to a JSON string representing the combined state of the proxy and ADB tunnels.
+   */
+  async getProxyState(next: any, driver: any): Promise<string> {
+    const adb = driver.adb;
+    const udid = adb.curDeviceId;
+    const adbReverseTunnels = await getAdbReverseTunnels(adb, udid);
+    const proxy = proxyCache.get(driver.sessionId);
+    const proxyServerStatus = {
+      isRegistered: !!proxy,
+      isStarted: proxy ? proxy.isStarted() : false,
+      ...proxy?.options,
+    };
+    const adbDeviceStatus = {
+      udid: udid,
+      activeAdbReverseTunnels: adbReverseTunnels,
+    };
+    const proxyState = {
+      proxyServerStatus: proxyServerStatus,
+      adbDeviceStatus: adbDeviceStatus,
+    };
+    return JSON.stringify(proxyState);
+  }
+
   async execute(next: any, driver: any, script: any, args: any) {
     return await this.executeMethod(next, driver, script, args);
   }

src/utils/adb.ts

@@ -83,6 +83,30 @@ export async function getGlobalProxyValue(
   }  
 }
 
+/**
+ * Retrieves the list of all active ADB reverse port forwardings for a specific device.
+ * * This method executes 'adb reverse --list' to identify which device ports are 
+ * currently bridged to the host machine. It is essential for diagnosing 
+ * connectivity between the mobile device and local proxy servers.
+ *
+ * @param adb - The ADB instance provided by the Appium driver.
+ * @param udid - The Unique Device Identifier (UDID) of the target Android device.
+ * @returns A Promise resolving to the raw string output of the 'adb reverse --list' command.
+ * @throws {Error} If the command fails to execute or the device is unreachable.
+ */
+export async function getAdbReverseTunnels(
+  adb: ADBInstance,
+  udid: UDID
+): Promise<string> {
+  try {
+    return await adbExecWithDevice(adb, udid, [
+      'reverse',
+      '--list',
+    ]);
+  } catch(error: any) {
+    throw new Error(`Failed to list active reverse tunnels for device ${udid}: ${error.message}`);
+  }
+}
 
 export async function openUrl(adb: ADBInstance, udid: UDID, url: string) {
   await adbExecWithDevice(adb, udid, [