Principle:SeleniumHQ Selenium Session Request Routing
| Knowledge Sources | |
|---|---|
| Domains | Distributed_Testing, Load_Balancing, Selenium_Grid |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Mechanism for routing incoming WebDriver session requests to the appropriate Grid node based on capability matching and slot availability.
Description
When a WebDriver client sends a POST /session request to the Grid Router, the request enters a multi-stage routing pipeline: the Router matches requests starting with /session/ and delegates new session creation to the Distributor. The LocalDistributor.newSession() method iterates over the desired capabilities list, checks whether any UP node supports each capability set via SlotMatcher, reserves a slot using SlotSelector.selectSlot() (which returns candidate SlotId values), and creates the session on the chosen node. The resulting session is registered in the SessionMap for subsequent command routing. If no slot is available but nodes support the capability, the request is retried via RetrySessionRequestException. A background NewSessionRunnable periodically polls the NewSessionQueue and dispatches requests to a thread pool for concurrent session creation.
Usage
Understanding session routing is essential for debugging "no matching node" errors, optimizing Grid utilization, and configuring custom slot matching or selection strategies.
Theoretical Basis
# Pseudocode: Session Request Routing
1. Client -> POST /session { capabilities } -> Router
2. Router matches request URI starting with "/session/"
3. For new sessions: CreateSession handler -> Distributor.newSession(SessionRequest)
4. LocalDistributor.newSession(request):
a. Validate capabilities (reject if empty)
b. For each Capabilities in request.getDesiredCapabilities():
i. isNotSupported(caps) -> check if any UP node has matching capability via SlotMatcher
ii. reserveSlot(requestId, caps):
- SlotSelector.selectSlot(caps, availableNodes, slotMatcher) -> Set<SlotId>
- Attempt to reserve each candidate slot (read lock for selection, write lock for reservation)
iii. startSession(selectedSlot, singleRequest) -> node.newSession(createSessionRequest)
iv. sessions.add(response.getSession()) -> register in SessionMap
v. Return Either.right(CreateSessionResponse)
c. If retry needed: wrap in RetrySessionRequestException -> re-queue
d. If all fail: Return Either.left(SessionNotCreatedException)
5. Subsequent commands: Router -> HandleSession -> SessionMap lookup -> forward to Node