Document BaseHTTPMiddleware bugs (#1640)

* Document `BaseHTTPMiddleware` bugs * Apply suggestions from code review Co-authored-by: Adrian Garcia Badaracco <[email protected]> Co-authored-by: Adrian Garcia Badaracco <[email protected]>
encode · May 22, 2022 · 82e07b3 · 82e07b3
1 parent 2518588
commit 82e07b3
Showing 1 changed file with 7 additions and 1 deletion.
diff --git 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