.. middleware:

Middleware
==========

.. module:: swingers.middleware
   :synopsis: Swingers' built-in middleware classes.

Swingers' built-in middleware classes.

Authentication middleware
-------------------------

.. class:: AuthenticationMiddleware

Adds functionality including:

- setting the request on our thread local storage ``_locals``.
- adds ``request.SITE_NAME`` and ``request.footer`` to the request object.
- checks ``request.GET`` and the ``HTTP_ACCESS_TOKEN`` header for an access
  token, and refreshes it if necessary.
- redirects the user to ``settings.LOGIN_URL`` if they are unauthenticated and
  the url is not in ``settings.LOGIN_EXEMPT_URLS`` and
  ``settings.ALLOW_ANONYMOUS_ACCESS`` is false.
- sets access control headers on the response for cross-site request forgery
  protection, and allows content types other than JSONP to be served to the
  client.

To enable it in your application add it to
:django:setting:`MIDDLEWARE_CLASSES`::

    MIDDLEWARE_CLASSES = (
        # previous middleware classes
        'swingers.middleware.AuthenticationMiddleware',
    )


Transaction middleware
----------------------

.. class:: ResponseStatusTransactionMiddleware

ResponseStatusTransactionMiddleware is almost exactly the same as Django's
included :class:`~django.middleware.transaction.TransactionMiddleware`, except
it will rollback the transaction when the HTTP response status is an error.
Response status codes that result in a rollback: `>= 400, >=500`. Use this if
you don't want to worry about transactions.

    .. note:: This is going to be deprecated since django's transaction middleware
              superseedes this in Django 1.6


Caching middleware
------------------

.. class:: UpdateCacheMiddleware

UpdateCacheMiddleware is almost exactly the same as Django's
:class:`~django.middleware.cache.UpdateCacheMiddleware`, it adds functionality
to invalidate cache entries based on what db tables were written to in the
current request.

Use this if you don't want to worry about caching too much.
Think twice about using this if majority of your site is login protected and/or
majority of requests are NOT read-only.

This middleware extends django's UpdateCacheMiddleware and builds up
an associative array of cache_key(request) to read db tables. It examines
`django.db.connection` to determine which db tables were written to and
consequently deletes all cache_keys that read from those db tables. It uses
django's caching middleware to determine the cache keys, fetch from cache,
update cache, etc.

    .. note:: Still very fresh/experimental and alpha :), needs some
              testing/review.


HTML middleware
------------------

.. class:: HtmlMinifyMiddleware

This is a customization of `django-htmlmin's
<https://pypi.python.org/pypi/django-htmlmin>`_
:class:`htmlmin.middleware.HtmlMinifyMiddleware` in that HTML is not minified
when DEBUG toolbar is shown (uses `SHOW_TOOLBAR_CALLBACK` function in
`settings`). If DEBUG toolbar is not used, default behaviour is preserved
(minify when `not DEBUG`).
