0
# Helidon WebServer
1

2
Helidon WebServer is a modern, high-performance HTTP server implementation that leverages Java 21 Virtual Threads to provide excellent throughput with thread-per-request simplicity. It serves as the core web server component of the Helidon microservices framework, supporting both Helidon SE (functional style) and Helidon MP (MicroProfile) programming models.
3

4
## Package Information
5

6
- **Package Name**: helidon-webserver
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: io.helidon.webserver
10
- **Artifact ID**: helidon-webserver
11
- **Version**: 4.2.2
12
- **Installation**: Add to Maven `pom.xml`:
13

14
```xml
15
<dependency>
16
    <groupId>io.helidon.webserver</groupId>
17
    <artifactId>helidon-webserver</artifactId>
18
    <version>4.2.2</version>
19
</dependency>
20
```
21

22
## Core Imports
23

24
```java
25
import io.helidon.webserver.WebServer;
26
import io.helidon.webserver.WebServerConfig;
27
import io.helidon.webserver.http.HttpRouting;
28
import io.helidon.webserver.http.Handler;
29
import io.helidon.webserver.http.ServerRequest;
30
import io.helidon.webserver.http.ServerResponse;
31
```
32

33
## Basic Usage
34

35
```java
36
import io.helidon.webserver.WebServer;
37
import io.helidon.webserver.http.HttpRouting;
38

39
public class HelloWorldServer {
40
    public static void main(String[] args) {
41
        // Create HTTP routing
42
        HttpRouting routing = HttpRouting.builder()
43
            .get("/hello", (req, res) -> res.send("Hello World!"))
44
            .get("/users/{id}", (req, res) -> {
45
                String userId = req.path().pathParameters().get("id");
46
                res.send("User ID: " + userId);
47
            })
48
            .post("/users", (req, res) -> {
49
                // Handle user creation
50
                res.status(201).send("User created");
51
            })
52
            .build();
53

54
        // Create and start the server
55
        WebServer server = WebServer.builder()
56
            .routing(routing)
57
            .port(8080)
58
            .build()
59
            .start();
60

61
        System.out.println("Server started at: http://localhost:" + server.port());
62
    }
63
}
64
```
65

66
## Architecture
67

68
Helidon WebServer is built around several key components:
69

70
- **WebServer**: The main server interface that manages listeners and lifecycles
71
- **Router**: Generic routing system supporting multiple protocols (HTTP, WebSocket, etc.)
72
- **HTTP Routing**: HTTP-specific routing with method-based handlers and filters
73
- **Virtual Thread Support**: Built-in support for Java 21 Virtual Threads for high concurrency
74
- **Protocol Abstraction**: Extensible architecture supporting HTTP/1.1, HTTP/2, and custom protocols
75
- **Service Provider Interface (SPI)**: Extensibility points for custom features and protocols
76

77
## Capabilities
78

79
### Server Management
80

81
Core server lifecycle management, configuration, and listener control. Essential for creating and managing HTTP servers with multiple protocols and configurations.
82

83
```java { .api }
84
interface WebServer extends RuntimeType.Api<WebServerConfig> {
85
    static WebServer create(WebServerConfig serverConfig);
86
    static WebServer create(Consumer<WebServerConfig.Builder> builderConsumer);
87
    static WebServerConfig.Builder builder();
88
    
89
    WebServer start();
90
    WebServer stop();
91
    boolean isRunning();
92
    int port();
93
    int port(String socketName);
94
    boolean hasTls();
95
    boolean hasTls(String socketName);
96
    void reloadTls(Tls tls);
97
    void reloadTls(String socketName, Tls tls);
98
    Context context();
99
}
100
```
101

102
[Server Management](./server-management.md)
103

104
### HTTP Routing
105

106
HTTP-specific routing system with method-based handlers, filters, and comprehensive request/response processing. Supports RESTful APIs, middleware, and error handling.
107

108
```java { .api }
109
interface HttpRouting extends Routing, Prototype.Api {
110
    static Builder builder();
111
    static HttpRouting create();
112
    static HttpRouting empty();
113
    
114
    void route(ConnectionContext ctx, RoutingRequest request, RoutingResponse response);
115
    HttpSecurity security();
116
    Class<? extends Routing> routingType();
117
}
118

119
interface HttpRouting.Builder extends HttpRules, io.helidon.common.Builder<Builder, HttpRouting> {
120
    Builder register(HttpService... service);
121
    Builder register(String path, HttpService... service);
122
    Builder route(HttpRoute route);
123
    Builder get(String pathPattern, Handler... handlers);
124
    Builder post(String pathPattern, Handler... handlers);
125
    Builder put(String pathPattern, Handler... handlers);
126
    Builder delete(String pathPattern, Handler... handlers);
127
    Builder addFilter(Filter filter);
128
    Builder addFeature(HttpFeature feature);
129
    <T extends Throwable> Builder error(Class<T> exceptionClass, ErrorHandler<? super T> handler);
130
}
131
```
132

