Creating custom middleware in Django - Mechanics & Internals

Overview - Creating custom middleware

What is it?

Creating custom middleware in Django means writing your own code that runs during the processing of web requests and responses. Middleware acts like a middle step between the browser and your Django app, allowing you to modify requests before they reach your views or change responses before they go back to the browser. Custom middleware lets you add special behaviors like logging, security checks, or modifying headers. It is a way to customize how your app handles web traffic at a central place.

Why it matters

Without middleware, you would have to repeat the same code in many places to handle common tasks like authentication, logging, or error handling. Middleware solves this by letting you write that code once and have it run automatically for every request or response. This saves time, reduces mistakes, and keeps your app organized. Without middleware, your app would be harder to maintain and less secure.

Where it fits

Before learning custom middleware, you should understand Django views, request-response cycle, and basic Python functions. After mastering middleware, you can explore Django signals, advanced request handling, and performance optimization techniques.

Mental Model

Core Idea

Middleware is like a checkpoint that every web request and response passes through, where you can inspect or change them before they continue.

Think of it like...

Imagine a security checkpoint at an airport where every passenger and their luggage are checked before entering or leaving. Middleware acts like that checkpoint for web requests and responses, allowing you to add security, logging, or other checks.

┌───────────────┐
│   Browser     │
└──────┬────────┘
       │ Request
       ▼
┌───────────────┐
│  Middleware   │
│ (process req) │
└──────┬────────┘
       │ Modified Request
       ▼
┌───────────────┐
│    Django     │
│    Views      │
└──────┬────────┘
       │ Response
       ▼
┌───────────────┐
│  Middleware   │
│ (process res) │
└──────┬────────┘
       │ Modified Response
       ▼
┌───────────────┐
│   Browser     │
└───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Django Middleware Basics

Concept: Middleware is a Python class that can modify requests and responses globally in Django.

Django middleware is a class with special methods that run on every request and response. The two main methods are `__init__` (runs once when the server starts) and `__call__` (runs on each request/response). Middleware sits between the browser and your views, letting you add code that runs automatically.

Result

You know that middleware is a class that can change requests before views see them and responses before they go back to the browser.

Understanding middleware as a global filter helps you see how to add features once and have them apply everywhere.

2

Foundation

Middleware Lifecycle and Request Flow

Concept: Middleware processes requests before views and responses after views in a defined order.

When a request comes in, Django sends it through each middleware's request method in order. Then the view runs. After the view returns a response, Django sends the response back through each middleware's response method in reverse order. This means middleware can change both requests and responses.

Result

You understand the order in which middleware runs and how it can affect both incoming and outgoing data.

Knowing the flow order prevents confusion about when your middleware code runs and what it can change.

3

Intermediate

Writing a Simple Custom Middleware Class

🤔Before reading on: do you think middleware must inherit from a special base class or just be a plain Python class? Commit to your answer.

Concept: Custom middleware is a plain Python class with specific methods to handle requests and responses.

To create custom middleware, write a class with an `__init__` method that takes `get_response` and a `__call__` method that takes the request. Inside `__call__`, you can modify the request before passing it to `get_response` (which calls the view), then modify the response before returning it. Example: class SimpleMiddleware: def __init__(self, get_response): self.get_response = get_response def __call__(self, request): # Code before view print('Before view') response = self.get_response(request) # Code after view print('After view') return response

Result

You can write middleware that runs code before and after views for every request.

Knowing that middleware is just a callable class clarifies how it fits into Django's request handling.

4

Intermediate

Modifying Requests and Responses in Middleware

🤔Before reading on: do you think middleware can change the request object so views see different data? Commit to your answer.

Concept: Middleware can change the request before views and the response before sending back to the browser.

Inside the `__call__` method, you can add or change attributes on the request object. For example, adding a custom header or user info. Similarly, you can modify the response object, like adding headers or changing content. Example: request.custom_attr = 'hello' response['X-Custom-Header'] = 'value'

Result

You can customize what views receive and what browsers get back by changing request and response in middleware.

Understanding that request and response are mutable objects lets you add powerful features globally.

5

Intermediate

