django/docs/topics/http/middleware.txt

==========
Middleware
==========

Middleware is a framework of hooks into Django's request/response processing.
It's a light, low-level "plugin" system for globally altering Django's input
or output.

Each middleware component is responsible for doing some specific function. For
example, Django includes a middleware component,
:class:`~django.contrib.auth.middleware.AuthenticationMiddleware`, that
associates users with requests using sessions.

This document explains how middleware works, how you activate middleware, and
how to write your own middleware. Django ships with some built-in middleware
you can use right out of the box. They're documented in the :doc:`built-in
middleware reference </ref/middleware>`.

.. versionchanged:: 1.10

    A new style of middleware was introduced for use with the new
    :setting:`MIDDLEWARE` setting. If you're using the old
    :setting:`MIDDLEWARE_CLASSES` setting, you'll need to :ref:`adapt old,
    custom middleware <upgrading-middleware>` before using the new setting.
    This document describes new-style middleware. Refer to this page in older
    versions of the documentation for a description of how old-style middleware
    works.

Writing your own middleware
===========================

A middleware factory is a callable that takes a ``get_response`` callable and
returns a middleware. A middleware is a callable that takes a request and
returns a response, just like a view.

A middleware can be written as a function that looks like this::

    def simple_middleware(get_response):
        # One-time configuration and initialization.

        def middleware(request):
            # Code to be executed for each request before
            # the view is called.

            try:
                response = get_response(request)
            except Exception as e:
                # Code to handle an exception that wasn't caught
                # further up the chain, if desired.
                ...

            # Code to be executed for each request/response after
            # the view is called.

            return response

        return middleware

Or it can be written as a class with a ``__call__()`` method, like this::

    class SimpleMiddleware(object):
        def __init__(self, get_response):
            self.get_response = get_response
            # One-time configuration and initialization.

        def __call__(self, request):
            # Code to be executed for each request before
            # the view is called.

            try:
                response = self.get_response(request)
            except Exception as e:
                # Code to handle an exception that wasn't caught
                # further up the chain, if desired.
                ...

            # Code to be executed for each request/response after
            # the view is called.

            return response

In both examples, the ``try``/``except`` isn't required if the middleware
doesn't need to handle any exceptions. If it is included, it should probably
catch something more specific than ``Exception``.

The ``get_response`` callable provided by Django might be the actual view (if
this is the last listed middleware) or it might be the next middleware in the
chain. The current middleware doesn't need to know or care what exactly it is,
just that it represents whatever comes next.

The above is a slight simplification -- the ``get_response`` callable for the
last middleware in the chain won't be the actual view but rather a wrapper
method from the handler which takes care of applying :ref:`view middleware
<view-middleware>`, calling the view with appropriate URL arguments, and
applying :ref:`template-response <template-response-middleware>` middleware.

Middleware can live anywhere on your Python path.

``__init__(get_response)``
--------------------------

Middleware classes must accept a ``get_response`` argument. You can also
initialize some global state for the middleware. Keep in mind a couple of
caveats:

* Django initializes your middleware with only the ``get_response`` argument,
  so you can't define ``__init__()`` as requiring any other arguments.

* Unlike the ``__call__()`` method which get called once per request,
  ``__init__()`` is called only *once*, when the Web server starts.

.. versionchanged:: 1.10

    In older versions, ``__init__`` was not called until the Web server
    responded to its first request.

    If you want to allow your middleware to be used in Django 1.9 and earlier,
    make ``get_response`` an optional argument (``get_response=None``).

Marking middleware as unused
----------------------------

It's sometimes useful to determine at startup time whether a piece of
middleware should be used. In these cases, your middleware's ``__init__()``
method may raise :exc:`~django.core.exceptions.MiddlewareNotUsed`. Django will
then remove that middleware from the middleware process and log a debug message
to the :ref:`django-request-logger` logger when :setting:`DEBUG` is ``True``.

Activating middleware
=====================

To activate a middleware component, add it to the :setting:`MIDDLEWARE` list in
your Django settings.

In :setting:`MIDDLEWARE`, each middleware component is represented by a string:
the full Python path to the middleware's class or function name. For example,
here's the default value created by :djadmin:`django-admin startproject
<startproject>`::

    MIDDLEWARE = [
        'django.middleware.security.SecurityMiddleware',
        'django.contrib.sessions.middleware.SessionMiddleware',
        'django.middleware.common.CommonMiddleware',
        'django.middleware.csrf.CsrfViewMiddleware',
        'django.contrib.auth.middleware.AuthenticationMiddleware',
        'django.contrib.messages.middleware.MessageMiddleware',
        'django.middleware.clickjacking.XFrameOptionsMiddleware',
    ]

A Django installation doesn't require any middleware — :setting:`MIDDLEWARE`
can be empty, if you'd like — but it's strongly suggested that you at least use
:class:`~django.middleware.common.CommonMiddleware`.

The order in :setting:`MIDDLEWARE` 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`. See
:ref:`middleware-ordering` for some common hints about ordering of Django
middleware classes.

Hooks and application order
===========================

During the request phase, before calling the view, Django applies middleware
in the order it's defined in :setting:`MIDDLEWARE`, top-down. You can think of
it like an onion: each middleware class is a "layer" that wraps the view.

Middleware see only the changes made by middleware that run before it. A
middleware (and the view) is skipped entirely if a preceding middleware
short-circuits by returning a response without ever calling ``get_response``.
That response will only pass through the middleware that have already run.

