0
# Request Routing
1

2
The request routing system handles incoming HTTP requests and routes them to appropriate grid components, providing the main entry point for WebDriver clients and grid management operations.
3

4
## Capabilities
5

6
### Core Router
7

8
Main router class that processes HTTP requests and coordinates with other grid components.
9

10
```java { .api }
11
/**
12
 * HTTP request router that serves as the main entry point for WebDriver requests
13
 */
14
class Router {
15
    /** Constructor with required grid component dependencies */
16
    Router(Tracer tracer, HttpClient.Factory clientFactory, SessionMap sessions, 
17
           NewSessionQueue queue, Distributor distributor);
18
    
19
    /** Check if the router is ready to handle requests */
20
    boolean isReady();
21
    
22
    /** Check if this router can handle the given request */
23
    boolean matches(HttpRequest req);
24
    
25
    /** Execute the HTTP request and return response */
26
    HttpResponse execute(HttpRequest req);
27
    
28
    /** Close the router and cleanup resources */
29
    void close();
30
}
31
```
32

33
**Usage Example:**
34

35
```java
36
// Create router with grid components
37
Router router = new Router(
38
    tracer,
39
    httpClientFactory,
40
    sessionMap,
41
    sessionQueue,
42
    distributor
43
);
44

45
// Router automatically handles:
46
// - POST /session (new session creation)
47
// - WebDriver commands (/session/{id}/*)
48
// - Grid status endpoints
49
// - WebSocket proxy connections
50

51
// Check router readiness
52
if (router.isReady()) {
53
    System.out.println("Router ready to accept requests");
54
}
55

56
// Process HTTP requests
57
HttpResponse response = router.execute(incomingRequest);
58
```
59

60
### Session Request Handler
61

62
Specialized handler for managing WebDriver session-related requests.
63

64
```java { .api }
65
/**
66
 * Handler for WebDriver session operations
67
 */
68
class HandleSession {
69
    HandleSession(SessionMap sessions, HttpClient.Factory httpClientFactory);
70
    
71
    /** Check if this handler matches the request */
72
    boolean matches(HttpRequest req);
73
    
74
    /** Execute the session-related request */
75
    HttpResponse execute(HttpRequest req);
76
    
77
    /** Get request details for debugging */
78
    String toString();
79
}
80
```
81

82
### Grid Status Handler
83

84
Handler for grid status and monitoring endpoints.
85

86
```java { .api }
87
/**
88
 * Handler for grid status and monitoring endpoints
89
 */
90
class GridStatusHandler {
91
    GridStatusHandler(JsonOutput json, Distributor distributor);
92
    
93
    /** Check if this handler matches the request */
94
    boolean matches(HttpRequest req);
95
    
96
    /** Execute the status request */
97
    HttpResponse execute(HttpRequest req);
98
}
99
```
100

101
### WebSocket Proxy
102

103
Handler for proxying WebSocket connections between clients and nodes.
104

105
```java { .api }
106
/**
107
 * WebSocket proxy for real-time communication with nodes
108
 */
109
class ProxyWebsocketsIntoGrid {
110
    ProxyWebsocketsIntoGrid(HttpClient.Factory httpClientFactory, SessionMap sessions);
111
    
112
    /** Check if this handler matches the WebSocket request */
113
    boolean matches(HttpRequest req);
114
    
115
    /** Execute the WebSocket proxy setup */
116
    HttpResponse execute(HttpRequest req);
117
}
118
```
119

120
### Configuration Options
121

122
Router-specific configuration settings and command-line flags.
123

124
```java { .api }
125
/**
126
 * Configuration options for router behavior
127
 */
128
class RouterOptions {
129
    static final String ROUTER_SECTION = "router";
130
    
131
    /** Get router session timeout */
132
    Duration getSessionTimeout(Config config);
133
    
134
    /** Get request timeout for upstream requests */
135
    Duration getRequestTimeout(Config config);
136
    
137
    /** Get whether to enable WebSocket proxying */
138
    boolean getWebSocketEnabled(Config config);
139
    
140
    /** Get router host binding */
141
    String getRouterHost(Config config);
142
    
143
    /** Get router port */  
144
    int getRouterPort(Config config);
145
}
146

147
/**
148
 * Command-line flags for router configuration
149
 */
150
class RouterFlags {
151
    @Parameter(names = {"--session-timeout"}, 
152
               description = "Session timeout in seconds")
153
    int sessionTimeout = 300;
154
    
155
    @Parameter(names = {"--request-timeout"}, 
156
               description = "Request timeout in seconds")
157
    int requestTimeout = 30;
158
    
159
    @Parameter(names = {"--enable-websockets"}, 
160
               description = "Enable WebSocket proxying")
161
    boolean enableWebSockets = true;
162
    
163
    @Parameter(names = {"--router-host"}, 
164
               description = "Router host binding")
165
    String routerHost = "0.0.0.0";
166
    
167
    @Parameter(names = {"--router-port"}, 
168
               description = "Router port")
169
    int routerPort = 4444;
170
}
171
```
172

