0
# Client Configuration
1

2
Flexible client configuration system with builder pattern for setting timeouts, authentication, proxies, SSL context, and filter chains for HTTP clients.
3

4
## Capabilities
5

6
### ClientConfig Class
7

8
Immutable configuration class using builder pattern for HTTP client setup with comprehensive options for network settings, security, and request processing.
9

10
```java { .api }
11
/**
12
 * Immutable HTTP client configuration using builder pattern
13
 * Provides comprehensive settings for timeouts, security, filtering, and network
14
 */
15
public class ClientConfig {
16
    /**
17
     * Creates default configuration with system property overrides
18
     * Connection timeout: 10 seconds (webdriver.httpclient.connectionTimeout)
19
     * Read timeout: 180 seconds (webdriver.httpclient.readTimeout)
20
     * Default filter: AddSeleniumUserAgent
21
     * HTTP version: System property (webdriver.httpclient.version)
22
     * @return Default ClientConfig instance
23
     */
24
    public static ClientConfig defaultConfig();
25
    
26
    /**
27
     * Sets base URI for all requests
28
     * @param baseUri Base URI for HTTP client
29
     * @return New ClientConfig instance with updated base URI
30
     */
31
    public ClientConfig baseUri(URI baseUri);
32
    
33
    /**
34
     * Sets base URL for all requests (converts to URI)
35
     * @param baseUrl Base URL for HTTP client
36
     * @return New ClientConfig instance with updated base URL
37
     * @throws RuntimeException if URL cannot be converted to URI
38
     */
39
    public ClientConfig baseUrl(URL baseUrl);
40
    
41
    /**
42
     * Gets configured base URI
43
     * @return Base URI or null if not set
44
     */
45
    public URI baseUri();
46
    
47
    /**
48
     * Gets configured base URL (converts from URI)
49
     * @return Base URL
50
     * @throws UncheckedIOException if URI cannot be converted to URL
51
     */
52
    public URL baseUrl();
53
    
54
    /**
55
     * Sets connection timeout duration
56
     * @param timeout Connection timeout (must be non-negative)
57
     * @return New ClientConfig instance with updated timeout
58
     */
59
    public ClientConfig connectionTimeout(Duration timeout);
60
    
61
    /**
62
     * Gets connection timeout duration
63
     * @return Connection timeout duration
64
     */
65
    public Duration connectionTimeout();
66
    
67
    /**
68
     * Sets read timeout duration
69
     * @param timeout Read timeout (must be non-negative)
70
     * @return New ClientConfig instance with updated timeout
71
     */
72
    public ClientConfig readTimeout(Duration timeout);
73
    
74
    /**
75
     * Gets read timeout duration
76
     * @return Read timeout duration
77
     */
78
    public Duration readTimeout();
79
    
80
    /**
81
     * Adds custom filter to filter chain
82
     * Filter is added before default AddSeleniumUserAgent filter
83
     * @param filter Custom filter to add
84
     * @return New ClientConfig instance with additional filter
85
     */
86
    public ClientConfig withFilter(Filter filter);
87
    
88
    /**
89
     * Enables automatic retry filter for failed requests
90
     * Adds RetryRequest filter to handle connection failures and server errors
91
     * @return New ClientConfig instance with retry support
92
     */
93
    public ClientConfig withRetries();
94
    
95
    /**
96
     * Gets current filter chain
97
     * @return Combined filter chain
98
     */
99
    public Filter filter();
100
    
101
    /**
102
     * Sets HTTP proxy for requests
103
     * @param proxy Proxy configuration
104
     * @return New ClientConfig instance with proxy settings
105
     */
106
    public ClientConfig proxy(Proxy proxy);
107
    
108
    /**
109
     * Gets configured proxy
110
     * @return Proxy configuration or null if not set
111
     */
112
    public Proxy proxy();
113
    
114
    /**
115
     * Sets authentication credentials
116
     * @param credentials Authentication credentials
117
     * @return New ClientConfig instance with authentication
118
     */
119
    public ClientConfig authenticateAs(Credentials credentials);
120
    
121
    /**
122
     * Gets authentication credentials
123
     * @return Credentials or null if not set
124
     */
125
    public Credentials credentials();
126
    
127
    /**
128
     * Sets custom SSL context for HTTPS connections
129
     * @param sslContext SSL context configuration
130
     * @return New ClientConfig instance with SSL settings
131
     */
132
    public ClientConfig sslContext(SSLContext sslContext);
133
    
134
    /**
135
     * Gets SSL context
136
     * @return SSL context or null if using default
137
     */
138
    public SSLContext sslContext();
139
    
140
    /**
141
     * Sets HTTP protocol version
142
     * @param version HTTP version string
143
     * @return New ClientConfig instance with version setting
144
     */
145
    public ClientConfig version(String version);
146
    
147
    /**
148
     * Gets HTTP protocol version
149
     * @return HTTP version string or null if using default
150
     */
151
    public String version();
152
    
153
    /**
154
     * String representation of configuration
155
     * @return String showing all configuration values
156
     */
157
    public String toString();
158
}
159
```
160

161
**Usage Examples:**
162

