From 1f6b3cf145fc1057f478607c2c845e66efaaf546 Mon Sep 17 00:00:00 2001
From: Claude Paroz <claude@2xlibre.net>
Date: Thu, 22 May 2014 17:08:32 +0200
Subject: [PATCH] [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 756c390fb5 from master.
---
 docs/ref/middleware.txt         | 68 +++++++++++++++++++++++++++++++++
 docs/topics/http/middleware.txt |  4 +-
 2 files changed, 71 insertions(+), 1 deletion(-)

diff --git a/docs/ref/middleware.txt b/docs/ref/middleware.txt
index 6a8ac6dde76..e5b2a946099 100644
--- a/docs/ref/middleware.txt
+++ b/docs/ref/middleware.txt
@@ -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.
diff --git a/docs/topics/http/middleware.txt b/docs/topics/http/middleware.txt
index b18573f0026..a2b71dc6648 100644
--- a/docs/topics/http/middleware.txt
+++ b/docs/topics/http/middleware.txt
@@ -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
 ===========================