260 |
261 |
262 |
263 | ["Cache Digests: Solving the Cache Invalidation Problem of HTTP/2 Server Push to Reduce Latency and Bandwidth"](https://calendar.perfplanet.com/2016/cache-digests-http2-server-push/) by Sebastiaan Deckers
264 |
265 |
222 |
223 | 
25 |
26 | This is a small middlware for Django v2.0+ to automatically generate preload headers from staticfiles used in template rendering, with support for using [`StreamingHttpResponse`](https://docs.djangoproject.com/en/2.2/ref/request-response/#django.http.StreamingHttpResponse) to send cached preload headers in advance of the actual response being generated. The preload headers alone provide large speed boost, but pre-sending the cached headers in advance of view execution is the real advantage that this library provides.
27 |
28 | It's also built to support modern security features like [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) using [`django-csp`](https://django-csp.readthedocs.io/en/latest/configuration.html), it sends `request.csp_nonce`
29 | in preload headers correctly so that preloads aren't rejected by your CSP policy if they require a nonce. Support for automatically generating and attaching CSP hashes for staticfiles and inline blocks is also planned in the near future.
30 |
31 | It's not yet production-ready (I'll put it on PyPI if/when it ever is), but for now it's easily installable by cloning it into your apps folder, and the codebase is small enough to be quickly reviewed and customized to a project's needs.
32 |
33 | ---
34 |
35 |
36 | ## How it works
37 |
38 | It works by providing a templatetag `{% http2static %}` that serves as a drop-in replacement for `{% static %}`, except it records all the urls used while rendering the template in `request.to_preload`.
39 |
40 | The http2 middleware then transforms the list of `to_preload` urls into a full HTTP preload header, which is then attached to the response. When `settings.HTTP2_PRESEND_CACHED_HEADERS = True`, the first response's preload headers will be cached and automatically sent in advance during later requests (using [`StreamingHttpResponse`](https://docs.djangoproject.com/en/2.2/ref/request-response/#django.http.StreamingHttpResponse) to send them before the view executes). Upstream servers like Nginx and CloudFlare can then use these headers to do HTTP2 server push, delivering the resources to clients before they are requested during browser parse & rendering. With [TCP fast-open](https://en.wikipedia.org/wiki/TCP_Fast_Open), [TLS 1.3](https://blog.cloudflare.com/rfc-8446-aka-tls-1-3/), and [HTTP2 server push](https://www.smashingmagazine.com/2017/04/guide-http2-server-push/), it's now possible to have entire pageloads with only 1 round-trip, now all we need are cache-digests and QUIC and then we'll be at web nirvana 🎂.
41 |
42 | 
43 |
44 | ### HTTP2 server-push
45 |
46 | When preload headers are sent fast and `HTTP2_SERVER_PUSH = True` is enabled in `settings.py`, upstream servers like Nginx or Cloudflare HTTP2 will usually finish server pushing all the page resources not only before the browser requests them, but even before the view is finished executing, providing a 100ms+ headstart to static file loading in some cases. When enabled it's very cool to look at the network waterfall visualization and see your page's statcifiles finish loading together, a full 50ms+ before the HTML is even returned from Django!
47 |
48 | Unfortunately, while shiny and exciting, this wont necessarily make your site faster for real-world users. In fact, it can sometimes make sites slower because after the first visit, users have most of the resources cached anyway, and pushing uneeded files on every request can waste network bandwidth and use IO & CPU capacity that otherwise would've gone towards loading the actual content. You should toggle the config options while testing your project to see if server push provides real-world speed gains, or use the [recommended settings](#Recommended-Settings) listed below that provide speed gains in most cases without the risk of wasting bandwidth to push uneeded resources. There are some cases where HTTP2 push is still worth it though, e.g. if you have to push a small bundle of static files for first paint and most of your users are first-time visitors without your site cached.
49 |
50 | HTTP2 server-push will eventually become the optimal method of page delivery once cache-digests are released (improving both latency and bandwidth use). Read these articles and the links within them to learn more about HTTP2, server push, and why cache digests are an important feature needed to make server-push worth it:
51 |
52 | - https://http2.github.io/faq/#whats-the-benefit-of-server-push
53 | - https://calendar.perfplanet.com/2016/cache-digests-http2-server-push/
54 | - https://httpwg.org/http-extensions/cache-digest.html#introduction
55 |
56 | This library is still useful without server push enabled though, as it's primary function is to collect statifiles and send them as `` preload headers in parallel *before the Django views finish executing*, which can provide a 100ms+ headstart for the browser to start loading page content in many cases. The optimal recommended settings for maximum speed gain (as of 2019/07) are to send preload headers, cache them and send them in advance, but don't enable `HTTP2_SERVER_PUSH` until cache-digest functionality is released in most browsers.
57 |
58 | ## Install:
59 |
60 | 1. Clone this repo as into your project folder next to `manage.py` as a new django app called "http2":
61 | ```bash
62 | cd /opt/your-project/project-django/
63 | git clone https://github.com/pirate/django-http2-middleware http2
64 | ```
65 |
66 | 2. Add `http2.middleware.HTTP2Middleware` to your `MIDDLEWARE` list in `settings.py`:
67 | ```python
68 | MIDDLEWARE = [
69 | ...
70 | 'csp.middleware.CSPMiddleware', # (optional if you use django-csp, it must be above the http2 middleware)
71 | 'http2.middleware.HTTP2Middleware', # (add the middleware at the end, but before gzip)
72 | ]
73 | # (adding "http2" to INSTALLED_APPS is not needed)
74 | ```
75 |
76 | 3. Add the required configuration options to your `settings.py`:
77 | ```python
78 | HTTP2_PRELOAD_HEADERS = True
79 | HTTP2_PRESEND_CACHED_HEADERS = True
80 | HTTP2_SERVER_PUSH = False
81 | ```
82 |
83 | 4. (Optional) Add the templatag as a global template builtin in `settings.py`:
84 | This will make `{% http2static %}` availabe in templates without needing `{% load http2 %}` at the top.
85 | ```python
86 | TEMPLATES = [
87 | {
88 | ...
89 | 'OPTIONS': {
90 | ...
91 | 'builtins': [
92 | ...
93 | 'http2.templatetags',
94 | ],
95 | },
96 | },
97 | ...
98 | ]
99 | ```
100 |
101 | 5. (Optional if using `django-csp`) Include nonces on any desired resource types in `settings.py`:
102 | Generated preload headers will automatically include this nonce using `{{request.csp_nonce}}`.
103 | ```python
104 | # add any types you want to use with nonce-validation (or just add it to the fallback default-src)
105 | CSP_DEFAULT_SRC = ("'self'", ...)
106 | CSP_INCLUDE_NONCE_IN = ('default-src', ...)
107 | ```
108 |
109 | ## Usage
110 |
111 | Just use the `{% http2static '...' %}` tag instead of `{% static '...' %}` anytime you want to have a resource preloaded.
112 |
113 | ```html
114 |
115 |
116 |
117 |
118 | ...
119 |
120 |
121 |
122 | ```
123 |
124 | Don't use `{% http2static %}` for everything, just use it for things in the critical render path that are needed for the initial pageload. It's best used for CSS, JS, fonts, and icons required to render the page nicely, but usually shouldn't be used for non-critical footer scripts and styles, async page content, images, video, audio, or other media.
125 |
126 |
127 | ## Configuration
128 |
129 | ### Recommended Settings
130 |
131 | These settings provide the most speed gains for 90% of sites, though it's worth testing all the possibilities to see the real-world results for your project.
132 |
133 | ```python
134 | HTTP2_PRELOAD_HEADERS = True
135 | HTTP2_PRESEND_CACHED_HEADERS = True
136 | HTTP2_SERVER_PUSH = False
137 | ```
138 | ### `django-http2-middleware` Configuration
139 |
140 | #### `HTTP2_PRELOAD_HEADERS`
141 | *Values:* [`True`]/`False`
142 |
143 | Attach any `{% http2static %}` urls used templates in an auto-generated HTTP preload header on the response.
144 | Disable this to turn off preload headers and disable the middleware entirely, this also prevents both header caching and http2 server push.
145 |
146 | #### `HTTP2_PRESEND_CACHED_HEADERS`
147 | *Values:* [`True`]/`False`
148 |
149 | Cache first request's preload urls and send in advance on subsequent requests.
150 | Eanble this to cache the first request's generated preload headers and use [`StreamingHttpResponse`](https://docs.djangoproject.com/en/2.2/ref/request-response/#django.http.StreamingHttpResponse) on subsequent requests to send the headers early before the view starts executing. Disable this to use normal HTTPResponses with the preload headers attached at the end of view execution.
151 |
152 | #### `HTTP2_SERVER_PUSH`
153 | *Values:* `True`/[`False`]
154 |
155 | Allow upstream servers to server-push any files in preload headers.
156 | Disable this to add `; nopush` to all the preload headers to prevent upstream servers from pushing resources in advance.
157 | Keeping this set to `False` is recommended until cache-digests are sent by most browsers.
158 |
159 | ### `django-csp` Configuration
160 |
161 | There are many ways to implement Content Security Policy headers and nonces with Django,
162 | the most popular for django is [`django-csp`](https://github.com/mozilla/django-csp),
163 | which is library maintained by Mozilla. This library is built to be compatible
164 | with Mozilla's `django-csp`, but it's not required to use both together. You can find more info about
165 | configuring Django to do CSP verification here:
166 |
167 | - https://django-csp.readthedocs.io/en/latest/configuration.html#policy-settings
168 | - https://content-security-policy.com/
169 | - https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy
170 |
171 | ### Webserver Configuration
172 |
173 | In order to use HTTP2 server push, you need a webserver in front of Django that reads
174 | the preload headers and pushes the files. Cloudflare has a GUI [control panel option](https://www.cloudflare.com/website-optimization/http2/serverpush/) to enable server push,
175 | and nginx can do it with only one extra line of config:
176 |
177 | ```nginx
178 | server {
179 | listen 443 ssl http2;
180 | http2_push_preload on; # nginx will automatically server-push anything specified in preload headers
181 | ...
182 | }
183 | ```
184 |
185 | See more info and nginx http2 options here:
186 |
187 | - https://www.nginx.com/blog/nginx-1-13-9-http2-server-push/
188 | - http://nginx.org/en/docs/http/ngx_http_v2_module.html
189 |
190 |
191 | ## Verifying it works
192 |
193 | 
194 |
195 | Responses can be served in three different ways when using `django-http2-middleware`. You can inspect which way is
196 | used for a given response by looking at the `x-http2-preload` header attached to the response.
197 | If all the options are enabled, it takes two initial requests after enabling the middleware and starting Django for the cache to warm up, one to detect the content type, and one to build the list of resource URLs used by the template:
198 |
199 | 1. The first request to a given URL has no preload headers sent in advance (`x-http2-preload: off`). It's used to confirm that the request and response are `Content-Type: text/html` and not a JSON API request, file download, or other non-html type that shouldn't have preload headers attached.
200 | 2. The second request has preload headers but only attaches them after the response is generated (`x-http2-preload: late`). It's used build the initial cache of preload urls for the given `request.path` by collecting urls used by `{% http2static %}` tags during template rendering.
201 | 3. If `HTTP2_PRESEND_CACHED_HEADERS = True`, the third request (and all requests after that) send the cached headers immediately before the response is generated (`x-http2-preload: early`). If presending cached headers is disabled, then `StreamingHttpResponse` wont be used to pre-send headers before the view, and preload headers will be attached after the response as usual in `x-http2-preload: late` mode.
202 |
203 | Start runserver behind nginx and reload your page 4 times while watching the dev console to confirm the cache warms up properly and later requests receive server-pushed resources. If everyting is working correctly,
204 | the third pageload and all subsequent loads by all users should show up with the `x-http2-preload: early` response header, and pushed resources should appear significantly earlier in the network timing watefall view.
205 |
206 | You can inspect the preload performance of a given page and confirm it matches what you expect for its `x-http2-preload` mode using the network requests waterfall graph in the Chrome/Firefox/Safari dev tools.
207 |
208 |
209 | | `x-http2-preload: off` | `x-http2-preload: late` | `x-http2-preload: early` |
210 | | ------------------------------ | -------------------------------------- | ------------------------------------- |
211 | |  |  |  |
212 | | Requires: | Requires: | Requires: |
213 | | `HTTP2_PRELOAD_HEADERS = True` | `HTTP2_PRELOAD_HEADERS = True` | `HTTP2_PRELOAD_HEADERS = True` |
214 | | | `HTTP2_PRESEND_CACHED_HEADERS = True` | `HTTP2_PRESEND_CACHED_HEADERS = True` |
215 | | | | `HTTP2_SERVER_PUSH = True` |
216 |
217 | If you set `HTTP2_PRESEND_CACHED_HEADERS = True` and `HTTP2_SERVER_PUSH = False`, responses will all be sent in `x-http2-preload: late` mode, which is the recommended mode until cache digests become available in most browsers.
218 |
219 |