HTTP/2

Spincast supports HTTP/2 in two ways:

Natively - the embedded server (for example the default Undertow server) manages the HTTP/2 connections by itself.
Behind a reverse proxy - the Spincast application is behind a reverse proxy such as Nginx or Apache which manages HTTP/2 requests before they even hit Spincast.

As you will learn in the next section, you can use server push in both situations!

HTTP/2 is now enabled by default in Spincast (since version 1.5.0). If you want to disable it, you can set the SpincastConfig#isEnableHttp2 configuration to false.

There is nothing more to do! Enabling HTTP/2 is very easy for an application developer as it is the server that has to deal with all the details. You can validate that your application is actually served using HTTP/2 by using your browser's dev tools, or by using a browser add-on (information).

Server Push

Server Push is a feature of HTTP/2 allowing you to send extra resources to the client before they are even requested! It can be used to send resources such as .js or .css that you know will be required.

You specify the extra resources you want to push during a request by using the push(...) method of the response() addon, in your route handler.

For example:

// Handler for GET "/"
public void handle(DefaultRequestContext context) {
    context.response()
           .push(HttpMethod.GET, 
                 "/public/main.js", 
                 SpincastStatics.map(HttpHeaders.ACCEPT_LANGUAGE,
                                     Lists.newArrayList(ContentTypeDefaults.JSON.getMainVariation())))
           .sendTemplateHtml("/templates/index.html");
}

Explanation :

4 : We call the push(...) method on the response() addon. The resource to push should be requested using a GET HTTP method.
5 : The absolute path to the resource to push.
6-7 : The headers to send to request the resource to push. Those can be null.

There are a couple of things to know when using the push(...) method:

The path of the resource must be absolute (it must start with "/". Otherwise one will be automatically added).
The path may contain a querystring and may contain a special "${cacheBuster}" placeholder (see Cache Busting for more information). The "${cacheBuster}" placeholder will be automatically replaced with the current cache buster code of your application.

For example, let's say you have a .css specified like this in your HTML: {% verbatim %}
```
<link rel="stylesheet" href="/public/css/{{spincast.cacheBuster}}main.css?theme=blue">
```
{% endverbatim %}

You could specify this .css resource to be pushed using:
```
context.response().push(HttpMethod.GET, 
                        "/public/css/${cacheBuster}main.css?theme=blue", 
                        null)
```
Server push works even if your application is running behind a reverse proxy managing the HTTP/2 connections! In that case, Spincast will send some special Link headers to ask the proxy to push the extra resources (read more about this).
The headers you specify will only be used if it is the embedded server that actually pushes the resources. If it's a reverse proxy in front of the application that manages the HTTP/2 connections, those headers won't be used... But Spincast will still tell the reverse proxy about the content-type to use by adding a special "AS" attribute in the Link header sent to the proxy!

If you use the default server, Undertow, you can enable an extra feature called LearningPushHandler by setting the SpincastUndertowConfig#isEnableLearningPushHandler() configuration to true. More information here. Note that this feature only works when Undertow manages the HTTP/2 connections by itself, not when it is behind a reverse proxy managing HTTP/2.

Make sure you read about server pushing before using this feature since it will not always improve performance and may lead to wasted bandwidth (the client may decide to not use the pushed resources)!

Nginx as a reverse proxy managing HTTP/2

Here are some useful information if you plan on running your Spincast application behind Nginx and you want to enable HTTP/2:

You need a version of Nginx equal or greater than 1.9.5 (the support for HTTP/2 was introduced in that version).
You need to add "http2" on your listen rule. For example: {% verbatim %}
```
listen 443 ssl http2;
```
{% endverbatim %}
If you want to be able to use server push, you also have to add "http2_push_preload on;" inside the "location" block where your application is configured. For example: {% verbatim %}
```
location / {
    proxy_pass http://localhost:44444;
    http2_push_preload on;
    
    //...
```
{% endverbatim %}

More information:

https://www.nginx.com/blog/nginx-1-13-9-http2-server-push

Finally, note that Nginx currently does not allow HTTP/2 traffic to reach your application! It insists to manage the protocol by itself. That means you don't need (or can) enable HTTP/2 on your embedded server if you are behind an HTTP/2 aware Nginx reverse proxy. Server push will still work though, but the actual push will be done by Nginx itself!

More information: