0
# Configuration
1

2
Type-safe configuration system using builder patterns and Blueprint annotations for all server components, providing comprehensive control over server behavior, connections, and protocols.
3

4
## Capabilities
5

6
### WebServerConfig Interface
7

8
Main configuration interface for WebServer instances with comprehensive server settings.
9

10
```java { .api }
11
/**
12
 * Configuration for WebServer instances.
13
 */
14
interface WebServerConfig extends Prototype.Api {
15
    /**
16
     * Create builder for WebServer configuration.
17
     * @return configuration builder
18
     */
19
    static Builder builder();
20
    
21
    /**
22
     * Get server port configuration.
23
     * @return server port
24
     */
25
    int port();
26
    
27
    /**
28
     * Get bind address configuration.
29
     * @return bind address
30
     */
31
    String bindAddress();
32
    
33
    /**
34
     * Get backlog configuration for server socket.
35
     * @return backlog size
36
     */
37
    int backlog();
38
    
39
    /**
40
     * Get receive buffer size.
41
     * @return receive buffer size
42
     */
43
    int receiveBufferSize();
44
    
45
    /**
46
     * Get socket options.
47
     * @return socket options
48
     */
49
    Map<SocketOption<?>, Object> socketOptions();
50
    
51
    /**
52
     * Get TLS configuration.
53
     * @return TLS configuration if enabled
54
     */
55
    Optional<Tls> tls();
56
    
57
    /**
58
     * Get connection configuration.
59
     * @return connection configuration
60
     */
61
    ConnectionConfig connection();
62
    
63
    /**
64
     * Get listener configurations.
65
     * @return map of listener configurations by name
66
     */
67
    Map<String, ListenerConfig> listeners();
68
    
69
    /**
70
     * Get routing configuration.
71
     * @return routing configuration
72
     */
73
    Optional<Router> router();
74
    
75
    /**
76
     * Get protocol configurations.
77
     * @return protocol configurations
78
     */
79
    List<ProtocolConfig> protocols();
80
}
81
```
82

83
### WebServerConfig Builder
84

85
Builder for creating WebServer configurations with fluent API.
86

87
```java { .api }
88
/**
89
 * Builder for WebServer configuration.
90
 */
91
interface WebServerConfig.Builder extends io.helidon.common.Builder<Builder, WebServerConfig> {
92
    /**
93
     * Set server port.
94
     * @param port server port
95
     * @return updated builder
96
     */
97
    Builder port(int port);
98
    
99
    /**
100
     * Set bind address.
101
     * @param bindAddress bind address
102
     * @return updated builder
103
     */
104
    Builder bindAddress(String bindAddress);
105
    
106
    /**
107
     * Set socket backlog.
108
     * @param backlog backlog size
109
     * @return updated builder
110
     */
111
    Builder backlog(int backlog);
112
    
113
    /**
114
     * Set receive buffer size.
115
     * @param receiveBufferSize buffer size
116
     * @return updated builder
117
     */
118
    Builder receiveBufferSize(int receiveBufferSize);
119
    
120
    /**
121
     * Add socket option.
122
     * @param option socket option
123
     * @param value option value
124
     * @param <T> option type
125
     * @return updated builder
126
     */
127
    <T> Builder socketOption(SocketOption<T> option, T value);
128
    
129
    /**
130
     * Set TLS configuration.
131
     * @param tls TLS configuration
132
     * @return updated builder
133
     */
134
    Builder tls(Tls tls);
135
    
136
    /**
137
     * Set TLS configuration using builder.
138
     * @param tlsBuilder TLS builder consumer
139
     * @return updated builder
140
     */
141
    Builder tls(Consumer<Tls.Builder> tlsBuilder);
142
    
143
    /**
144
     * Set connection configuration.
145
     * @param connection connection configuration
146
     * @return updated builder
147
     */
148
    Builder connection(ConnectionConfig connection);
149
    
150
    /**
151
     * Set connection configuration using builder.
152
     * @param connectionBuilder connection builder consumer
153
     * @return updated builder
154
     */
155
    Builder connection(Consumer<ConnectionConfig.Builder> connectionBuilder);
156
    
157
    /**
158
     * Add named listener configuration.
159
     * @param name listener name
160
     * @param listener listener configuration
161
     * @return updated builder
162
     */
163
    Builder addListener(String name, ListenerConfig listener);
164
    
165
    /**
166
     * Add named listener using builder.
167
     * @param name listener name
168
     * @param listenerBuilder listener builder consumer
169
     * @return updated builder
170
     */
171
    Builder addListener(String name, Consumer<ListenerConfig.Builder> listenerBuilder);
172
    
173
    /**
174
     * Set router configuration.
175
     * @param router router configuration
176
     * @return updated builder
177
     */
178
    Builder router(Router router);
179
    
180
    /**
181
     * Set router using builder.
182
     * @param routerBuilder router builder consumer
183
     * @return updated builder
184
     */
185
    Builder router(Consumer<Router.Builder> routerBuilder);
186
    
187
    /**
188
     * Add routing configuration.
189
     * @param routing routing to add
190
     * @return updated builder
191
     */
192
    Builder routing(io.helidon.common.Builder<?, ? extends Routing> routing);
193
    
194
    /**
195
     * Add named routing configuration.
196
     * @param name routing name
197
     * @param routing routing to add
198
     * @return updated builder
199
     */
200
    Builder addNamedRouting(String name, io.helidon.common.Builder<?, ? extends Routing> routing);
201
    
202
    /**
203
     * Add protocol configuration.
204
     * @param protocol protocol configuration
205
     * @return updated builder
206
     */
207
    Builder addProtocol(ProtocolConfig protocol);
208
}
209
```
210

