Initializer: __init__(self)

Use __init__() to perform systemwide setup for a given middleware class.

For performance reasons, each activated middleware class is instantiated only once per server process. This means that __init__() is called only once at server startup not for individual requests.

A common reason to implement an __init__() method is to check whether the middleware is indeed needed. If __init__() raises django.core.exceptions.MiddlewareNotUsed , then Django will remove the middleware from the middleware stack. You might use this feature to check for some piece of software that the middleware class requires, or check whether the server is running debug mode, or any other such environment situation.

If a middleware class defines an __init__() method, the method should take no arguments beyond the standard self .

Request Preprocessor: process_request(self, request)

This method gets called as soon as the request has been received before Django has parsed the URL to determine which view to run. It gets passed the HttpRequest object, which you may modify at will.

process_request() should return either None or an HttpResponse object.

• If it returns None , Django will continue processing this request, executing any other middleware and then the appropriate view.

• If it returns an HttpResponse object, Django wont bother calling any other middleware (of any type) or the appropriate view. Django will immediately return that HttpResponse .

View Preprocessor: process_view(self, request, view, args, kwargs)

This method gets called after the request preprocessor is called and Django has determined which view to execute, but before that view has actually been executed.

The arguments passed to this view are shown in Table 15-1.

Just like process_request() , process_view() should return either None or an HttpResponse object.

• If it returns None , Django will continue processing this request, executing any other middleware and then the appropriate view.

• If it returns an HttpResponse object, Django wont bother calling any other middleware (of any type) or the appropriate view. Django will immediately return that HttpResponse .

Response Postprocessor: process_response(self, request, response)

This method gets called after the view function is called and the response is generated. Here, the processor can modify the content of a response; one obvious use case is content compression, such as gzipping of the requests HTML.

The parameters should be pretty self-explanatory: request is the request object, and response is the response object returned from the view.

Unlike the request and view preprocessors, which may return None , process_response() must return an HttpResponse object. That response could be the original one passed into the function (possibly modified) or a brand-new one.

Exception Postprocessor: process_exception(self, request, exception)

This method gets called only if something goes wrong and a view raises an uncaught exception. You can use this hook to send error notifications, dump postmortem information to a log, or even try to recover from the error automatically.

The parameters to this function are the same request object weve been dealing with all along, and exception , which is the actual Exception object raised by the view function.

process_exception() should return a either None or an HttpResponse object.

• If it returns None , Django will continue processing this request with the frameworks built-in exception handling.

• If it returns an HttpResponse object, Django will use that response instead of the frameworks built-in exception handling.

Note

Django ships with a number of middleware classes (discussed in the following section) that make good examples. Reading the code for them should give you a good feel for the power of middleware.

You can also find a number of community-contributed examples on Djangos wiki: http://code.djangoproject.com/wiki/ContributedMiddleware

Authentication Support Middleware

Middleware class: django.contrib.auth.middleware.AuthenticationMiddleware .

This middleware enables authentication support. It adds the request.user attribute, representing the currently logged-in user, to every incoming HttpRequest object.

See Chapter 12 for complete details.

Common Middleware

Middleware class: django.middleware.common.CommonMiddleware .

This middleware adds a few conveniences for perfectionists:

Forbids access to user agents in the ``DISALLOWED_USER_AGENTS`` setting : If provided, this setting should be a list of compiled regular expression objects that are matched against the user-agent header for each incoming request. Heres an example snippet from a settings file:

import re

DISALLOWED_USER_AGENTS = (
    re.compile(r'^OmniExplorer_Bot'),
    re.compile(r'^Googlebot')
)

Note the import re , because DISALLOWED_USER_AGENTS requires its values to be compiled regexes (i.e., the output of re.compile() ). The settings file is regular python, so its perfectly OK to include Python import statements in it.

