Add deprecation warning to BaseHTTPMiddleware

setup.cfg

@@ -31,6 +31,7 @@ filterwarnings=
     ignore: run_until_first_complete is deprecated and will be removed in a future version.:DeprecationWarning
     ignore: starlette\.middleware\.wsgi is deprecated and will be removed in a future release\.*:DeprecationWarning
     ignore: Async generator 'starlette\.requests\.Request\.stream' was garbage collected before it had been exhausted.*:ResourceWarning
+    ignore: BaseHTTPMiddleware has multiple bugs.*:DeprecationWarning
 
 [coverage:run]
 source_pkgs = starlette, tests

starlette/middleware/base.py

@@ -1,4 +1,5 @@
 import typing
+import warnings
 
 import anyio
 
@@ -11,13 +12,26 @@
     [Request, RequestResponseEndpoint], typing.Awaitable[Response]
 ]
 
+_WARNING = """\
+BaseHTTPMiddleware has multiple bugs/technical limitations\
+ (please see https://www.starlette.io/middleware/#basehttpmiddleware for more details)\
+ that we believe cannot be fixed under the current API.
+Because of this, we are deprecating this functionality and will remove it in the first\
+ minor version release made after January 2023.
+If you would like this functionality to be preserved in Starlette _and_ are\
+ able to contribute fixes to these bugs/limitations please comment on\
+ https://github.com/encode/starlette/issues/1678 or open a pull request to fix\
+ these bugs.
+"""
+
 
 class BaseHTTPMiddleware:
     def __init__(
         self, app: ASGIApp, dispatch: typing.Optional[DispatchFunction] = None
     ) -> None:
         self.app = app
         self.dispatch_func = self.dispatch if dispatch is None else dispatch
+        warnings.warn(_WARNING, DeprecationWarning)
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
         if scope["type"] != "http":

tests/middleware/test_base.py

@@ -206,3 +206,14 @@ async def homepage(request):
     client = test_client_factory(app)
     response = client.get("/")
     assert response.status_code == 200, response.content
+
+
+def test_deprecation(test_client_factory):
+    async def app(scope, receive, send):
+        assert False  # pragma: no cover
+
+    async def dispatch(request, call_next):
+        assert False  # pragma: no cover
+
+    with pytest.warns(DeprecationWarning):
+        BaseHTTPMiddleware(app, dispatch=dispatch)