/docs/ref/middleware.txt

  1==========
  2Middleware
  3==========
  4
  5.. module:: django.middleware
  6   :synopsis: Django's built-in middleware classes.
  7
  8This document explains all middleware components that come with Django. For
  9information on how to use them and how to write your own middleware, see
 10the :doc:`middleware usage guide </topics/http/middleware>`.
 11
 12Available middleware
 13====================
 14
 15Cache middleware
 16----------------
 17
 18.. module:: django.middleware.cache
 19   :synopsis: Middleware for the site-wide cache.
 20
 21.. class:: UpdateCacheMiddleware
 22
 23.. class:: FetchFromCacheMiddleware
 24
 25Enable the site-wide cache. If these are enabled, each Django-powered page will
 26be cached for as long as the :setting:`CACHE_MIDDLEWARE_SECONDS` setting
 27defines. See the :doc:`cache documentation </topics/cache>`.
 28
 29"Common" middleware
 30-------------------
 31
 32.. module:: django.middleware.common
 33   :synopsis: Middleware adding "common" conveniences for perfectionists.
 34
 35.. class:: CommonMiddleware
 36
 37Adds a few conveniences for perfectionists:
 38
 39    * Forbids access to user agents in the :setting:`DISALLOWED_USER_AGENTS`
 40      setting, which should be a list of strings.
 41
 42    * Performs URL rewriting based on the :setting:`APPEND_SLASH` and
 43      :setting:`PREPEND_WWW` settings.
 44
 45      If :setting:`APPEND_SLASH` is ``True`` and the initial URL doesn't end
 46      with a slash, and it is not found in the URLconf, then a new URL is
 47      formed by appending a slash at the end. If this new URL is found in the
 48      URLconf, then Django redirects the request to this new URL. Otherwise,
 49      the initial URL is processed as usual.
 50
 51      For example, ``foo.com/bar`` will be redirected to ``foo.com/bar/`` if
 52      you don't have a valid URL pattern for ``foo.com/bar`` but *do* have a
 53      valid pattern for ``foo.com/bar/``.
 54
 55      If :setting:`PREPEND_WWW` is ``True``, URLs that lack a leading "www."
 56      will be redirected to the same URL with a leading "www."
 57
 58      Both of these options are meant to normalize URLs. The philosophy is that
 59      each URL should exist in one, and only one, place. Technically a URL
 60      ``foo.com/bar`` is distinct from ``foo.com/bar/`` -- a search-engine
 61      indexer would treat them as separate URLs -- so it's best practice to
 62      normalize URLs.
 63
 64    * Sends broken link notification emails to :setting:`MANAGERS` if
 65      :setting:`SEND_BROKEN_LINK_EMAILS` is set to ``True``.
 66
 67    * Handles ETags based on the :setting:`USE_ETAGS` setting. If
 68      :setting:`USE_ETAGS` is set to ``True``, Django will calculate an ETag
 69      for each request by MD5-hashing the page content, and it'll take care of
 70      sending ``Not Modified`` responses, if appropriate.
 71
 72View metadata middleware
 73------------------------
 74
 75.. module:: django.middleware.doc
 76   :synopsis: Middleware to help your app self-document.
 77
 78.. class:: XViewMiddleware
 79
 80Sends custom ``X-View`` HTTP headers to HEAD requests that come from IP
 81addresses defined in the :setting:`INTERNAL_IPS` setting. This is used by
 82Django's :doc:`automatic documentation system </ref/contrib/admin/admindocs>`.
 83
 84GZIP middleware
 85---------------
 86
 87.. module:: django.middleware.gzip
 88   :synopsis: Middleware to serve gziped content for performance.
 89
 90.. class:: GZipMiddleware
 91
 92Compresses content for browsers that understand gzip compression (all modern
 93browsers).
 94
 95It is suggested to place this first in the middleware list, so that the
 96compression of the response content is the last thing that happens. Will not
 97compress content bodies less than 200 bytes long, when the response code is
 98something other than 200, JavaScript files (for IE compatibility), or
 99responses that have the ``Content-Encoding`` header already specified.
100
101GZip compression can be applied to individual views using the
102:func:`~django.views.decorators.http.gzip_page()` decorator.
103
104Conditional GET middleware
105--------------------------
106
107.. module:: django.middleware.http
108   :synopsis: Middleware handling advanced HTTP features.
109
110.. class:: ConditionalGetMiddleware
111
112Handles conditional GET operations. If the response has a ``ETag`` or
113``Last-Modified`` header, and the request has ``If-None-Match`` or
114``If-Modified-Since``, the response is replaced by an
115:class:`~django.http.HttpNotModified`.
116
117Also sets the ``Date`` and ``Content-Length`` response-headers.
118
119Reverse proxy middleware
120------------------------
121
122.. class:: SetRemoteAddrFromForwardedFor
123
124This middleware was removed in Django 1.1. See :ref:`the release notes
125<removed-setremoteaddrfromforwardedfor-middleware>` for details.
126
127Locale middleware
128-----------------
129
130.. module:: django.middleware.locale
131   :synopsis: Middleware to enable language selection based on the request.
132
133.. class:: LocaleMiddleware
134
135Enables language selection based on data from the request. It customizes
136content for each user. See the :doc:`internationalization documentation
137</topics/i18n/index>`.
138
139Message middleware
140------------------
141
142.. module:: django.contrib.messages.middleware
143   :synopsis: Message middleware.
144
145.. class:: MessageMiddleware
146
147.. versionadded:: 1.2
148   ``MessageMiddleware`` was added.
149
150Enables cookie- and session-based message support. See the
151:doc:`messages documentation </ref/contrib/messages>`.
152
153Session middleware
154------------------
155
156.. module:: django.contrib.sessions.middleware
157   :synopsis: Session middleware.
158
159.. class:: SessionMiddleware
160
161Enables session support. See the :doc:`session documentation
162</topics/http/sessions>`.
163
164Authentication middleware
165-------------------------
166
167.. module:: django.contrib.auth.middleware
168  :synopsis: Authentication middleware.
169
170.. class:: AuthenticationMiddleware
171
172Adds the ``user`` attribute, representing the currently-logged-in user, to
173every incoming ``HttpRequest`` object. See :doc:`Authentication in Web requests
174</topics/auth>`.
175
176CSRF protection middleware
177--------------------------
178
179.. module:: django.middleware.csrf
180   :synopsis: Middleware adding protection against Cross Site Request
181              Forgeries.
182
183.. class:: CsrfMiddleware
184
185Adds protection against Cross Site Request Forgeries by adding hidden form
186fields to POST forms and checking requests for the correct value. See the
187:doc:`Cross Site Request Forgery protection documentation </ref/contrib/csrf>`.
188
189Transaction middleware
190----------------------
191
192.. module:: django.middleware.transaction
193   :synopsis: Middleware binding a database transaction to each Web request.
194
195.. class:: TransactionMiddleware
196
197Binds commit and rollback to the request/response phase. If a view function
198runs successfully, a commit is done. If it fails with an exception, a rollback
199is done.
200
201The order of this middleware in the stack is important: middleware modules
202running outside of it run with commit-on-save - the default Django behavior.
203Middleware modules running inside it (coming later in the stack) will be under
204the same transaction control as the view functions.
205
206See the :doc:`transaction management documentation </topics/db/transactions>`.