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 called views-dir which is relative to where the devlove.yaml is.

• { "change-url" : [ "/ -> /target/+common/"] }: ShimmerCat will use a file called index.html inside the directory views-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!