133
[HTTP Routing](./http-routing.md)
134

135
### Request and Response Handling
136

137
Complete HTTP request and response interfaces with entity handling, headers, parameters, and content negotiation.
138

139
```java { .api }
140
interface ServerRequest extends HttpRequest {
141
    // Request interface methods
142
}
143

144
interface ServerResponse {
145
    // Response interface methods  
146
}
147

148
interface Handler {
149
    void handle(ServerRequest req, ServerResponse res);
150
    
151
    static Handler create(Consumer<ServerRequest> handler);
152
    static Handler create(Function<ServerRequest, ?> handler);
153
    static Handler create(Supplier<?> handler);
154
}
155
```
156

157
[Request and Response Handling](./request-response.md)
158

159
### HTTP Services and Features
160

161
Modular service system for creating reusable HTTP components, middleware, and features that can be registered with routing.
162

163
```java { .api }
164
interface HttpService {
165
    void routing(HttpRules rules);
166
}
167

168
interface HttpFeature {
169
    void setup(HttpRouting.Builder routing);
170
}
171

172
interface Filter {
173
    void filter(FilterChain chain, RoutingRequest req, RoutingResponse res);
174
}
175

176
interface ErrorHandler<T extends Throwable> {
177
    void handle(ServerRequest req, ServerResponse res, T throwable);
178
}
179
```
180

181
[HTTP Services and Features](./http-services.md)
182

183
### Configuration
184

185
Type-safe configuration system using builder patterns and Blueprint annotations for all server components.
186

187
```java { .api }
188
interface WebServerConfig extends Prototype.Api {
189
    static Builder builder();
190
    // Configuration methods
191
}
192

193
interface ListenerConfig extends Prototype.Api {
194
    static Builder builder();
195
    // Listener configuration methods
196
}
197

198
interface ConnectionConfig extends Prototype.Api {
199
    static Builder builder();
200
    // Connection configuration methods
201
}
202
```
203

204
[Configuration](./configuration.md)
205

206
### HTTP/1.1 Protocol Implementation
207

208
Complete HTTP/1.1 protocol implementation with connection management, request parsing, and response generation.
209

210
```java { .api }
211
interface Http1Config extends Prototype.Api {
212
    static Builder builder();
213
    // HTTP/1.1 specific configuration
214
}
215

216
class Http1Connection implements ServerConnection {
217
    // HTTP/1.1 connection implementation
218
}
219

220
class Http1ServerRequest implements ServerRequest {
221
    // HTTP/1.1 request implementation
222
}
223

224
class Http1ServerResponse implements ServerResponse {
225
    // HTTP/1.1 response implementation
226
}
227
```
228

229
[HTTP/1.1 Protocol](./http1-protocol.md)
230

231
### Service Provider Interface (SPI)
232

233
Extension points for custom protocols, features, and connection handling. Enables third-party integrations and custom server functionality.
234

235
```java { .api }
236
interface ServerFeature {
237
    // Server feature SPI
238
}
239

240
interface ProtocolConfigProvider {
241
    // Protocol configuration provider SPI
242
}
243

244
interface ServerConnectionSelectorProvider {
245
    // Connection selector provider SPI
246
}
247

248
interface SinkProvider {
249
    // Streaming response provider SPI
250
}
251
```
252

253
[Service Provider Interface](./spi.md)
254

255
## Common Types
256

257
```java { .api }
258
interface Routing {
259
    Class<? extends Routing> routingType();
260
}
261

262
interface Route {
263
    // Base route interface
264
}
265

266
interface ConnectionContext {
267
    // Connection context interface
268
}
269

270
class CloseConnectionException extends RuntimeException {
271
    // Exception to close connections
272
}
273

274
class ServerConnectionException extends RuntimeException {
275
    // Server connection related exceptions
276
}
277
```
278

279
## Error Handling
280

281
Helidon WebServer provides comprehensive error handling through:
282

283
- **ErrorHandler<T>**: Type-safe exception handlers for specific exception types
284
- **Global error handlers**: Default error handling for unhandled exceptions
285
- **HTTP status mapping**: Automatic HTTP status code assignment based on exception types
286
- **Custom error responses**: Full control over error response format and content