The easiest way to configure the WebServer is in your application code.

WebServer.builder()
        .port(8080)
        .build()
        .start();

You can also define the configuration in a file.

server:
  port: 8080
  host: "0.0.0.0"

Then, in your application code, load the configuration from that file.

Config config = Config.create(); 
WebServer.builder()
        .config(config.get("server")); 

• application.yaml is a default configuration source loaded when YAML support is on classpath, so we can just use Config.create()
• Server expects the configuration tree located on the node of server

Configure TLS either programmatically, or by the Helidon configuration framework.

Configuring TLS in Your Code

Tls tls = Tls.builder()
        .privateKey(pk -> pk
                .keystore(keys -> keys.keystore(it -> it.resourcePath("private-key.p12"))
                        .passphrase("password".toCharArray())))
        .trust(trust -> trust
                .keystore(keys -> keys.keystore(it -> it.resourcePath("trust.p12"))))
        .build();

WebServer.builder()
        .tls(tls);

Configuring TLS in the Config File

server:
  tls:
    #Truststore setup
    trust:
      keystore:
        passphrase: "password"
        trust-store: true
        resource:
          # load from classpath
          resource-path: "keystore.p12" 
    # Keystore with private key and server certificate
    private-key:
      keystore:
        passphrase: "password"
        resource:
          # load from file system
          path: "/path/to/keystore.p12" 

Config config = Config.create(); 
WebServer.builder()
        .config(config.get("server")); 

Config config = Config.create();
WebServer.builder()
        .tls(it -> it.config(config.get("server.tls")));

server:
  tls:
    #Truststore setup
    trust:
      pem:
        certificates:
          resource:
            resource-path: "ca-bundle.pem"
    private-key:
      pem:
        key:
          resource:
            resource-path: "key.pem"
        cert-chain:
          resource:
            resource-path: "chain.pem"

Configuration options

Routing also supports Error Routing which binds Java Throwable to the handling logic.

Configure HTTP request routing using HttpRouting.Builder.

WebServer.builder()
        .routing(it -> it
                .get("/hello", (req, res) -> res.send("Hello World!"))) 
        .build(); 

• Handle all GETs to /hello path. Send the Hello World! string.
• Create a server instance with the provided routing

HttpRouting.Builder lets you specify how to handle each HTTP method. For example:

You can combine HTTP method routing with request path matching.

routing.post("/some/path", (req, res) -> { /* handler */ });

You can use path pattern instead of path with the following syntax:

• /foo/bar/baz - Exact path match against resolved path even with non-usual characters

