Using HTTP/2 Push

Push lists

Push lists are for telling ShimmerCat how to push resources to the browser. As its name implies, a push list is just a list of assets to push. The only peculiarity is that resources are prioritized by how early in the list they stand.

To use a push list, create a YAML file next to an index.html or __index.html page in your site, with the same name plus the extra-extension .push-list.

For example, to serve this very page you are reading we use a file en/info/__index.html.push-list next to our en/info/__index.html file with the following contents:

---
hints:
- /fonts/font-awesome.min.css?vh=61075de8e
- /sass/main.css?vh=4fe8ea6bd
# ... other files ...
schema: push-list-v1

This file instructs ShimmerCat to push the URLs /fonts/font-awesome.min.css?vh=61075de8e, /sass/main.css?vh=4fe8ea6bd, etc to the browser. Notice the inclusion of the query string, which we discuss in the next subsection. We also include the attribute schema, because we intend to create more sophisticated ways to push assets in the future.

HTTP/2 Push is done via URL paths

Push is done via URL, and browsers consider any query strings part of the URL.

You may want to use different URL paths+query string combinations for different versions of your resources. This is an approach built into many major frontend and backend frameworks.

Popular options for structuring URLs try to include a version number or a fragment of a hash from the URLs contents.

Finding which files the browser doesn’t like via HTTP/2 Push

There are often differences in the fetching behavior of browsers, particularly regarding resources which different browsers prefer in different formats, like favicons and webfonts. You may want to remove those assets from the push list and allow the browser to “pull” the format it prefers. Of course, you should do the same with any assets that you are not actually using.

To know if you are pushing files to a browser that it doesn’t like, you can use ShimmerCat’s log. Browsers tend to send a special HTTP/2 packet, Stream Reset, everytime they receive a push promise for an asset they don’t need. From version 1.4.2, the log message M21022 warns about pushed streams that the browser resets.