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

[dankefox]

Summary

Add an optional reverse TCP tunnel mode that allows WDA to actively connect outbound to an external relay server. This enables remote control of iOS devices in network environments where inbound connections to port 8100 are not feasible.

Problem

WDA defaults to listening on port 8100 for inbound HTTP connections. However, in many real-world environments, inbound connections to the iOS device are blocked or unreachable:

• Symmetric NAT — common in corporate and campus networks
• Multi-layer firewalls — enterprise security policies blocking inbound traffic to mobile devices
• VPN tunnels — overlay networks where iOS restricts inbound TCP on the tunnel interface
• Remote test labs — devices behind NAT gateways with no port forwarding

In these scenarios, the standard http://<device-ip>:8100 approach simply does not work.

Solution

Instead of requiring the client to connect in to WDA, this PR lets WDA connect out to a relay server. The relay bridges HTTP clients on one side and the WDA reverse connection on the other.

How it works

1. Set WDA_RELAY_HOST and optionally WDA_RELAY_PORT (default: 8201) as environment variables when launching WDA
2. On startup, WDA opens an outbound TCP connection to the relay
3. The relay forwards HTTP requests through this connection and returns responses
4. If the connection drops, WDA automatically reconnects after 5 seconds

When not configured

Zero impact. If WDA_RELAY_HOST is not set, the feature is completely inactive. No code paths are touched, no connections are made, existing behavior is identical.

Changes

File	Change
FBConfiguration.h/m	Add relayHost and relayPort accessors reading from WDA_RELAY_HOST / WDA_RELAY_PORT env vars
FBWebServer.m	Add reverse tunnel client using Apple's Network.framework (nw_connection), with auto-reconnect on failure
Scripts/wda-relay-server.js	Example Node.js relay server (~100 lines) that bridges HTTP ↔ reverse tunnel

Usage

# 1. Start the relay server on a reachable host
node Scripts/wda-relay-server.js  # listens on 8201 (relay) and 8100 (HTTP proxy)

# 2. Launch WDA with relay configured
WDA_RELAY_HOST=192.168.1.100 WDA_RELAY_PORT=8201 xcodebuild test-without-building \
  -project WebDriverAgent.xcodeproj \
  -scheme WebDriverAgentRunner \
  -destination 'id=<device-udid>'

# 3. Use WDA as usual — requests go through the relay
curl http://localhost:8100/status

Design decisions

• Opt-in via environment variables — consistent with existing USE_PORT, USE_IP, and MJPEG_SERVER_PORT patterns in FBConfiguration
• Network.framework — uses Apple's modern networking API (nw_connection) for reliable connection management
• 4-byte length-prefixed framing — simple binary protocol for multiplexing HTTP over a single TCP connection
• Auto-reconnect — 5-second backoff on connection failure, no manual intervention needed
• Relay server as example script — included in Scripts/ for easy adoption, not a required component

Testing

Tested on:

• iPhone 16 Pro Max, iOS 26.3.1
• Xcode 26.4
• macOS Tahoe 26.4
• Relay server running on a separate host behind NAT

Verified: /status, /session, tap, swipe, screenshot, and other WDA endpoints all work correctly through the reverse tunnel.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: dankefox / name: dankefox (24f73f1, abafbc5, d909419, e462c41)

[mykola-mokhnach]

this functionality must be extracted to a separate module and covered by integration tests

[dankefox]

Makes sense. I'll extract the reverse tunnel into its own module (e.g., FBReverseTunnel.h/m) so it's cleanly separated from FBWebServer. FBWebServer would just call [FBReverseTunnel startWithHost:port:] if the env vars are set.

Will also add integration test coverage for the module.

[mykola-mokhnach]

I still don't observe any tests, neither in WDA objc sources nor in nodejs sources

[mykola-mokhnach]

I'm not sure why to reinvent a custom protocol if the project already uses CocoaHTTPServer

[dankefox]

Thank you for the review @mykola-mokhnach!

Regarding CocoaHTTPServer — it serves as an inbound HTTP server (listening on a port for incoming connections). The core problem this PR addresses is precisely that inbound connections to the iOS device are blocked in NAT-restricted environments.

The reverse tunnel requires WDA to initiate an outbound TCP connection to an external relay. During development, I tested three approaches for the outbound connection:

1. NSStream — failed to establish reliable connections over VPN/tunnel interfaces
2. POSIX sockets — also unreliable on iOS for outbound TCP over non-standard network paths
3. nw_connection (Network.framework) — worked reliably, and is Apple's recommended API for modern network connections

The 4-byte length-prefixed framing is intentionally minimal — just enough to multiplex HTTP request/response pairs over a single persistent TCP connection. I considered using HTTP itself as the transport (e.g., long-polling or WebSocket), but a raw TCP connection with simple framing has significantly lower overhead and latency for this use case.