• /foo/* - convenience method to match /foo or any subpath (but not /foobar)

• /foo/{}/baz - {} Unnamed regular expression segment ([^/]+)

• /foo/{var}/baz - Named regular expression segment ([^/]+)

• /foo/{var:\d+} - Named regular expression segment with a specified expression

• /foo/{:\d+} - Unnamed regular expression segment with a specified expression

• /foo/{+var} - Convenience shortcut for {var:.+}

• /foo/{+} - Convenience shortcut for unnamed segment with regular expression {:.+}

• /foo/{*} - Convenience shortcut for unnamed segment with regular expression {:.*}

• /foo[/bar] - An optional block, which translates to the /foo(/bar)? regular expression

• /* or /foo* - * Wildcard character can be matched with any number of characters.

For more precise setup of path, you can use factory methods on io.helidon.http.PathMatchers and register using HttpRouting.Builder.route(Predicate<Method>, PathMatcher, Handler) method.

To have more control over selecting which requests should be handled by a specific route, you can use the io.helidon.webserver.http.HttpRoute interface using its Builder.

routing.route(HttpRoute.builder()
                      .path("/hello")
                      .methods(Method.POST, Method.PUT) 
                      .handler((req, res) -> {
                          String requestEntity = req.content().as(String.class);
                          res.send(requestEntity); 
                      }));

• The route is specified for GET and POST requests
• The handler consumes the request payload and echoes it back

By implementing the io.helidon.webserver.http.HttpService interface you can organize your code into one or more services, each with its own path prefix and set of handlers.

routing.register("/hello", new HelloService());

class HelloService implements HttpService {
    @Override
    public void routing(HttpRules rules) {
        rules.get("/subpath", (req, res) -> {
            // Some logic
        });
    }
}

In this example, the GET handler matches requests to /hello/subpath.

In Helidon 4 your HttpService can interpose on the server lifecycle by overriding the beforeStart and afterStop methods:

static class MyService implements HttpService {
    @Override
    public void beforeStart() {
        System.out.println("MyService: Helidon WebServer is starting!");
    }

    @Override
    public void afterStop() {
        System.out.println("MyService: Helidon WebServer has stopped.");
    }

By implementing the io.helidon.webserver.http.HttpFeature interface, you can organize multiple routes and/or filters into a feature, that will be setup according to its defined io.helidon.common.Weight (or using io.helidon.common.Weighted).

Each service has access to the routing builder. HTTP Features are configured for each routing builder. If there is a need to configure a feature for multiple sockets, you can use Server Feature instead.

Each Handler has two parameters. ServerRequest and ServerResponse.

• Request provides access to the request method, URI, path, query parameters, headers and entity.

• Response provides an ability to set response code, headers, and entity.

Filtering can be done either using a dedicated Filter, or through routes.

Filter

routing.addFilter((chain, req, res) -> {
    try {
        chain.proceed();
    } finally {
        // do something for any finished request
    }
});

Routes

To complete the request handling, you must send a response by calling the res.send() method.

rules.get("/hello", (req, res) -> { 
    // terminating logic
    res.status(Status.ACCEPTED_202)
            .send("Saved!"); 
});

• handler that terminates the request handling for any HTTP method using the /hello path
• send the response

To set up requested URI discovery on the default socket for your server, use the WebServerConfig.Builder:

import io.helidon.common.configurable.AllowList;
import jakarta.json.Json;
import jakarta.json.JsonBuilderFactory;
import jakarta.json.JsonObject;

import static io.helidon.http.RequestedUriDiscoveryContext.RequestedUriDiscoveryType.FORWARDED;
import static io.helidon.http.RequestedUriDiscoveryContext.RequestedUriDiscoveryType.X_FORWARDED;

AllowList trustedProxies = AllowList.builder()
        .addAllowedPattern(Pattern.compile("lb.+\\.mycorp\\.com"))
        .addDenied("lbtest.mycorp.com")
        .build(); 

WebServer.builder()
        .requestedUriDiscoveryContext(it -> it
                .addDiscoveryType(FORWARDED) 
                .addDiscoveryType(X_FORWARDED)
                .trustedProxies(trustedProxies)); 

• Create the AllowList describing the intermediate networks nodes to trust and not trust. Presumably the lbxxx.mycorp.com nodes are trusted load balancers except for the test load balancer lbtest, and no other nodes are trusted. AllowList accepts prefixes, suffixes, predicates, regex patterns, and exact matches. See the AllowList JavaDoc for complete information.
• Use Forwarded first, then try X-Forwarded-* on each request.
• Set the AllowList for trusted intermediaries.

If you build your server with additional sockets, you can control requested URI discovery separately for each.

You can also use configuration to set up the requested URI discovery behavior. The following example replicates the settings assigned programmatically in the earlier code example:

server:
  port: 0
  requested-uri-discovery:
    types: FORWARDED,X_FORWARDED
    trusted-proxies:
      allow:
        pattern: "lb.*\\.mycorp\\.com"
      deny:
        exact: "lbtest.mycorp.com""

Your code obtains the requested URI information from the Helidon server request object:

import io.helidon.common.tls.Tls;
import io.helidon.common.uri.UriInfo;

rules.get((req, res) -> {
    UriInfo uriInfo = req.requestedUri();
    // ...
});

See the UriInfo JavaDoc for more information.

You may register an error handler for a specific Throwable in a HttpRouting.Builder method.

routing.error(MyException.class, (req, res, ex) -> { 
    // handle the error, set the HTTP status code
    res.send(errorDescriptionObject); 
});

• Registers an error handler that handles MyException that are thrown from the upstream handlers
• Finishes the request handling by sending a response

Error handlers are called when

• an exception is thrown from a handler

As with the standard handlers, the error handler must either

• send a response

  routing.error(MyException.class, (req, res, ex) -> {
      res.status(Status.BAD_REQUEST_400);
      res.send("Unable to parse request. Message: " + ex.getMessage());
  });

  content_copy Copied

• or throw an exception

  routing.error(MyException.class, (req, res, ex) -> {
      // some logic
      throw ex;
  });

  content_copy Copied

Exceptions thrown from error handlers are not error handled, and will end up in an InternalServerError.

If no user-defined error handler is matched, or if the error handler of the exception threw an exception, then the exception is translated to an HTTP response as follows:

• Subtypes of HttpException are translated to their associated HTTP error codes.

  Reply with the 406 HTTP error code by throwing an exception

  rules.get((req, res) -> {
      throw new HttpException(
              "Amount of money must be greater than 0.",
              Status.NOT_ACCEPTABLE_406); 
  });

  content_copy Copied

• Otherwise, the exceptions are translated to an Internal Server Error HTTP error code 500.

There are a number of scenarios where errors can be detected before the request routing phase is initiated, some of these include: error validating requests (e.g. a bad URI), CORS rejections, invalid payloads, unsupported HTTP versions, etc. For all these type of events, Helidon provides the so-called direct handlers. The complete list of events that are handled in this way is defined by the enum EventType.

Direct handlers can be configured independently for each port exposed by the Webserver; similar to other config, if configured directly on the Webserver they will only apply to the default port. For more information see directHandlers method in ListenerConfig.

The following example shows how to register a custom handler for a request that is deemed invalid before the routing phase stars. The custom handler in this example simply returns a status code of 400 and a message that references the server log.

public static void main(String[] args) {
    WebServer server = WebServer.builder()
            .directHandlers(DirectHandlers.builder()
                    .addHandler(EventType.BAD_REQUEST, new MyDirectHandler())
                    .build())
            .build()
            .start();
}

static class MyDirectHandler implements DirectHandler {

    @Override
    public TransportResponse handle(TransportRequest transportRequest,
                                    EventType eventType,
                                    Status status,
                                    ServerResponseHeaders serverResponseHeaders,
                                    String s) {
        return DirectHandler.TransportResponse.builder()
                .status(Status.BAD_REQUEST_400)
                .entity("Bad request, see server log")
                .build();
    }
}

Default Direct Error Handler

server:
  error-handling:
    include-entity: true
    log-all-messages: true

Configuration options

Context feature adds a filter that executes all requests within the context of io.helidon.common.context.Context. A Context instance is available on ServerRequest even if this feature is not added. This feature adds support for obtaining request context through io.helidon.common.context.Contexts.context().

This feature will provide the same behavior as previous versions of Helidon. Since Helidon 4.0.0, this feature is not automatically added.

To enable execution of routes within Context, add the following dependency to project’s pom.xml:

<dependency>
    <groupId>io.helidon.webserver</groupId>
    <artifactId>helidon-webserver-context</artifactId>
</dependency>

Context feature can be configured, all options shown below are also available both in config, and programmatically when using builder.

• server.features.context

See the manifest for all available types.

Access logging in Helidon is done by a dedicated module that can be added to WebServer and configured.

Access logging is a Helidon WebServer ServerFeature. Access Log feature has a very high weight, so it is registered before other features (such as security) that may terminate a request. This is to ensure the log contains all requests with appropriate status codes.

To enable Access logging add the following dependency to project’s pom.xml:

<dependency>
    <groupId>io.helidon.webserver</groupId>
    <artifactId>helidon-webserver-access-log</artifactId>
</dependency>

Configuring Access Log in Your Code

WebServer.builder()
        .addFeature(AccessLogFeature.builder()
                            .commonLogFormat()
                            .build());

Configuring Access Log in a Configuration File

server:
  port: 8080
  features:
    access-log:
      format: "%h %l %u %t %r %s %b %{Referer}i"

• server.features.access-log

See the manifest for all available types.

To enable HTTP/2 support add the following dependency to your project’s pom.xml.

<dependency>
    <groupId>io.helidon.webserver</groupId>
    <artifactId>helidon-webserver-http2</artifactId>
</dependency>

To enable Static Content Support add the following dependency to your project’s pom.xml.

<dependency>
    <groupId>io.helidon.webserver</groupId>
    <artifactId>helidon-webserver-static-content</artifactId>
</dependency>

To register static content based on a file system (/pictures), and classpath (/):

builder.addFeature(StaticContentFeature.builder() 
                           .addPath(p -> p.location(Paths.get("/some/WEB/pics")) 
                                   .context("/pictures")) 
                           .addClasspath(cl -> cl.location("/static-content") 
                                   .welcome("index.html") 
                                   .context("/")) 
                           .build());

• Create a new StaticContentFeature to register with the web server (will be served on all sockets by default)
• Add path location served from /some/WEB/pics absolute path
• Associate the path location with server context /pictures
• Add classpath location to serve resources from the contextual ClassLoader from location /static-content
• index.html is the file that is returned if a directory is requested
• serve the classpath content on root context /

Static content can also be registered using the configuration of server feature.

If you use Config with your webserver setup, you can register the same static content using configuration:

server:
  features:
    static-content:
      path:
        - context: "/pictures"
          location: "/some/WEB/pics"
      classpath:
        - context: "/"
          welcome: "index.html"
          location: "/static-content"

See Static Content Feature Configuration Reference for details of configuration options.

The WebServer supports JSON-P. When enabled, you can send and receive JSON-P objects transparently.

Maven Coordinates

<dependency>
    <groupId>io.helidon.http.media</groupId>
    <artifactId>helidon-http-media-jsonp</artifactId>
</dependency>

Usage

static final JsonBuilderFactory JSON_FACTORY = Json.createBuilderFactory(Map.of()); 

rules.post("/hello", (req, res) -> {
    JsonObject requestEntity = req.content().as(JsonObject.class); 
    JsonObject responseEntity = JSON_FACTORY.createObjectBuilder() 
            .add("message", "Hello " + requestEntity.getString("name"))
            .build();
    res.send(responseEntity); 
});

curl --noproxy '*' -X POST -H "Content-Type: application/json" \
    http://localhost:8080/sayhello -d '{"name":"Joe"}'

{"message":"Hello Joe"}

The WebServer supports the JSON-B specification. When this support is enabled, Java objects will be serialized to and deserialized from JSON automatically using Yasson, an implementation of the JSON-B specification.

Maven Coordinates

<dependency>
    <groupId>io.helidon.http.media</groupId>
    <artifactId>helidon-http-media-jsonb</artifactId>
</dependency>

Configuration

jsonb:
  boolean-properties:
    jsonb.null-values: true
  properties:
    jsonb.property-naming-strategy: "LOWER_CASE_WITH_DASHES"

Usage

public class Person {

    private String name;

    public Person() {
        super();
    }

    public String getName() {
        return this.name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

rules.post("/echo", (req, res) -> {
    res.send(req.content().as(Person.class)); 
});

curl --noproxy '*' -X POST -H "Content-Type: application/json" \
    http://localhost:8080/echo -d '{"name":"Joe"}'
{"name":"Joe"}

The WebServer supports Jackson. When this support is enabled, Java objects will be serialized to and deserialized from JSON automatically using Jackson.

Maven Coordinates

<dependency>
    <groupId>io.helidon.http.media</groupId>
    <artifactId>helidon-http-media-jackson</artifactId>
</dependency>

Configuration

jackson:
  properties:
    FAIL_ON_UNKNOWN_PROPERTIES: false

Usage

public class Person {

    private String name;

    public Person() {
        super();
    }

    public String getName() {
        return this.name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

rules.post("/echo", (req, res) -> {
    res.send(req.content().as(Person.class)); 
});

curl --noproxy '*' -X POST -H "Content-Type: application/json" \
    http://localhost:8080/echo -d '{"name":"Joe"}'

{"name":"Joe"}

The WebServer supports Gson. When this support is enabled, Java objects will be serialized to and deserialized from JSON automatically using Gson.

Maven Coordinates

<dependency>
    <groupId>io.helidon.http.media</groupId>
    <artifactId>helidon-http-media-gson</artifactId>
</dependency>

Configuration

gson:
  properties:
    serialize-nulls: false

Usage

public class Person {

    private String name;

    public Person() {
        super();
    }

    public String getName() {
        return this.name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

rules.post("/echo", (req, res) -> {
    res.send(req.content().as(Person.class)); 
});

curl --noproxy '*' -X POST -H "Content-Type: application/json" \
    http://localhost:8080/echo -d '{"name":"Joe"}'

{"name":"Joe"}

HTTP encoding support is discovered automatically by WebServer from the classpath, or it can be customized programmatically.

Encoding can be configured per socket.

Disabling discovery and registering a Gzip encoding support:

WebServer.builder()
        .contentEncoding(it -> it
        .contentEncodingsDiscoverServices(false)
        .addContentEncoding(GzipEncoding.create()));

Or use a config file using the following options:

Configuration options

HTTP compression negotiation is controlled by clients using the Accept-Encoding header. The value of this header is a comma-separated list of encodings. The WebServer will select one of these encodings for compression purposes; it currently supports gzip and deflate.

For example, if the request includes Accept-Encoding: gzip, deflate, and HTTP compression has been enabled as shown above, the response shall include the header Content-Encoding: gzip and a compressed payload.

There are two ways in which the header data can be accessed in your application. One way is by obtaining the protocol data directly from a request as shown next:

rules.get("/", (req, res) -> {
    ProxyProtocolData data = req.proxyProtocolData().orElse(null);
    if (data != null
        && data.family() == ProxyProtocolData.Family.IPv4
        && data.protocol() == ProxyProtocolData.Protocol.TCP
        && data.sourceAddress().equals("192.168.0.1")
        && data.destAddress().equals("192.168.0.11")
        && data.sourcePort() == 56324
        && data.destPort() == 443) {
        // ...
    }
});

Alternatively, the WebServer also makes the original client source address and source port available in the HTTP headers X-Forwarded-For and X-Forwarded-Port, respectively. In some cases, it is just simpler to inspect these headers instead of getting the complete ProxyProtocolData instance as shown above.

The binary (V2) version of the Proxy Protocol includes additional information beyond that found in the text (V1) protocol version. The V2 version exposes a proxy command type (LOCAL or PROXY), allows source and destination addresses to be Unix domain sockets, and supports structured metadata using Tag-Length-Value (TLV) encoded structures. Helidon makes this additional information available through the ProxyProtocolV2Data interface, which extends ProxyProtocolData.

To access the V2 data, check whether the ProxyProtocolData object obtained from the request implements the ProxyProtocolV2Data interface:

rules.get("/", (req, res) -> {
    ProxyProtocolData data = req.proxyProtocolData().orElse(null);
    // The data object will be an instance of ProxyProtocolV2Data if V2 of the Proxy Protocol
    // was used by the upstream proxy.
    if (data instanceof ProxyProtocolV2Data v2Data) {
        // PROXY or LOCAL?
        ProxyProtocolV2Data.Command command = v2Data.command();

        // Will be either an InetSocketAddress (for IPv4 or IPv6) or a UnixDomainSocketAddress.
        SocketAddress sourceSocketAddress = v2Data.sourceSocketAddress();
        SocketAddress destSocketAddress = v2Data.destSocketAddress();

        // Contains all of the Tag-Length-Value objects from the Proxy Protocol header.
        List<ProxyProtocolV2Data.Tlv> tlvData = v2Data.tlvs();
    }
});