Document `BaseHTTPMiddleware` bugs (#1640)

* Document `BaseHTTPMiddleware` bugs

* Apply suggestions from code review

Co-authored-by: Adrian Garcia Badaracco <1755071+adriangb@users.noreply.github.com>
Co-authored-by: Adrian Garcia Badaracco <1755071+adriangb@users.noreply.github.com>

diff --git a/docs/middleware.md b/docs/middleware.md
index b219142913353c335a3d4e55c143cea7014d28a4..817f63662be11b21e245d3ec1de0a4585647d155 100644 (file)
--- a/docs/middleware.md
+++ b/docs/middleware.md
@@ -215,7 +215,6 @@ class CustomHeaderMiddleware(BaseHTTPMiddleware):
         return response
 
 
-
 middleware = [
     Middleware(CustomHeaderMiddleware, header_value='Customized')
 ]
@@ -227,6 +226,13 @@ Middleware classes should not modify their state outside of the `__init__` metho
 Instead you should keep any state local to the `dispatch` method, or pass it
 around explicitly, rather than mutating the middleware instance.
 
+!!! bug
+    Currently, the `BaseHTTPMiddleware` has some known issues:
+
+    - It's not possible to use multiple `BaseHTTPMiddleware` based middlewares.
+    - It's not possible to use `BackgroundTasks` with `BaseHTTPMiddleware`.
+    - Using `BaseHTTPMiddleware` will prevent changes to `contextlib.ContextVar`s from propagating upwards. That is, if you set a value for a `ContextVar` in your endpoint and try to read it from a middleware you will find that the value is not the same value you set in your endpoint (see [this test](https://github.com/encode/starlette/blob/621abc747a6604825190b93467918a0ec6456a24/tests/middleware/test_base.py#L192-L223) for an example of this behavior).
+
 ## Using middleware in other frameworks
 
 To wrap ASGI middleware around other ASGI applications, you should use the