What can a remote WebDriver endpoint address decide beyond which machine answers the request?

## The address is a front door, not a desk A local run starts by launching a browser process. A remote run starts with an **address**, and that address is the whole interface: a scheme, an optional user-info component, a host, a port and a path. The instinctive reading is that its host is the machine the browser will run on. On a rented fleet it almost never is. The address names a front door — an intermediary that accepts the new-session request and then decides which machine behind it serves the session. The W3C WebDriver specification names the two roles: an **intermediary node** as distinct from an **endpoint node**. It says an intermediary node "may use the result of the capabilities processing algorithm to route the new session request to the appropriate endpoint node". Routing is specified behaviour of the thing you were handed an address for, not a quirk you happened to hit. ## Regions: routing configured for the account, not requested by the suite Ggr, an open Selenium balancer unmaintained by its own README, is the clearest readable model, because its routing table is a plain file. Each account gets a quota file — an XML document named after that account — and inside it the nesting is: - `<browser>` elements naming the browsers the account may ask for, each with a `defaultVersion` attribute; - `<version>` elements beneath a browser; - `<region>` elements beneath a version, which Ggr's own `quota-files.adoc` glosses as "in cloud term, i.e. data centers"; - `<host>` elements beneath a region, each carrying a `name`, a `port` and a `count`. Two consequences fall straight out. First, geography is a property of the entitlement sitting behind the address, not something a suite asks for at run time: the credit-union statements portal suite writes one address, and that file decides which data centre answers. Second, the route is not sticky, though it moves less than you would hope. In Ggr's retry loop a host whose Selenium answered the new-session request with an error status is classified `browserFailed` and simply dropped from the candidate list, so the next attempt can land on a sibling host in the same data centre. Only a transport or protocol failure — Ggr's `seleniumError` — adds that host's region to an `excludedRegions` set and searches again, and Ggr empties that set once every region is excluded. `count` is worth naming carefully, because the word invites the wrong reading. Ggr, unmaintained by its own README, says in `quota-files.adoc` that "`count` is the relative host weight allowing to adjust the load to every host depending on its capacity". It biases weighted random selection between hosts; it is not a ceiling. ## Relay: one endpoint standing in front of another The second routing mechanism is that the service behind your address may not run browsers at all. `docker-selenium` documents a Grid node whose entire job is to forward: `SE_NODE_RELAY_URL` points such a node at another WebDriver-speaking service, and `SE_NODE_RELAY_STATUS_ENDPOINT` names the health path it polls. Its README is explicit about what that far service can be — relaying is "useful to connect an external service that supports WebDriver to Selenium Grid", and "an example of such service could be a cloud provider or an Appium server". So an endpoint address can be a facade in front of a second one, and the client cannot tell. The request may cross an intermediary, a relay node and a provider's own router before any browser starts. | what you write | what actually decides it | |---|---| | host and port | which front door you knock on | | the entitlement behind the account | which region and which host serve you | | the far service's own configuration | whether a relay forwards you somewhere else again | ## What follows in practice - **Latency is a property of the route, not of your code.** Every command is a round trip to whatever the address resolved to that day, so an extra hop costs on every command, not once at start-up. - **You cannot pin a machine from the client.** Selection happens on the far side of the address; asking the suite to "use the fast host" has nowhere to go. - **Two runs on the same address need not get the same hardware**, so timing calibrated against yesterday's run is fragile. - **A relayed endpoint hides its far end.** If a suite is failing only for one platform, the interesting configuration may live in a relay definition nobody on the test team owns. ## Common misreadings 1. *"The host in the address is where my browser runs."* It is where the router runs. The browser host is chosen after the request arrives. 2. *"A retry hits the same host."* It does not — Ggr, unmaintained by its own README, drops the failed host from its candidate list. But the softer belief that a retry leaves the region holds only for Ggr's `seleniumError` branch, never for an ordinary failed browser start. 3. *"`count` limits how much I can run on that host."* It is a load-balancing weight, as Ggr's own documentation says, from a project unmaintained by its own README; it imposes no ceiling. 4. *"A rented endpoint and a self-run Grid endpoint are different kinds of thing."* Structurally both are an address in front of a routing decision you do not make.