templates.docs.http2.html Maven / Gradle / Ivy
Show all versions of spincast-website Show documentation
{#==========================================
Docs : "HTTP/2"
==========================================#}
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("someHeader", "someHeaderValue"))
.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 : Headers to send to request the resource.
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:
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: