Vert.x-Web

To use vert.x web, add the following dependency to the dependencies section of your build descriptor:

Vert.x-Web uses and exposes the API from Vert.x core, so it’s well worth getting familiar with the basic concepts of writing HTTP servers using Vert.x core, if you’re not already.

The Vert.x core HTTP documentation goes into a lot of detail on this.

Here’s a hello world web server written using Vert.x core. At this point there is no Vert.x-Web involved:

We create an HTTP server instance, and we set a request handler on it. The request handler will be called whenever a request arrives on the server.

When that happens we are just going to set the content type to text/plain, and write Hello World! and end the response.

We then tell the server to listen at port 8080 (default host is localhost).

You can run this, and point your browser at http://localhost:8080 to verify that it works as expected.

Here’s the 10000 foot view:

A Router is one of the core concepts of Vert.x-Web. It’s an object which maintains zero or more Routes .

A router takes an HTTP request and finds the first matching route for that request, and passes the request to that route.

The route can have a handler associated with it, which then receives the request. You then do something with the request, and then, either end it or pass it to the next matching handler.

Here’s a simple router example:

It basically does the same thing as the Vert.x Core HTTP server hello world example from the previous section, but this time using Vert.x-Web.

We create an HTTP server as before, then we create a router. Once we’ve done that we create a simple route with no matching criteria so it will match all requests that arrive on the server.

We then specify a handler for that route. That handler will be called for all requests that arrive on the server.

The object that gets passed into the handler is a RoutingContext - this contains the standard Vert.x HttpServerRequest and HttpServerResponse but also various other useful stuff that makes working with Vert.x-Web simpler.

For every request that is routed there is a unique routing context instance, and the same instance is passed to all handlers for that request.

Once we’ve set up the handler, we set the request handler of the HTTP server to pass all incoming requests to handle.

So, that’s the basics. Now we’ll look at things in more detail:

When Vert.x-Web decides to route a request to a matching route, it calls the handler of the route passing in an instance of RoutingContext. A route can have different handlers, that you can append using handler

If you don’t end the response in your handler, you should call next so another matching route can handle the request (if any).

You don’t have to call next before the handler has finished executing. You can do this some time later, if you want:

In the above example route1 is written to the response, then 5 seconds later route2 is written to the response, then 5 seconds later route3 is written to the response and the response is ended.

Note, all this happens without any thread blocking.

Sometimes, you might have to do something in a handler that might block the event loop for some time, e.g. call a legacy blocking API or do some intensive calculation.

You can’t do that in a normal handler, so we provide the ability to set blocking handlers on a route.

A blocking handler looks just like a normal handler but it’s called by Vert.x using a thread from the worker pool not using an event loop.

You set a blocking handler on a route with blockingHandler. Here’s an example:

By default, any blocking handlers executed on the same context (e.g. the same verticle instance) are ordered - this means the next one won’t be executed until the previous one has completed. If you don’t care about orderering and don’t mind your blocking handlers executing in parallel you can set the blocking handler specifying ordered as false using blockingHandler.

Note, if you need to process multipart form data from a blocking handler, you MUST use a non-blocking handler FIRST in order to call setExpectMultipart(true). Here is an example:

A route can be set-up to match the path from the request URI. In this case it will match any request which has a path that’s the same as the specified path.

In the following example the handler will be called for a request /some/path/. We also ignore trailing slashes so it will be called for paths /some/path and /some/path// too:

Often you want to route all requests that begin with a certain path. You could use a regex to do this, but a simply way is to use an asterisk * at the end of the path when declaring the route path.

In the following example the handler will be called for any request with a URI path that starts with /some/path/.

For example /some/path/foo.html and /some/path/otherdir/blah.css would both match.

With any path it can also be specified when creating the route:

It’s possible to match paths using placeholders for parameters which are then available in the request params.

Here’s an example

The placeholders consist of : followed by the parameter name. Parameter names consist of any alphabetic character, numeric character or underscore.

In the above example, if a POST request is made to path: /catalogue/products/tools/drill123/ then the route will match and productType will receive the value tools and productID will receive the value drill123.

Regular expressions can also be used to match URI paths in routes.

Alternatively the regex can be specified when creating the route:

