Document middleware ordering requirements explicitly
Per the middleware usage guide, “The order in MIDDLEWARE_CLASSES
matters”, and one example is given (AuthenticationMiddleware
's need to run after SessionMiddleware
). But other than that, specific information on middleware ordering requirements is scant and scattered.
Some incomplete hints are found here and there:
- the default
MIDDLEWARE_CLASSES
order from startproject
may be taken to implicitly suggest that no known requirements are violated by that order (but doesn't inform as to valid deviations from that order)
- the above-mentioned example (
AuthenticationMiddleware
's need to run after SessionMiddleware
) is not mentioned in the middleware reference sections for these two middlewares, nor in the authentication and sessions documentation they link to.
- this StackOverflow question tries to plug this documentation hole (unauthoritatively), and that seems pretty welcome : ) (“Why this question doesn't have hundreds more stars and upvotes, I'll never know! Thanks!”)
Example cases in which this information is valuable:
- when resolving ordering dependencies for custom middleware: “My
FooMiddleware
needs to be after CsrfViewMiddleware
and before SessionMiddleware
; is it OK to swap the order of these two in the default startproject
middleware order to satisfy this, or must I redesign FooMiddleware
to eliminate one of those two requirements?
- when troubleshooting problems in production (as I am doing now): “Here
CsrfViewMiddleware
has been put first, unlike the default startproject
middleware order; might that be why we're seeing spurious CSRF failures in legitimate usage? Or can I eliminate that theory and better spend my time chasing another theory?”
Change History
(5)
Triage Stage: |
Unreviewed → Accepted
|
Type: |
Uncategorized → Cleanup/optimization
|
Has patch: |
set
|
Version: |
1.5 → master
|
Triage Stage: |
Accepted → Ready for checkin
|
Resolution: |
→ fixed
|
Status: |
new → closed
|
Pull request: https://github.com/django/django/pull/2702