Chapter 10. Undertow

Undertow is a web server designed to be used for both blocking and non-blocking tasks. It replaces JBoss Web in JBoss EAP 7. Some of its main features are:

Request Lifecycle

When a client connects to the server, Undertow creates a io.undertow.server.HttpServerConnection. When the client sends a request, it is parsed by the Undertow parser, and then the resulting io.undertow.server.HttpServerExchange is passed to the root handler. When the root handler finishes, one of four things can happen:

By far the most common use of HttpServerExchange.dispatch() is to move execution from an IO thread, where blocking is not allowed, into a worker thread, which does allow for blocking operations.

public void handleRequest(final HttpServerExchange exchange) throws Exception {
    if (exchange.isInIoThread()) {
      exchange.dispatch(this);
      return;
    }
    //handler code
}

Because the exchange is not actually dispatched until the call stack returns, you can be sure that more than one thread is never active in an exchange at once. The exchange is not thread safe. However, it can be passed between multiple threads as long as both threads do not attempt to modify it at once.

Ending the Exchange

There are two ways to end an exchange, either by fully reading the request channel and calling shutdownWrites() on the response channel and then flushing it, or by calling HttpServerExchange.endExchange(). When endExchange() is called, Undertow will check if the content has been generated yet. If it has, then it will simply drain the request channel and close and flush the response channel. If not and there are any default response listeners registered on the exchange, then Undertow will give each of them a chance to generate a default response. This mechanism is how default error pages are generated.

For more information on configuring Undertow, see Configuring the Web Server in the JBoss EAP Configuration Guide.

Undertow provides a default set of handlers that you can use with any application deployed to JBoss EAP.

To use a handler with a deployment, you need to add a WEB-INF/undertow-handlers.conf file.

allowed-methods(methods='GET')

All handlers can also take an optional predicate to apply that handler in specific cases.

path('/my-path') -> allowed-methods(methods='GET')

The above example will only apply the allowed-methods handler to the path /my-path.

Undertow Handler Default Parameter

Some handlers have a default parameter, which allows you to specify the value of that parameter in the handler definition without using the name.

path('/a') -> redirect('/b')

You can also update the WEB-INF/jboss-web.xml file to include the definition of one or more handlers, but using WEB-INF/undertow-handlers.conf is preferred.

<jboss-web>
    <http-handler>
        <class-name>io.undertow.server.handlers.AllowedMethodsHandler</class-name>
        <param>
            <param-name>methods</param-name>
            <param-value>GET</param-value>
        </param>
    </http-handler>
</jboss-web>

A full list of the provided Undertow handlers can be found in the Provided Undertow Handlers reference.

There are two ways to define custom handlers:

Defining Custom Handlers Using the WEB-INF/jboss-web.xml File

A custom handler can be defined in the WEB-INF/jboss-web.xml file.

<jboss-web>
    <http-handler>
        <class-name>org.jboss.example.MyHttpHandler</class-name>
    </http-handler>
</jboss-web>

package org.jboss.example;

import io.undertow.server.HttpHandler;
import io.undertow.server.HttpServerExchange;

public class MyHttpHandler implements HttpHandler {
    private HttpHandler next;

    public MyHttpHandler(HttpHandler next) {
        this.next = next;
    }

    public void handleRequest(HttpServerExchange exchange) throws Exception {
        // do something
        next.handleRequest(exchange);
    }
}

Parameters can also be set for the custom handler using the WEB-INF/jboss-web.xml file.

<jboss-web>
    <http-handler>
        <class-name>org.jboss.example.MyHttpHandler</class-name>
        <param>
            <param-name>myParam</param-name>
            <param-value>foobar</param-value>
        </param>
    </http-handler>
</jboss-web>

For these parameters to work, the handler class needs to have corresponding setters.

package org.jboss.example;

import io.undertow.server.HttpHandler;
import io.undertow.server.HttpServerExchange;

public class MyHttpHandler implements HttpHandler {
    private HttpHandler next;
    private String myParam;

    public MyHttpHandler(HttpHandler next) {
        this.next = next;
    }

    public void setMyParam(String myParam) {
        this.myParam = myParam;
    }

    public void handleRequest(HttpServerExchange exchange) throws Exception {
        // do something, use myParam
        next.handleRequest(exchange);
    }
}

Defining Custom Handlers in the WEB-INF/undertow-handlers.conf File

Instead of using the WEB-INF/jboss-web.xml for defining the handler, it could also be defined in the WEB-INF/undertow-handlers.conf file.

myHttpHandler(myParam='foobar')

For the handler defined in WEB-INF/undertow-handlers.conf to work, two things need to be created:

When Elytron is used to secure a web application, it is possible to implement custom HTTP authentication mechanisms that can be registered using the elytron subsystem. It is then also possible to override the configuration within the deployment to make use of this mechanism without requiring modifications to the deployment.

In general, for an HTTP mechanism, the evaluateRequest method is called to handle the request passing in the HTTPServerRequest object. The mechanism processes the request and uses one of the following callback methods on the request to indicate the outcome:

After creating a custom HTTP mechanism that implements the HttpServerAuthenticationMechanism interface, the next step is to create a factory that returns instances of this mechanism. The factory must implement the HttpAuthenticationFactory interface. The most important step in the factory implementation is to double check the name of the mechanism requested. It is important for the factory to return null if it cannot create the required mechanism. The mechanism factory can also take into account properties in the map passed in to decide if it can create the requested mechanism.

There are two different approaches that can be used to advertise the availability of a mechanism factory.

The mechanism can then be installed in the application server, as a module ready to be used:

module add --name=org.wildfly.security.examples.custom-http --resources=/path/to/custom-http-mechanism.jar --dependencies=org.wildfly.security.elytron,javax.api

Using a Custom HTTP Mechanism