211
**Usage Examples:**
212

213
```java
214
import io.helidon.webserver.WebServerConfig;
215
import io.helidon.common.tls.Tls;
216
import java.net.StandardSocketOptions;
217

218
// Basic server configuration
219
WebServerConfig basicConfig = WebServerConfig.builder()
220
    .port(8080)
221
    .bindAddress("0.0.0.0")
222
    .backlog(1024)
223
    .build();
224

225
// Advanced server configuration
226
WebServerConfig advancedConfig = WebServerConfig.builder()
227
    .port(8443)
228
    .bindAddress("localhost")
229
    .backlog(2048)
230
    .receiveBufferSize(8192)
231
    
232
    // Socket options
233
    .socketOption(StandardSocketOptions.SO_KEEPALIVE, true)
234
    .socketOption(StandardSocketOptions.SO_REUSEADDR, true)
235
    .socketOption(StandardSocketOptions.TCP_NODELAY, true)
236
    
237
    // TLS configuration
238
    .tls(tls -> tls
239
        .keystore(keystore -> keystore
240
            .keystore(Paths.get("keystore.p12"))
241
            .keystorePassphrase("password"))
242
        .truststore(truststore -> truststore
243
            .truststore(Paths.get("truststore.p12"))
244
            .truststorePassphrase("password")))
245
    
246
    // Connection configuration
247
    .connection(conn -> conn
248
        .connectTimeout(Duration.ofSeconds(10))
249
        .readTimeout(Duration.ofSeconds(30))
250
        .maxConcurrentRequests(100))
251
    
252
    // Routing configuration
253
    .routing(HttpRouting.builder()
254
        .get("/health", (req, res) -> res.send("OK"))
255
        .get("/api/*", (req, res) -> res.send("API")))
256
    
257
    .build();
258

259
// Multi-listener configuration
260
WebServerConfig multiListenerConfig = WebServerConfig.builder()
261
    .port(8080) // Default listener
262
    
263
    // Admin listener on different port
264
    .addListener("admin", listener -> listener
265
        .port(8081)
266
        .bindAddress("127.0.0.1"))
267
    
268
    // Secure listener with TLS
269
    .addListener("secure", listener -> listener
270
        .port(8443)
271
        .tls(tlsConfig))
272
    
273
    // Default routing
274
    .routing(HttpRouting.builder()
275
        .get("/", (req, res) -> res.send("Main")))
276
    
277
    // Admin routing
278
    .addNamedRouting("admin", HttpRouting.builder()
279
        .get("/health", (req, res) -> res.send("Healthy"))
280
        .get("/metrics", (req, res) -> res.send("Metrics")))
281
    
282
    // Secure routing
283
    .addNamedRouting("secure", HttpRouting.builder()
284
        .get("/secure", (req, res) -> res.send("Secure content")))
285
    
286
    .build();
287
```
288

