View method middleware

In most circumstances, data in requests & responses is added, removed or updated in a piecemeal fashion in view methods. However, sometimes it's convenient to apply these changes on all requests and responses.

For example, if you want to access certain data on all view methods, it's easier to use a middleware class to make this data accessible across all requests. Just as if you want to enforce a security check on all responses, it's easier to do so globally with a middleware class.

Since middleware is a rather abstract concept, before I describe the structure of a Django middleware class, I'll walk you through the various built-in Django middleware classes so you can get a firmer understanding of where middleware is good design choice.

Built-in middleware classes

Django comes equipped with a series of middleware classes, some of which are enabled by default on all Django projects. If you open a Django project's settings.py file you'll notice the MIDDLEWARE variable whose default contents are shown in listing 2-29.

Listing 2-29 Default Django middleware classes in MIDDLEWARE

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',
]

As you can see in listing 2-29, Django projects in their out-of-the-box state come enabled with seven middleware classes, so all requests and responses are set to run through these seven classes. If you plan to leverage Django's main features, I advise you not to remove any of these default middleware classes. However, you can leave the MIDDLEWARE variable empty if you wish, just be aware doing so may break certain Django functionalities.

To give you a better understanding of what the Django middleware classes in listing 2-29 do and help you make a more informed decision to disable them or not, table 2-7 describes the functionality for each of these middleware classes.

Table 2-7 Django default middleware classes and functionality

Middleware class Functionality
django.middleware.security.SecurityMiddleware Provides security enhancements, such as:
  • SSL redirects based on the SECURE_SSL_REDIRECT and SECURE_SSL_HOST settings. Strict transport security through a variety of settings.
django.contrib.sessions.middleware.
SessionMiddleware
Enables session support.
django.middleware.common.CommonMiddleware Provides a common set of features, such as:
  • Forbidding access to user agents in the DISALLOWED_USER_AGENTS setting, which can be a list of compiled regular expression objects.
  • Performing url rewriting based on the APPEND_SLASH and PREPEND_WWW settings in order to normalize urls.
  • Setting the HTTP Content-Length header for non-streaming responses.
django.middleware.csrf.CsrfViewMiddleware Adds protection against Cross Site Request Forgeries by adding hidden form fields to POST forms and checking requests for the correct value.
django.contrib.auth.middleware.
AuthenticationMiddleware
Adds the user attribute, representing the currently-logged-in user, to every incoming HttpRequest object. NOTE: This middleware class depends on functionality from the middleware django.contrib.sessions.middleware.
SessionMiddleware
and must appear after it.
django.contrib.messages.middleware.
MessageMiddleware
Enables cookie-based and session-based message support. NOTE: This middleware class depends on functionality from the middleware django.contrib.sessions.middleware.SessionMiddleware and must appear after it.
django.middleware.clickjacking.
XFrameOptionsMiddleware
Provides clickjacking protection via the X-Frame-Options header. For more details on what is clickjacking see: http://en.wikipedia.org/wiki/Clickjacking.

As you can see in table 2-7, although the purpose of the various default middleware classes varies considerably, their functionality applies to features that need to be applied across all requests or responses in a project.

Another important factor of the middleware classes in table 2-7 is that some are dependent on others. For example, the AuthenticationMiddleware class is designed on the assumption it will have access to functionality provided by the SessionMiddleware class. Such dependencies are important because it makes the middleware class definition order relevant (i.e. certain middleware classes need to be defined before others in MIDDLEWARE) a topic I'll elaborate on more in the next section.

In addition to the default middleware classes presented in table 2-7, Django also offers other middleware classes. Table 2-7 illustrates the remaining set of Django middleware classes you can leverage in your projects, which can be helpful so you don't have to write middleware classes from scratch.

Table 2-8 Other Django middleware classes and functionality