173
## Request Routing Flow
174

175
### New Session Creation
176

177
```java
178
// 1. Client sends POST /session with capabilities
179
HttpRequest newSessionRequest = new HttpRequest(POST, "/session")
180
    .setContent(asJson(Map.of("capabilities", capabilities)));
181

182
// 2. Router processes request
183
if (router.matches(newSessionRequest)) {
184
    HttpResponse response = router.execute(newSessionRequest);
185
    
186
    // 3. Router coordinates with:
187
    // - SessionQueue to queue the request
188
    // - Distributor to find available node
189
    // - SessionMap to track the created session
190
    // - Returns session ID and WebDriver endpoint
191
}
192
```
193

194
### WebDriver Command Execution
195

196
```java
197
// 1. Client sends WebDriver command to existing session
198
HttpRequest webdriverCommand = new HttpRequest(POST, "/session/abc-123/element")
199
    .setContent(asJson(Map.of("using", "id", "value", "submit-button")));
200

201
// 2. Router looks up session location
202
if (router.matches(webdriverCommand)) {
203
    HttpResponse response = router.execute(webdriverCommand);
204
    
205
    // 3. Router:
206
    // - Uses SessionMap to find which node owns the session
207
    // - Proxies request to the appropriate node
208
    // - Returns node's response to client
209
}
210
```
211

212
### Grid Status Monitoring
213

214
```java
215
// Grid status endpoint
216
HttpRequest statusRequest = new HttpRequest(GET, "/status");
217
HttpResponse statusResponse = router.execute(statusRequest);
218

219
// Response includes:
220
// - Overall grid readiness
221
// - Node count and availability
222
// - Active session count  
223
// - Supported capabilities across all nodes
224
```
225

226
## Route Patterns
227

228
The router handles several URL patterns:
229

230
| Pattern | Purpose | Handler |
231
|---------|---------|---------|
232
| `POST /session` | Create new session | Internal routing to Distributor |
233
| `GET,DELETE /session/{id}` | Session lifecycle | HandleSession |
234
| `POST /session/{id}/*` | WebDriver commands | HandleSession |
235
| `GET /status` | Grid status | GridStatusHandler |
236
| `GET /ui/*` | Grid UI assets | Static file handler |
237
| WebSocket upgrades | Real-time proxy | ProxyWebsocketsIntoGrid |
238
239
## Error Handling
240

241
```java
242
// Router error responses
243
try {
244
    HttpResponse response = router.execute(request);
245
    
246
    if (response.getStatus() == HTTP_NOT_FOUND) {
247
        // Session not found or invalid endpoint
248
    } else if (response.getStatus() == HTTP_INTERNAL_ERROR) {
249
        // Node communication failure or internal error
250
    } else if (response.getStatus() == HTTP_REQUEST_TIMEOUT) {
251
        // Request timeout (node unresponsive)
252
    }
253
    
254
} catch (Exception e) {
255
    // Network errors, malformed requests, etc.
256
    System.err.println("Router error: " + e.getMessage());
257
}
258
```
259

260
## Integration with Grid Components
261

262
```java
263
// Router depends on all major grid components
264
public class GridRouter {
265
    public static Router create(Config config) {
266
        // Create dependencies
267
        EventBus eventBus = new GuavaEventBus();
268
        SessionMap sessionMap = LocalSessionMap.create(config);
269
        NewSessionQueue sessionQueue = LocalNewSessionQueue.create(config);
270
        Distributor distributor = LocalDistributor.create(config);
271
        
272
        // Create router with all components
273
        return new Router(
274
            tracer,
275
            httpClientFactory,
276
            sessionMap,
277
            sessionQueue,
278
            distributor
279
        );
280
    }
281
}
282
```