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

WebServer webServer = WebServer.builder()
      .bindAddress(InetAddress.getLocalHost())
      .port(8080)
      .build();

You can also define the configuration in a file.

server:
  port: 8080
  bind-address: "0.0.0.0"

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

Config config = Config.create(); 
WebServer webServer = WebServer.create(routing, 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

Configuration of the HTTP server.

Type: io.helidon.webserver.WebServer

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

Configuration options

Default value is #DEFAULT_BACKLOG_SIZE.

Default is `false`

Default is `16384`

Default is `4096`

Default is `64*1024`

If `0` then use implementation default.

An additional named server socket may have a dedicated Routing configured
through io.helidon.webserver.WebServer.Builder#addNamedRouting(String, Routing).

If this method is called again, the previous configuration would be ignored.

Configuration key: `workers`

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

Configure HTTP request routing using Routing.Builder.

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

WebServer webServer = WebServer.create(routing); 

• Handle all GETs to /hello path. Send the Hello World! string.
• Add the routing to the WebServer.

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

You can combine HTTP method routing with request path matching.

Routing.builder()
       .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/{}/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:.+}. A matcher is not a true URI template (as defined by RFC) but this convenience is in sync with the Apiary templates

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

Use the RequestPredicate utility class to identify more criteria. You can construct (build) a predicate based on typical request criteria such as content type, or the existence of a header or cookie. You can also construct a handler that only processes requests accepted by the predicate. All other requests are nexted, meaning that they are routed to the next valid handler.