Middleware class Functionality
django.middleware.cache.CacheMiddleware Basic caching middleware for simple sites.
django.middleware.cache.UpdateCacheMiddleware Response-phase cache middleware that updates the cache if the response is cacheable. NOTE:UpdateCacheMiddleware must be the first piece of middleware in MIDDLEWARE so that it'll get called last during the response phase.
django.middleware.cache.FetchFromCacheMiddleware Request-phase cache middleware that fetches a page from the cache. NOTE: FetchFromCacheMiddleware must be the last piece of middleware in MIDDLEWARE so that it'll get called last during the request phase.
django.middleware.common.BrokenLinkEmailsMiddleware Sends broken link notification emails to MANAGERS.
django.middleware.gzip.GZipMiddleware Compresses content for browsers that understand GZip compression. NOTE: GZipMiddleware should be placed before any other middleware that needs to read or write the response body so that compression happens afterward. Compression is only done by this middleware if the request party sends gzip on the HTTP Accept-Encoding header and if content is larger than 200 bytes and the response hasn't set the HTTP Content-Encoding header.
django.middleware.http.ConditionalGetMiddleware Handles conditional GET operations. If the response doesn't have an HTTP ETag header, one is added. If the response has an ETag or Last-Modified header, and the request has If-None-Match or If-Modified-Since, the response is replaced by an HttpNotModified.
django.middleware.locale.LocaleMiddleware Parses a request and decides what translation object to install in the current thread context. This allows pages to be dynamically translated to the language the user desires.. See the section User language preferences: HTTP headers and Django middleware for details on how this middleware works.
django.contrib.admindocs.middleware.XViewMiddleware Used by the Django admin docs application to add an X-View header to internal HEAD requests.
django.contrib.auth.middleware.PersistentRemoteUserMiddleware Adds REMOTE_USER -- available in request.META -- via an external source (e.g. web server) for the purpose of Django authentication.
django.contrib.auth.middleware.RemoteUserMiddleware Allows web-server provided authentication. If request.user is not authenticated, this middleware attempts to authenticate the username passed in the REMOTE_USER request header. If authentication is successful, the user is automatically logged in to persist the user in the session.
django.contrib.flatpages.middleware.FlatpageFallbackMiddleware Each time a Django application raises a 404 error, this middleware checks the flatpages database for the requested url as a last resort.
django.contrib.redirects.middleware.RedirectFallbackMiddleware Each time a Django application raises a 404 error, this middleware checks the redirects database for the requested url as a last resort.
django.contrib.sites.middleware.CurrentSiteMiddleware Adds the site attribute representing the current site to every incoming HttpRequest object.

Now that you know about Django's built-in middleware classes and what it's they're used for, lets take a look at the structure of middleware classes and their execution process.

Middleware structure & execution process

A Django middleware class has two required methods and three optional methods that execute at different points of the view request/response life-cycle. Listing 2-30 illustrates a sample middleware class with its various parts.

Listing 2-30. Django middleware class structure

class CoffeehouseMiddleware(object):

    def __init__(self, get_response):
        self.get_response = get_response
        # One-time configuration and initialization on start-up
	
    def __call__(self, request):
        # Logic executed on a request before the view (and other middleware) is called.
        # get_response call triggers next phase
        response = self.get_response(request)
        # Logic executed on response after the view is called.
        # Return response to finish middleware sequence
        return response
	
    def process_view(self, request, view_func, view_args, view_kwargs):
        # Logic executed before a call to view
        # Gives access to the view itself & arguments
	
    def process_exception(self,request, exception):
        # Logic executed if an exception/error occurs in the view
	
    def process_template_response(self,request, response):
        # Logic executed after the view is called, 
        # ONLY IF view response is TemplateResponse, see listing 2-24 

In order for view methods to execute the Django middleware class in listing 2-30, middleware classes must be added to the MIDDLEWARE variable in settings.py. So for example, if the CoffeehouseMiddleware class in listing 2-30 is stored in a file/module named middleware.py under the coffeehouse/utils/ project folders, you would add the coffeehouse.utils.middleware.CoffeeMiddleware statement to the list of MIDDLEWARE values in settings.py.

Next, I'll describe the two required methods in every Django middleware class shown In listing 2-30:

This is the core logic behind every Django middleware class performed by these two required methods. Now let's take a look at the three optional middleware class methods presented in listing 2-30:

Warning The process_template_response middleware method is only triggered if a view method returns a TemplateResponse. If a view method generates a response with render() the process_template_response is not triggered. See listing 2-24 for view method responses and additional details about using TemplateResponse or render().

