Implementation:SeleniumHQ Selenium Router And LocalDistributor

Knowledge Sources	Selenium
Domains	Distributed_Testing, Load_Balancing, Selenium_Grid
Last Updated	2026-02-11 00:00 GMT

Overview

Concrete tool for routing WebDriver session requests through the Grid provided by the Router and LocalDistributor classes.

Description

Router implements HasReadyState, Routable, and Closeable. Its constructor wires routes for /status (via GridStatusHandler), the session map, the session queue, the distributor, and a catch-all HandleSession handler for requests matching /session/*. Router.isReady() checks readiness of distributor, sessions, and queue in parallel using Set.of(...).parallelStream().

LocalDistributor extends Distributor and implements Closeable. It is annotated with @ManagedService for JMX management. The newSession(SessionRequest) method iterates desired capabilities, checks node support via isNotSupported(), calls reserveSlot() which uses SlotSelector.selectSlot(caps, availableNodes, slotMatcher) with a read lock, then reserve(slotId) with a write lock. Session creation is delegated to node.newSession(CreateSessionRequest). The NewSessionRunnable inner class runs on a ScheduledExecutorService, polling the NewSessionQueue and dispatching to a fixed-size sessionCreatorExecutor thread pool. Failed sessions can be retried via sessionQueue.retryAddToQueue(). Invalid sessions (timed out or dropped connections) are cleaned up by stopping the browser.

Usage

These are internal Grid components not directly instantiated by users. Understanding their behavior is important for debugging session creation failures and configuring Grid performance.

Code Reference

Source Location

Repository: Selenium
File: java/src/org/openqa/selenium/grid/router/Router.java (L39-96)
File: java/src/org/openqa/selenium/grid/distributor/local/LocalDistributor.java (L100-672)
File: java/src/org/openqa/selenium/grid/distributor/CreateSession.java (L35-63)
File: java/src/org/openqa/selenium/grid/distributor/selector/SlotSelector.java (L30-33)

Signature

public class Router implements HasReadyState, Routable, Closeable {
    public Router(Tracer tracer, HttpClient.Factory clientFactory,
                  SessionMap sessions, NewSessionQueue queue, Distributor distributor);
    public boolean isReady();
    public boolean matches(HttpRequest req);
    public HttpResponse execute(HttpRequest req);
    public void close();
}

@ManagedService(objectName = "org.seleniumhq.grid:type=Distributor,name=LocalDistributor",
                description = "Grid 4 node distributor")
public class LocalDistributor extends Distributor implements Closeable {
    public LocalDistributor(Tracer tracer, EventBus bus, HttpClient.Factory clientFactory,
        SessionMap sessions, NewSessionQueue sessionQueue, SlotSelector slotSelector,
        Secret registrationSecret, Duration healthcheckInterval,
        boolean rejectUnsupportedCaps, Duration sessionRequestRetryInterval,
        int newSessionThreadPoolSize, SlotMatcher slotMatcher, Duration purgeNodesInterval);
    public static Distributor create(Config config);
    public Either<SessionNotCreatedException, CreateSessionResponse> newSession(SessionRequest request);
    public LocalDistributor add(Node node);
    public boolean drain(NodeId nodeId);
    public void remove(NodeId nodeId);
    public DistributorStatus getStatus();
    public boolean isReady();
    public void close();
}

@FunctionalInterface
public interface SlotSelector {
    Set<SlotId> selectSlot(Capabilities capabilities, Set<NodeStatus> nodes, SlotMatcher slotMatcher);
}

Import

// Internal Grid classes - not directly imported by end users
import org.openqa.selenium.grid.router.Router;
import org.openqa.selenium.grid.distributor.local.LocalDistributor;
import org.openqa.selenium.grid.distributor.selector.SlotSelector;

I/O Contract

Inputs

Name	Type	Required	Description
SessionRequest	SessionRequest	Yes	Desired capabilities list and request metadata
SlotMatcher	SlotMatcher	Yes (config)	Predicate for capability matching against node stereotypes
SlotSelector	SlotSelector	Yes (config)	Strategy for choosing among available slots; returns Set<SlotId>
rejectUnsupportedCaps	boolean	Yes (config)	Whether to immediately reject requests with no matching node capability

Outputs

Name	Type	Description
CreateSessionResponse	CreateSessionResponse	Session ID, matched capabilities, node URI on success
SessionNotCreatedException	Exception	Error if no matching node/slot available
RetrySessionRequestException	Exception	Signal to re-queue the request for later retry

Usage Examples

Client-Side (Using Grid)

import org.openqa.selenium.remote.RemoteWebDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import java.net.URL;

// Point to Grid Router
RemoteWebDriver driver = new RemoteWebDriver(
    new URL("http://grid-host:4444"),
    new ChromeOptions());

// Router handles session routing internally
driver.get("https://example.com");
driver.quit();

Related Pages

Implements Principle

Principle:SeleniumHQ_Selenium_Session_Request_Routing

Requires Environment

Environment:SeleniumHQ_Selenium_Grid_Deployment_Environment

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment