appium-ios-remotexpc 5.19.0 → 5.19.2

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [5.19.2](https://github.com/appium/appium-ios-remotexpc/compare/v5.19.1...v5.19.2) (2026-09-16)
+
+### Bug Fixes
+
+* **scripts:** fall back to a free registry port when starting the Apple TV tunnel ([#327](https://github.com/appium/appium-ios-remotexpc/issues/327)) ([84dccad](https://github.com/appium/appium-ios-remotexpc/commit/84dccad88e3f52effc54f62130f33ab400f146de))
+
+## [5.19.1](https://github.com/appium/appium-ios-remotexpc/compare/v5.19.0...v5.19.1) (2026-09-15)
+
+### Bug Fixes
+
+* **test:** stop registry server spec from overwriting the persisted tunnel port ([#326](https://github.com/appium/appium-ios-remotexpc/issues/326)) ([0b62a88](https://github.com/appium/appium-ios-remotexpc/commit/0b62a8889dfd1f9ac7c09fc7d5eeb7c3935a6d8e))
+
 ## [5.19.0](https://github.com/appium/appium-ios-remotexpc/compare/v5.18.9...v5.19.0) (2026-09-08)
 
 ### Features

package/README.md

@@ -102,7 +102,7 @@ The `appium-ios-tuntap (previously tuntap-bridge)` module plays a crucial role i
 5. **Service Access**: Enables access to iOS shim services through the tunnel
 
 **Technical Details:**
-- **Platform Support**: Works on both macOS and Linux
+- **Platform Support**: Works on macOS, Linux, and Windows (Windows uses WinTun and requires an elevated shell)
 - **IPv6 Support**: Creates IPv6 tunnels for modern iOS communication
 - **Packet Handling**: Manages packet routing between virtual interface and device
 - **Automatic Cleanup**: Properly closes tunnels and cleans up interfaces
@@ -118,7 +118,7 @@ The `appium-ios-tuntap (previously tuntap-bridge)` module plays a crucial role i
 ```typescript
 import {
   createLockdownServiceByUDID,
-  rsdSessionLockKey,
+  discoverServices,
   startCoreDeviceProxyTcp,
   TunnelManager,
 } from 'appium-ios-remotexpc';
@@ -137,21 +137,13 @@ const { socket, cert, key } = await startCoreDeviceProxyTcp(
 const tunnel = await TunnelManager.getTunnel(socket, { cert, key });
 console.log(`Tunnel created at ${tunnel.Address} with RSD port ${tunnel.RsdPort}`);
 
-// Discover RSD services (serialized per tunnel; closed before return)
-await TunnelManager.runSerializedRsdSession(
-  rsdSessionLockKey(tunnel.Address, tunnel.RsdPort),
-  async () => {
-    const remoteXPC = await TunnelManager.connectRemoteXPCUnlocked(
-      tunnel.Address,
-      tunnel.RsdPort,
-    );
-    try {
-      console.log(remoteXPC.getServices());
-    } finally {
-      await remoteXPC.close();
-    }
-  },
-);
+// Discover RSD services (concurrent calls for the same device are coalesced;
+// the RSD connection is closed before the promise resolves)
+if (!tunnel.RsdPort) {
+  throw new Error('Tunnel did not report an RSD port');
+}
+const services = await discoverServices(udid, tunnel.Address, tunnel.RsdPort);
+console.log(services);
 ```
 
 ### iPhone / iPad over WiFi (usbmuxd “network” devices)
@@ -166,7 +158,7 @@ There is no separate “WiFi API” in this library: call `createUsbmux()` → `
 2. Allow the device to connect over WiFi (e.g. in Finder under the device, enable **Show this [device] when on WiFi**, or use Xcode **Devices and Simulators** with the equivalent option so lockdown can reach the device without USB).
 3. Confirm **usbmuxd** reports the device with **`ConnectionType: Network`**—for example by logging the result of `listDevices()` from this library, or by checking another usbmuxd client’s device list while the device is on the same network and not on USB.
 
-For an end-to-end tunnel smoke test with the tunnel registry HTTP API, use `npm run tunnel-creation` or `npm run test:tunnel-creation` (see `scripts/test-tunnel-creation.ts`), usually with **sudo** for TUN/TAP.
+For an end-to-end tunnel smoke test with the tunnel registry HTTP API, use `npm run tunnel-creation` (see `scripts/tunnel-creation.mjs`), usually with **sudo** for TUN/TAP.
 
 ### Apple TV / tvOS over WiFi
 
@@ -219,12 +211,13 @@ All pull requests must pass these checks before merging. The workflows are defin
 - `npm run lint` - Run lint
 - `npm run format` - Run format
 - `npm run lint:fix` - Run lint with auto-fix
-- `npm test` - Run tests (requires sudo privileges for tunneling)
+- `npm test` - Run unit tests
+- `npm run test:all` - Run unit and integration tests (see [Testing](#testing) for integration test requirements)
 
 CLI helpers under `scripts/` are ESM (`.mjs`) and load the library via the package entrypoint. Run `npm run build` before using them so `appium-ios-remotexpc` resolves to `build/`.
 
-- `npm run tunnel-creation` / `npm run test:tunnel-creation` — Create USB tunnels and start the tunnel registry HTTP API (requires `sudo`)
-- `npm run test:tunnel-creation:lsof` — Same as above with `--keep-open` (for inspecting open sockets)
+- `npm run tunnel-creation` — Create USB tunnels and start the tunnel registry HTTP API (requires `sudo`)
+- `npm run tunnel-creation -- --keep-open` — Same as above with `--keep-open` (for inspecting open sockets)
 - `npm run pair-appletv` — Pair an Apple TV over WiFi for Remote XPC (requires `sudo`)
 - `npm run start-appletv-tunnel` — Start an Apple TV WiFi tunnel and tunnel registry (requires `sudo`)
 
@@ -250,8 +243,11 @@ Pass `--help` after `--` to any of these npm scripts to see CLI flags (for examp
 ## Testing
 
 ```bash
-# Run all tests
+# Run unit tests
 npm test
+
+# Run unit and integration tests
+npm run test:all
 ```
 
 Note: Integration tests require:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-ios-remotexpc",
-  "version": "5.19.0",
+  "version": "5.19.2",
   "description": "",
   "keywords": [],
   "bugs": {

package/scripts/lib/registry-port.mjs

@@ -0,0 +1,39 @@
+import net from 'node:net';
+
+const TUNNEL_REGISTRY_HOST = '127.0.0.1';
+
+/**
+ * Binds to `port` (0 = OS-assigned), then releases it and resolves the bound port.
+ * @param {number} port
+ * @returns {Promise<number>}
+ */
+function bindFreePort(port) {
+  return new Promise((resolve, reject) => {
+    const probe = net.createServer();
+    probe.once('error', reject);
+    probe.listen(port, TUNNEL_REGISTRY_HOST, () => {
+      const address = probe.address();
+      if (!address || typeof address === 'string') {
+        probe.close(() => reject(new Error('Could not resolve a free port')));
+        return;
+      }
+      probe.close((err) => (err ? reject(err) : resolve(address.port)));
+    });
+  });
+}
+
+/**
+ * Returns `preferredPort` if free, else a free port chosen by the OS.
+ * @param {number} preferredPort
+ * @param {{warn: (message: string) => void}} log
+ * @returns {Promise<number>}
+ */
+export async function resolveAvailableRegistryPort(preferredPort, log) {
+  try {
+    return await bindFreePort(preferredPort);
+  } catch {
+    const port = await bindFreePort(0);
+    log.warn(`Tunnel registry port ${preferredPort} is in use; using ${port} instead`);
+    return port;
+  }
+}

package/scripts/start-appletv-tunnel.mjs

@@ -21,6 +21,7 @@ import {Command} from 'commander';
 import {DEFAULT_TUNNEL_REGISTRY_PORT, DEFAULT_WIRELESS_APPLETV_DISCOVERY_TIMEOUT_MS} from './lib/constants.mjs';
 import {parseNonNegativeIntegerOption, parsePortOption, parsePositiveIntegerOption} from './lib/options.mjs';
 import {startTimeoutProgressLogger} from './lib/progress.mjs';
+import {resolveAvailableRegistryPort} from './lib/registry-port.mjs';
 import {assertRoot} from './lib/root.mjs';
 import {sleep} from './lib/timers.mjs';
 import {
@@ -432,7 +433,8 @@ async function main() {
   program.parse(process.argv);
   const options = program.opts();
   const deviceIdentifier = program.args[0];
-  const registryPort = options.tunnelRegistryPort ?? DEFAULT_TUNNEL_REGISTRY_PORT;
+  const registryPort =
+    options.tunnelRegistryPort ?? (await resolveAvailableRegistryPort(DEFAULT_TUNNEL_REGISTRY_PORT, log));
 
   await assertRoot(path.join('scripts', path.basename(fileURLToPath(import.meta.url))));