You can also capture path parameters when using regular expressions, here’s an example:

In the above example, if a request is made to path: /tools/drill123/ then the route will match and productType will receive the value tools and productID will receive the value drill123.

Captures are denoted in regular expressions with capture groups (i.e. surrounding the capture with round brackets)

Using int index param names might be troublesome in some cases. It’s possible to use named capture groups in the regex path.

In the example above, named capture groups are mapped to path parameters of the same name as the group.

Additionally, you can still access group parameters as you would with normal groups (i.e. params0, params1…​)

By default a route will match all HTTP methods.

If you want a route to only match for a specific HTTP method you can use method

Or you can specify this with a path when creating the route:

If you want to route for a specific HTTP method you can also use the methods such as get, post and put named after the HTTP method name. For example:

If you want to specify a route will match for more than HTTP method you can call method multiple times:

By default routes are matched in the order they are added to the router.

When a request arrives the router will step through each route and check if it matches, if it matches then the handler for that route will be called.

If the handler subsequently calls next the handler for the next matching route (if any) will be called. And so on.

Here’s an example to illustrate this:

In the above example the response will contain:

As the routes have been called in that order for any request that starts with /some/path.

If you want to override the default ordering for routes, you can do so using order, specifying an integer value.

Routes are assigned an order at creation time corresponding to the order in which they were added to the router, with the first route numbered 0, the second route numbered 1, and so on.

By specifying an order for the route you can override the default ordering. Order can also be negative, e.g. if you want to ensure a route is evaluated before route number 0.

Let’s change the ordering of route2 so it runs before route1:

then the response will now contain:

If two matching routes have the same value of order, then they will be called in the order they were added.

You can also specify that a route is handled last, with last

You can specify that a route will match against matching request MIME types using consumes.

In this case, the request will contain a content-type header specifying the MIME type of the request body. This will be matched against the value specified in consumes.

Basically, consumes is describing which MIME types the handler can consume.

Matching can be done on exact MIME type matches:

Multiple exact matches can also be specified:

Matching on wildcards for the sub-type is supported:

And you can also match on the top level type

If you don’t specify a / in the consumers, it will assume you meant the sub-type.

The HTTP accept header is used to signify which MIME types of the response are acceptable to the client.

An accept header can have multiple MIME types separated by ‘,’.

MIME types can also have a q value appended to them* which signifies a weighting to apply if more than one response MIME type is available matching the accept header. The q value is a number between 0 and 1.0. If omitted it defaults to 1.0.

For example, the following accept header signifies the client will accept a MIME type of only text/plain:

Accept: text/plain

With the following the client will accept text/plain or text/html with no preference.

Accept: text/plain, text/html

With the following the client will accept text/plain or text/html but prefers text/html as it has a higher q value (the default value is q=1.0)

Accept: text/plain; q=0.9, text/html

If the server can provide both text/plain and text/html it should provide the text/html in this case.

By using produces you define which MIME type(s) the route produces, e.g. the following handler produces a response with MIME type application/json.

In this case the route will match with any request with an accept header that matches application/json.

Here are some examples of accept headers that will match:

