django-cache-headers 0.3

Configurable middleware to add HTTP caching headers for URL's.

Django Cache Headers
====================

.. figure:: https://travis-ci.org/praekelt/django-cache-headers.svg?branch=develop
:align: center
:alt: Travis

Overview
--------

Django Cache Headers allows you to set HTTP caching headers for URL patterns
according to certain policies. It does not perform any caching itself - it
merely sets the headers on the response which are then interpreted by eg. Varnish.

Doing a truly zero-conf Varnish turned out to be fragile, so Django Cache
Headers now generates a VCL file that can be included into or adapted to your
default Varnish configuration file.

Installation
------------

1. Install or add ``django-cache-headers`` to your Python path.
2. Add ``cache_headers`` to your ``INSTALLED_APPS`` setting.
3. Add ``cache_headers.middleware.CacheHeadersMiddleware`` before
SessionMiddleware and AuthenticationMiddleware and MessageMiddleware to your
``MIDDLEWARE_CLASSES`` setting.

Policies
--------
Django Cache Headers provides four caching policies. You may define your own policies.:

1. all-users - response is marked as cached once for all users.
2. anonymous-only - response is marked as cached once only for anonymous users.
3. anonymous-and-authenticated - response is marked as cached once for anonymous users and once for authenticated users.
4. per-user - response is marked as cached once for anonymous users and for each authenticated user individually.

Settings
--------

The ``timeouts`` key combines the policy, timeout in seconds and URL regexes in a nested dictionary::

CACHE_HEADERS = {
"timeouts": {
"all-users": {
60: (
"^/all-users/",
)
},
"anonymous-only": {
60: (
"^/anonymous-only/",
)
},
"anonymous-and-authenticated": {
60: (
"^/anonymous-and-authenticated/",
)
},
"per-user": {
60: (
"^/per-user/",
)
},
"custom-policy": {
60: (
"^/custom-policy/",
)
}
}
}

Set ``browser-cache-seconds`` to specify how long the browser may cache a
response before it has to revalidate with the server. It defaults to 5 seconds.::

CACHE_HEADERS = {"browser-cache-seconds": 10}

Varnish configuration
---------------------

Generate the VCL snippet::

python manage.py generate_vcl > /path/to/generated.vcl

Save the contents of `sample.vcl <sample.vcl>`_ as `/etc/varnish/default.vcl`.
Restart Varnish for the configuration to take effect.

Authors
=======

Praekelt Consulting
-------------------

* Hedley Roos
* Altus Barry
Changelog
=========

0.3
---
#. Added vcl generation management command, to be used in tandem with varnish. sample.vcl updated to reflect usage.
#. Make use of on_user_auth_event to ensure no-cache header is set during login and logout.
#. Extra protection against tampered session cookie.
#. Policies no longer makes an assumption on the session cookie name.

0.2.2
-----
#. Iterate over regexes in order of most specific (longest) to least specific (shortest).
#. Revert OrderedDict change since it is not required anymore due to the above change.

0.2.1
-----
#. Use an OrderedDict for guaranteed policy iteration order.

0.2
---
#. Ignoring cookies completely when setting headers turned out to be a mistake due to too many security concerns. Restore them.

0.1.3
-----
#. Handle case where user may also be logged in and a cookie not being set.

0.1.2
-----
#. Use the s-maxage header for compatability with Varnish.

0.1.1
-----
#. Leave response untouched if status code is not 200.

0.1
---
#. Initial release.