289
### ListenerConfig Interface
290

291
Configuration for individual server listeners with port and protocol settings.
292

293
```java { .api }
294
/**
295
 * Configuration for server listeners.
296
 */
297
interface ListenerConfig extends Prototype.Api {
298
    /**
299
     * Create builder for listener configuration.
300
     * @return configuration builder
301
     */
302
    static Builder builder();
303
    
304
    /**
305
     * Get listener port.
306
     * @return port number
307
     */
308
    int port();
309
    
310
    /**
311
     * Get listener bind address.
312
     * @return bind address
313
     */
314
    String bindAddress();
315
    
316
    /**
317
     * Get listener backlog.
318
     * @return backlog size
319
     */
320
    int backlog();
321
    
322
    /**
323
     * Get TLS configuration for this listener.
324
     * @return TLS configuration if enabled
325
     */
326
    Optional<Tls> tls();
327
    
328
    /**
329
     * Get connection configuration for this listener.
330
     * @return connection configuration
331
     */
332
    ConnectionConfig connection();
333
    
334
    /**
335
     * Get protocol configurations for this listener.
336
     * @return protocol configurations
337
     */
338
    List<ProtocolConfig> protocols();
339
    
340
    /**
341
     * Get socket options for this listener.
342
     * @return socket options
343
     */
344
    Map<SocketOption<?>, Object> socketOptions();
345
}
346
```
347

348
### ConnectionConfig Interface
349

350
Configuration for connection handling and timeouts.
351

352
```java { .api }
353
/**
354
 * Configuration for connections.
355
 */
356
interface ConnectionConfig extends Prototype.Api {
357
    /**
358
     * Create builder for connection configuration.
359
     * @return configuration builder
360
     */
361
    static Builder builder();
362
    
363
    /**
364
     * Get connect timeout.
365
     * @return connect timeout duration
366
     */
367
    Duration connectTimeout();
368
    
369
    /**
370
     * Get read timeout.
371
     * @return read timeout duration
372
     */
373
    Duration readTimeout();
374
    
375
    /**
376
     * Get connection idle timeout.
377
     * @return idle timeout duration
378
     */
379
    Duration idleTimeout();
380
    
381
    /**
382
     * Get maximum concurrent requests per connection.
383
     * @return max concurrent requests
384
     */
385
    int maxConcurrentRequests();
386
    
387
    /**
388
     * Get initial buffer size for connections.
389
     * @return initial buffer size
390
     */
391
    int initialBufferSize();
392
    
393
    /**
394
     * Get maximum buffer size for connections.
395
     * @return maximum buffer size
396
     */
397
    int maxBufferSize();
398
    
399
    /**
400
     * Get connection backpressure buffer size.
401
     * @return backpressure buffer size
402
     */
403
    int backpressureBufferSize();
404
    
405
    /**
406
     * Check if connection pooling is enabled.
407
     * @return true if connection pooling enabled
408
     */
409
    boolean connectionPooling();
410
}
411
```
412

413
**Usage Examples:**
414

415
```java
416
import io.helidon.webserver.ConnectionConfig;
417
import java.time.Duration;
418

419
// Basic connection configuration
420
ConnectionConfig basicConnection = ConnectionConfig.builder()
421
    .connectTimeout(Duration.ofSeconds(10))
422
    .readTimeout(Duration.ofSeconds(30))
423
    .idleTimeout(Duration.ofMinutes(5))
424
    .build();
425

426
// High-performance connection configuration
427
ConnectionConfig highPerfConnection = ConnectionConfig.builder()
428
    .connectTimeout(Duration.ofSeconds(5))
429
    .readTimeout(Duration.ofSeconds(60))
430
    .idleTimeout(Duration.ofMinutes(10))
431
    .maxConcurrentRequests(1000)
432
    .initialBufferSize(16384)
433
    .maxBufferSize(1048576) // 1MB
434
    .backpressureBufferSize(65536)
435
    .connectionPooling(true)
436
    .build();
437

438
// Use in server configuration
439
WebServerConfig serverConfig = WebServerConfig.builder()
440
    .port(8080)
441
    .connection(highPerfConnection)
442
    .build();
443
```
444

