In Appium, what do the directConnect fields in a new-session response change?

## The shape of the mechanism Everything about an Appium session normally flows through one base URL: the handshake creates the session, and every later request is that same base URL plus `/session/:sessionId/...`. Direct connect is the one sanctioned exception. The response to `POST /session` may carry four extra fields — `directConnectProtocol`, `directConnectHost`, `directConnectPort` and `directConnectPath` — which between them describe a complete second base URL: scheme, host, port and path prefix. A client that has been configured to honour them rebuilds its base URL from those four values and uses it for everything afterwards. A client that has not simply ignores four unrecognised keys in a response, which is harmless. ## What changes and what does not | Aspect | After a direct-connect redirect | |---|---| | Session id | Unchanged — the same session, reached differently | | Capability set | Unchanged — it was consumed at the handshake | | Command set and route shapes | Unchanged — still `/session/:sessionId/...` | | Base URL for later requests | Replaced by the four direct-connect values | | Teardown | `DELETE /session/:sessionId` goes to the new base URL | The first row matters most during an incident. Because the session id survives, correlation on the server side looks completely normal; nothing announces that the client changed where it was pointing. That is precisely what makes the failure mode below confusing the first time you meet it. ## Why an endpoint would do this The handshake and the command stream have different characteristics. The handshake is one request that decides which server should own the session; the command stream is thousands of small round trips whose latency dominates a run. Separating them lets an operator answer the handshake at one address and then hand the client a more direct route for the rest of the conversation. From the client's side the useful framing is: **the URL you configure is where you ask for a session, not necessarily where the session lives.** That is a genuine break with the usual mental model, and it is worth holding explicitly rather than discovering it mid-triage. ## The failure signature The symptom is unusually specific: - `POST /session` succeeds and returns a session id. - The first command after it fails at the transport layer, not with a driver error. - Nothing in the capability set is implicated, and the same capabilities work when direct connect is not honoured. That pattern almost always means the redirect target is not reachable from where the client is running, even though the original endpoint was. The two addresses are resolved and routed independently, so one working says nothing about the other. When you see it, the checks are: 1. Print the four direct-connect values the response actually carried, rather than assuming what they should be. 2. Try reaching the rebuilt base URL from the client machine directly. 3. Turn off the client's honouring of the fields and re-run — if the suite passes, the redirect target is the fault and the diagnosis is complete. 4. Confirm the path field, not just the host: a redirect that supplies a prefix produces the same 404 family as any other base-path mismatch. ## Opt-in, and why that is a feature Because honouring the fields is a client-side setting, direct connect can be turned on and off without touching capabilities or server configuration. That gives you a clean A/B during triage: the same suite, the same Android or iOS capability set, the same endpoint, one flag apart. Very few problems in this area can be isolated that cleanly, so it is worth knowing the switch exists before you need it. It also means "the client did not follow the redirect" is a legitimate, non-broken state. A client that ignores the fields is not misconfigured; it is routing everything through the address it was given, which always works if the handshake worked. ## Platform independence None of this differs by platform. An Android capability set (`platformName` of `Android`, `appium:automationName`, Android's `appium:appPackage`) and an iOS capability set (`platformName` of `iOS`, iOS's `appium:bundleId`) are unaffected: they were consumed when the session was created and are not re-sent to the new address. Direct connect is purely about where bytes go, which is why it belongs to the endpoint story and not to the capability story. ## The summary worth remembering The base URL is an entry point that a response may replace for the remainder of the session, keeping the session id, the capability set and the route shapes exactly as they were — and if that replacement is unreachable from the client, the handshake still passes and the first command still fails.