Commit 1f6b3cf1 authored by Claude Paroz's avatar Claude Paroz
Browse files

[1.7.x] Fixed #20816 -- Added hints about Django middleware ordering 

Thanks gthb Trac user for the report, kolypto StackOverflow
user for the initial list and Tim Graham for the review.
Backport of 756c390f from master.
parent 7d4a51e2

docs/ref/middleware.txt

+68 −0
Original line number Diff line number Diff line
@@ -264,3 +264,71 @@ X-Frame-Options middleware 
.. class:: XFrameOptionsMiddleware



Simple :doc:`clickjacking protection via the X-Frame-Options header </ref/clickjacking/>`.



.. _middleware-ordering:



Middleware ordering

===================



Here are some hints about the ordering of various Django middleware classes:



#. :class:`~django.middleware.cache.UpdateCacheMiddleware`



   Before those that modify the ``Vary`` header (``SessionMiddleware``,

   ``GZipMiddleware``, ``LocaleMiddleware``).



#. :class:`~django.middleware.gzip.GZipMiddleware`



   Before any middleware that may change or use the response body.



   After ``UpdateCacheMiddleware``: Modifies ``Vary`` header.



#. :class:`~django.middleware.http.ConditionalGetMiddleware`



   Before ``CommonMiddleware``: uses its ``Etag`` header when

   :setting:`USE_ETAGS` = ``True``.



#. :class:`~django.contrib.sessions.middleware.SessionMiddleware`



   After ``UpdateCacheMiddleware``: Modifies ``Vary`` header.



#. :class:`~django.middleware.locale.LocaleMiddleware`



   One of the topmost, after ``SessionMiddleware`` (uses session data) and

   ``CacheMiddleware`` (modifies ``Vary`` header).



#. :class:`~django.middleware.common.CommonMiddleware`



   Before any middleware that may change the response (it calculates ``ETags``).



   After ``GZipMiddleware`` so it won't calculate an ``ETag`` header on gzipped

   contents.



   Close to the top: it redirects when :setting:`APPEND_SLASH` or

   :setting:`PREPEND_WWW` are set to ``True``.



#. :class:`~django.middleware.csrf.CsrfViewMiddleware`



   Before any view middleware that assumes that CSRF attacks have been dealt

   with.



#. :class:`~django.contrib.auth.middleware.AuthenticationMiddleware`



   After ``SessionMiddleware``: uses session storage.



#. :class:`~django.contrib.messages.middleware.MessageMiddleware`



   After ``SessionMiddleware``: can use session-based storage.



#. :class:`~django.middleware.cache.FetchFromCacheMiddleware`



   After any middleware that modifies the ``Vary`` header: that header is used

   to pick a value for the cache hash-key.



#. :class:`~django.contrib.flatpages.middleware.FlatpageFallbackMiddleware`



   Should be near the bottom as it's a last-resort type of middleware.



#. :class:`~django.contrib.redirects.middleware.RedirectFallbackMiddleware`



   Should be near the bottom as it's a last-resort type of middleware.

docs/topics/http/middleware.txt

+3 −1
Original line number Diff line number Diff line
@@ -45,7 +45,9 @@ The order in :setting:`MIDDLEWARE_CLASSES` matters because a middleware can 
depend on other middleware. For instance,

:class:`~django.contrib.auth.middleware.AuthenticationMiddleware` stores the

authenticated user in the session; therefore, it must run after

:class:`~django.contrib.sessions.middleware.SessionMiddleware`.

:class:`~django.contrib.sessions.middleware.SessionMiddleware`. See

:ref:`middleware-ordering` for some common hints about ordering of Django

middleware classes.



Hooks and application order

===========================