Accept: application/json Accept: application/* Accept: application/json, text/html Accept: application/json;q=0.7, text/html;q=0.8, text/plain

You can also mark your route as producing more than one MIME type. If this is the case, then you use getAcceptableContentType to find out the actual MIME type that was accepted.

In the above example, if you sent a request with the following accept header:

Accept: application/json; q=0.7, text/html

Then the route would match and acceptableContentType would contain text/html as both are acceptable but that has a higher q value.

You can combine all the above routing criteria in many different ways, for example:

You can disable a route with disable. A disabled route will be ignored when matching.

You can re-enable a disabled route with enable

You can use the context data in the RoutingContext to maintain any data that you want to share between handlers for the lifetime of the request.

Here’s an example where one handler sets some data in the context data and a subsequent handler retrieves it:

You can use the put to put any object, and get to retrieve any object from the context data.

A request sent to path /some/path/other will match both routes.

Until now all routing mechanism allow you to handle your requests in a sequential way, however there might be times where you will want to go back. Since the context does not expose any information about the previous or next handler, mostly because this information is dynamic there is a way to restart the whole routing from the start of the current Router.

So from the code you can see that if a request arrives at /some/path if first add a value to the context, then moves to the next handler that re routes the request to /some/path/B which terminates the request.

You can reroute based on a new path or based on a new path and method. Note however that rerouting based on method might introduce security issues since for example a usually safe GET request can become a DELETE.

Reroute is also allowed on the failure handler, however due to the nature of re router when called the current status code and failure reason are reset. In order the rerouted handler should generate the correct status code if needed, for example:

It should be clear that reroute works on paths, so if you need to preserve and or add state across reroutes, one should use the RoutingContext object. For example you want to reroute to a new path with a extra parameter:

Even though the wrong reroute path will warn you that the query string is ignored, the reroute will happen since the implementation will strip any query string or html fragment from the path.

Sometimes if you have a lot of handlers it can make sense to split them up into multiple routers. This is also useful if you want to reuse a set of handlers in a different application, rooted at a different path root.

To do this you can mount a router at a mount point in another router. The router that is mounted is called a sub-router. Sub routers can mount other sub routers so you can have several levels of sub-routers if you like.

Let’s look at a simple example of a sub-router mounted with another router.

This sub-router will maintain the set of handlers that corresponds to a simple fictional REST API. We will mount that on another router. The full implementation of the REST API is not shown.

Here’s the sub-router:

If this router was used as a top level router, then GET/PUT/DELETE requests to urls like /products/product1234 would invoke the API.

However, let’s say we already have a web-site as described by another router:

We can now mount the sub router on the main router, against a mount point, in this case /productsAPI

This means the REST API is now accessible via paths like: /productsAPI/products/product1234

Vert.x Web parses the Accept-Language header and provides some helper methods to identify which is the preferred locale for a client or the sorted list of preferred locales by quality.

The main method acceptableLocales will return the ordered list of locales the user understands, if you’re only interested in the user prefered locale then the helper: preferredLocale will return the 1st element of the list or null if no locale was provided by the user.

If no routes match for any particular request, Vert.x-Web will signal a 404 error.

This can then be handled by your own error handler, or perhaps the augmented error handler that we supply to use, or if no error handler is provided Vert.x-Web will send back a basic 404 (Not Found) response.

As well as setting handlers to handle requests you can also set handlers to handle failures in routing.

Failure handlers are used with the exact same route matching criteria that you use with normal handlers.

For example you can provide a failure handler that will only handle failures on certain paths, or for certain HTTP methods.

This allows you to set different failure handlers for different parts of your application.

Here’s an example failure handler that will only be called for failure that occur when routing to GET requests to paths that start with /somepath/:

Failure routing will occur if a handler throws an exception, or if a handler calls fail specifying an HTTP status code to deliberately signal a failure.

If an exception is caught from a handler this will result in a failure with status code 500 being signalled.

When handling the failure, the failure handler is passed the routing context which also allows the failure or failure code to be retrieved so the failure handler can use that to generate a failure response.

For the eventuality that an error occurs when running the error handler related usage of not allowed characters in status message header, then the original status message will be changed to the default message from the error code. This is a tradeoff to keep the semantics of the HTTP protocol working instead of abruptly creash and close the socket without properly completing the protocol.

The BodyHandler allows you to retrieve request bodies, limit body sizes and handle file uploads.

You should make sure a body handler is on a matching route for any requests that require this functionality.

The usage of this handler requires that it is installed as soon as possible in the router since it needs to install handlers to consume the HTTP request body and this must be done before executing any async call.

Vert.x-Web has cookies support using the CookieHandler.

You should make sure a cookie handler is on a matching route for any requests that require this functionality.

Vert.x-Web provides out of the box support for sessions.

Sessions last between HTTP requests for the length of a browser session and give you a place where you can add session-scope information, such as a shopping basket.

Vert.x-Web uses session cookies to identify a session. The session cookie is temporary and will be deleted by your browser when it’s closed.

We don’t put the actual data of your session in the session cookie - the cookie simply uses an identifier to look-up the actual session on the server. The identifier is a random UUID generated using a secure random, so it should be effectively unguessable.

Cookies are passed across the wire in HTTP requests and responses so it’s always wise to make sure you are using HTTPS when sessions are being used. Vert.x will warn you if you attempt to use sessions over straight HTTP.

To enable sessions in your application you must have a SessionHandler on a matching route before your application logic.

The session handler handles the creation of session cookies and the lookup of the session so you don’t have to do that yourself.

Vert.x comes with some out-of-the-box handlers for handling both authentication and authorisation.

Vert.x-Web comes with an out of the box handler for serving static web resources so you can write static web servers very easily.

To serve static resources such as .html, .css, .js or any other static resource, you use an instance of StaticHandler.

Any requests to paths handled by the static handler will result in files being served from a directory on the file system or from the classpath. The default static file directory is webroot but this can be configured.

In the following example all requests to paths starting with /static/ will get served from the directory webroot:

For example, if there was a request with path /static/css/mystyles.css the static serve will look for a file in the directory webroot/css/mystyle.css.

It will also look for a file on the classpath called webroot/css/mystyle.css. This means you can package up all your static resources into a jar file (or fatjar) and distribute them like that.

When Vert.x finds a resource on the classpath for the first time it extracts it and caches it in a temporary directory on disk so it doesn’t have to do this each time.

The handler will handle range aware requests. When a client makes a request to a static resource, the handler will notify that it can handle range aware request by stating the unit on the Accept-Ranges header. Further requests that contain the Range header with the correct unit and start and end indexes will then receive partial responses with the correct Content-Range header.

Cross Origin Resource Sharing is a safe mechanism for allowing resources to be requested from one domain and served from another.

Vert.x-Web includes a handler CorsHandler that handles the CORS protocol for you.

Here’s an example:

Vert.x-Web includes dynamic page generation capabilities by including out of the box support for several popular template engines. You can also easily add your own.

Template engines are described by TemplateEngine. In order to render a template render is used.

The simplest way to use templates is not to call the template engine directly but to use the TemplateHandler. This handler calls the template engine for you based on the path in the HTTP request.

By default the template handler will look for templates in a directory called templates. This can be configured.

The handler will return the results of rendering with a content type of text/html by default. This can also be configured.

When you create the template handler you pass in an instance of the template engine you want. Template engines are not embedded in vertx-web so, you need to configure your project to access them. Configuration is provided for each template engine.

Here are some examples:

You can render your own errors using a template handler or otherwise but Vert.x-Web also includes an out of the boxy "pretty" error handler that can render error pages for you.

The handler is ErrorHandler. To use the error handler just set it as a failure handler for any paths that you want covered.

Vert.x-Web includes a handler LoggerHandler that you can use to log HTTP requests.

By default requests are logged to the Vert.x logger which can be configured to use JUL logging, log4j or SLF4J.

See LoggerFormat.

Vert.x-Web includes the handler FaviconHandler especially for serving favicons.

Favicons can be specified using a path to the filesystem, or by default Vert.x-Web will look for a file on the classpath with the name favicon.ico. This means you bundle the favicon in the jar of your application.

Vert.x-Web includes a timeout handler that you can use to timeout requests if they take too long to process.

This is configured using an instance of TimeoutHandler.

If a request times out before the response is written a 503 response will be returned to the client.

Here’s an example of using a timeout handler which will timeout all requests to paths starting with /foo after 5 seconds:

This handler sets the header x-response-time response header containing the time from when the request was received to when the response headers were written, in ms., e.g.:

x-response-time: 1456ms

The ResponseContentTypeHandler can set the Content-Type header automatically. Suppose we are building a RESTful web application. We need to set the content type in all our handlers:

If the API surface becomes pretty large, setting the content type can become cumbersome. To avoid this situation, add the ResponseContentTypeHandler to the corresponding routes:

The handler gets the approriate content type from getAcceptableContentType. As a consequence, you can easily share the same handler to produce data of different types:

SockJS is a client side JavaScript library and protocol which provides a simple WebSocket-like interface allowing you to make connections to SockJS servers irrespective of whether the actual browser or network will allow real WebSockets.

It does this by supporting various different transports between browser and server, and choosing one at run-time according to browser and network capabilities.

All this is transparent to you - you are simply presented with the WebSocket-like interface which just works.

Please see the SockJS website for more information on SockJS.

Vert.x-Web comes with a built-in SockJS socket handler called the event bus bridge which effectively extends the server-side Vert.x event bus into client side JavaScript.

This creates a distributed event bus which not only spans multiple Vert.x instances on the server side, but includes client side JavaScript running in browsers.

We can therefore create a huge distributed bus encompassing many browsers and servers. The browsers don’t have to be connected to the same server as long as the servers are connected.

This is done by providing a simple client side JavaScript library called vertx-eventbus.js which provides an API very similar to the server-side Vert.x event-bus API, which allows you to send and publish messages to the event bus and register handlers to receive messages.

This JavaScript library uses the JavaScript SockJS client to tunnel the event bus traffic over SockJS connections terminating at at a SockJSHandler on the server-side.

A special SockJS socket handler is then installed on the SockJSHandler which handles the SockJS data and bridges it to and from the server side event bus.

To activate the bridge you simply call bridge on the SockJS handler.

In client side JavaScript you use the 'vertx-eventbus.js` library to create connections to the event bus and to send and receive messages:

The first thing the example does is to create a instance of the event bus

The parameter to the constructor is the URI where to connect to the event bus. Since we create our bridge with the prefix eventbus we will connect there.

You can’t actually do anything with the connection until it is opened. When it is open the onopen handler will be called.

The bridge supports automatic reconnection, with configurable delay and backoff options.

You can retrieve the client library using a dependency manager:

The library is also available on:

Notice that the API has changed between the 3.0.0 and 3.1.0 version. Please check the changelog. The previous client is still compatible and can still be used, but the new client offers more feature and is closer to the vert.x event bus API.

CSRF or sometimes also known as XSRF is a technique by which an unauthorized site can gain your user’s private data. Vert.x-Web includes a handler CSRFHandler that you can use to prevent cross site request forgery requests.

On each get request under this handler a cookie is added to the response with a unique token. Clients are then expected to return this token back in a header. Since cookies are sent it is required that the cookie handler is also present on the router.

When developing non single page applications that rely on the User-Agent to perform the POST action, Headers cannot be specified on HTML Forms. In order to solve this problem the header value will also be checked if and only if no header was present in the Form attributes under the same name as the header, e.g.:

It is the responsibility of the user to fill in the right value for the form field. Users who prefer to use an HTML only solution can fill this value by fetching the the token value from the routing context under the key X-XSRF-TOKEN or the header name they have chosen during the instantiation of the CSRFHandler object.

The Virtual Host Handler will verify the request hostname and if it matches it will send the request to the registered handler, otherwise will continue inside the normal handlers chain.

Request are checked against the Host header to a match and patterns allow the usage of wildcards, as for example .vertx.io or fully domain names as www.vertx.io.

The OAuth2AuthHandler allows quick setup of secure routes using the OAuth2 protocol. This handler simplifies the authCode flow. An example of using it to protect some resource and authenticate with GitHub can be implemented as:

The OAuth2AuthHandler will setup a proper callback OAuth2 handler so the user does not need to deal with validation of the authority server response. It is quite important to know that authority server responses are only valid once, this means that if a client issues a reload of the callback URL it will be asserted as a invalid request since the validation will fail.

A rule of thumb is once a valid callback is executed issue a client side redirect to a protected resource. This redirect should also create a session cookie (or other session mechanism) so the user is not required to authenticate for every request.

Due to the nature of OAuth2 spec there are slight changes required in order to use other OAuth2 providers but vertx-auth provides you with many out of the box implementations:

However if you’re using an unlisted provider you can still do it using the base API like this:

You will need to provide all the details of your provider manually but the end result is the same.

The handler will pin your application the the configured callback url. The usage is simple as providing the handler a route instance and all setup will be done for you. In a typical use case your provider will ask you what is the callback url to your application, your then enter a url like: https://myserver.com/callback. This is the second argument to the handler now you just need to set it up. To make it easier to the end user all you need to do is call the setupCallback method.

This is how you pin your handler to the server https://myserver.com:8447/callback. Note that the port number is not mandatory for the default values, 80 for http, 443 for https.

In the example the route object is created inline by Router.route() however if you want to have full control of the order the handler is called (for example you want it to be called as soon as possible in the chain) you can always create the route object before and pass it as a reference to this method.