Performs URL rewriting based on the ``APPEND_SLASH`` and ``PREPEND_WWW`` settings : If APPEND_SLASH is True , URLs that lack a trailing slash will be redirected to the same URL with a trailing slash, unless the last component in the path contains a period. So foo.com/bar is redirected to foo.com/bar/ , but foo.com/bar/file.txt is passed through unchanged.

If PREPEND_WWW is True , URLs that lack a leading www. will be redirected to the same URL with a leading www..

Both of these options are meant to normalize URLs. The philosophy is that each URL should exist in one and only one place. Technically the URL example.com/bar is distinct from example.com/bar/ , which in turn is distinct from www.example.com/bar/ . A search-engine indexer would treat these as separate URLs, which is detrimental to your sites search-engine rankings, so its a best practice to normalize URLs.

Handles ETags based on the ``USE_ETAGS`` setting : ETags are an HTTP-level optimization for caching pages conditionally. If USE_ETAGS is set to True , Django will calculate an ETag for each request by MD5-hashing the page content, and it will take care of sending Not Modified responses, if appropriate.

Note there is also a conditional GET middleware, covered shortly, which handles ETags and does a bit more.

Compression Middleware

Middleware class: django.middleware.gzip.GZipMiddleware .

This middleware automatically compresses content for browsers that understand gzip compression (all modern browsers). This can greatly reduce the amount of bandwidth a Web server consumes. The tradeoff is that it takes a bit of processing time to compress pages.

We usually prefer speed over bandwidth, but if you prefer the reverse, just enable this middleware.

Conditional GET Middleware

Middleware class: django.middleware.http.ConditionalGetMiddleware .

This middleware provides support for conditional GET operations. If the response has an Last-Modified or ETag or header, and the request has If-None-Match or If-Modified-Since , the response is replaced by an 304 (Not modified) response. ETag support depends on on the USE_ETAGS setting and expects the ETag response header to already be set. As discussed above, the ETag header is set by the Common middleware.

It also removes the content from any response to a HEAD request and sets the Date and Content-Length response headers for all requests.

Reverse Proxy Support (X-Forwarded-For Middleware)

Middleware class: django.middleware.http.SetRemoteAddrFromForwardedFor .

This is the example we examined in the Whats Middleware? section earlier. It sets request.META['REMOTE_ADDR'] based on request.META['HTTP_X_FORWARDED_FOR'] , if the latter is set. This is useful if youre sitting behind a reverse proxy that causes each requests REMOTE_ADDR to be set to 127.0.0.1 .

Danger!

This middleware does not validate HTTP_X_FORWARDED_FOR .

If youre not behind a reverse proxy that sets HTTP_X_FORWARDED_FOR automatically, do not use this middleware. Anybody can spoof the value of HTTP_X_FORWARDED_FOR , and because this sets REMOTE_ADDR based on HTTP_X_FORWARDED_FOR , that means anybody can fake his IP address.

Only use this middleware when you can absolutely trust the value of HTTP_X_FORWARDED_FOR .

Session Support Middleware

Middleware class: django.contrib.sessions.middleware.SessionMiddleware .

This middleware enables session support. See Chapter 12 for details.

Sitewide Cache Middleware

Middleware class: django.middleware.cache.CacheMiddleware .

This middleware caches each Django-powered page. This was discussed in detail in Chapter 13.

Transaction Middleware

Middleware class: django.middleware.transaction.TransactionMiddleware .

This middleware binds a database COMMIT or ROLLBACK to the request/response phase. If a view function runs successfully, a COMMIT is issued. If the view raises an exception, a ROLLBACK is issued.

The order of this middleware in the stack is important. Middleware modules running outside of it run with commit-on-save the default Django behavior. Middleware modules running inside it (coming later in the stack) will be under the same transaction control as the view functions.

See Appendix C for more about information about database transactions.

X-View Middleware

Middleware class: django.middleware.doc.XViewMiddleware .

This middleware sends custom X-View HTTP headers to HEAD requests that come from IP addresses defined in the INTERNAL_IPS setting. This is used by Djangos automatic documentation system.