0
# HTTP Configuration
1

2
HTTP configuration manages protocol settings, buffer sizes, security options, and request customization through the `HttpConfiguration` class and its customizers.
3

4
## HttpConfiguration Class
5

6
The core class for configuring HTTP protocol behavior.
7

8
```java { .api }
9
public class HttpConfiguration implements Dumpable {
10
    // Constructors
11
    public HttpConfiguration();
12
    public HttpConfiguration(HttpConfiguration config);
13
    
14
    // Buffer size configuration
15
    public int getOutputBufferSize();
16
    public void setOutputBufferSize(int outputBufferSize);
17
    public int getOutputAggregationSize();
18
    public void setOutputAggregationSize(int outputAggregationSize);
19
    public int getRequestHeaderSize();
20
    public void setRequestHeaderSize(int requestHeaderSize);
21
    public int getResponseHeaderSize();
22
    public void setResponseHeaderSize(int responseHeaderSize);
23
    public int getHeaderCacheSize();
24
    public void setHeaderCacheSize(int headerCacheSize);
25
    
26
    // Server identification
27
    public boolean getSendServerVersion();
28
    public void setSendServerVersion(boolean sendServerVersion);
29
    public boolean getSendDateHeader();
30
    public void setSendDateHeader(boolean sendDateHeader);
31
    public boolean getSendXPoweredBy();
32
    public void setSendXPoweredBy(boolean sendXPoweredBy);
33
    public String getServerAuthority();
34
    public void setServerAuthority(String serverAuthority);
35
    
36
    // URI and path configuration
37
    public int getSecurePort();
38
    public void setSecurePort(int securePort);
39
    public String getSecureScheme();
40
    public void setSecureScheme(String secureScheme);
41
    public long getIdleTimeout();
42
    public void setIdleTimeout(long idleTimeout);
43
    
44
    // HTTP compliance
45
    public HttpCompliance getRequestCookieCompliance();
46
    public void setRequestCookieCompliance(HttpCompliance requestCookieCompliance);
47
    public HttpCompliance getResponseCookieCompliance();
48
    public void setResponseCookieCompliance(HttpCompliance responseCookieCompliance);
49
    
50
    // Customizers
51
    public void addCustomizer(Customizer customizer);
52
    public List<Customizer> getCustomizers();
53
    public void removeCustomizer(Customizer customizer);
54
    
55
    // Nested interfaces
56
    interface Customizer {
57
        Request customize(Request request, HttpConfiguration configuration);
58
    }
59
    
60
    interface ConnectionFactory {
61
        HttpConfiguration getHttpConfiguration();
62
    }
63
}
64
```
65

66
## Basic Configuration Example
67

68
```java
69
// Create HTTP configuration
70
HttpConfiguration httpConfig = new HttpConfiguration();
71

72
// Buffer sizes
73
httpConfig.setOutputBufferSize(32768);        // 32KB output buffer
74
httpConfig.setOutputAggregationSize(8192);    // 8KB aggregation buffer
75
httpConfig.setRequestHeaderSize(8192);        // 8KB request headers
76
httpConfig.setResponseHeaderSize(8192);       // 8KB response headers
77
httpConfig.setHeaderCacheSize(512);           // 512 cached headers
78

79
// Server behavior
80
httpConfig.setSendServerVersion(false);       // Hide server version
81
httpConfig.setSendDateHeader(true);           // Include Date header
82
httpConfig.setSendXPoweredBy(false);          // Hide X-Powered-By
83

84
// Security configuration
85
httpConfig.setSecureScheme("https");
86
httpConfig.setSecurePort(8443);
87

88
// Timeout configuration
89
httpConfig.setIdleTimeout(30000);             // 30 second idle timeout
90

91
// Create connector with configuration
92
HttpConnectionFactory factory = new HttpConnectionFactory(httpConfig);
93
ServerConnector connector = new ServerConnector(server, factory);
94
```
95

96
## HTTP Customizers
97

98
Customizers modify requests during processing to add security headers, handle forwarded headers, and implement protocol features.
99

100
### SecureRequestCustomizer
101

102
Adds security features for HTTPS connections.
103