445
### ErrorHandling Interface
446

447
Configuration for error handling behavior.
448

449
```java { .api }
450
/**
451
 * Configuration for error handling.
452
 */
453
interface ErrorHandling extends Prototype.Api {
454
    /**
455
     * Create builder for error handling configuration.
456
     * @return configuration builder
457
     */
458
    static Builder builder();
459
    
460
    /**
461
     * Check if stack traces should be sent in error responses.
462
     * @return true if stack traces should be sent
463
     */
464
    boolean sendStackTrace();
465
    
466
    /**
467
     * Check if debugging information should be included.
468
     * @return true if debug info should be included
469
     */
470
    boolean debug();
471
    
472
    /**
473
     * Get custom error page mappings.
474
     * @return map of status codes to error page paths
475
     */
476
    Map<Integer, String> errorPages();
477
    
478
    /**
479
     * Get default error content type.
480
     * @return default content type for error responses
481
     */
482
    MediaType defaultErrorContentType();
483
}
484
```
485

486
**Usage Examples:**
487

488
```java
489
import io.helidon.webserver.ErrorHandling;
490
import io.helidon.http.MediaType;
491

492
// Development error handling (includes stack traces)
493
ErrorHandling devErrorHandling = ErrorHandling.builder()
494
    .sendStackTrace(true)
495
    .debug(true)
496
    .defaultErrorContentType(MediaType.APPLICATION_JSON)
497
    .build();
498

499
// Production error handling (no stack traces)
500
ErrorHandling prodErrorHandling = ErrorHandling.builder()
501
    .sendStackTrace(false)
502
    .debug(false)
503
    .errorPages(Map.of(
504
        404, "/errors/404.html",
505
        500, "/errors/500.html"
506
    ))
507
    .defaultErrorContentType(MediaType.TEXT_HTML)
508
    .build();
509
```
510

511
## Configuration Patterns
512

513
### Environment-Based Configuration
514

515
```java
516
import io.helidon.config.Config;
517

518
// Load configuration from environment and config files
519
Config config = Config.create();
520

521
WebServerConfig serverConfig = WebServerConfig.builder()
522
    .port(config.get("server.port").asInt().orElse(8080))
523
    .bindAddress(config.get("server.host").asString().orElse("0.0.0.0"))
524
    .connection(conn -> conn
525
        .connectTimeout(config.get("server.connect-timeout")
526
                             .as(Duration.class)
527
                             .orElse(Duration.ofSeconds(10)))
528
        .readTimeout(config.get("server.read-timeout")
529
                           .as(Duration.class)
530
                           .orElse(Duration.ofSeconds(30)))
531
        .maxConcurrentRequests(config.get("server.max-concurrent-requests")
532
                                    .asInt()
533
                                    .orElse(100)))
534
    .build();
535
```
536

537
### Profile-Based Configuration
538

539
```java
540
public class ServerConfigFactory {
541
    
542
    public static WebServerConfig createDevelopmentConfig() {
543
        return WebServerConfig.builder()
544
            .port(8080)
545
            .bindAddress("localhost")
546
            .connection(conn -> conn
547
                .connectTimeout(Duration.ofSeconds(30))
548
                .readTimeout(Duration.ofMinutes(5))
549
                .maxConcurrentRequests(10))
550
            .build();
551
    }
552
    
553
    public static WebServerConfig createProductionConfig() {
554
        return WebServerConfig.builder()
555
            .port(80)
556
            .bindAddress("0.0.0.0")
557
            .backlog(8192)
558
            .receiveBufferSize(32768)
559
            .connection(conn -> conn
560
                .connectTimeout(Duration.ofSeconds(5))
561
                .readTimeout(Duration.ofSeconds(30))
562
                .idleTimeout(Duration.ofMinutes(2))
563
                .maxConcurrentRequests(1000)
564
                .initialBufferSize(16384)
565
                .maxBufferSize(2097152)
566
                .connectionPooling(true))
567
            .tls(tls -> tls
568
                .keystore(keystore -> keystore
569
                    .keystore(Paths.get("/etc/ssl/server.p12"))
570
                    .keystorePassphrase(System.getenv("KEYSTORE_PASSWORD")))
571
                .protocols("TLSv1.3", "TLSv1.2")
572
                .cipherSuites("TLS_AES_256_GCM_SHA384", "TLS_AES_128_GCM_SHA256"))
573
            .build();
574
    }
575
}
576
```
577

