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

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