feat: Middleware constraints (#4167)

Author: provinzkraut

docs/examples/middleware/constraints.py

@@ -0,0 +1,7 @@
+from litestar.middleware.authentication import AbstractAuthenticationMiddleware
+from litestar.middleware.base import ASGIMiddleware
+from litestar.middleware.constraints import MiddlewareConstraints
+
+
+class CachingMiddleware(ASGIMiddleware):
+    constraints = MiddlewareConstraints(after=(AbstractAuthenticationMiddleware,))

docs/examples/middleware/constraints_string_ref.py

@@ -0,0 +1,9 @@
+from litestar.middleware.base import ASGIMiddleware
+from litestar.middleware.constraints import MiddlewareConstraints
+
+
+class SomeMiddleware(ASGIMiddleware):
+    constraints = MiddlewareConstraints().apply_after(
+        "some_package.some_module.SomeMiddleware",
+        ignore_import_error=True,
+    )

docs/reference/middleware/constraints.rst

@@ -0,0 +1,5 @@
+constraints
+===========
+
+.. automodule:: litestar.middleware.constraints
+    :members:

docs/reference/middleware/index.rst

@@ -15,3 +15,4 @@ middleware
     logging
     rate_limit
     session/index
+    constraints

docs/release-notes/whats-new-3.rst

@@ -332,3 +332,15 @@ parameter.
 .. attention::
     This has been intentionally made a breaking change because the new parameter has
     slightly different behaviour and defaults to ``False`` instead of ``True``.
+
+
+Middleware configuration constraints
+-------------------------------------
+
+:class:`~litestar.middleware.ASGIMiddleware`\ s can now express constraints for how
+they are applied in the middleware stack, which are then validated on application
+startup.
+
+.. seealso::
+
+    :ref:`usage/middleware/creating-middleware:configuration-constraints

docs/usage/middleware/creating-middleware.rst

@@ -1,4 +1,3 @@
-
 Creating Middleware
 ===================
 
@@ -47,6 +46,91 @@ outgoing responses:
     :language: python
 
 
+Configuration constraints
+++++++++++++++++++++++++++
+
+While it's good practice to keep middlewares decoupled from another, there are times
+where implicit coupling is unavoidable due to the nature of the functionality provided
+by the middlewares.
+
+For example a caching middleware and an authentication middleware
+can produce very different results depending on the order they are applied in; Assuming
+a naive caching middleware that does not take authentication state into account, if it's
+applied *before* the authentication middleware, it might cache an authenticated response
+and serve it to the next, unauthenticated request.
+
+Especially when applications grow larger and more complex, it can become difficult to
+keep track of all these implicit couplings and dependencies, or downright impossible if
+the middleware is implemented in a separate package and has no knowledge about how it is
+being applied.
+
+To help with this, :class:`~litestar.middleware.ASGIMiddleware` allows to specify a set
+of :class:`~litestar.middleware.constraints.MiddlewareConstraints` - Once configured,
+these will be validated on application startup.
+
+Using constraints, the example given above might be solved like this:
+
+.. literalinclude:: /examples/middleware/constraints.py
+    :language: python
+
+Here, we specify that every instance of ``CachingMiddleware`` must come after any
+instance of
+:class:`~litestar.middleware.authentication.AbstractAuthenticationMiddleware`.
+
+
+.. tip::
+
+    When referencing classes, the constraints always apply to all instances and
+    subclasses of the type
+
+
+Forward references
+~~~~~~~~~~~~~~~~~~
+
+Constraints that reference other middleware can use strings as forward references, to
+handle situations like circular imports or middlewares from packages that may not be
+available:
+
+.. literalinclude:: /examples/middleware/constraints_string_ref.py
+    :language: python
+
+This forward reference will try to import ``SomeMiddleware`` from
+``some_package.some_module``. With ``ignore_import_error=True``, if the import is not
+successful, the constraint will be ignored.
+
+
+Middleware order
+~~~~~~~~~~~~~~~~
+
+For order constraints (``before``, ``after``, ``first``, ``last``), it is important to
+note that the order is defined in terms of proximity to the location. In practice, this
+means that a middleware that has set ``first=True`` must be the *first* middleware on
+the *first* layer (i.e. the application), and a middleware setting ``last=True`` must
+be the *last* middleware on the *last* layer (i.e. the route handler).
+
+.. code-block:: python
+
+    @get("/", middleware=[FifthMiddleware, SixthMiddleware])
+    async def handler() -> None:
+        pass
+
+    router = Router(
+        "/",
+        [handler],
+        middleware=[
+            ThirdMiddleware(),
+            FourthMiddleware()
+        ]
+    )
+
+    app = Litestar(
+        middleware=[
+            FirstMiddleware(),
+            SecondMiddleware()
+        ]
+    )
+
+
 
 Migrating from ``MiddlewareProtocol`` / ``AbstractMiddleware``
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

docs/usage/middleware/using-middleware.rst

@@ -61,15 +61,39 @@ because we declared it on the application level.
 Middleware Call Order
 ---------------------
 
-Since it's also possible to define multiple middlewares on every layer, the call order for
-middlewares will be **top to bottom** and **left to right**. This means for each layer, the
-middlewares will be called in the order they have been passed, while the layers will be
-traversed in the usual order:
+due to the way we're traversing over the app layers, the middleware stack is
+constructed in 'application > handler' order, which is the order we want the
+middleware to be called in.
+
+using this order however, since each middleware wraps the next callable, the
+*first* middleware in the stack would up being the *innermost* wrapper, i.e.
+the last one to receive the request and the first one to see the response.
+
+to achieve the intended call order, we perform the wrapping in reverse
+('handler -> application').
+
 
 .. mermaid::
 
-   flowchart LR
-       Application --> Router --> Controller --> Handler
+    graph TD
+        request --> M1
+        M1 --> M2
+        M2 --> H
+        H --> M2R
+        M2R --> M1R
+        M1R --> response
+
+        subgraph M1 [middleware_1]
+            M2
+            subgraph M2 [middleware_2]
+                H[handler]
+            end
+        end
+
+        style M1 stroke:#333,stroke-width:2px
+        style M2 stroke:#555,stroke-width:1.5px
+        style H stroke:#777,stroke-width:1px
+
 
 
 .. literalinclude:: /examples/middleware/call_order.py

litestar/_asgi/routing_trie/mapping.py

@@ -214,6 +214,34 @@ def build_route_middleware_stack(
         if app.allowed_hosts:
             asgi_handler = AllowedHostsMiddleware(app=asgi_handler, config=app.allowed_hosts)
 
-        for middleware in handler_middleware:
+        # due to the way we're traversing over the app layers, the middleware stack is
+        # constructed in 'application > handler' order, which is the order we want the
+        # middleware to be called in.
+        #
+        # using this order however, since each middleware wraps the next callable, the
+        # *first* middleware in the stack would up being the *innermost* wrapper, i.e.
+        # the last one to receive the request and the first one to see the response.
+        #
+        # to achieve the intended call order, we perform the wrapping in reverse
+        # ('handler -> application').
+        #
+        # example:
+        #   given: an 'application' with 'middleware_1', a 'handler' with 'middleware_2'
+        #   resolved stack: [middleware_1, middleware_2]
+        #   desired call chain: middleware_1 -> middleware_2 -> handler
+        #   wrapping structure:
+        #
+        #     request -->
+        #       +--------------------+
+        #       | middleware_1       |  <-- outermost
+        #       |   +--------------+ |
+        #       |   | middleware_2 | |
+        #       |   |   +--------+ | |
+        #       |   |   | handler| | |
+        #       |   |   +--------+ | |
+        #       |   +--------------+ |
+        #       +--------------------+
+        #                          --> response
+        for middleware in reversed(handler_middleware):
             asgi_handler = middleware(asgi_handler)
     return asgi_handler

litestar/handlers/base.py

@@ -8,6 +8,7 @@
 from litestar.di import Provide
 from litestar.dto import DTOData
 from litestar.exceptions import ImproperlyConfiguredException, LitestarException
+from litestar.middleware.constraints import check_middleware_constraints
 from litestar.serialization import default_deserializer, default_serializer
 from litestar.types import (
     Dependencies,
@@ -214,15 +215,6 @@ def _get_merge_opts(self, others: tuple[Router, ...]) -> dict[str, Any]:
         merge_opts["dto"] = value_or_default(self._dto, merge_opts.get("dto", Empty))
         merge_opts["return_dto"] = value_or_default(self._return_dto, merge_opts.get("return_dto", Empty))
 
-        # due to the way we're traversing over the app layers, the middleware stack is
-        # constructed in the wrong order (handler > application). reversing the order
-        # here is easier than handling it correctly at every intermediary step.
-        #
-        # we only call this if 'others' is non-empty, to ensure we don't change anything
-        # if no layers have been merged (happens in '._with_changes' for example)
-        if others:
-            merge_opts["middleware"] = tuple(reversed(merge_opts["middleware"]))
-
         return merge_opts
 
     def _with_changes(self, **kwargs: Any) -> Self:
@@ -520,6 +512,8 @@ def on_registration(self, route: BaseRoute, app: Litestar) -> None:
         self._validate_handler_function()
         self._finalize_dependencies(app=app)
 
+        check_middleware_constraints(self.middleware)
+
     def _validate_handler_function(self) -> None:
         """Validate the route handler function once set by inspecting its return annotations."""
         if self.parsed_data_field is not None and self.parsed_data_field.is_subclass_of(DTOData) and not self.data_dto:

litestar/middleware/base.py

@@ -18,8 +18,8 @@
     "MiddlewareProtocol",
 )
 
-
 if TYPE_CHECKING:
+    from litestar.middleware.constraints import MiddlewareConstraints
     from litestar.types import Scopes
     from litestar.types.asgi_types import ASGIApp, Receive, Scope, Send
 
@@ -170,9 +170,10 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
 
 
 class ASGIMiddleware(abc.ABC):
-    """An abstract base class to easily construct ASGI middlewares, providing functionality
-    to dynamically skip the middleware based on ASGI ``scope["type"]``, handler ``opt``
-    keys or path patterns and a simple way to pass configuration to middlewares.
+    """An abstract base class to easily construct ASGI middlewares, providing
+    functionality to dynamically skip the middleware based on ASGI ``scope["type"]``,
+    handler ``opt`` keys or path patterns and a simple way to pass configuration to
+    middlewares.
 
     This base class does not implement an ``__init__`` method, so subclasses are free
     to use it to customize the middleware's configuration.
@@ -216,6 +217,7 @@ async def handle(
     )
     exclude_path_pattern: str | tuple[str, ...] | None = None
     exclude_opt_key: str | None = None
+    constraints: MiddlewareConstraints | None = None
 
     def __call__(self, app: ASGIApp) -> ASGIApp:
         """Create the actual middleware callable"""