Opened 2 years ago

Closed 16 months ago

Last modified 16 months ago

#20816 closed Cleanup/optimization (fixed)

Document middleware ordering requirements explicitly

Reported by: gthb Owned by: nobody
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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)

comment:1 Changed 2 years ago by timo

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted
  • Type changed from Uncategorized to Cleanup/optimization

comment:2 Changed 16 months ago by claudep

  • Has patch set
  • Version changed from 1.5 to master

comment:3 Changed 16 months ago by timo

  • Triage Stage changed from Accepted to Ready for checkin

comment:4 Changed 16 months ago by Claude Paroz <claude@…>

  • Resolution set to fixed
  • Status changed from new to closed

In 756c390fb5bce5157d2882526be0b99f45ce52c9:

Fixed #20816 -- Added hints about Django middleware ordering

Thanks gthb Trac user for the report, kolypto StackOverflow
user for the initial list and Tim Graham for the review.

comment:5 Changed 16 months ago by Claude Paroz <claude@…>

In 1f6b3cf145fc1057f478607c2c845e66efaaf546:

[1.7.x] Fixed #20816 -- Added hints about Django middleware ordering

Thanks gthb Trac user for the report, kolypto StackOverflow
user for the initial list and Tim Graham for the review.
Backport of 756c390fb5 from master.

Note: See TracTickets for help on using tickets.
Back to Top