Similarly, a middleware that sees the request on the way in and doesn't return
a response is guaranteed that it will always see the response on the way back
out. If the middleware also wants to see any uncaught exception on the way out,
it can wrap its call to ``get_response()`` in a ``try``/``except``.

Besides the middleware pattern described earlier, you can add two other methods
to class-based middleware:

.. _view-middleware:

``process_view()``
------------------

.. method:: process_view(request, view_func, view_args, view_kwargs)

``request`` is an :class:`~django.http.HttpRequest` object. ``view_func`` is
the Python function that Django is about to use. (It's the actual function
object, not the name of the function as a string.) ``view_args`` is a list of
positional arguments that will be passed to the view, and ``view_kwargs`` is a
dictionary of keyword arguments that will be passed to the view. Neither
``view_args`` nor ``view_kwargs`` include the first view argument
(``request``).

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

It should return either ``None`` or an :class:`~django.http.HttpResponse`
object. If it returns ``None``, Django will continue processing this request,
executing any other ``process_view()`` middleware and, then, the appropriate
view. If it returns an :class:`~django.http.HttpResponse` object, Django won't
bother calling the appropriate view; it'll apply response middleware to that
:class:`~django.http.HttpResponse` and return the result.

.. note::

    Accessing :attr:`request.POST <django.http.HttpRequest.POST>` inside
    middleware before the view runs or in ``process_view()`` will prevent any
    view running after the middleware from being able to :ref:`modify the
    upload handlers for the request <modifying_upload_handlers_on_the_fly>`,
    and should normally be avoided.

    The :class:`~django.middleware.csrf.CsrfViewMiddleware` class can be
    considered an exception, as it provides the
    :func:`~django.views.decorators.csrf.csrf_exempt` and
    :func:`~django.views.decorators.csrf.csrf_protect` decorators which allow
    views to explicitly control at what point the CSRF validation should occur.

.. _template-response-middleware:

``process_template_response()``
-------------------------------

.. method:: process_template_response(request, response)

``request`` is an :class:`~django.http.HttpRequest` object. ``response`` is
the :class:`~django.template.response.TemplateResponse` object (or equivalent)
returned by a Django view or by a middleware.

``process_template_response()`` is called just after the view has finished
executing, if the response instance has a ``render()`` method, indicating that
it is a :class:`~django.template.response.TemplateResponse` or equivalent.

It must return a response object that implements a ``render`` method. It could
alter the given ``response`` by changing ``response.template_name`` and
``response.context_data``, or it could create and return a brand-new
:class:`~django.template.response.TemplateResponse` or equivalent.

You don't need to explicitly render responses -- responses will be
automatically rendered once all template response middleware has been
called.

Middleware are run in reverse order during the response phase, which
includes ``process_template_response()``.

Dealing with streaming responses
================================

Unlike :class:`~django.http.HttpResponse`,
:class:`~django.http.StreamingHttpResponse` does not have a ``content``
attribute. As a result, middleware can no longer assume that all responses
will have a ``content`` attribute. If they need access to the content, they
must test for streaming responses and adjust their behavior accordingly::

    if response.streaming:
        response.streaming_content = wrap_streaming_content(response.streaming_content)
    else:
        response.content = alter_content(response.content)

.. note::

    ``streaming_content`` should be assumed to be too large to hold in memory.
    Response middleware may wrap it in a new generator, but must not consume
    it. Wrapping is typically implemented as follows::

        def wrap_streaming_content(content):
            for chunk in content:
                yield alter_content(chunk)

.. _exception-middleware:

Exception middleware
====================

A middleware that does some custom exception handling might looks like this::

    class ExceptionMiddleware(object):
        def __init__(self, get_response):
            self.get_response = get_response

        def __call__(self, request):
            try:
                response = self.get_response(request)
            except Exception as e:
                # Do something with the exception and possibly reraise it
                # unless you wish to silence it.
                ...
            return response

Middleware that wants to do something for all exception responses, an HTTP 404
for example, need to both catch the appropriate exception (e.g. ``Http404``)
and look for regular responses with the status code of interest. You can
subclass  :class:`~django.middleware.exception.ExceptionMiddleware` if you want
to transform exceptions into the appropriate response.

.. _upgrading-middleware:

Upgrading pre-Django 1.10-style middleware
==========================================

.. class:: django.utils.deprecation.MiddlewareMixin
    :module:

Django provides ``django.utils.deprecation.MiddlewareMixin`` to ease providing
the existing built-in middleware in both new-style and old-style forms and to
ease similar conversions of third-party middleware.

In most cases, this mixin will be sufficient to convert a middleware with
sufficient backwards-compatibility; the new short-circuiting semantics will be
harmless or even beneficial to the existing middleware.

In a few cases, a middleware class may need more invasive changes to adjust to
the new semantics.

For example, in the current request-handling logic, the handler transforms any
exception that passes through all ``process_exception`` middleware uncaught
into a response with appropriate status code (e.g. 404, 403, 400, or 500), and
then passes that response through the full chain of ``process_response``
middleware.

In new-style middleware, a given middleware only gets one shot at a given
response or uncaught exception "on the way out," and will see either a returned
response or an uncaught exception, but not both.

This means that certain middleware which want to do something with all 404
responses (for example, the ``RedirectFallbackMiddleware`` and
``FlatpageFallbackMiddleware`` in ``django.contrib.redirects`` and
``django.contrib.flatpages``) now need to watch out for both a 404 response
and an uncaught ``Http404`` exception. They do this by subclassing
:class:`~django.middleware.exception.ExceptionMiddleware`.