In summary, the execution process for a single middleware class is the following:

  1. __init__ method triggered (On server start-up).
  2. __call__ method triggered (On every request).
  3. If declared, process_view() method triggered.
  4. View method starts with self.get_response(request) statement in __call__.
  5. If declared, process_exception() method triggered when exception occurs in view.
  6. View method finishes.
  7. If declared, process_template_response() triggered when view returns TemplateResponse.

Although it's important to understand the execution process of a single middleware class, a more important aspect is to understand the execution process of multiple middleware classes. As I mentioned at the outset of this section, Django projects are enabled with seven middleware classes shown in listing 2-29, so the execution of multiple middleware classes is more the norm rather than the exception.

Django middleware classes are executed back-to-back, but the view method represents an inflection point in their execution order. The execution order for the default middleware classes in listing 2-29, is the following:

Server start-up

__init__ on django.middleware.security.SecurityMiddleware called
__init__ on django.contrib.sessions.middleware.SessionMiddleware called
__init__ on django.middleware.common.CommonMiddleware called
__init__ on django.middleware.csrf.CsrfViewMiddleware called
__init__ on django.contrib.auth.middleware.AuthenticationMiddleware called
__init__ on django.contrib.messages.middleware.MessageMiddleware called 
__init__ on django.middleware.clickjacking.XframeOptionsMiddleware called

A request for index() view method

__call__ on django.middleware.security.SecurityMiddleware called
process_view on django.middleware.security.SecurityMiddleware called (if declared)
__call__ on django.contrib.sessions.middleware.SessionMiddleware called
process_view on django.contrib.sessions.middleware.SessionMiddleware called (if declared)
__call__ on django.middleware.common.CommonMiddleware called
process_view on django.middleware.common.CommonMiddleware called (if declared)
__call__ on django.middleware.csrf.CsrfViewMiddleware called
process_view on django.middleware.csrf.CsrfViewMiddleware called (if declared)
__call__ on django.contrib.auth.middleware.AuthenticationMiddleware called
process_view on django.contrib.auth.middleware.AuthenticationMiddleware called (if declared)
__call__ on django.contrib.messages.middleware.MessageMiddleware called
process_view on django.contrib.messages.middleware.MessageMiddleware called (if declared)
__call__ on django.middleware.clickjacking.XframeOptionsMiddleware called
process_view on django.middleware.clickjacking.XframeOptionsMiddleware called (if declared)

Start index() view method logic

If an exception occurs in index() view

process_exception on django.middleware.clickjacking.XframeOptionsMiddleware called (if declared)
process_exception on django.contrib.messages.middleware.MessageMiddleware called (if declared)
process_exception on django.contrib.auth.middleware.AuthenticationMiddleware called(if declared)
process_exception on django.middleware.csrf.CsrfViewMiddleware called (if declared)
process_exception on django.middleware.common.CommonMiddleware called (if declared)
process_exception on django.contrib.sessions.middleware.SessionMiddleware called (if declared)
process_exception on django.middleware.security.SecurityMiddleware called (if declared)

If index() view returns TemplateResponse

process_template_response on django.middleware.clickjacking.XframeOptionsMiddleware called (if declared)
process_template_response on django.contrib.messages.middleware.MessageMiddleware called (if declared)
process_template_response on django.contrib.auth.middleware.AuthenticationMiddleware called(if declared)
process_template_response on django.middleware.csrf.CsrfViewMiddleware called (if declared)
process_template_response on django.middleware.common.CommonMiddleware called (if declared)
process_template_response on django.contrib.sessions.middleware.SessionMiddleware called (if declared)
process_template_response on django.middleware.security.SecurityMiddleware called (if declared) 

Notice the execution order for middleware classes prior to entering the execution of the view method, follows the declared order (i.e. first declared runs first, last declared last). But once the view method is executed, the middleware execution order is inverted (i.e. last declared runs first, first declared last).

This behavior is similar to a corkscrew, where to get to the center (view method) you move in one direction (1 to 7) and to move out you go in the opposite direction (7 to 1). Therefore the middleware methods process_exception and process_template_response execute in the opposite order of __init__, __call__ and process_view.

Visually the execution process for the default Django middleware classes in listing 2-29 is illustrated in figure 2-4.

Figure 2-4. Django middleware execution process