Debian Codegraph @

django/utils/cache.py

raw
1 """
2 This module contains helper functions for controlling caching. It does so by
3 managing the "Vary" header of responses. It includes functions to patch the
4 header of response objects directly and decorators that change functions to do
5 that header-patching themselves.
6
7 For information on the Vary header, see RFC 9110 Section 12.5.5.
8
9 Essentially, the "Vary" HTTP header defines which headers a cache should take
10 into account when building its cache key. Requests with the same path but
11 different header content for headers named in "Vary" need to get different
12 cache keys to prevent delivery of wrong content.
13
14 An example: i18n middleware would need to distinguish caches by the
15 "Accept-language" header.
16 """
17
18 import time
19 from collections import defaultdict
20 from hashlib import md5
21
22 from django.conf import settings
23 from django.core.cache import caches
24 from django.http import HttpResponse, HttpResponseNotModified
25 from django.utils.http import http_date, parse_etags, parse_http_date_safe, quote_etag
26 from django.utils.log import log_response
27 from django.utils.regex_helper import _lazy_re_compile
28 from django.utils.timezone import get_current_timezone_name
29 from django.utils.translation import get_language
30
31 cc_delim_re = _lazy_re_compile(r"\s*,\s*")
32
33
34 def patch_cache_control(response, **kwargs):
35 """
36 Patch the Cache-Control header by adding all keyword arguments to it.
37 The transformation is as follows:
38
39 * All keyword parameter names are turned to lowercase, and underscores
40 are converted to hyphens.
41 * If the value of a parameter is True (exactly True, not just a
42 true value), only the parameter name is added to the header.
43 * All other parameters are added with their value, after applying
44 str() to it.
45 """
46
47 def dictitem(s):
48 t = s.split("=", 1)
49 if len(t) > 1:
50 return (t[0].lower(), t[1])
51 else:
52 return (t[0].lower(), True)
53
54 def dictvalue(*t):
55 if t[1] is True:
56 return t[0]
57 else:
58 return "%s=%s" % (t[0], t[1])
59
60 cc = defaultdict(set)
61 if response.get("Cache-Control"):
62 for field in cc_delim_re.split(response.headers["Cache-Control"]):
63 directive, value = dictitem(field)
64 if directive == "no-cache":
65 # no-cache supports multiple field names.
66 cc[directive].add(value)
67 else:
68 cc[directive] = value
69
70 # If there's already a max-age header but we're being asked to set a new
71 # max-age, use the minimum of the two ages. In practice this happens when
72 # a decorator and a piece of middleware both operate on a given view.
73 if "max-age" in cc and "max_age" in kwargs:
74 kwargs["max_age"] = min(int(cc["max-age"]), kwargs["max_age"])
75
76 # Allow overriding private caching and vice versa
77 if "private" in cc and "public" in kwargs:
78 del cc["private"]
79 elif "public" in cc and "private" in kwargs:
80 del cc["public"]
81
82 for k, v in kwargs.items():
83 directive = k.replace("_", "-")
84 if directive == "no-cache":
85 # no-cache supports multiple field names.
86 cc[directive].add(v)
87 else:
88 cc[directive] = v
89
90 directives = []
91 for directive, values in cc.items():
92 if isinstance(values, set):
93 if True in values:
94 # True takes precedence.
95 values = {True}
96 directives.extend([dictvalue(directive, value) for value in values])
97 else:
98 directives.append(dictvalue(directive, values))
99 cc = ", ".join(directives)
100 response.headers["Cache-Control"] = cc
101
102
103 def get_max_age(response):
104 """
105 Return the max-age from the response Cache-Control header as an integer,
106 or None if it wasn't found or wasn't an integer.
107 """
108 if not response.has_header("Cache-Control"):
109 return
110 cc = dict(
111 _to_tuple(el) for el in cc_delim_re.split(response.headers["Cache-Control"])
112 )
113 try:
114 return int(cc["max-age"])
115 except (ValueError, TypeError, KeyError):
116 pass
117
118
119 def set_response_etag(response):
120 if not response.streaming and response.content:
121 response.headers["ETag"] = quote_etag(
122 md5(response.content, usedforsecurity=False).hexdigest(),
123 )
124 return response
125
126
127 def _precondition_failed(request):
128 response = HttpResponse(status=412)
129 log_response(
130 "Precondition Failed: %s",
131 request.path,
132 response=response,
133 request=request,
134 )
135 return response
136
137
138 def _not_modified(request, response=None):
139 new_response = HttpResponseNotModified()
140 if response:
141 # Preserve the headers required by RFC 9110 Section 15.4.5, as well as
142 # Last-Modified.
143 for header in (
144 "Cache-Control",
145 "Content-Location",
146 "Date",
147 "ETag",
148 "Expires",
149 "Last-Modified",
150 "Vary",
151 ):
152 if header in response:
153 new_response.headers[header] = response.headers[header]
154
155 # Preserve cookies as per the cookie specification: "If a proxy server
156 # receives a response which contains a Set-cookie header, it should
157 # propagate the Set-cookie header to the client, regardless of whether
158 # the response was 304 (Not Modified) or 200 (OK).
159 # https://curl.haxx.se/rfc/cookie_spec.html
160 new_response.cookies = response.cookies
161 return new_response
162
163
164 def get_conditional_response(request, etag=None, last_modified=None, response=None):
165 # Only return conditional responses on successful requests.
166 if response and not (200 <= response.status_code < 300):
167 return response
168
169 # Get HTTP request headers.
170 if_match_etags = parse_etags(request.META.get("HTTP_IF_MATCH", ""))
171 if_unmodified_since = request.META.get("HTTP_IF_UNMODIFIED_SINCE")
172 if_unmodified_since = if_unmodified_since and parse_http_date_safe(
173 if_unmodified_since
174 )
175 if_none_match_etags = parse_etags(request.META.get("HTTP_IF_NONE_MATCH", ""))
176 if_modified_since = request.META.get("HTTP_IF_MODIFIED_SINCE")
177 if_modified_since = if_modified_since and parse_http_date_safe(if_modified_since)
178
179 # Evaluation of request preconditions below follows RFC 9110 Section
180 # 13.2.2.
181 # Step 1: Test the If-Match precondition.
182 if if_match_etags and not _if_match_passes(etag, if_match_etags):
183 return _precondition_failed(request)
184
185 # Step 2: Test the If-Unmodified-Since precondition.
186 if (
187 not if_match_etags
188 and if_unmodified_since
189 and not _if_unmodified_since_passes(last_modified, if_unmodified_since)
190 ):
191 return _precondition_failed(request)
192
193 # Step 3: Test the If-None-Match precondition.
194 if if_none_match_etags and not _if_none_match_passes(etag, if_none_match_etags):
195 if request.method in ("GET", "HEAD"):
196 return _not_modified(request, response)
197 else:
198 return _precondition_failed(request)
199
200 # Step 4: Test the If-Modified-Since precondition.
201 if (
202 not if_none_match_etags
203 and if_modified_since
204 and not _if_modified_since_passes(last_modified, if_modified_since)
205 and request.method in ("GET", "HEAD")
206 ):
207 return _not_modified(request, response)
208
209 # Step 5: Test the If-Range precondition (not supported).
210 # Step 6: Return original response since there isn't a conditional response.
211 return response
212
213
214 def _if_match_passes(target_etag, etags):
215 """
216 Test the If-Match comparison as defined in RFC 9110 Section 13.1.1.
217 """
218 if not target_etag:
219 # If there isn't an ETag, then there can't be a match.
220 return False
221 elif etags == ["*"]:
222 # The existence of an ETag means that there is "a current
223 # representation for the target resource", even if the ETag is weak,
224 # so there is a match to '*'.
225 return True
226 elif target_etag.startswith("W/"):
227 # A weak ETag can never strongly match another ETag.
228 return False
229 else:
230 # Since the ETag is strong, this will only return True if there's a
231 # strong match.
232 return target_etag in etags
233
234
235 def _if_unmodified_since_passes(last_modified, if_unmodified_since):
236 """
237 Test the If-Unmodified-Since comparison as defined in RFC 9110 Section
238 13.1.4.
239 """
240 return last_modified and last_modified <= if_unmodified_since
241
242
243 def _if_none_match_passes(target_etag, etags):
244 """
245 Test the If-None-Match comparison as defined in RFC 9110 Section 13.1.2.
246 """
247 if not target_etag:
248 # If there isn't an ETag, then there isn't a match.
249 return True
250 elif etags == ["*"]:
251 # The existence of an ETag means that there is "a current
252 # representation for the target resource", so there is a match to '*'.
253 return False
254 else:
255 # The comparison should be weak, so look for a match after stripping
256 # off any weak indicators.
257 target_etag = target_etag.strip("W/")
258 etags = (etag.strip("W/") for etag in etags)
259 return target_etag not in etags
260
261
262 def _if_modified_since_passes(last_modified, if_modified_since):
263 """
264 Test the If-Modified-Since comparison as defined in RFC 9110 Section
265 13.1.3.
266 """
267 return not last_modified or last_modified > if_modified_since
268
269
270 def patch_response_headers(response, cache_timeout=None):
271 """
272 Add HTTP caching headers to the given HttpResponse: Expires and
273 Cache-Control.
274
275 Each header is only added if it isn't already set.
276
277 cache_timeout is in seconds. The CACHE_MIDDLEWARE_SECONDS setting is used
278 by default.
279 """
280 if cache_timeout is None:
281 cache_timeout = settings.CACHE_MIDDLEWARE_SECONDS
282 if cache_timeout < 0:
283 cache_timeout = 0 # Can't have max-age negative
284 if not response.has_header("Expires"):
285 response.headers["Expires"] = http_date(time.time() + cache_timeout)
286 patch_cache_control(response, max_age=cache_timeout)
287
288
289 def add_never_cache_headers(response):
290 """
291 Add headers to a response to indicate that a page should never be cached.
292 """
293 patch_response_headers(response, cache_timeout=-1)
294 patch_cache_control(
295 response, no_cache=True, no_store=True, must_revalidate=True, private=True
296 )
297
298
299 def patch_vary_headers(response, newheaders):
300 """
301 Add (or update) the "Vary" header in the given HttpResponse object.
302 newheaders is a list of header names that should be in "Vary". If headers
303 contains an asterisk, then "Vary" header will consist of a single asterisk
304 '*'. Otherwise, existing headers in "Vary" aren't removed.
305 """
306 # Note that we need to keep the original order intact, because cache
307 # implementations may rely on the order of the Vary contents in, say,
308 # computing an MD5 hash.
309 if response.has_header("Vary"):
310 vary_headers = cc_delim_re.split(response.headers["Vary"])
311 else:
312 vary_headers = []
313 # Use .lower() here so we treat headers as case-insensitive.
314 existing_headers = {header.lower() for header in vary_headers}
315 additional_headers = [
316 newheader
317 for newheader in newheaders
318 if newheader.lower() not in existing_headers
319 ]
320 vary_headers += additional_headers
321 if "*" in vary_headers:
322 response.headers["Vary"] = "*"
323 else:
324 response.headers["Vary"] = ", ".join(vary_headers)
325
326
327 def has_vary_header(response, header_query):
328 """
329 Check to see if the response has a given header name in its Vary header.
330 """
331 if not response.has_header("Vary"):
332 return False
333 vary_headers = cc_delim_re.split(response.headers["Vary"])
334 existing_headers = {header.lower().strip() for header in vary_headers}
335 return header_query.lower().strip() in existing_headers
336
337
338 def _i18n_cache_key_suffix(request, cache_key):
339 """If necessary, add the current locale or time zone to the cache key."""
340 if settings.USE_I18N:
341 # first check if LocaleMiddleware or another middleware added
342 # LANGUAGE_CODE to request, then fall back to the active language
343 # which in turn can also fall back to settings.LANGUAGE_CODE
344 cache_key += ".%s" % getattr(request, "LANGUAGE_CODE", get_language())
345 if settings.USE_TZ:
346 cache_key += ".%s" % get_current_timezone_name()
347 return cache_key
348
349
350 def _generate_cache_key(request, method, headerlist, key_prefix):
351 """Return a cache key from the headers given in the header list."""
352 ctx = md5(usedforsecurity=False)
353 for header in headerlist:
354 value = request.META.get(header)
355 if value is not None:
356 ctx.update(value.encode())
357 url = md5(request.build_absolute_uri().encode("ascii"), usedforsecurity=False)
358 cache_key = "views.decorators.cache.cache_page.%s.%s.%s.%s" % (
359 key_prefix,
360 method,
361 url.hexdigest(),
362 ctx.hexdigest(),
363 )
364 return _i18n_cache_key_suffix(request, cache_key)
365
366
367 def _generate_cache_header_key(key_prefix, request):
368 """Return a cache key for the header cache."""
369 url = md5(request.build_absolute_uri().encode("ascii"), usedforsecurity=False)
370 cache_key = "views.decorators.cache.cache_header.%s.%s" % (
371 key_prefix,
372 url.hexdigest(),
373 )
374 return _i18n_cache_key_suffix(request, cache_key)
375
376
377 def get_cache_key(request, key_prefix=None, method="GET", cache=None):
378 """
379 Return a cache key based on the request URL and query. It can be used
380 in the request phase because it pulls the list of headers to take into
381 account from the global URL registry and uses those to build a cache key
382 to check against.
383
384 If there isn't a headerlist stored, return None, indicating that the page
385 needs to be rebuilt.
386 """
387 if key_prefix is None:
388 key_prefix = settings.CACHE_MIDDLEWARE_KEY_PREFIX
389 cache_key = _generate_cache_header_key(key_prefix, request)
390 if cache is None:
391 cache = caches[settings.CACHE_MIDDLEWARE_ALIAS]
392 headerlist = cache.get(cache_key)
393 if headerlist is not None:
394 return _generate_cache_key(request, method, headerlist, key_prefix)
395 else:
396 return None
397
398
399 def learn_cache_key(request, response, cache_timeout=None, key_prefix=None, cache=None):
400 """
401 Learn what headers to take into account for some request URL from the
402 response object. Store those headers in a global URL registry so that
403 later access to that URL will know what headers to take into account
404 without building the response object itself. The headers are named in the
405 Vary header of the response, but we want to prevent response generation.
406
407 The list of headers to use for cache key generation is stored in the same
408 cache as the pages themselves. If the cache ages some data out of the
409 cache, this just means that we have to build the response once to get at
410 the Vary header and so at the list of headers to use for the cache key.
411 """
412 if key_prefix is None:
413 key_prefix = settings.CACHE_MIDDLEWARE_KEY_PREFIX
414 if cache_timeout is None:
415 cache_timeout = settings.CACHE_MIDDLEWARE_SECONDS
416 cache_key = _generate_cache_header_key(key_prefix, request)
417 if cache is None:
418 cache = caches[settings.CACHE_MIDDLEWARE_ALIAS]
419 if response.has_header("Vary"):
420 is_accept_language_redundant = settings.USE_I18N
421 # If i18n is used, the generated cache key will be suffixed with the
422 # current locale. Adding the raw value of Accept-Language is redundant
423 # in that case and would result in storing the same content under
424 # multiple keys in the cache. See #18191 for details.
425 headerlist = []
426 for header in cc_delim_re.split(response.headers["Vary"]):
427 header = header.upper().replace("-", "_")
428 if header != "ACCEPT_LANGUAGE" or not is_accept_language_redundant:
429 headerlist.append("HTTP_" + header)
430 headerlist.sort()
431 cache.set(cache_key, headerlist, cache_timeout)
432 return _generate_cache_key(request, request.method, headerlist, key_prefix)
433 else:
434 # if there is no Vary header, we still need a cache key
435 # for the request.build_absolute_uri()
436 cache.set(cache_key, [], cache_timeout)
437 return _generate_cache_key(request, request.method, [], key_prefix)
438
439
440 def _to_tuple(s):
441 t = s.split("=", 1)
442 if len(t) == 2:
443 return t[0].lower(), t[1]
444 return t[0].lower(), True