That said, I'm absolutely open to alternative approaches if you have a preferred pattern in mind. Would it make sense to, for example, use CocoaHTTPServer as an HTTP client (reverse proxy) that forwards to a relay via HTTP? I'd be happy to explore that if it fits better with the project's architecture.

[dankefox]

Updated the PR based on all review feedback:

• Extracted to separate module: All reverse tunnel logic is now in FBReverseTunnel.h/m. FBWebServer.m has a single one-line call: [FBReverseTunnel startIfConfiguredWithLocalPort:]
• Split complex methods: FBReverseTunnel.m is organized into focused methods — parseHTTPRequest:, buildLocalRequestWithMethod:path:body:, buildFramedResponse:statusCode:, sendData:throughConnection:, etc.
• Named constants: Extracted FBReverseTunnelMaxPayloadSize (10 MB) and FBReverseTunnelReconnectDelay (5s) with documenting comments
• Relay script: Kept in Scripts/ as it is a required counterpart (users need a relay server on the other end). Happy to move to a different directory if preferred.

Regarding the CLA — I'll get that signed. The commit email needs to be linked to my GitHub account.

Ready for another round of review!

[KazuCocoa]

So, this is when a client wants to connect to the WDA over ip:port (which is not though local proxy forward appium xcuitest driver generally does,) correct? For example, this PR + appium:webDriverAgentUrl (to the relay), configuration? - just to understand the usage properly

[dankefox]

Yes, exactly! The primary use case is:

1. WDA runs on an iOS device behind NAT/firewall (cellular network, corporate firewall, etc.) where inbound TCP is blocked
2. A relay server runs on a publicly accessible host
3. WDA initiates an outbound connection to the relay and establishes a reverse tunnel
4. The Appium client connects to the relay using appium:webDriverAgentUrl pointed at the relay address

So the flow is: Appium Client → Relay Server ← WDA (reverse tunnel)

This is particularly useful for remote device farms, CI/CD pipelines with devices on cellular networks, or any environment where direct port access to the iOS device isn't possible.

[mykola-mokhnach]

Consider restructuring this example, so corresponding code pieces are organised into classes. I am not a big fan of global module variables (especially mutable ones) unless it could be proven they are required

[dankefox]

Fair point. For the relay server (which lives in docs/ as a reference implementation), I've kept it straightforward since users will likely adapt it to their own infrastructure. The relay is intentionally minimal — the important complexity lives on the WDA side in FBReverseTunnel.

Happy to restructure if you feel strongly about it.

[mykola-mokhnach]

it's not about minimalism, but rather about designing it properly, so entities belonging to different domains are not mixed together. Also, properly designed architecture makes it easier to adapt/modify it for different purposes as it is easier to parse and understand.
I can observe you are anyway extensively using AI, so it must not be a complicated task to supply it with an appropriate prompt.

[mykola-mokhnach]

can we use existing HTTP vendor libs for this purpose?

[dankefox]

The tunnel relays raw HTTP bytes — the payload from the relay is a complete HTTP request (method line + headers + body) that the local WDA server parses directly.

Using POSIX socket lets us forward these raw bytes to 127.0.0.1:port without parsing/reconstructing the HTTP message. An HTTP client library (like NSURLSession) would require parsing the raw request into a structured NSURLRequest first, which adds complexity and potential for subtle differences in header handling.

The raw forwarding approach is simpler, produces byte-identical requests to the local server, and has been tested extensively in production.

[mykola-mokhnach]

I agree it does not make sense to replace everything, but for example the below stuff

  const char *err = "HTTP/1.1 502 Bad Gateway\r\n\r\nLocal WDA unreachable";
  [response appendBytes:err length:strlen(err)];

is confusing and unoptimal. I would rather supply a proper http message there, with content length, content type, etc. headers

[KazuCocoa]

Could you leave one security notice for the user? So, "you'll need to be responsible for the network security by yourself"

[KazuCocoa]

Also, NW_PARAMETERS_DISABLE_PROTOCOL is provided in the FBReverseTunnel.m, which will work for the plain TCP replay server only (not a full TLS handshake). Architecture section probably can address this behavior as well

[KazuCocoa]

These might have issues in CI:

• npm run lint
• unit test in WDA project

[mykola-mokhnach]

WDA also provides shutdown endpoint. Consider stopping this server as well when the main web server is stopped

[mykola-mokhnach]

consider making these to class properties. Avoid using static as it makes the entity less flexible

[mykola-mokhnach]

this is a breaking change, please revert

[mykola-mokhnach]

Please extract this part into a separate private method

[mykola-mokhnach]

this is also a breaking change, please revert