Registering Middleware in Django Settings

Concept: Middleware must be added to the Django settings to run automatically.

After writing your middleware class, you add its full Python path to the `MIDDLEWARE` list in `settings.py`. The order in this list matters because middleware runs in that sequence for requests and reverse for responses. Example: MIDDLEWARE = [ 'django.middleware.security.SecurityMiddleware', 'myapp.middleware.SimpleMiddleware', 'django.middleware.common.CommonMiddleware', ]

Result

Your custom middleware runs automatically on every request and response.

Knowing that middleware order affects behavior helps prevent bugs and unexpected results.

6

Advanced

Handling Exceptions and Short-Circuiting Responses

🤔Before reading on: can middleware stop a request from reaching the view by returning a response early? Commit to your answer.

Concept: Middleware can return a response directly to stop further processing or handle exceptions globally.

If middleware returns a response object instead of calling `get_response`, Django skips the view and later middleware. This lets you block requests or return errors early. Middleware can also catch exceptions from views to handle errors in one place. Example: if not request.user.is_authenticated: return HttpResponse('Unauthorized', status=401)

Result

Middleware can control access and handle errors before views run.

Knowing middleware can short-circuit requests enables building security and error handling layers efficiently.

7

Expert

Middleware Performance and Async Support

🤔Before reading on: do you think Django middleware can be asynchronous to improve performance? Commit to your answer.

Concept: Modern Django supports async middleware to handle asynchronous requests efficiently.

Starting with Django 3.1, middleware can be async by defining `async def __call__`. Async middleware can await async views and other async code, improving performance for IO-bound tasks. However, mixing sync and async middleware requires care. Example: class AsyncMiddleware: def __init__(self, get_response): self.get_response = get_response async def __call__(self, request): # async code before response = await self.get_response(request) # async code after return response

Result

You can write middleware that works well with async views and improves scalability.

Understanding async middleware unlocks modern Django's full potential for high-performance web apps.

Under the Hood

Django middleware works by wrapping the main request handler function with a chain of callable middleware classes. Each middleware receives the request, optionally modifies it, then calls the next middleware or view. After the view returns a response, the middleware chain processes the response in reverse order. This wrapping uses Python's callable objects and closures to create a layered pipeline.

Why designed this way?

Middleware was designed as a chain of callables to allow flexible, reusable processing steps without changing core Django code. This design lets developers add or remove features easily and keeps concerns separated. Alternatives like modifying views directly would cause duplication and tight coupling.

Request Flow:
Browser
  │
  ▼
Middleware 1 ──┐
Middleware 2 ──┼─▶ View
Middleware 3 ──┘

Response Flow:
View
  │
  ▼
Middleware 3
Middleware 2
Middleware 1
  │
  ▼
Browser

Myth Busters - 4 Common Misconceptions

Quick: Does middleware always run before views, or can it run after views too? Commit to your answer.

Common Belief: Middleware only runs before the view to modify requests.

Reality: Middleware runs both before the view (processing requests) and after the view (processing responses).

Why it matters: Thinking middleware only runs before views causes confusion about where to put response modifications or cleanup code.

Quick: Can middleware stop a request from reaching the view by returning a response early? Commit to your answer.

Common Belief: Middleware cannot stop the request; it must always call the view.

Reality: Middleware can return a response directly, preventing the view and later middleware from running.

Why it matters: Not knowing this limits middleware use cases like access control or maintenance mode pages.

Quick: Is middleware required to inherit from a special Django base class? Commit to your answer.

Common Belief: Middleware classes must inherit from a Django base middleware class.

Reality: Middleware is a plain Python class with a specific interface; no inheritance is required.

Why it matters: Believing inheritance is required can confuse beginners and complicate middleware design unnecessarily.

Quick: Does middleware always run synchronously? Commit to your answer.

Common Belief: Middleware is always synchronous and cannot handle async views.

Reality: Modern Django supports async middleware that can await async views and code.

Why it matters: Ignoring async middleware prevents leveraging Django's performance improvements for async web apps.

Expert Zone

1

Middleware order is critical: a middleware early in the list can affect all later middleware and views, so careful ordering avoids bugs.

