docs: clarify BaseHTTPMiddleware impact on contextvars for subsequent middleware

[yakimka]

This PR updates the documentation for BaseHTTPMiddleware to clarify an important limitation regarding contextvars propagation.

The "Limitations" section previously noted that BaseHTTPMiddleware prevents contextvars changes from propagating upwards. This change adds a crucial detail: if a BaseHTTPMiddleware is positioned earlier in the middleware stack, it will also disrupt contextvars propagation for any subsequent Pure ASGI Middleware that relies on them.

This clarification helps users understand a potential pitfall when mixing BaseHTTPMiddleware and Pure ASGI Middleware, ensuring they design their middleware stack appropriately for contextvars to function as expected.

Example

from __future__ import annotations

import contextvars
import random
from typing import TYPE_CHECKING

import uvicorn
from fastapi import Request, Response
from starlette.applications import Starlette
from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
from starlette.responses import JSONResponse
from starlette.routing import Route

if TYPE_CHECKING:
    from starlette.types import ASGIApp, Receive, Scope, Send


context = contextvars.ContextVar("context", default=None)


class BadMiddleware(BaseHTTPMiddleware):
    async def dispatch(
        self, request: Request, call_next: RequestResponseEndpoint
    ) -> Response:
        print("BadMiddleware called")
        response = await call_next(request)
        print("BadMiddleware context:", context.get())
        print("BadMiddleware finished")
        return response


class ShinyMiddleware:
    def __init__(self, app: ASGIApp) -> None:
        self.app = app

    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
        if scope["type"] != "http":
            await self.app(scope, receive, send)
            return

        print("ShinyMiddleware called")
        await self.app(scope, receive, send)
        print("ShinyMiddleware context:", context.get())
        print("ShinyMiddleware finished")


async def homepage(request):
    random_int = random.randint(1, 100)
    context.set({"random_int": random_int})
    return JSONResponse({"random_int": random_int})


app = Starlette(debug=True, routes=[
    Route("/", homepage),
])


app.add_middleware(ShinyMiddleware)
app.add_middleware(BadMiddleware)


if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

If you run this app and curl localhost:8000, you can see that everything happens as described in the documentation:

BadMiddleware called
ShinyMiddleware called
BadMiddleware context: None
BadMiddleware finished
INFO:     127.0.0.1:55240 - "GET / HTTP/1.1" 200 OK
ShinyMiddleware context: {'random_int': 97}
ShinyMiddleware finished

But if you swap BadMiddleware and ShinyMiddleware, you will get unexpected (?) behavior:

ShinyMiddleware called
BadMiddleware called
BadMiddleware context: None
BadMiddleware finished
INFO:     127.0.0.1:55332 - "GET / HTTP/1.1" 200 OK
ShinyMiddleware context: None
ShinyMiddleware finished

Checklist

• [x] I understand that this PR may be closed in case there was no previous discussion. (This doesn't apply to typos!)
• [x] I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• [x] I've updated the documentation accordingly.