.post("/foo",
      RequestPredicate.create()
                      .containsHeader("my-gr8-header")
                      .accepts(MediaType.TEXT_PLAIN)
                      .and(this::isUserAuthenticated)
                      .thenApply((req, resp) -> {
                           // Some logic
                      })
                      .otherwise((req, resp) -> { /* Otherwise logic */ }); // Optional. Default logic is req.next()

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

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

public class HelloService implements Service {
    @Override
    public void update(Routing.Rules rules) {
        rules.get("/subpath", this::getHandler);
    }

    private void getHandler(ServerRequest request,
                            ServerResponse response) {
        // Some logic
    }
}

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

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.

The handler forwards the request to the downstream handlers by nexting. There are two options:

• call req.next()

  .any("/hello", (req, res) -> { 
      // filtering logic  
      req.next(); 
  })

  content_copy Copied
  • handler for any HTTP method using the /hello path
  • business logic implementation
  • forward the current request to the downstream handler

• call req.next(throwable) to forward the handling to the error handling

  .any("/hello", (req, res) -> { 
      // filtering logic (e.g., validating parameters) 
      if (userParametersOk()) {
          req.next(); 
      } else {
          req.next(new IllegalArgumentException("Invalid parameters."); 
      }
  })

  content_copy Copied
  • handler for any HTTP method using the /hello path
  • custom logic
  • forward the current request to the downstream handler
  • forward the request to the error handler

The handling logic can explicitly forward the execution to a different thread. This is the reason why returning from the handler can’t automatically trigger calling the next handler.

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

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

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

Handling routes based on the protocol version is possible by registering specific routes on routing builder.

.routing(r -> r
        .get("/any-version", (req, res) -> res.send("HTTP Version " + req.version()))
        .route(Http1Route.route(GET, "/version-specific", (req, res) -> res.send("HTTP/1.1 route")))
        .route(Http2Route.route(GET, "/version-specific", (req, res) -> res.send("HTTP/2 route")))
)

While Http1Route for Http/1 is always available with Helidon webserver, other routes like Http2Route for HTTP/2 needs to be added as additional dependency.

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

import io.helidon.common.configurable.AllowList;
import static io.helidon.webserver.SocketConfiguration.RequestedUriDiscoveryType.FORWARDED;
import static io.helidon.webserver.SocketConfiguration.RequestedUriDiscoveryType.X_FORWARDED;

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

WebServer.Builder builder = WebServer.builder()
        .defaultSocket(s -> s
                .host("localhost")
                .port(0)
                .requestedUriDiscoveryTypes(List.of(FORWARDED, X_FORWARDED)) 
                .trustedProxies(trustedProxies)) 
        .addRouting(yourRouting)
        .config(serverConfig);

• 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.http.UriInfo;

public class MyHandler implements Handler {

    @Override
    public void accept(ServerRequest req, ServerResponse res) {
        UriInfo uriInfo = req.requestedUri();
        // ...
    }
}

See the UriInfo JavaDoc for more information.

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

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

• 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

• req.next(ex) is called, where ex is an instance of Throwable

As with the standard handlers, the error handler must either

• send a response

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

  content_copy Copied

• or, forward the error handling to the downstream error handlers

  .error(Throwable.class, (req, res, ex) -> {
      // some logic
      req.next(ex);
  })

  content_copy Copied

Error handling can’t be forwarded to the standard handlers. In fact, invoking req.next(ex) or req.next() in an error handler are equivalent.

.error(Throwable.class, (req, res, ex) -> {
    if (condition) {
        req.next(ex); 
    } else {
        req.next(); 
    }
})

• Call a downstream error handler with the Throwable instance.
• Here, req.next() is the same as req.next(ex). In both cases, the downstream error handler is called.

If no user-defined error handler is matched, or if the last error handler of the exception called req.next(), 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

  (req, res) -> throw new HttpException("Amount of money must be greater than 0.", Http.Status.NOT_ACCEPTABLE_406) 

  content_copy Copied

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

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.builder()
       .register("/pictures", StaticContentSupport.create(Paths.get("/some/WEB/pics"))) 
       .register("/", StaticContentSupport.builder("/static-content") 
                                   .welcomeFileName("index.html") 
                                   .build());

• Create a new StaticContentSupport object to serve data from the file system, and associate it with the "/pictures" context path.
• Create a StaticContentSupport 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 StaticContentSupport 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.

To enable Jersey (JAX-RS) Support add the following dependency to your project’s pom.xml.

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

You can register a Jersey (JAX-RS) application at a context root using the JerseySupport class.

Registering a Jersey Application

@Path("/")
public class HelloWorld {

    @GET
    @Path("hello")
    public Response hello() {
        return Response.ok("Hello World!").build();
    }
}

Routing.builder()
       .register("/jersey", 
                 JerseySupport.builder()
                              .register(HelloWorld.class) 
                              .build())
       .build();

Routing.builder()
       .register("/jersey", 
                 JerseySupport.builder(new MyApplication()) 
                              .build())
       .build();

@Path("/")
@RequestScoped
public class HelloWorld {
    @Context
    private ServerRequest request;

    @Context
    private ServerResponse response;
}

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

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

To enable JSON-P support, first register it with the web server. Then you can add routes that handle and return JSON.

JsonpSupport jsonbSupport = JsonpSupport.create(); 
WebServer webServer = WebServer.builder()
    .addMediaSupport(jsonpSupport) 
    .build();

• Register JsonpSupport to enable transformation from and to JsonObject objects
• Register that JsonpSupport instance to enable automatic deserialization of Java objects from and serialization of Java objects to JSON.

private static final JsonBuilderFactory JSON_FACTORY = Json.createBuilderFactory(Collections.emptyMap()); 

private void sayHello(ServerRequest req, ServerResponse res, JsonObject json) { 
        JsonObject msg = JSON_FACTORY.createObjectBuilder()   
          .add("message", "Hello " + json.getString("name"))
          .build();
        res.send(msg);                            
}

• Using a JsonBuilderFactory is more efficient than Json.createObjectBuilder()
• JsonObject is passed to handler
• Create a JsonObject using JSON-P to hold return data
• Send JsonObject in response

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

{"message":"Hello Joe"}

To configure JSON-P JsonReaderFactory and JsonWriterFactory that are used by the JsonpSupport instance, create the JsonpSupport object:

JsonpSupport.create(Map.of(JsonGenerator.PRETTY_PRINTING, false));

To enable JSON-B Support add the following dependency to your project’s pom.xml.

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

To enable JSON-B support, first create and register a JsonbSupport instance with a WebServer.Builder.

JsonbSupport jsonbSupport = JsonbSupport.create(); 
WebServer webServer = WebServer.builder()
    .addMediaSupport(jsonbSupport) 
    .build();

• Create a JsonbSupport instance. This instance may be reused freely.
• Register that JsonbSupport instance to enable automatic deserialization of Java objects from and serialization of Java objects to JSON.

Now that automatic JSON serialization and deserialization facilities have been set up, you can register a Handler that works with Java objects instead of raw JSON. Deserialization from and serialization to JSON will be handled according to the JSON-B specification.

Suppose you have a Person class that looks like this:

public class Person {

    private String name;

    public Person() {
        super();
    }

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

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

Then you can set up a Handler like this:

final Routing routing =
    routingBuilder.post("/echo", 
                        Handler.create(Person.class, 
                                       (req, res, person) -> res.send(person)))) 
    .build();

• Set up a route for POST requests using the Routing.Builder#post(String, Handler…​) method
• Use the Handler#create(Class, Handler.EntityHandler) method to install a Handler.EntityHandler that works with Person instances.
• This Handler.EntityHandler consumes a Person instance (person) and simply echoes it back. Note that there is no working with raw JSON here.

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

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

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

To enable Jackson support, first create and register a JacksonSupport instance with a WebServer.Builder.

JacksonSupport jacksonSupport = JacksonSupport.create(); 
WebServer webServer = WebServer.builder()
    .addMediaSupport(jacksonSupport) 
    .build();

• Create a JacksonSupport instance. This instance may be reused freely.
• Register that JacksonSupport instance to enable automatic deserialization of Java objects from and serialization of Java objects to JSON.

Now that automatic JSON serialization and deserialization facilities have been set up, you can register a Handler that works with Java objects instead of raw JSON. Deserialization from and serialization to JSON will be handled by Jackson.

Suppose you have a Person class that looks like this:

public class Person {

    private String name;

    public Person() {
        super();
    }

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

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

Then you can set up a Handler like this:

final Routing routing =
    routingBuilder.post("/echo", 
                        Handler.create(Person.class, 
                                       (req, res, person) -> res.send(person)))) 
    .build();

• Set up a route for POST requests using the Routing.Builder#post(String, Handler…​) method
• Use the Handler#create(Class, Handler.EntityHandler) method to install a Handler.EntityHandler that works with Person instances.
• This Handler.EntityHandler consumes a Person instance (person) and simply echoes it back. Note that there is no working with raw JSON here.

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

{"name":"Joe"}

Access log is configured in your code by registering it as a service with Routing

Routing.builder()
    .register(AccessLogSupport.create(config.get("server.access-log")))
    .get("/greet", myService)

The order of registration is significant - make sure AccessLogSupport is registered first (even before security, tracing etc.).

Access log can be configured as follows:

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

All options shown above are also available programmatically when using builder.

The following configuration options can be defined:

Supported Log Entries

Helidon Log Format

192.168.0.104 - [18/Jun/2019:22:28:55 +0200] "GET /greet/test HTTP/1.1" 200 53
0:0:0:0:0:0:0:1 - [18/Jun/2019:22:29:00 +0200] "GET /metrics/vendor HTTP/1.1" 200 1658
0:0:0:0:0:0:0:1 jack [18/Jun/2019:22:29:07 +0200] "PUT /greet/greeting HTTP/1.1" 200 21
0:0:0:0:0:0:0:1 jill [18/Jun/2019:22:29:12 +0200] "PUT /greet/greeting HTTP/1.1" 403 0
0:0:0:0:0:0:0:1 - [18/Jun/2019:22:29:17 +0200] "PUT /greet/greeting HTTP/1.1" 401 0

To configure TLS in WebServer programmatically create your keystore configuration and pass it to the WebServer builder.

KeyConfig keyConfig = KeyConfig.keystoreBuilder()
                //Whether this keystore is also trust store
                .trustStore()
                //Keystore location/name
                .keystore(Resource.create("keystore.p12"))
                //Password to the keystore
                .keystorePassphrase("password")
                .build();

WebServer.builder()
         .tls(WebServerTls.builder()
               .trust(keyConfig)
               .privateKey(keyConfig)
               .build())
         .build();

It is also possible to configure TLS via 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"

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

Config config = Config.create();
WebServer webClient = WebServer.create(routing, config.get("server"));

Or you can only create WebServerTls instance based on the config file.

Config config = Config.create();
WebServerTls.builder()
    .config(config.get("server.tls"))
    .build();

This can alternatively be configured with paths to PKCS#8 PEM files rather than KeyStores:

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.WebServerTls

Configuration options

HTTP compression in the Helidon WebServer is disabled by default. It can sometimes interfere with certain applications that use streaming, even if a compression encoding has not been negotiated with the client.

It can be enabled either programmatically or via configuration, and it can also be enabled on a per-socket basis. When configured at the server level, it applies only to the default socket.

Programmatically, simply use the enableCompression method during server creation:

WebServer.builder()
         .port(8080)
         .routing(...)
         .enableCompression(true)        // compression enabled
         .build()

Or use a config file as follows and make sure the WebServer is created using it:

server:
  port: 8080
  enable-compression: true

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.