163
```java
164
import org.openqa.selenium.remote.http.*;
165
import java.net.URL;
166
import java.net.Proxy;
167
import java.net.InetSocketAddress;
168
import java.time.Duration;
169
import javax.net.ssl.SSLContext;
170

171
// Basic configuration
172
ClientConfig basicConfig = ClientConfig.defaultConfig()
173
    .baseUrl(new URL("https://api.example.com"))
174
    .connectionTimeout(Duration.ofSeconds(30))
175
    .readTimeout(Duration.ofMinutes(2));
176

177
// Configuration with proxy
178
Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress("proxy.company.com", 8080));
179
ClientConfig proxyConfig = ClientConfig.defaultConfig()
180
    .baseUrl(new URL("https://api.example.com"))
181
    .proxy(proxy);
182

183
// Configuration with authentication
184
Credentials credentials = new UsernamePasswordCredentials("username", "password");
185
ClientConfig authConfig = ClientConfig.defaultConfig()
186
    .baseUrl(new URL("https://api.example.com"))
187
    .authenticateAs(credentials);
188

189
// Configuration with custom SSL context
190
SSLContext sslContext = SSLContext.getInstance("TLS");
191
// ... configure SSL context
192
ClientConfig sslConfig = ClientConfig.defaultConfig()
193
    .baseUrl(new URL("https://api.example.com"))
194
    .sslContext(sslContext);
195

196
// Configuration with retries and custom filter
197
Filter loggingFilter = new DumpHttpExchangeFilter();
198
ClientConfig advancedConfig = ClientConfig.defaultConfig()
199
    .baseUrl(new URL("https://api.example.com"))
200
    .connectionTimeout(Duration.ofSeconds(45))
201
    .readTimeout(Duration.ofMinutes(3))
202
    .withFilter(loggingFilter)
203
    .withRetries()
204
    .version("HTTP/2");
205

206
// Create HTTP client with configuration
207
HttpClient client = HttpClient.Factory.createDefault().createClient(advancedConfig);
208

209
// Configuration is immutable - each method returns new instance
210
ClientConfig config1 = ClientConfig.defaultConfig();
211
ClientConfig config2 = config1.connectionTimeout(Duration.ofSeconds(30));
212
// config1 still has original timeout, config2 has new timeout
213

214
System.out.println("Config details: " + advancedConfig.toString());
215
```
216

217
### System Property Configuration
218

219
Default configuration can be influenced by system properties:
220

221
```java
222
// Connection timeout (default: 10 seconds)
223
System.setProperty("webdriver.httpclient.connectionTimeout", "30");
224

225
// Read timeout (default: 180 seconds)  
226
System.setProperty("webdriver.httpclient.readTimeout", "300");
227

228
// HTTP client version
229
System.setProperty("webdriver.httpclient.version", "HTTP/2");
230

231
// HTTP client implementation (used by Factory.createDefault())
232
System.setProperty("webdriver.http.factory", "my-custom-client");
233

234
// Create client with system property defaults
235
ClientConfig config = ClientConfig.defaultConfig();
236
```
237

238
### Configuration Chaining
239

240
All configuration methods return new instances, enabling fluent method chaining:
241

242
```java
243
import org.openqa.selenium.remote.http.*;
244
import java.net.URL;
245
import java.time.Duration;
246

247
// Chain multiple configuration options
248
ClientConfig config = ClientConfig.defaultConfig()
249
    .baseUrl(new URL("https://api.example.com"))
250
    .connectionTimeout(Duration.ofSeconds(30))
251
    .readTimeout(Duration.ofMinutes(5))
252
    .withRetries()
253
    .withFilter(new DumpHttpExchangeFilter())
254
    .proxy(new Proxy(Proxy.Type.HTTP, 
255
           new InetSocketAddress("proxy.example.com", 8080)))
256
    .authenticateAs(new UsernamePasswordCredentials("user", "pass"))
257
    .version("HTTP/1.1");
258

259
// Create client with comprehensive configuration
260
HttpClient client = HttpClient.Factory.createDefault().createClient(config);
261

262
// Execute request with all configured settings
263
HttpRequest request = new HttpRequest(HttpMethod.GET, "/users");
264
HttpResponse response = client.execute(request);
265

266
System.out.println("Response from " + response.getTargetHost() + 
267
                   ": " + response.getStatus());
268
```
269

270
### Configuration Validation
271

272
The ClientConfig class performs validation on configuration values:
273

274
```java
275
import java.time.Duration;
276

277
try {
278
    // Negative timeouts are rejected
279
    ClientConfig.defaultConfig()
280
        .connectionTimeout(Duration.ofSeconds(-1)); // Throws exception
281
} catch (IllegalArgumentException e) {
282
    System.err.println("Invalid timeout: " + e.getMessage());
283
}
284

285
try {
286
    // Null values are rejected where appropriate
287
    ClientConfig.defaultConfig()
288
        .baseUri(null); // Throws exception
289
} catch (NullPointerException e) {
290
    System.err.println("Null URI not allowed");
291
}
292

293
// Valid configurations
294
ClientConfig validConfig = ClientConfig.defaultConfig()
295
    .connectionTimeout(Duration.ZERO) // Zero timeout is allowed
296
    .readTimeout(Duration.ofDays(1));  // Very long timeout is allowed
297
```
298

299
## Built-in Filters
300

301
The ClientConfig includes several built-in filters that are automatically applied:
302

303
### AddSeleniumUserAgent Filter
304

305
Automatically applied to all configurations, adds Selenium user agent header:
306

307
```java
308
// Default configuration includes AddSeleniumUserAgent filter
309
ClientConfig config = ClientConfig.defaultConfig();
310
// User-Agent header will be automatically added to all requests
311

312
// The User-Agent format includes Selenium version and Java platform info
313
// Example: "selenium/4.33.0 (java mac)"
314
```
315

316
### RetryRequest Filter
317

318
Optional filter for automatic retry of failed requests:
319

320
```java
321
// Enable retry filter
322
ClientConfig configWithRetries = ClientConfig.defaultConfig()
323
    .withRetries();
324

325
// The retry filter automatically retries:
326
// - Connection failures (ConnectionFailedException)
327
// - Server errors (5xx status codes)
328
// - With exponential backoff strategy
329
```