1 ==========

     2 Middleware

     3 ==========

     4 

     5 Middleware is a framework of hooks into Django's request/response processing.

     6 It's a light, low-level "plugin" system for globally altering Django's input

     7 and/or output.

     8 

     9 Each middleware component is responsible for doing some specific function. For

    10 example, Django includes a middleware component, ``XViewMiddleware``, that adds

    11 an ``"X-View"`` HTTP header to every response to a ``HEAD`` request.

    12 

    13 This document explains all middleware components that come with Django, how to

    14 use them, and how to write your own middleware.

    15 

    16 Activating middleware

    17 =====================

    18 

    19 To activate a middleware component, add it to the ``MIDDLEWARE_CLASSES`` list

    20 in your Django settings. In ``MIDDLEWARE_CLASSES``, each middleware component

    21 is represented by a string: the full Python path to the middleware's class

    22 name. For example, here's the default ``MIDDLEWARE_CLASSES`` created by

    23 ``django-admin.py startproject``::

    24 

    25     MIDDLEWARE_CLASSES = (

    26         'django.middleware.common.CommonMiddleware',

    27         'django.contrib.sessions.middleware.SessionMiddleware',

    28         'django.contrib.auth.middleware.AuthenticationMiddleware',

    29         'django.middleware.doc.XViewMiddleware',

    30     )

    31 

    32 Django applies middleware in the order it's defined in ``MIDDLEWARE_CLASSES``,

    33 except in the case of response and exception middleware, which is applied in

    34 reverse order.

    35 

    36 A Django installation doesn't require any middleware -- e.g.,

    37 ``MIDDLEWARE_CLASSES`` can be empty, if you'd like -- but it's strongly

    38 suggested that you use ``CommonMiddleware``.

    39 

    40 Available middleware

    41 ====================

    42 

    43 django.middleware.cache.CacheMiddleware

    44 ---------------------------------------

    45 

    46 Enables site-wide cache. If this is enabled, each Django-powered page will be

    47 cached for as long as the ``CACHE_MIDDLEWARE_SECONDS`` setting defines. See

    48 the `cache documentation`_.

    49 

    50 .. _`cache documentation`: ../cache/#the-per-site-cache

    51 

    52 django.middleware.common.CommonMiddleware

    53 -----------------------------------------

    54 

    55 Adds a few conveniences for perfectionists:

    56 

    57 * Forbids access to user agents in the ``DISALLOWED_USER_AGENTS`` setting,

    58   which should be a list of strings.

    59 

    60 * Performs URL rewriting based on the ``APPEND_SLASH`` and ``PREPEND_WWW``

    61   settings. If ``APPEND_SLASH`` is ``True``, URLs that lack a trailing

    62   slash will be redirected to the same URL with a trailing slash, unless the

    63   last component in the path contains a period. So ``foo.com/bar`` is

    64   redirected to ``foo.com/bar/``, but ``foo.com/bar/file.txt`` is passed

    65   through unchanged.

    66 

    67   If ``PREPEND_WWW`` is ``True``, URLs that lack a leading "www." will be

    68   redirected to the same URL with a leading "www."

    69 

    70   Both of these options are meant to normalize URLs. The philosophy is that

    71   each URL should exist in one, and only one, place. Technically a URL

    72   ``foo.com/bar`` is distinct from ``foo.com/bar/`` -- a search-engine

    73   indexer would treat them as separate URLs -- so it's best practice to

    74   normalize URLs.

    75 

    76 * Handles ETags based on the ``USE_ETAGS`` setting. If ``USE_ETAGS`` is set

    77   to ``True``, Django will calculate an ETag for each request by

    78   MD5-hashing the page content, and it'll take care of sending

    79   ``Not Modified`` responses, if appropriate.

    80 

    81 django.middleware.doc.XViewMiddleware

    82 -------------------------------------

    83 

    84 Sends custom ``X-View`` HTTP headers to HEAD requests that come from IP

    85 addresses defined in the ``INTERNAL_IPS`` setting. This is used by Django's

    86 automatic documentation system.

    87 

    88 django.middleware.gzip.GZipMiddleware

    89 -------------------------------------

    90 

    91 Compresses content for browsers that understand gzip compression (all modern

    92 browsers).

    93 

    94 django.middleware.http.ConditionalGetMiddleware

    95 -----------------------------------------------

    96 

    97 Handles conditional GET operations. If the response has a ``ETag`` or

    98 ``Last-Modified`` header, and the request has ``If-None-Match`` or

    99 ``If-Modified-Since``, the response is replaced by an HttpNotModified.

   100 

   101 Also removes the content from any response to a HEAD request and sets the

   102 ``Date`` and ``Content-Length`` response-headers.

   103 

   104 django.middleware.http.SetRemoteAddrFromForwardedFor

   105 ----------------------------------------------------

   106 

   107 Sets ``request.META['REMOTE_ADDR']`` based on

   108 ``request.META['HTTP_X_FORWARDED_FOR']``, if the latter is set. This is useful

   109 if you're sitting behind a reverse proxy that causes each request's

   110 ``REMOTE_ADDR`` to be set to ``127.0.0.1``.

   111 

   112 **Important note:** This does NOT validate ``HTTP_X_FORWARDED_FOR``. If you're

   113 not behind a reverse proxy that sets ``HTTP_X_FORWARDED_FOR`` automatically, do

   114 not use this middleware. Anybody can spoof the value of

   115 ``HTTP_X_FORWARDED_FOR``, and because this sets ``REMOTE_ADDR`` based on

   116 ``HTTP_X_FORWARDED_FOR``, that means anybody can "fake" their IP address. Only

   117 use this when you can absolutely trust the value of ``HTTP_X_FORWARDED_FOR``.

   118 

   119 django.contrib.sessions.middleware.SessionMiddleware

   120 ----------------------------------------------------

   121 

   122 Enables session support. See the `session documentation`_.

   123 

   124 .. _`session documentation`: ../sessions/

   125 

   126 django.contrib.auth.middleware.AuthenticationMiddleware

   127 -------------------------------------------------------

   128 

   129 Adds the ``user`` attribute, representing the currently-logged-in user, to

   130 every incoming ``HttpRequest`` object. See `Authentication in Web requests`_.

   131 

   132 .. _Authentication in Web requests: ../authentication/#authentication-in-web-requests

   133 

   134 django.middleware.transaction.TransactionMiddleware

   135 ---------------------------------------------------

   136 

   137 Binds commit and rollback to the request/response phase. If a view function runs

   138 successfully, a commit is done. If it fails with an exception, a rollback is

   139 done.

   140 

   141 The order of this middleware in the stack is important: middleware modules

   142 running outside of it run with commit-on-save - the default Django behavior.

   143 Middleware modules running inside it (coming later in the stack) will be under

   144 the same transaction control as the view functions.

   145 

   146 See the `transaction management documentation`_.

   147 

   148 .. _`transaction management documentation`: ../transactions/

   149 

   150 Writing your own middleware

   151 ===========================

   152 

   153 Writing your own middleware is easy. Each middleware component is a single

   154 Python class that defines one or more of the following methods:

   155 

   156 process_request

   157 ---------------

   158 

   159 Interface: ``process_request(self, request)``

   160 

   161 ``request`` is an ``HttpRequest`` object. This method is called on each

   162 request, before Django decides which view to execute.

   163 

   164 ``process_request()`` should return either ``None`` or an ``HttpResponse``

   165 object. If it returns ``None``, Django will continue processing this request,

   166 executing any other middleware and, then, the appropriate view. If it returns

   167 an ``HttpResponse`` object, Django won't bother calling ANY other middleware or

   168 the appropriate view; it'll return that ``HttpResponse``.

   169 

   170 process_view

   171 ------------

   172 

   173 Interface: ``process_view(self, request, view_func, view_args, view_kwargs)``

   174 

   175 ``request`` is an ``HttpRequest`` object. ``view_func`` is the Python function

   176 that Django is about to use. (It's the actual function object, not the name of

   177 the function as a string.) ``view_args`` is a list of positional arguments that

   178 will be passed to the view, and ``view_kwargs`` is a dictionary of keyword

   179 arguments that will be passed to the view. Neither ``view_args`` nor

   180 ``view_kwargs`` include the first view argument (``request``).

   181 

   182 ``process_view()`` is called just before Django calls the view. It should

   183 return either ``None`` or an ``HttpResponse`` object. If it returns ``None``,

   184 Django will continue processing this request, executing any other

   185 ``process_view()`` middleware and, then, the appropriate view. If it returns an

   186 ``HttpResponse`` object, Django won't bother calling ANY other middleware or

   187 the appropriate view; it'll return that ``HttpResponse``.

   188 

   189 process_response

   190 ----------------

   191 

   192 Interface: ``process_response(self, request, response)``

   193 

   194 ``request`` is an ``HttpRequest`` object. ``response`` is the ``HttpResponse``

   195 object returned by a Django view.

   196 

   197 ``process_response()`` should return an ``HttpResponse`` object. It could alter

   198 the given ``response``, or it could create and return a brand-new

   199 ``HttpResponse``.

   200 

   201 process_exception

   202 -----------------

   203 

   204 Interface: ``process_exception(self, request, exception)``

   205 

   206 ``request`` is an ``HttpRequest`` object. ``exception`` is an ``Exception``

   207 object raised by the view function.

   208 

   209 Django calls ``process_exception()`` when a view raises an exception.

   210 ``process_exception()`` should return either ``None`` or an ``HttpResponse``

   211 object. If it returns an ``HttpResponse`` object, the response will be returned

   212 to the browser. Otherwise, default exception handling kicks in.

   213 

   214 Guidelines

   215 ----------

   216 

   217     * Middleware classes don't have to subclass anything.

   218 

   219     * The middleware class can live anywhere on your Python path. All Django

   220       cares about is that the ``MIDDLEWARE_CLASSES`` setting includes the path

   221       to it.

   222 

   223     * Feel free to look at Django's available middleware for examples. The

   224       core Django middleware classes are in ``django/middleware/`` in the

   225       Django distribution. The session middleware is in ``django/contrib/sessions``.

   226 

   227     * If you write a middleware component that you think would be useful to

   228       other people, contribute to the community! Let us know, and we'll

   229       consider adding it to Django.