104
```java { .api }
105
public class SecureRequestCustomizer implements HttpConfiguration.Customizer {
106
    // HSTS (HTTP Strict Transport Security)
107
    public long getStsMaxAge();
108
    public void setStsMaxAge(long stsMaxAge);
109
    public boolean isStsIncludeSubDomains();
110
    public void setStsIncludeSubDomains(boolean stsIncludeSubDomains);
111
    
112
    // SNI (Server Name Indication)
113
    public boolean isSniRequired();
114
    public void setSniRequired(boolean sniRequired);
115
    public boolean isSniHostCheck();
116
    public void setSniHostCheck(boolean sniHostCheck);
117
    
118
    // Client certificates
119
    public Request customize(Request request, HttpConfiguration configuration);
120
}
121
```
122

123
### Usage Example
124

125
```java
126
// Create HTTPS configuration
127
HttpConfiguration httpsConfig = new HttpConfiguration();
128
httpsConfig.setSecureScheme("https");
129
httpsConfig.setSecurePort(8443);
130

131
// Add secure request customizer
132
SecureRequestCustomizer secureCustomizer = new SecureRequestCustomizer();
133
secureCustomizer.setStsMaxAge(31536000);           // 1 year HSTS
134
secureCustomizer.setStsIncludeSubDomains(true);    // Include subdomains
135
secureCustomizer.setSniRequired(false);            // SNI optional
136
secureCustomizer.setSniHostCheck(true);            // Validate SNI hostname
137
httpsConfig.addCustomizer(secureCustomizer);
138

139
// SSL context factory
140
SslContextFactory.Server sslContextFactory = new SslContextFactory.Server();
141
sslContextFactory.setKeyStorePath("keystore.jks");
142
sslContextFactory.setKeyStorePassword("password");
143

144
// Create HTTPS connector
145
ServerConnector httpsConnector = new ServerConnector(server,
146
    new SslConnectionFactory(sslContextFactory, "http/1.1"),
147
    new HttpConnectionFactory(httpsConfig));
148
httpsConnector.setPort(8443);
149
server.addConnector(httpsConnector);
150
```
151

152
### ForwardedRequestCustomizer
153

154
Handles X-Forwarded-* headers from reverse proxies.
155

156
```java { .api }
157
public class ForwardedRequestCustomizer implements HttpConfiguration.Customizer {
158
    // Header names
159
    public String getForwardedHeader();
160
    public void setForwardedHeader(String forwardedHeader);
161
    public String getForwardedHostHeader();
162
    public void setForwardedHostHeader(String forwardedHostHeader);
163
    public String getForwardedServerHeader();  
164
    public void setForwardedServerHeader(String forwardedServerHeader);
165
    public String getForwardedProtoHeader();
166
    public void setForwardedProtoHeader(String forwardedProtoHeader);
167
    public String getForwardedForHeader();
168
    public void setForwardedForHeader(String forwardedForHeader);
169
    public String getForwardedHttpsHeader();
170
    public void setForwardedHttpsHeader(String forwardedHttpsHeader);
171
    public String getForwardedSslSessionIdHeader();
172
    public void setForwardedSslSessionIdHeader(String forwardedSslSessionIdHeader);
173
    public String getForwardedCipherSuiteHeader();
174
    public void setForwardedCipherSuiteHeader(String forwardedCipherSuiteHeader);
175
    
176
    // Processing options
177
    public boolean getProxyAsAuthority();
178
    public void setProxyAsAuthority(boolean proxyAsAuthority);
179
    
180
    // Request customization
181
    public Request customize(Request request, HttpConfiguration configuration);
182
}
183
```
184

185
### Usage Example
186

187
```java
188
// Create HTTP configuration for reverse proxy
189
HttpConfiguration proxyConfig = new HttpConfiguration();
190

191
// Add forwarded request customizer
192
ForwardedRequestCustomizer forwardedCustomizer = new ForwardedRequestCustomizer();
193

194
// Configure standard headers
195
forwardedCustomizer.setForwardedHostHeader("X-Forwarded-Host");
196
forwardedCustomizer.setForwardedServerHeader("X-Forwarded-Server");
197
forwardedCustomizer.setForwardedProtoHeader("X-Forwarded-Proto");
198
forwardedCustomizer.setForwardedForHeader("X-Forwarded-For");
199

200
// Handle HTTPS detection
201
forwardedCustomizer.setForwardedHttpsHeader("X-Forwarded-HTTPS");
202

203
// Trust proxy for authority
204
forwardedCustomizer.setProxyAsAuthority(true);
205

206
proxyConfig.addCustomizer(forwardedCustomizer);
207

208
// Create connector
209
ServerConnector connector = new ServerConnector(server, 
210
    new HttpConnectionFactory(proxyConfig));
211
connector.setPort(8080);
212
```
213

