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:
          resource-path: "keystore.p12"
    # Keystore with private key and server certificate
    private-key:
      keystore:
        passphrase: "password"
        resource:
          resource-path: "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"

Type: io.helidon.webserver.WebServer

This is a standalone configuration type, prefix from configuration root: server

Configuration options

@return backlog

@return connection configuration

@return socket options

@return content encoding context

@return server features

@return host address to listen on (for the default socket)

@return period of checking for idle connections

@return timeout of idle connections

@return number of requests that can be processed on this listener, regardless of protocol

Note that for some entity types we cannot use streaming, as they are already fully in memory (String, byte[]), for such
cases, this option is ignored.

Default is 128Kb.

@return maximal number of bytes to buffer in memory for supported writers

@return maximal number of bytes of entity

@return number of TCP connections that can be opened to this listener, regardless of protocol

@return media context

@return name of the socket

@return port to listen on (for the default socket)

@return all defined protocol configurations, loaded from service loader by default

@return buffer size in bytes

@return grace period

Defaults to true. Set this to false such that a shutdown hook is not registered.

@return whether to register a shutdown hook

@return map of listener configurations, except for the default one

@return tls of this configuration

@return initial buffer size used for writing

@return maximal number of queued writes, defaults to 0

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[/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.

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.

Type: io.helidon.common.tls.Tls

Configuration options

@return cipher suits to enable, by default (or if list is empty), all available cipher suites
        are enabled

@return what type of mutual TLS to use, defaults to TlsClientAuth#NONE

@return enabled flag

@return configure endpoint identification algorithm, or set to `NONE`
        to disable endpoint identification (equivalent to hostname verification).
        Defaults to `Tls#ENDPOINT_IDENTIFICATION_HTTPS`

@return keystore provider, if not defined, provider is not specified

@return keystore type, defaults to java.security.KeyStore#getDefaultType()

@return algorithm to use

@return the tls manager of the tls instance
@see ConfiguredTlsManager

@return private key to use

@return protocol to use, defaults to `DEFAULT_PROTOCOL`

@return protocols to enable, by default (or if list is empty), all available protocols are enabled

@return provider to use, defaults to none (only #protocol() is used by default)

@return certificate revocation configuration

@return algorithm to use, by default uses java.security.SecureRandom constructor

@return provider to use, by default no provider is specified

@return session cache size, defaults to 1024

@return session timeout, defaults to 30 minutes

@return certificates to be trusted

<b>This is a dangerous setting: </b> if set to `true`, any certificate will be accepted, throwing away
most of the security advantages of TLS. <b>NEVER</b> do this in production.

@return whether to trust all certificates, do not use in production

@return algorithm to use

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.

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"

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 (/):

routing.register("/pictures", StaticContentService.create(Paths.get("/some/WEB/pics"))) 
        .register("/", StaticContentService.builder("/static-content") 
                .welcomeFileName("index.html") 
                .build());

• Create a new StaticContentService object to serve data from the file system, and associate it with the "/pictures" context path.
• Create a StaticContentService object to serve resources from the contextual ClassLoader. The specific classloader can be also defined. A builder lets you provide more configuration values.
• index.html is the file that is returned if a directory is requested.

A StaticContentService object can be created using create(…​) factory methods or a builder. The builder lets you provide more configuration values, including welcome file-name and mappings of filename extensions to media types.

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>

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>

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:

Type: io.helidon.http.encoding.ContentEncodingContext

Configuration options

@return list of content encodings to be used (such as `gzip,deflate`)

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.