| """ |
| This module contains helper functions for controlling caching. It does so by |
| managing the "Vary" header of responses. It includes functions to patch the |
| header of response objects directly and decorators that change functions to do |
| that header-patching themselves. |
| |
| For information on the Vary header, see: |
| |
| http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44 |
| |
| Essentially, the "Vary" HTTP header defines which headers a cache should take |
| into account when building its cache key. Requests with the same path but |
| different header content for headers named in "Vary" need to get different |
| cache keys to prevent delivery of wrong content. |
| |
| A example: i18n middleware would need to distinguish caches by the |
| "Accept-language" header. |
| """ |
| |
| import datetime, md5, re |
| from django.conf import settings |
| from django.core.cache import cache |
| |
| cc_delim_re = re.compile(r'\s*,\s*') |
| |
| def patch_cache_control(response, **kwargs): |
| """ |
| This function patches the Cache-Control header by adding all |
| keyword arguments to it. The transformation is as follows: |
| |
| * All keyword parameter names are turned to lowercase, and underscores |
| are converted to hyphens. |
| * If the value of a parameter is True (exactly True, not just a |
| true value), only the parameter name is added to the header. |
| * All other parameters are added with their value, after applying |
| str() to it. |
| """ |
| def dictitem(s): |
| t = s.split('=',1) |
| if len(t) > 1: |
| return (t[0].lower().replace('-', '_'), t[1]) |
| else: |
| return (t[0].lower().replace('-', '_'), True) |
| |
| def dictvalue(t): |
| if t[1] == True: |
| return t[0] |
| else: |
| return t[0] + '=' + str(t[1]) |
| |
| if response.has_header('Cache-Control'): |
| cc = cc_delim_re.split(response['Cache-Control']) |
| cc = dict([dictitem(el) for el in cc]) |
| else: |
| cc = {} |
| for (k,v) in kwargs.items(): |
| cc[k.replace('_', '-')] = v |
| cc = ', '.join([dictvalue(el) for el in cc.items()]) |
| response['Cache-Control'] = cc |
| |
| vary_delim_re = re.compile(r',\s*') |
| |
| def patch_response_headers(response, cache_timeout=None): |
| """ |
| Adds some useful headers to the given HttpResponse object: |
| ETag, Last-Modified, Expires and Cache-Control |
| |
| Each header is only added if it isn't already set. |
| |
| cache_timeout is in seconds. The CACHE_MIDDLEWARE_SECONDS setting is used |
| by default. |
| """ |
| if cache_timeout is None: |
| cache_timeout = settings.CACHE_MIDDLEWARE_SECONDS |
| now = datetime.datetime.utcnow() |
| if not response.has_header('ETag'): |
| response['ETag'] = md5.new(response.content).hexdigest() |
| if not response.has_header('Last-Modified'): |
| response['Last-Modified'] = now.strftime('%a, %d %b %Y %H:%M:%S GMT') |
| if not response.has_header('Expires'): |
| expires = now + datetime.timedelta(0, cache_timeout) |
| response['Expires'] = expires.strftime('%a, %d %b %Y %H:%M:%S GMT') |
| if cache_timeout < 0: |
| cache_timeout = 0 # Can't have max-age negative |
| patch_cache_control(response, max_age=cache_timeout) |
| |
| def add_never_cache_headers(response): |
| """ |
| Add headers to a response to indicate that |
| a page should never be cached. |
| """ |
| patch_response_headers(response, cache_timeout=-1) |
| |
| def patch_vary_headers(response, newheaders): |
| """ |
| Adds (or updates) the "Vary" header in the given HttpResponse object. |
| newheaders is a list of header names that should be in "Vary". Existing |
| headers in "Vary" aren't removed. |
| """ |
| # Note that we need to keep the original order intact, because cache |
| # implementations may rely on the order of the Vary contents in, say, |
| # computing an MD5 hash. |
| vary = [] |
| if response.has_header('Vary'): |
| vary = vary_delim_re.split(response['Vary']) |
| oldheaders = dict([(el.lower(), 1) for el in vary]) |
| for newheader in newheaders: |
| if not newheader.lower() in oldheaders: |
| vary.append(newheader) |
| response['Vary'] = ', '.join(vary) |
| |
| def _generate_cache_key(request, headerlist, key_prefix): |
| "Returns a cache key from the headers given in the header list." |
| ctx = md5.new() |
| for header in headerlist: |
| value = request.META.get(header, None) |
| if value is not None: |
| ctx.update(value) |
| return 'views.decorators.cache.cache_page.%s.%s.%s' % (key_prefix, request.path, ctx.hexdigest()) |
| |
| def get_cache_key(request, key_prefix=None): |
| """ |
| Returns a cache key based on the request path. It can be used in the |
| request phase because it pulls the list of headers to take into account |
| from the global path registry and uses those to build a cache key to check |
| against. |
| |
| If there is no headerlist stored, the page needs to be rebuilt, so this |
| function returns None. |
| """ |
| if key_prefix is None: |
| key_prefix = settings.CACHE_MIDDLEWARE_KEY_PREFIX |
| cache_key = 'views.decorators.cache.cache_header.%s.%s' % (key_prefix, request.path) |
| headerlist = cache.get(cache_key, None) |
| if headerlist is not None: |
| return _generate_cache_key(request, headerlist, key_prefix) |
| else: |
| return None |
| |
| def learn_cache_key(request, response, cache_timeout=None, key_prefix=None): |
| """ |
| Learns what headers to take into account for some request path from the |
| response object. It stores those headers in a global path registry so that |
| later access to that path will know what headers to take into account |
| without building the response object itself. The headers are named in the |
| Vary header of the response, but we want to prevent response generation. |
| |
| The list of headers to use for cache key generation is stored in the same |
| cache as the pages themselves. If the cache ages some data out of the |
| cache, this just means that we have to build the response once to get at |
| the Vary header and so at the list of headers to use for the cache key. |
| """ |
| if key_prefix is None: |
| key_prefix = settings.CACHE_MIDDLEWARE_KEY_PREFIX |
| if cache_timeout is None: |
| cache_timeout = settings.CACHE_MIDDLEWARE_SECONDS |
| cache_key = 'views.decorators.cache.cache_header.%s.%s' % (key_prefix, request.path) |
| if response.has_header('Vary'): |
| headerlist = ['HTTP_'+header.upper().replace('-', '_') for header in vary_delim_re.split(response['Vary'])] |
| cache.set(cache_key, headerlist, cache_timeout) |
| return _generate_cache_key(request, headerlist, key_prefix) |
| else: |
| # if there is no Vary header, we still need a cache key |
| # for the request.path |
| cache.set(cache_key, [], cache_timeout) |
| return _generate_cache_key(request, [], key_prefix) |
