feat(core)!: Add zero-cost middleware exclusion (#4372)

Author: provinzkraut

docs/release-notes/changelog.rst

@@ -198,3 +198,31 @@
         Use ``litestar[piccolo]`` extra installation target
         and ``litestar_piccolo`` plugin instead:
         https://github.com/litestar-org/litestar-piccolo
+
+    .. change:: Zero cost excluded middlewares
+        :type: feature
+        :breaking:
+
+        Middlewares inheriting from :class:`~litestar.middleware.base.ASGIMiddleware`
+        will now have zero runtime cost when they are excluded e.g. via the ``scope`` or
+        ``exclude_opt_key`` options.
+
+        Previously, the base middleware was always being invoked for every request,
+        evaluating the exclusion criteria, and then calling the user defined middleware
+        functions. If a middleware had defined ``scopes = (ScopeType.HTTP,)``, it would
+        still be called for *every* request, regardless of the scope type. Only for
+        requests with the type ``HTTP``, it would then call the user's function.
+
+        .. note::
+            This behaviour is still true for the legacy ``AbstractMiddleware``
+
+        With *zero cost exclusion*, the exclusion is being evaluated statically. At app
+        creation time, when route handlers are registered and their middleware stacks
+        are being built, a middleware that is to be excluded will simply not be included
+        in the stack.
+
+        .. note::
+            Even though this change is marked as breaking, no runtime behaviour
+            difference is expected. Some test cases may break though if they relied on
+            the fact that the middleware wrapper created by ``ASGIMiddleware`` was
+            always being called

litestar/_asgi/routing_trie/mapping.py

@@ -183,6 +183,7 @@ def build_route_middleware_stack(
         An ASGIApp that is composed of a "stack" of middlewares.
     """
     from litestar.middleware.allowed_hosts import AllowedHostsMiddleware
+    from litestar.middleware.base import ASGIMiddleware
     from litestar.middleware.compression import CompressionMiddleware
     from litestar.middleware.csrf import CSRFMiddleware
     from litestar.middleware.response_cache import ResponseCacheMiddleware
@@ -243,5 +244,7 @@ def build_route_middleware_stack(
         #       +--------------------+
         #                          --> response
         for middleware in reversed(handler_middleware):
+            if isinstance(middleware, ASGIMiddleware) and middleware.should_bypass_for_handler(route_handler):
+                continue
             asgi_handler = middleware(asgi_handler)
     return asgi_handler

litestar/middleware/_utils.py

@@ -48,6 +48,16 @@ def build_exclude_path_pattern(
         ) from e
 
 
+def match_exclude_path(exclude_path_pattern: Pattern, scope: Scope) -> bool:
+    return bool(
+        exclude_path_pattern.findall(
+            scope["raw_path"].decode()
+            if getattr(scope.get("route_handler", None), "is_mount", False)
+            else scope["path"]
+        )
+    )
+
+
 def should_bypass_middleware(
     *,
     exclude_http_methods: Sequence[Method] | None = None,
@@ -56,7 +66,7 @@ def should_bypass_middleware(
     scope: Scope,
     scopes: Scopes,
 ) -> bool:
-    """Determine weather a middleware should be bypassed.
+    """Determine whether a middleware should be bypassed.
 
     Args:
         exclude_http_methods: A sequence of http methods that do not require authentication.
@@ -77,9 +87,4 @@ def should_bypass_middleware(
     if exclude_http_methods and scope.get("method") in exclude_http_methods:
         return True
 
-    return bool(
-        exclude_path_pattern
-        and exclude_path_pattern.findall(
-            scope["raw_path"].decode() if getattr(scope.get("route_handler", {}), "is_mount", False) else scope["path"]
-        )
-    )
+    return exclude_path_pattern is not None and match_exclude_path(exclude_path_pattern, scope)

litestar/middleware/base.py

@@ -20,7 +20,7 @@
 
 if TYPE_CHECKING:
     from litestar.middleware.constraints import MiddlewareConstraints
-    from litestar.types import Scopes
+    from litestar.types import RouteHandlerType, Scopes
     from litestar.types.asgi_types import ASGIApp, Receive, Scope, Send
 
 
@@ -215,27 +215,79 @@ async def handle(
         ScopeType.WEBSOCKET,
         ScopeType.ASGI,
     )
+    """Scope types this middleware should be applied to"""
     exclude_path_pattern: str | tuple[str, ...] | None = None
+    r"""
+    A regex pattern (or tuple of patterns) to exclude this middleware from route
+    handlers whose path matches any of the provided patterns.
+
+    .. important::
+        Pattern matching is performed against the **handler's path** (e.g.,
+        ``/user/{user_id:int}/``), NOT against the actual **request path** (e.g.,
+        ``/user/1234/``). This is a critical distinction for dynamic routes.
+
+    **Example 1: Static path**
+
+    Handler path::
+
+        /api/health
+
+    To exclude this handler, use a pattern like::
+
+        exclude_path_pattern = r"^/api/health$"
+
+    **Example 2: Dynamic path (path parameters)**
+
+    Handler path::
+
+        /user/{user_id:int}/profile
+             └─────┬──────┘
+                   └─ This is what the pattern matches against
+
+    Actual request paths that match this handler::
+
+        /user/1234/profile
+        /user/5678/profile
+        /user/9999/profile
+
+    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
     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``.
+        """
+        from litestar.handlers import ASGIRouteHandler, HTTPRouteHandler, WebsocketRouteHandler
+
+        if isinstance(handler, HTTPRouteHandler) and ScopeType.HTTP not in self.scopes:
+            return True
+        if isinstance(handler, WebsocketRouteHandler) and ScopeType.WEBSOCKET not in self.scopes:
+            return True
+        if isinstance(handler, ASGIRouteHandler) and ScopeType.ASGI not in self.scopes:
+            return True
+
+        if self.exclude_opt_key and handler.opt.get(self.exclude_opt_key):
+            return True
+
+        pattern = build_exclude_path_pattern(exclude=self.exclude_path_pattern, middleware_cls=type(self))
+        if pattern and any(pattern.search(path) for path in handler.paths):
+            return True
+
+        return False
+
     def __call__(self, app: ASGIApp) -> ASGIApp:
         """Create the actual middleware callable"""
         handle = self.handle
-        exclude_pattern = build_exclude_path_pattern(exclude=self.exclude_path_pattern, middleware_cls=type(self))
-        scopes = set(self.scopes)
-        exclude_opt_key = self.exclude_opt_key
 
         async def middleware(scope: Scope, receive: Receive, send: Send) -> None:
-            if should_bypass_middleware(
-                scope=scope,
-                scopes=scopes,  # type: ignore[arg-type]
-                exclude_opt_key=exclude_opt_key,
-                exclude_path_pattern=exclude_pattern,
-            ):
-                await app(scope, receive, send)
-            else:
-                await handle(scope=scope, receive=receive, send=send, next_app=app)
+            await handle(scope=scope, receive=receive, send=send, next_app=app)
 
         return middleware
 

pyproject.toml

@@ -429,6 +429,7 @@ lint.ignore = [
   "A005",    # Module shadows a built-in Python standard library module
   "PLC0415", # `import` should be at the top-level of a file
   "PLW1641", # Object does not implement `__hash__` method
+  "SIM103",  # 'Return the condition directly': This is a bit overzealous
 ]
 lint.select = [
   "A",   # flake8-builtins

tests/unit/test_middleware/test_base_middleware.py

@@ -1,10 +1,12 @@
 from typing import TYPE_CHECKING, Union
+from unittest.mock import MagicMock, call
 from warnings import catch_warnings
 
 import pytest
 
-from litestar import MediaType, asgi, get
+from litestar import MediaType, WebSocket, asgi, get, websocket
 from litestar.datastructures.headers import MutableScopeHeaders
+from litestar.enums import ScopeType
 from litestar.exceptions import LitestarWarning, ValidationException
 from litestar.middleware import AbstractMiddleware, ASGIMiddleware, DefineMiddleware
 from litestar.response.base import ASGIResponse
@@ -211,19 +213,64 @@ def handler() -> dict:
         assert response.status_code == HTTP_400_BAD_REQUEST
 
 
+@pytest.mark.parametrize(
+    "allowed_scopes,expected_calls",
+    [
+        ((ScopeType.HTTP,), ["/http"]),
+        ((ScopeType.ASGI,), ["/asgi"]),
+        ((ScopeType.WEBSOCKET,), ["/ws"]),
+        ((ScopeType.HTTP, ScopeType.ASGI), ["/http", "/asgi"]),
+        ((ScopeType.HTTP, ScopeType.WEBSOCKET), ["/http", "/ws"]),
+        ((ScopeType.ASGI, ScopeType.WEBSOCKET), ["/asgi", "/ws"]),
+    ],
+)
+def test_asgi_middleware_exclude_by_scope_type(
+    allowed_scopes: tuple[ScopeType, ...], expected_calls: list[str]
+) -> None:
+    mock = MagicMock()
+
+    class SubclassMiddleware(ASGIMiddleware):
+        scopes = allowed_scopes
+
+        async def handle(self, scope: "Scope", receive: "Receive", send: "Send", next_app: "ASGIApp") -> None:
+            mock(scope["path"])
+            await next_app(scope, receive, send)
+
+    @get("/http")
+    def http_handler() -> None:
+        return None
+
+    @websocket("/ws")
+    async def websocket_handler(socket: WebSocket) -> None:
+        await socket.accept()
+        await socket.close()
+
+    @asgi("/asgi")
+    async def asgi_handler(scope: "Scope", receive: "Receive", send: "Send") -> None:
+        response = ASGIResponse(body=b"ok", media_type=MediaType.TEXT)
+        await response(scope, receive, send)
+
+    with create_test_client(
+        [http_handler, asgi_handler, websocket_handler], middleware=[SubclassMiddleware()]
+    ) as client:
+        assert client.get("/http").status_code == 200
+        assert client.get("/asgi").status_code == 200
+        with client.websocket_connect("/ws"):
+            pass
+
+        mock.assert_has_calls([call(path) for path in expected_calls])
+
+
 def test_asgi_middleware_exclude_by_pattern() -> None:
+    mock = MagicMock()
+
     class SubclassMiddleware(ASGIMiddleware):
         def __init__(self) -> None:
             self.exclude_path_pattern = r"^/123"
 
         async def handle(self, scope: "Scope", receive: "Receive", send: "Send", next_app: "ASGIApp") -> None:
-            async def _send(message: "Message") -> None:
-                if message["type"] == "http.response.start":
-                    headers = MutableScopeHeaders(message)
-                    headers.add("test", str(123))
-                await send(message)
-
-            await next_app(scope, receive, _send)
+            mock(scope["raw_path"].decode())
+            await next_app(scope, receive, send)
 
     @get("/123")
     def first_handler() -> dict:
@@ -239,28 +286,22 @@ async def handler(scope: "Scope", receive: "Receive", send: "Send") -> None:
         await response(scope, receive, send)
 
     with create_test_client([first_handler, second_handler, handler], middleware=[SubclassMiddleware()]) as client:
-        response = client.get("/123")
-        assert "test" not in response.headers
-
-        response = client.get("/456")
-        assert "test" in response.headers
+        assert client.get("/123").status_code == 200
+        assert client.get("/456").status_code == 200
+        assert client.get("/mount/123").status_code == 200
 
-        response = client.get("/mount/123")
-        assert "test" in response.headers
+        mock.assert_has_calls([call("/456"), call("/mount/123")])
 
 
 def test_asgi_middleware_exclude_by_pattern_tuple() -> None:
+    mock = MagicMock()
+
     class SubclassMiddleware(ASGIMiddleware):
         exclude_path_pattern = ("123", "456")
 
         async def handle(self, scope: "Scope", receive: "Receive", send: "Send", next_app: "ASGIApp") -> None:
-            async def _send(message: "Message") -> None:
-                if message["type"] == "http.response.start":
-                    headers = MutableScopeHeaders(message)
-                    headers.add("test", str(123))
-                await send(message)
-
-            await next_app(scope, receive, _send)
+            mock(scope["path"])
+            await next_app(scope, receive, send)
 
     @get("/123")
     def first_handler() -> dict:
@@ -277,12 +318,31 @@ def third_handler() -> dict:
     with create_test_client(
         [first_handler, second_handler, third_handler], middleware=[SubclassMiddleware()]
     ) as client:
-        response = client.get("/123")
-        assert "test" not in response.headers
-        response = client.get("/456")
-        assert "test" not in response.headers
-        response = client.get("/789")
-        assert "test" in response.headers
+        assert client.get("/123").status_code == 200
+        assert client.get("/456").status_code == 200
+        assert client.get("/789").status_code == 200
+
+        mock.assert_called_once_with("/789")
+
+
+def test_asgi_middleware_exclude_dynamic_handler_by_pattern() -> None:
+    mock = MagicMock()
+
+    class SubclassMiddleware(ASGIMiddleware):
+        def __init__(self) -> None:
+            self.exclude_path_pattern = r"^/foo/{bar"  # use a pattern that ensures we match the raw handler path
+
+        async def handle(self, scope: "Scope", receive: "Receive", send: "Send", next_app: "ASGIApp") -> None:
+            mock()
+            await next_app(scope, receive, send)
+
+    @get("/foo/{bar:int}")
+    def handler(bar: int) -> None:
+        return None
+
+    with create_test_client([handler], middleware=[SubclassMiddleware()]) as client:
+        assert client.get("/foo/1").status_code == 200
+        mock.assert_not_called()
 
 
 @pytest.mark.parametrize("excludes", ["/", ("/", "/foo"), "/*", "/.*"])
@@ -310,22 +370,19 @@ async def handle(self, scope: "Scope", receive: "Receive", send: "Send", next_ap
 
 
 def test_asgi_middleware_exclude_by_opt_key() -> None:
+    mock = MagicMock()
+
     class SubclassMiddleware(ASGIMiddleware):
         exclude_opt_key = "exclude_route"
 
         async def handle(self, scope: "Scope", receive: "Receive", send: "Send", next_app: "ASGIApp") -> None:
-            async def _send(message: "Message") -> None:
-                if message["type"] == "http.response.start":
-                    headers = MutableScopeHeaders(message)
-                    headers.add("test", str(123))
-                await send(message)
-
-                await next_app(scope, receive, send)
+            mock()
+            await next_app(scope, receive, send)
 
     @get("/", exclude_route=True)
     def handler() -> dict:
         return {"hello": "world"}
 
     with create_test_client(handler, middleware=[SubclassMiddleware()]) as client:
-        response = client.get("/")
-        assert "test" not in response.headers
+        assert client.get("/").status_code == 200
+        mock.assert_not_called()