578
### Dynamic Configuration
579

580
```java
581
public class DynamicServerConfig {
582
    private final AtomicReference<WebServerConfig> currentConfig;
583
    private final ConfigWatcher configWatcher;
584
    
585
    public DynamicServerConfig(Config initialConfig) {
586
        this.currentConfig = new AtomicReference<>(buildConfig(initialConfig));
587
        this.configWatcher = ConfigWatcher.create(initialConfig);
588
        
589
        configWatcher.onChange(this::updateConfiguration);
590
    }
591
    
592
    private void updateConfiguration(Config newConfig) {
593
        WebServerConfig newServerConfig = buildConfig(newConfig);
594
        WebServerConfig oldConfig = currentConfig.getAndSet(newServerConfig);
595
        
596
        // Apply configuration changes
597
        applyConfigurationChanges(oldConfig, newServerConfig);
598
    }
599
    
600
    private WebServerConfig buildConfig(Config config) {
601
        return WebServerConfig.builder()
602
            .port(config.get("server.port").asInt().orElse(8080))
603
            .connection(conn -> conn
604
                .connectTimeout(config.get("server.timeouts.connect")
605
                                     .as(Duration.class)
606
                                     .orElse(Duration.ofSeconds(10)))
607
                .readTimeout(config.get("server.timeouts.read")
608
                                   .as(Duration.class)
609
                                   .orElse(Duration.ofSeconds(30)))
610
                .maxConcurrentRequests(config.get("server.limits.concurrent-requests")
611
                                            .asInt()
612
                                            .orElse(100)))
613
            .build();
614
    }
615
}
616
```
617

618
### Configuration Validation
619

620
```java
621
public class ConfigurationValidator {
622
    
623
    public static void validateServerConfig(WebServerConfig config) {
624
        // Validate port range
625
        if (config.port() < 1 || config.port() > 65535) {
626
            throw new IllegalArgumentException("Port must be between 1 and 65535");
627
        }
628
        
629
        // Validate connection settings
630
        ConnectionConfig conn = config.connection();
631
        if (conn.connectTimeout().isNegative()) {
632
            throw new IllegalArgumentException("Connect timeout cannot be negative");
633
        }
634
        
635
        if (conn.maxConcurrentRequests() < 1) {
636
            throw new IllegalArgumentException("Max concurrent requests must be at least 1");
637
        }
638
        
639
        // Validate buffer sizes
640
        if (conn.initialBufferSize() > conn.maxBufferSize()) {
641
            throw new IllegalArgumentException("Initial buffer size cannot exceed max buffer size");
642
        }
643
        
644
        // Validate listeners
645
        config.listeners().forEach((name, listener) -> {
646
            if (listener.port() == config.port() && 
647
                listener.bindAddress().equals(config.bindAddress())) {
648
                throw new IllegalArgumentException(
649
                    "Listener '" + name + "' conflicts with default listener");
650
            }
651
        });
652
    }
653
    
654
    public static WebServerConfig createValidatedConfig(
655
            Consumer<WebServerConfig.Builder> configurer) {
656
        WebServerConfig.Builder builder = WebServerConfig.builder();
657
        configurer.accept(builder);
658
        WebServerConfig config = builder.build();
659
        
660
        validateServerConfig(config);
661
        return config;
662
    }
663
}
664
```