| 1 |
=========================== |
| 2 |
Conditional View Processing |
| 3 |
=========================== |
| 4 |
|
| 5 |
HTTP clients can send a number of headers to tell the server about copies of a |
| 6 |
resource that they have already seen. This is commonly used when retrieving a |
| 7 |
web page (using an HTTP ``GET`` request) to avoid sending all the data for |
| 8 |
something the client has already retrieved. However, the same headers can be |
| 9 |
used for all HTTP methods (``POST``, ``PUT``, ``DELETE``, etc.). |
| 10 |
|
| 11 |
For each page (response) that Django sends back from a view, it might provide |
| 12 |
two HTTP headers: the ``ETag`` header and the ``Last-Modified`` header. These |
| 13 |
headers are optional on HTTP responses. They can be set by your view function, |
| 14 |
or you can rely on the :class:`~django.middleware.http.ConditionalGetMiddleware` |
| 15 |
middleware to set the ``ETag`` header. |
| 16 |
|
| 17 |
When the client next requests the same resource, it might send along a header |
| 18 |
such as either :rfc:`If-Modified-Since <9110#section-13.1.3>` or |
| 19 |
:rfc:`If-Unmodified-Since <9110#section-13.1.4>`, containing the date of the |
| 20 |
last modification time it was sent, or either :rfc:`If-Match |
| 21 |
<9110#section-13.1.1>` or :rfc:`If-None-Match <9110#section-13.1.2>`, |
| 22 |
containing the last ``ETag`` it was sent. If the current version of the page |
| 23 |
matches the ``ETag`` sent by the client, or if the resource has not been |
| 24 |
modified, a 304 status code can be sent back, instead of a full response, |
| 25 |
telling the client that nothing has changed. Depending on the header, if the |
| 26 |
page has been modified or does not match the ``ETag`` sent by the client, a 412 |
| 27 |
status code (Precondition Failed) may be returned. |
| 28 |
|
| 29 |
When you need more fine-grained control you may use per-view conditional |
| 30 |
processing functions. |
| 31 |
|
| 32 |
.. _conditional-decorators: |
| 33 |
|
| 34 |
The ``condition`` decorator |
| 35 |
=========================== |
| 36 |
|
| 37 |
Sometimes (in fact, quite often) you can create functions to rapidly compute |
| 38 |
the :rfc:`ETag <9110#section-8.8.3>` value or the last-modified time for a |
| 39 |
resource, **without** needing to do all the computations needed to construct |
| 40 |
the full view. Django can then use these functions to provide an |
| 41 |
"early bailout" option for the view processing. Telling the client that the |
| 42 |
content has not been modified since the last request, perhaps. |
| 43 |
|
| 44 |
These two functions are passed as parameters to the |
| 45 |
``django.views.decorators.http.condition`` decorator. This decorator uses |
| 46 |
the two functions (you only need to supply one, if you can't compute both |
| 47 |
quantities easily and quickly) to work out if the headers in the HTTP request |
| 48 |
match those on the resource. If they don't match, a new copy of the resource |
| 49 |
must be computed and your normal view is called. |
| 50 |
|
| 51 |
The ``condition`` decorator's signature looks like this:: |
| 52 |
|
| 53 |
condition(etag_func=None, last_modified_func=None) |
| 54 |
|
| 55 |
The two functions, to compute the ETag and the last modified time, will be |
| 56 |
passed the incoming ``request`` object and the same parameters, in the same |
| 57 |
order, as the view function they are helping to wrap. The function passed |
| 58 |
``last_modified_func`` should return a standard datetime value specifying the |
| 59 |
last time the resource was modified, or ``None`` if the resource doesn't |
| 60 |
exist. The function passed to the ``etag`` decorator should return a string |
| 61 |
representing the :rfc:`ETag <9110#section-8.8.3>` for the resource, or ``None`` |
| 62 |
if it doesn't exist. |
| 63 |
|
| 64 |
The decorator sets the ``ETag`` and ``Last-Modified`` headers on the response |
| 65 |
if they are not already set by the view and if the request's method is safe |
| 66 |
(``GET`` or ``HEAD``). |
| 67 |
|
| 68 |
Using this feature usefully is probably best explained with an example. |
| 69 |
Suppose you have this pair of models, representing a small blog system:: |
| 70 |
|
| 71 |
import datetime |
| 72 |
from django.db import models |
| 73 |
|
| 74 |
|
| 75 |
class Blog(models.Model): ... |
| 76 |
|
| 77 |
|
| 78 |
class Entry(models.Model): |
| 79 |
blog = models.ForeignKey(Blog, on_delete=models.CASCADE) |
| 80 |
published = models.DateTimeField(default=datetime.datetime.now) |
| 81 |
... |
| 82 |
|
| 83 |
If the front page, displaying the latest blog entries, only changes when you |
| 84 |
add a new blog entry, you can compute the last modified time very quickly. You |
| 85 |
need the latest ``published`` date for every entry associated with that blog. |
| 86 |
One way to do this would be:: |
| 87 |
|
| 88 |
def latest_entry(request, blog_id): |
| 89 |
return Entry.objects.filter(blog=blog_id).latest("published").published |
| 90 |
|
| 91 |
You can then use this function to provide early detection of an unchanged page |
| 92 |
for your front page view:: |
| 93 |
|
| 94 |
from django.views.decorators.http import condition |
| 95 |
|
| 96 |
|
| 97 |
@condition(last_modified_func=latest_entry) |
| 98 |
def front_page(request, blog_id): ... |
| 99 |
|
| 100 |
.. admonition:: Be careful with the order of decorators |
| 101 |
|
| 102 |
When ``condition()`` returns a conditional response, any decorators below |
| 103 |
it will be skipped and won't apply to the response. Therefore, any |
| 104 |
decorators that need to apply to both the regular view response and a |
| 105 |
conditional response must be above ``condition()``. In particular, |
| 106 |
:func:`~django.views.decorators.vary.vary_on_cookie`, |
| 107 |
:func:`~django.views.decorators.vary.vary_on_headers`, and |
| 108 |
:func:`~django.views.decorators.cache.cache_control` should come first |
| 109 |
because :rfc:`RFC 9110 <9110#section-15.4.5>` requires that the headers |
| 110 |
they set be present on 304 responses. |
| 111 |
|
| 112 |
Shortcuts for only computing one value |
| 113 |
====================================== |
| 114 |
|
| 115 |
As a general rule, if you can provide functions to compute *both* the ETag and |
| 116 |
the last modified time, you should do so. You don't know which headers any |
| 117 |
given HTTP client will send you, so be prepared to handle both. However, |
| 118 |
sometimes only one value is easy to compute and Django provides decorators |
| 119 |
that handle only ETag or only last-modified computations. |
| 120 |
|
| 121 |
The ``django.views.decorators.http.etag`` and |
| 122 |
``django.views.decorators.http.last_modified`` decorators are passed the same |
| 123 |
type of functions as the ``condition`` decorator. Their signatures are:: |
| 124 |
|
| 125 |
etag(etag_func) |
| 126 |
last_modified(last_modified_func) |
| 127 |
|
| 128 |
We could write the earlier example, which only uses a last-modified function, |
| 129 |
using one of these decorators:: |
| 130 |
|
| 131 |
@last_modified(latest_entry) |
| 132 |
def front_page(request, blog_id): ... |
| 133 |
|
| 134 |
...or:: |
| 135 |
|
| 136 |
def front_page(request, blog_id): ... |
| 137 |
|
| 138 |
|
| 139 |
front_page = last_modified(latest_entry)(front_page) |
| 140 |
|
| 141 |
Use ``condition`` when testing both conditions |
| 142 |
---------------------------------------------- |
| 143 |
|
| 144 |
It might look nicer to some people to try and chain the ``etag`` and |
| 145 |
``last_modified`` decorators if you want to test both preconditions. However, |
| 146 |
this would lead to incorrect behavior. |
| 147 |
|
| 148 |
:: |
| 149 |
|
| 150 |
# Bad code. Don't do this! |
| 151 |
@etag(etag_func) |
| 152 |
@last_modified(last_modified_func) |
| 153 |
def my_view(request): ... |
| 154 |
|
| 155 |
|
| 156 |
# End of bad code. |
| 157 |
|
| 158 |
The first decorator doesn't know anything about the second and might |
| 159 |
answer that the response is not modified even if the second decorators would |
| 160 |
determine otherwise. The ``condition`` decorator uses both callback functions |
| 161 |
simultaneously to work out the right action to take. |
| 162 |
|
| 163 |
Using the decorators with other HTTP methods |
| 164 |
============================================ |
| 165 |
|
| 166 |
The ``condition`` decorator is useful for more than only ``GET`` and |
| 167 |
``HEAD`` requests (``HEAD`` requests are the same as ``GET`` in this |
| 168 |
situation). It can also be used to provide checking for ``POST``, |
| 169 |
``PUT`` and ``DELETE`` requests. In these situations, the idea isn't to return |
| 170 |
a "not modified" response, but to tell the client that the resource they are |
| 171 |
trying to change has been altered in the meantime. |
| 172 |
|
| 173 |
For example, consider the following exchange between the client and server: |
| 174 |
|
| 175 |
#. Client requests ``/foo/``. |
| 176 |
#. Server responds with some content with an ETag of ``"abcd1234"``. |
| 177 |
#. Client sends an HTTP ``PUT`` request to ``/foo/`` to update the |
| 178 |
resource. It also sends an ``If-Match: "abcd1234"`` header to specify |
| 179 |
the version it is trying to update. |
| 180 |
#. Server checks to see if the resource has changed, by computing the ETag |
| 181 |
the same way it does for a ``GET`` request (using the same function). |
| 182 |
If the resource *has* changed, it will return a 412 status code, |
| 183 |
meaning "precondition failed". |
| 184 |
#. Client sends a ``GET`` request to ``/foo/``, after receiving a 412 |
| 185 |
response, to retrieve an updated version of the content before updating |
| 186 |
it. |
| 187 |
|
| 188 |
The important thing this example shows is that the same functions can be used |
| 189 |
to compute the ETag and last modification values in all situations. In fact, |
| 190 |
you **should** use the same functions, so that the same values are returned |
| 191 |
every time. |
| 192 |
|
| 193 |
.. admonition:: Validator headers with non-safe request methods |
| 194 |
|
| 195 |
The ``condition`` decorator only sets validator headers (``ETag`` and |
| 196 |
``Last-Modified``) for safe HTTP methods, i.e. ``GET`` and ``HEAD``. If you |
| 197 |
wish to return them in other cases, set them in your view. See |
| 198 |
:rfc:`9110#section-9.3.4` to learn about the distinction between setting a |
| 199 |
validator header in response to requests made with ``PUT`` versus ``POST``. |
| 200 |
|
| 201 |
Comparison with middleware conditional processing |
| 202 |
================================================= |
| 203 |
|
| 204 |
Django provides conditional ``GET`` handling via |
| 205 |
:class:`django.middleware.http.ConditionalGetMiddleware`. While being suitable |
| 206 |
for many situations, the middleware has limitations for advanced usage: |
| 207 |
|
| 208 |
* It's applied globally to all views in your project. |
| 209 |
* It doesn't save you from generating the response, which may be expensive. |
| 210 |
* It's only appropriate for HTTP ``GET`` requests. |
| 211 |
|
| 212 |
You should choose the most appropriate tool for your particular problem here. |
| 213 |
If you have a way to compute ETags and modification times quickly and if some |
| 214 |
view takes a while to generate the content, you should consider using the |
| 215 |
``condition`` decorator described in this document. If everything already runs |
| 216 |
fairly quickly, stick to using the middleware and the amount of network |
| 217 |
traffic sent back to the clients will still be reduced if the view hasn't |
| 218 |
changed. |