Debian Codegraph @

docs/topics/conditional-view-processing.txt

raw
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.