214
### ProxyCustomizer
215

216
Handles HAProxy PROXY protocol for preserving client connection information.
217

218
```java { .api }
219
public class ProxyCustomizer implements HttpConfiguration.Customizer {
220
    // Request customization for PROXY protocol
221
    public Request customize(Request request, HttpConfiguration configuration);
222
}
223
```
224

225
### HostHeaderCustomizer
226

227
Validates and processes Host headers.
228

229
```java { .api }
230
public class HostHeaderCustomizer implements HttpConfiguration.Customizer {
231
    // Authority validation
232
    public String getServerAuthority();
233
    public void setServerAuthority(String serverAuthority);
234
    
235
    // Request customization
236
    public Request customize(Request request, HttpConfiguration configuration);
237
}
238
```
239

240
## Custom Customizer Implementation
241

242
```java
243
// Custom security headers customizer
244
public class SecurityHeadersCustomizer implements HttpConfiguration.Customizer {
245
    private final Map<String, String> securityHeaders;
246
    
247
    public SecurityHeadersCustomizer() {
248
        this.securityHeaders = new HashMap<>();
249
        
250
        // Default security headers
251
        securityHeaders.put("X-Content-Type-Options", "nosniff");
252
        securityHeaders.put("X-Frame-Options", "DENY");
253
        securityHeaders.put("X-XSS-Protection", "1; mode=block");
254
        securityHeaders.put("Referrer-Policy", "strict-origin-when-cross-origin");
255
        securityHeaders.put("Content-Security-Policy", 
256
            "default-src 'self'; script-src 'self' 'unsafe-inline'");
257
    }
258
    
259
    public void addHeader(String name, String value) {
260
        securityHeaders.put(name, value);
261
    }
262
    
263
    public void removeHeader(String name) {
264
        securityHeaders.remove(name);
265
    }
266
    
267
    @Override
268
    public Request customize(Request request, HttpConfiguration configuration) {
269
        // Wrap request to add response headers
270
        return new SecurityHeaderRequest(request, securityHeaders);
271
    }
272
}
273

274
// Request wrapper that adds security headers to response
275
public class SecurityHeaderRequest extends Request.Wrapper {
276
    private final Map<String, String> securityHeaders;
277
    
278
    public SecurityHeaderRequest(Request wrapped, Map<String, String> securityHeaders) {
279
        super(wrapped);
280
        this.securityHeaders = securityHeaders;
281
    }
282
    
283
    // Could override response to add headers, or use a response wrapper
284
    // Implementation depends on how you want to inject the headers
285
}
286

287
// Usage
288
HttpConfiguration config = new HttpConfiguration();
289
SecurityHeadersCustomizer securityCustomizer = new SecurityHeadersCustomizer();
290
securityCustomizer.addHeader("Permissions-Policy", 
291
    "geolocation=(), microphone=(), camera=()");
292
config.addCustomizer(securityCustomizer);
293
```
294

295
## Advanced Configuration
296

297
### HTTP Compliance Configuration
298

299
```java
300
// Configure HTTP compliance levels
301
HttpConfiguration config = new HttpConfiguration();
302

303
// Request cookie compliance
304
config.setRequestCookieCompliance(HttpCompliance.RFC6265);
305

306
// Response cookie compliance  
307
config.setResponseCookieCompliance(HttpCompliance.RFC6265);
308

309
// Create compliance violation listener
310
ComplianceViolation.Listener violationListener = new ComplianceViolation.Listener() {
311
    @Override
312
    public void onComplianceViolation(ComplianceViolation.Event event) {
313
        System.err.println("HTTP Compliance Violation: " + event.getDescription());
314
    }
315
};
316

317
config.addBean(violationListener);
318
```
319

320
### Multi-Configuration Setup
321

