1. Enable HTTP/2 push¶
One of ShimmerCat’s working principles is to use HTTP/2 Push to deliver assets while the application’s backend is still generating the HTML response. For this to be possible at all, we need to know what to push very early on, something that we achieve using a mechanism called push lists.
The push lists are YAML files with the relative locations of the assets to push. Push-lists are either tied one-to-one to a view, or tied to a particular page rendered by a view, being many-to-one to their view.
The first case is covered by this tutorial. The second case is more advanced, as it allows ShimmerCat QS and the accelerator platform to use arbitrary details from a request to key the push lists, and is not covered in this document.
In the first case, the push list lives in a file with the same name and at the same place
than the view, with an added .push-list
extension. For the example we could have a .push-list
file like this one:
hints:
- /assets/css/material-icons.css
- /assets/css/font-awesome.min.css
- /assets/css/bootstrap.min.css
- /assets/js/vendor/modernizr-2.8.3.min.js
- /assets/js/vendor/jquery-1.12.0.min.js
schema: push-list-v1
Let’s go about adding it to the instance deployment.
Move to the install-dir
directory:
$ cd /home/shimmercat/test/shimmercat-accelerator
Create a view:
$ mkdir -p views-dir/hand-coded/
$ cat > views-dir/manual/example1/index.html
<!--
shimmercat:
content-disposition: replace
-->
and finally copy the .push-list
file with the contents above so that it
ends up in a file views-dir/manual/example1/index.html.push-list
We now have the .push-list
in place
for the view at manual/example1
, which can be accessed using
that URL, or any other URL if configured with the re-write engine.
One important detail is that our accelerator platform, a cloud service largely
independent from ShimmerCat itself, creates the push lists
using traffic data, and it also spreads them over all the sc_pack
deployments automatically.
To do this and at the same time let users have their own push-lists if they so wish,
the accelerator platform regards the relative path of a view (and its push-list) as
a set of tags, one for each path component.
The accelerator platform considers views whose path contains the tag +target
, and
for example the optimization of having a common set of pushed assets is triggered by
the additional tag common
.
For example, all views whose path relative to the views-dir
contains +target/common
,
would receive a .push-list
with assets that every browser navigating the site
is extremely likely to fetch.
In the example above, manual/example1
would be decomposed as the set of
tags {"manual", "example1"}
,
which holds no special meaning for the accelerator platform, and thus the view and
any push-lists associated to it would be left alone.
To benefit from automatic .push-list construction for e.g. the root location
of the site,
use a re-write rule.
Below is an example of a devlove.yaml
file that does that:
---
shimmercat-devlove:
domains:
elec vlad-accelerator.shimmercat.com:
root-dir: www
views-dir: views-dir
change-url:
- / -> /target/+common/
We added three lines to it:
views-dir: views-dir
: we are letting ShimmerCat know that the views are under a directory calledviews-dir
which is relative to where thedevlove.yaml
is.{ "change-url" : [ "/ -> /target/+common/"] }
: ShimmerCat will use a file calledindex.html
inside the directoryviews-dir/target/+common
when a request to/
is done.
We don’t have yet a views-dir/target/+common/index.html
in place, let’s fix that.
cat > views-dir/target/+common/index.html
<!--
shimmercat:
content-disposition: replace
-->
Note the content-disposition
clause, ShimmerCat uses this to decide what to do
with contents coming from the backend, and replace
means
“replace any HTML in this (the view) file with the unchanged HTML coming from the backend application”.
There are other content dispositions, for example there is one for splicing JSON data from the backend
in the HTML of the view and sending it to the browser,
and there is another for asking ShimmerCat to just send the contents of the view file to the browser,
while giving it all the special treatment that a response from the backend would get.
1.1. How to check that HTTP/2 Push is working¶
Run the sc_pack supervisord
command, open a browser and visit: https://example-accelerator.shimmercat.com:4043/. To see the
pushed resources:
open the browser developer tools (press F12),
disable the cache (see the screenshot below you’ll see the
Disable cache
checkbox checked)refresh the page (press F5) and then you will see something like the image below if you used Google Chrome browser:
Notice how the resources we added to the index.html.push-list
are with the Push / (index)
description on the Initiator
column.
Thanks a lot for your time, and keep reading!