feat: optional reverse TCP tunnel for WDA in NAT-restricted environments

Add opt-in reverse TCP tunnel mode that allows WDA to actively connect
outbound to an external relay server, enabling remote control in
environments where inbound connections to the iOS device are not feasible
(symmetric NAT, multi-layer firewalls, corporate VPNs, etc.).

Controlled via environment variables (disabled by default):
- WDA_RELAY_HOST: relay server address
- WDA_RELAY_PORT: relay server port (default 8201)

When not configured, WDA behavior is completely unchanged.

Changes based on review feedback:
- Extracted reverse tunnel into dedicated FBReverseTunnel module
- Split complex methods into focused, single-responsibility functions
- Extracted magic numbers into named constants
- FBWebServer only has a single-line call to FBReverseTunnel

Implementation notes:
- Uses Network.framework (nw_connection) for outbound TCP — tested and
  verified after NSStream and POSIX sockets both proved unreliable for
  outbound connections over VPN/tunnel interfaces on iOS
- 4-byte big-endian length-prefixed framing for minimal overhead
- Auto-reconnect with configurable delay on connection failure

Includes:
- FBConfiguration: relay host/port accessors from env vars
- FBReverseTunnel: standalone reverse tunnel module
- Scripts/wda-relay-server.js: reference relay server implementation
  (required counterpart — users need a relay to connect to)

Author: dankefox

Scripts/wda-relay-server.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * WDA Reverse Tunnel Relay Server
+ *
+ * This server acts as a bridge between WDA (running on an iOS device behind NAT)
+ * and HTTP clients. WDA connects outbound to this relay; HTTP clients connect
+ * to localhost:8100 as usual.
+ *
+ * Usage:
+ *   WDA_RELAY_HOST=<this-server-ip> WDA_RELAY_PORT=8201 xcodebuild test-without-building ...
+ *   node wda-relay-server.js              # relay on 8201, proxy on 8100
+ *   node wda-relay-server.js 9201 9100    # custom ports
+ *
+ * Protocol (between relay and WDA):
+ *   [4-byte big-endian length][payload]
+ *   Request payload:  raw HTTP request  (method + headers + body)
+ *   Response payload: raw HTTP response (status + headers + body)
+ */
+
+const net = require('net');
+const http = require('http');
+
+const RELAY_PORT = parseInt(process.argv[2]) || 8201;
+const PROXY_PORT = parseInt(process.argv[3]) || 8100;
+
+let wdaSocket = null;
+let pendingRequests = new Map();
+let requestCounter = 0;
+
+// --- Relay server: accepts reverse connection from WDA ---
+const relayServer = net.createServer((socket) => {
+  console.log(`[relay] WDA connected from ${socket.remoteAddress}`);
+  wdaSocket = socket;
+
+  let buffer = Buffer.alloc(0);
+
+  socket.on('data', (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+
+    while (buffer.length >= 4) {
+      const len = buffer.readUInt32BE(0);
+      if (buffer.length < 4 + len) break;
+
+      const payload = buffer.slice(4, 4 + len);
+      buffer = buffer.slice(4 + len);
+
+      // Route response to the oldest pending HTTP request
+      const oldest = pendingRequests.entries().next().value;
+      if (oldest) {
+        const [id, res] = oldest;
+        pendingRequests.delete(id);
+
+        const text = payload.toString();
+        const headerEnd = text.indexOf('\r\n\r\n');
+        if (headerEnd !== -1) {
+          const statusMatch = text.match(/^HTTP\/\d\.\d (\d+)/);
+          const statusCode = statusMatch ? parseInt(statusMatch[1]) : 200;
+          const body = payload.slice(headerEnd + 4);
+          res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+          res.end(body);
+        } else {
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(payload);
+        }
+      }
+    }
+  });
+
+  socket.on('close', () => {
+    console.log('[relay] WDA disconnected');
+    wdaSocket = null;
+  });
+
+  socket.on('error', (err) => {
+    console.error('[relay] Socket error:', err.message);
+    wdaSocket = null;
+  });
+});
+
+// --- HTTP proxy: accepts normal WDA API requests ---
+const proxyServer = http.createServer((req, res) => {
+  if (!wdaSocket || wdaSocket.destroyed) {
+    res.writeHead(503, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'WDA not connected to relay' }));
+    return;
+  }
+
+  let body = [];
+  req.on('data', (chunk) => body.push(chunk));
+  req.on('end', () => {
+    const bodyBuf = Buffer.concat(body);
+    const httpReq = `${req.method} ${req.url} HTTP/1.1\r\nHost: localhost\r\n` +
+      Object.entries(req.headers).map(([k, v]) => `${k}: ${v}`).join('\r\n') +
+      '\r\n\r\n' + bodyBuf.toString();
+
+    const reqBuf = Buffer.from(httpReq);
+    const lenBuf = Buffer.alloc(4);
+    lenBuf.writeUInt32BE(reqBuf.length);
+
+    const id = requestCounter++;
+    pendingRequests.set(id, res);
+
+    try {
+      wdaSocket.write(Buffer.concat([lenBuf, reqBuf]));
+    } catch (err) {
+      pendingRequests.delete(id);
+      res.writeHead(502, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Failed to forward request' }));
+    }
+  });
+});
+
+relayServer.listen(RELAY_PORT, () => {
+  console.log(`[relay] Waiting for WDA on port ${RELAY_PORT}`);
+});
+
+proxyServer.listen(PROXY_PORT, () => {
+  console.log(`[proxy] HTTP proxy on port ${PROXY_PORT}`);
+  console.log(`\nUsage: set WDA_RELAY_HOST and WDA_RELAY_PORT env vars when launching WDA`);
+  console.log(`  WDA_RELAY_HOST=<this-ip> WDA_RELAY_PORT=${RELAY_PORT} xcodebuild test-without-building ...`);
+  console.log(`  curl http://localhost:${PROXY_PORT}/status`);
+});

WebDriverAgentLib/Routing/FBReverseTunnel.h

@@ -0,0 +1,38 @@
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ Optional reverse TCP tunnel for NAT-restricted environments.
+
+ When WDA_RELAY_HOST is set, this module opens an outbound TCP connection
+ to an external relay server, allowing WDA to be controlled in environments
+ where inbound connections to port 8100 are not feasible (symmetric NAT,
+ multi-layer firewalls, VPN tunnels, etc.).
+
+ The tunnel uses a simple 4-byte big-endian length-prefixed framing protocol
+ to multiplex HTTP request/response pairs over a single persistent connection.
+
+ When WDA_RELAY_HOST is not set, this module is completely inactive.
+ */
+@interface FBReverseTunnel : NSObject
+
+/**
+ Starts the reverse tunnel if WDA_RELAY_HOST is configured.
+ Does nothing if the environment variable is not set (default behavior unchanged).
+
+ @param localPort The local WDA HTTP server port to forward requests to
+ */
++ (void)startIfConfiguredWithLocalPort:(NSUInteger)localPort;
+
+@end
+
+NS_ASSUME_NONNULL_END