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

Author: provinzkraut

docs/release-notes/changelog.rst

@@ -277,3 +277,12 @@
               id: ReadOnly[int]
 
         ``typing_extensions.ReadOnly`` should be used for python versions <3.13.
+
+
+    .. change:: Add ``should_bypass_for_scope`` to ``ASGIMiddleware`` to allow excluding middlewares dynamically
+        :type: feature
+        :pr: 4441
+
+        Add a new attribute :attr:`~litestar.middleware.ASGIMiddleware.should_bypass_for_scope`;
+        A callable which takes in a :class:`~litestar.types.Scope` and returns a boolean
+        to indicate whether to bypass the middleware for the current request.

litestar/middleware/base.py

@@ -226,6 +226,10 @@ async def handle(
         ``/user/{user_id:int}/``), NOT against the actual **request path** (e.g.,
         ``/user/1234/``). This is a critical distinction for dynamic routes.
 
+        If you need to exclude based on paths dynamically, use
+        :attr:`~litestar.middleware.ASGIMiddleware.should_bypass_for_scope`
+        instead, matching on ``scope["path"]``.
+
     **Example 1: Static path**
 
     Handler path::
@@ -250,19 +254,44 @@ async def handle(
         /user/5678/profile
         /user/9999/profile
 
-    To exclude this handler, the pattern must match the **handler**, not the actual
-    request path:
+    To exclude this handler, the pattern must match the **handler**, not the actual request path::
 
         exclude_path_pattern = "/user/{user_id:int}/profile"
         exclude_path_pattern = "/user/\{.+?\}/"
     """
     exclude_opt_key: str | None = None
+    """
+    Exclude this middleware for handlers with an opt-key of this name that is truthy
+    """
+    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:: 3.0
+    """
     constraints: MiddlewareConstraints | None = None
 
     def should_bypass_for_handler(self, handler: RouteHandlerType) -> bool:
         """Return ``True`` if this middleware should be bypassed for ``handler``, according
-        to ``scopes``, ``exclude_path_pattern`` or ``exclude_opt_key``, otherwise
-        ``False``.
+        to :attr:`~litestar.middleware.ASGIMiddleware.scopes`,
+        :attr:`~litestar.middleware.ASGIMiddleware.exclude_path_pattern` or
+        :attr:`~litestar.middleware.ASGIMiddleware.exclude_opt_key`, otherwise ``False``.
         """
         from litestar.handlers import ASGIRouteHandler, HTTPRouteHandler, WebsocketRouteHandler
 
@@ -286,8 +315,18 @@ def __call__(self, app: ASGIApp) -> ASGIApp:
         """Create the actual middleware callable"""
         handle = self.handle
 
-        async def middleware(scope: Scope, receive: Receive, send: Send) -> None:
-            await handle(scope=scope, receive=receive, send=send, next_app=app)
+        should_bypass_for_scope = self.should_bypass_for_scope
+        if should_bypass_for_scope is None:
+
+            async def middleware(scope: Scope, receive: Receive, send: Send) -> None:
+                await handle(scope=scope, receive=receive, send=send, next_app=app)
+        else:
+
+            async def middleware(scope: Scope, receive: Receive, send: Send) -> None:
+                if should_bypass_for_scope(scope):
+                    await app(scope, receive, send)
+                else:
+                    await handle(scope=scope, receive=receive, send=send, next_app=app)
 
         return middleware
 

tests/unit/test_middleware/test_base_middleware.py

@@ -345,6 +345,29 @@ def handler(bar: int) -> None:
         mock.assert_not_called()
 
 
+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):