feat(middleware): Add should_bypass_for_scope to ASGIMiddleware to allow excluding middlewares dynamically (#4441)

(cherry picked from commit 94073d3)

Author: provinzkraut

litestar/middleware/base.py

@@ -217,6 +217,29 @@ async def handle(
     exclude_path_pattern: str | tuple[str, ...] | None = None
     exclude_opt_key: str | None = None
 
+    should_bypass_for_scope: Callable[[Scope], bool] | None = None
+    r"""
+    A callable that takes in the :class:`~litestar.types.Scope` of the current
+    connection and returns a boolean, indicating if the middleware should be skipped for
+    the current request.
+
+    This can for example be used to exclude a middleware based on a dynamic path::
+
+        should_bypass_for_scope = lambda scope: scope["path"].endswith(".jpg")
+
+    Applied to a route with a dynamic path like ``/static/{file_name:str}``, it would
+    be skipped *only* if ``file_name`` has a ``.jpg`` extension.
+
+    .. note::
+
+        If it is not required to dynamically match the path of a request,
+        :attr:`~litestar.middleware.ASGIMiddleware.exclude_path_pattern` should be
+        used instead. Since its exclusion is done statically at startup time, it has no
+        performance cost at runtime.
+
+    .. versionadded:: 2.19
+    """
+
     def __call__(self, app: ASGIApp) -> ASGIApp:
         """Create the actual middleware callable"""
         handle = self.handle

tests/unit/test_middleware/test_base_middleware.py

@@ -285,6 +285,29 @@ def third_handler() -> dict:
         assert "test" in response.headers
 
 
+def test_asgi_middleware_should_exclude_scope() -> None:
+    mock = MagicMock()
+
+    class SubclassMiddleware(ASGIMiddleware):
+        @staticmethod
+        def should_bypass_for_scope(scope: "Scope") -> bool:
+            return scope["path"].endswith(".jpg")
+
+        async def handle(self, scope: "Scope", receive: "Receive", send: "Send", next_app: "ASGIApp") -> None:
+            mock(scope["path"])
+            await next_app(scope, receive, send)
+
+    @get("/{file_name:str}")
+    def handler(file_name: str) -> str:
+        return file_name
+
+    with create_test_client([handler], middleware=[SubclassMiddleware()]) as client:
+        assert client.get("/test.txt").status_code == 200
+        assert client.get("/test.jpg").status_code == 200
+
+        mock.assert_called_once_with("/test.txt")
+
+
 @pytest.mark.parametrize("excludes", ["/", ("/", "/foo"), "/*", "/.*"])
 def test_asgi_middleware_exclude_by_pattern_warns_if_exclude_all(excludes: Union[str, Tuple[str, ...]]) -> None:
     class SubclassMiddleware(ASGIMiddleware):