2

Middleware should be lightweight and fast because it runs on every request; heavy processing here slows the whole app.

3

Async middleware must be compatible with sync middleware; mixing them incorrectly can cause subtle bugs or performance issues.

When NOT to use

Middleware is not suitable for per-view logic or complex business rules; use decorators or view mixins instead. For very high-performance needs, consider ASGI middleware or server-level middleware alternatives.

Production Patterns

In production, middleware is used for security headers, authentication checks, request logging, response compression, and error handling. Teams often write reusable middleware packages to share common features across projects.

Connections

HTTP Interceptors

Middleware in Django is similar to HTTP interceptors in frontend frameworks like Angular, both intercepting requests and responses.

Understanding middleware helps grasp how web apps globally handle requests and responses across different layers.

Operating System Network Stack

Middleware acts like a network firewall or proxy that inspects and modifies data packets before they reach the destination.

Seeing middleware as a network checkpoint clarifies its role in security and data transformation.

Assembly Line in Manufacturing

Middleware layers are like stations on an assembly line, each adding or checking something before the product moves on.

This connection shows how middleware enforces order and modularity in processing complex tasks.

Common Pitfalls

#1 Trying to modify the request after calling get_response.

Wrong approach:

def __call__(self, request):
response = self.get_response(request)
request.custom_attr = 'value'
return response

Correct approach:

def __call__(self, request):
request.custom_attr = 'value'
response = self.get_response(request)
return response

Root cause:

Misunderstanding that request modifications must happen before passing it to the view.

#2 Returning None instead of a response from middleware.

Wrong approach:

def __call__(self, request):
# forgot to return response
self.get_response(request)

Correct approach:

def __call__(self, request):
response = self.get_response(request)
return response

Root cause:

Forgetting that middleware must always return a response object.

#3 Adding middleware to settings but with wrong import path.

Wrong approach:

MIDDLEWARE = [
'myapp.middleware.NonExistentMiddleware',
]

Correct approach:

MIDDLEWARE = [
'myapp.middleware.SimpleMiddleware',
]

Root cause:

Typo or incorrect Python path causes Django to fail loading middleware.

Key Takeaways

Middleware is a powerful way to run code on every request and response in Django, acting as a global filter.

Custom middleware is a simple Python class that wraps the request-response cycle, letting you modify or block requests and responses.

Middleware order matters because requests flow through middleware in sequence and responses flow back in reverse.

Middleware can short-circuit requests by returning responses early, enabling features like access control and maintenance modes.

Modern Django supports async middleware, allowing better performance with asynchronous views and code.

Practice

1. What is the main purpose of custom middleware in Django?

easy

A. To run code before and after a view processes a request

B. To define database models

C. To create HTML templates

D. To handle user authentication only

Solution

1. Step 1: Understand middleware role

   Middleware runs code before and after views handle requests.

2. Step 2: Compare options

   Only To run code before and after a view processes a request describes middleware's purpose correctly; others describe unrelated tasks.

3. Final Answer:

   To run code before and after a view processes a request -> Option A

4. Quick Check:

   Middleware = pre/post view code [OK]

Hint: Middleware runs code around views, not models or templates [OK]

Common Mistakes:

• Confusing middleware with models or templates
• Thinking middleware only handles authentication
• Believing middleware runs only after views

2. Which method must a Django custom middleware class implement to process requests and responses?

easy

A. __call__

B. __init__

C. process_request

D. handle_request

Solution

1. Step 1: Recall middleware class structure

   Custom middleware uses __init__ for setup and __call__ to handle requests and responses.

2. Step 2: Identify correct method for processing

   __call__ is the method that processes requests and responses; others are incorrect or deprecated.

3. Final Answer:

   __call__ -> Option A

4. Quick Check:

   Middleware processing method = __call__ [OK]

Hint: Use __call__ to process requests in custom middleware [OK]

Common Mistakes:

• Using process_request which is old style
• Confusing __init__ with request processing
• Inventing non-existent methods like handle_request

3. Given this middleware code, what will be printed when a request is processed?

class SimpleMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response
        print('Middleware initialized')

    def __call__(self, request):
        print('Before view')
        response = self.get_response(request)
        print('After view')
        return response

medium

A. After view\nBefore view\nMiddleware initialized

B. Middleware initialized\nBefore view\nAfter view

C. Before view\nAfter view\nMiddleware initialized

D. Middleware initialized only

Solution

1. Step 1: Understand when __init__ runs

   __init__ runs once when middleware is created, printing 'Middleware initialized'.

2. Step 2: Trace __call__ execution order

   __call__ prints 'Before view', calls the view, then prints 'After view'.

3. Final Answer:

   Middleware initialized\nBefore view\nAfter view -> Option B

4. Quick Check:

   Init then before and after view prints [OK]

Hint: Init prints once; __call__ prints before and after view [OK]

Common Mistakes:

• Thinking __init__ runs on every request
• Mixing order of print statements
• Ignoring that __call__ wraps the view call

4. What is wrong with this custom middleware code?

class MyMiddleware:
    def __init__(self):
        pass

    def __call__(self, request):
        response = self.get_response(request)
        return response

medium

A. No error, code is correct

B. __call__ should not return a response

C. Missing get_response parameter in __init__

D. Middleware classes cannot have __call__ method

Solution

1. Step 1: Check __init__ signature

   Middleware __init__ must accept get_response parameter to store it for later use.

2. Step 2: Identify missing attribute

   get_response is used in __call__, but not saved in __init__, causing an error.

3. Final Answer:

   Missing get_response parameter in __init__ -> Option C

4. Quick Check:

   __init__ needs get_response [OK]

Hint: Always accept get_response in __init__ for middleware [OK]

Common Mistakes:

• Omitting get_response parameter
• Not storing get_response as instance variable
• Thinking __call__ cannot return response

5. You want to create a custom middleware that adds a header 'X-Hello: World' to every response. Which code snippet correctly implements this?

hard

A. class HelloMiddleware:
def __init__(self, get_response):
self.get_response = get_response
def process_response(self, request, response):
response['X-Hello'] = 'World'
return response

B. class HelloMiddleware:
def __init__(self):
pass
def __call__(self, request):
response = self.get_response(request)
response.headers.add('X-Hello', 'World')
return response

C. class HelloMiddleware:
def __call__(self, request):
response = self.get_response(request)
response['X-Hello'] = 'World'
return response

D. class HelloMiddleware:
def __init__(self, get_response):
self.get_response = get_response
def __call__(self, request):
response = self.get_response(request)
response['X-Hello'] = 'World'
return response

Solution

1. Step 1: Confirm __init__ accepts get_response

   class HelloMiddleware: def __init__(self, get_response): self.get_response = get_response def __call__(self, request): response = self.get_response(request) response['X-Hello'] = 'World' return response correctly accepts and stores get_response in __init__.

2. Step 2: Check __call__ modifies response

   class HelloMiddleware: def __init__(self, get_response): self.get_response = get_response def __call__(self, request): response = self.get_response(request) response['X-Hello'] = 'World' return response calls get_response, adds header, and returns response properly.

3. Step 3: Identify errors in other options

   class HelloMiddleware: def __init__(self): pass def __call__(self, request): response = self.get_response(request) response.headers.add('X-Hello', 'World') return response misses get_response in __init__; class HelloMiddleware: def __call__(self, request): response = self.get_response(request) response['X-Hello'] = 'World' return response misses __init__; class HelloMiddleware: def __init__(self, get_response): self.get_response = get_response def process_response(self, request, response): response['X-Hello'] = 'World' return response uses old process_response method not supported in new style middleware.

4. Final Answer:

   class HelloMiddleware: def __init__(self, get_response): self.get_response = get_response def __call__(self, request): response = self.get_response(request) response['X-Hello'] = 'World' return response -> Option D

5. Quick Check:

   New middleware = __init__ + __call__ + modify response [OK]

Hint: New middleware needs get_response in __init__ and modifies response in __call__ [OK]

Common Mistakes:

• Omitting get_response in __init__
• Using old process_response method
• Trying to add headers before calling get_response