322
```java
323
public class MultiConfigurationServer {
324
    
325
    public void setupServer() {
326
        Server server = new Server();
327
        
328
        // Internal API configuration (relaxed)
329
        HttpConfiguration internalConfig = createInternalConfig();
330
        ServerConnector internalConnector = new ServerConnector(server,
331
            new HttpConnectionFactory(internalConfig));
332
        internalConnector.setHost("127.0.0.1");
333
        internalConnector.setPort(8081);
334
        
335
        // External API configuration (strict)
336
        HttpConfiguration externalConfig = createExternalConfig();
337
        ServerConnector externalConnector = new ServerConnector(server,
338
            new HttpConnectionFactory(externalConfig));
339
        externalConnector.setHost("0.0.0.0");
340
        externalConnector.setPort(8080);
341
        
342
        // HTTPS configuration
343
        HttpConfiguration httpsConfig = createHttpsConfig();
344
        SslContextFactory.Server sslContextFactory = createSslContextFactory();
345
        ServerConnector httpsConnector = new ServerConnector(server,
346
            new SslConnectionFactory(sslContextFactory, "http/1.1"),
347
            new HttpConnectionFactory(httpsConfig));
348
        httpsConnector.setPort(8443);
349
        
350
        server.setConnectors(new Connector[]{
351
            internalConnector, externalConnector, httpsConnector
352
        });
353
    }
354
    
355
    private HttpConfiguration createInternalConfig() {
356
        HttpConfiguration config = new HttpConfiguration();
357
        config.setOutputBufferSize(65536);    // Larger buffers for internal
358
        config.setRequestHeaderSize(16384);   // Allow larger headers
359
        config.setSendServerVersion(true);    // Include version for debugging
360
        return config;
361
    }
362
    
363
    private HttpConfiguration createExternalConfig() {
364
        HttpConfiguration config = new HttpConfiguration();
365
        config.setOutputBufferSize(32768);    // Standard buffers
366
        config.setRequestHeaderSize(8192);    // Standard header size
367
        config.setSendServerVersion(false);   // Hide version
368
        config.setSendXPoweredBy(false);      // Hide implementation
369
        
370
        // Add forwarded headers support for reverse proxy
371
        config.addCustomizer(new ForwardedRequestCustomizer());
372
        
373
        return config;
374
    }
375
    
376
    private HttpConfiguration createHttpsConfig() {
377
        HttpConfiguration config = new HttpConfiguration();
378
        config.setSecureScheme("https");
379
        config.setSecurePort(8443);
380
        
381
        // Add HTTPS security features
382
        SecureRequestCustomizer secureCustomizer = new SecureRequestCustomizer();
383
        secureCustomizer.setStsMaxAge(31536000);        // 1 year HSTS
384
        secureCustomizer.setStsIncludeSubDomains(true); // Include subdomains
385
        config.addCustomizer(secureCustomizer);
386
        
387
        return config;
388
    }
389
    
390
    private SslContextFactory.Server createSslContextFactory() {
391
        SslContextFactory.Server sslContextFactory = new SslContextFactory.Server();
392
        sslContextFactory.setKeyStorePath("keystore.jks");
393
        sslContextFactory.setKeyStorePassword("password");
394
        sslContextFactory.setIncludeProtocols("TLSv1.2", "TLSv1.3");
395
        return sslContextFactory;
396
    }
397
}
398
```
399

400
## Configuration Monitoring and Debugging
401

402
### Configuration Dumping
403

404
```java
405
// Dump configuration for debugging
406
HttpConfiguration config = new HttpConfiguration();
407
// ... configure ...
408

409
// Dump configuration to string
410
StringWriter writer = new StringWriter();
411
config.dump(writer, "");
412
System.out.println("HTTP Configuration:");
413
System.out.println(writer.toString());
414
```
415

416
### Dynamic Configuration Updates
417

418
```java
419
public class DynamicConfigurationManager {
420
    private final HttpConfiguration config;
421
    private final List<HttpConfiguration.Customizer> customizers;
422
    
423
    public DynamicConfigurationManager(HttpConfiguration config) {
424
        this.config = config;
425
        this.customizers = new ArrayList<>(config.getCustomizers());
426
    }
427
    
428
    public void updateBufferSizes(int outputBuffer, int headerSize) {
429
        config.setOutputBufferSize(outputBuffer);
430
        config.setRequestHeaderSize(headerSize);
431
        config.setResponseHeaderSize(headerSize);
432
    }
433
    
434
    public void enableSecurityHeaders() {
435
        SecurityHeadersCustomizer securityCustomizer = new SecurityHeadersCustomizer();
436
        config.addCustomizer(securityCustomizer);
437
    }
438
    
439
    public void disableServerIdentification() {
440
        config.setSendServerVersion(false);
441
        config.setSendXPoweredBy(false);
442
    }
443
    
444
    public void resetCustomizers() {
445
        // Remove all customizers
446
        config.getCustomizers().clear();
447
        
448
        // Restore original customizers
449
        for (HttpConfiguration.Customizer customizer : customizers) {
450
            config.addCustomizer(customizer);
451
        }
452
    }
453
}
454
```