Deprecating BaseHTTPMiddleware

Based on many previous discussions, I am proposing that we deprecate BaseHTTPMiddleware.

We’ll put a deprecation warning in the constructor. In this warning we will give:

• Some background on the issue
• A date at which we will remove BaseHTTPMiddleware
• Options for developers (basically help us fix it or migrate to ASGI middleware).

This will be a part of a multipronged approach consisting of:

• ~Better documentation. We’ve already documented the limitations and issues with BaseHTTPMiddleware both in our docs and tests. #1656 will give us better documentation on creating ASGI middleware.~ This is now done!
• ~I (and I think @Kludex as well) are prepared to personally contribute to downstream packages by porting their middlewares to pure ASGI middleware. We’ll probably just look for any packages with > X stars or something and make PRs.~ We’ve proposed (and merged some) upstream fixes into some of the most popular libraries using BaseHTTPMiddleware we could find on GitHub.
• Providing an alternative implementation. #1691 proposes an alternative safer implementation of a simple request/response middleware. I’m not sure this is necessary now that we have better ASGI middleware docs, but it’s an option.
• Deprecating and eventually removing BaseHTTPMiddleware

[florimondmanca]

This is a rather bold move to make given the usage of BaseHTTPMiddleware in the wild, so let’s pause and think it through. I’m sure there’s been discussion before (are there any links available?), but jotting down some thoughts and questions…

In general, what’s the migration path going to be like for users of BaseHTTPMiddleware? Should we start by exploring how FastAPI could do without? It’s still relying on @app.middleware extensively. If the hundreds of thousands (maybe?) of FastAPI users get this deprecation warning, what action should they take to keep their systems running? Certainly the action might be on some intermediate dependency maintenance team. Does this mean we should first help folks migrate, then deprecate?

What does addressing the two problems mentioned in the docs (context vars, background tasks) look like with pure ASGI middleware?

What do existing examples in the BaseHTTPMiddleware docs look like using pure ASGI middleware?

While I reckon the limitations of BaseHTTPMiddleware, and the fact that currently users expect certain things to work that don’t, I also fear « pure ASGI middleware all the things » might be really off putting a lot of folks who’d like to do very simple edits to requests or responses.

[florimondmanca]

Now, if we consider something like #1691, I think a migration path could be:

1. Issue a release with the new generator-based API, and perhaps (best if we want to be able to drop BaseHTTPMiddleware eventually?) a deprecation warning hinting users to switch to that or pure ASGI middleware. #1691 makes it so that the transformation from BaseHTTPMiddleware style to HTTPMiddleware style is fairly straightforward – basically (request, call_next) -> (conn) and response = await call_next(request) -> response = yield. If this falls on intermediate libraries, end-users can always -W ignore this particular deprecation for a while.
2. When Starlette 1.0 lands, drop BaseHTTPMiddleware. (I think this criteria is better than committing to a specific date, even in the form of “First minor bump of 2023”. If folks want to prepare, they can’t know what minor that’s going to be.)

?