Debian Codegraph @

docs/usage/middleware/using-middleware.rst

raw
1 .. _using-middleware:
2
3 Using Middleware
4 ================
5
6 A middleware in Litestar is any callable that receives at least one kwarg called ``app`` and returns an
7 :class:`ASGIApp <litestar.types.ASGIApp>`. An ``ASGIApp`` is nothing but an async function that receives the ASGI
8 primitives ``scope`` , ``receive`` and ``send`` , and either calls the next ``ASGIApp`` or returns a response / handles
9 the websocket connection.
10
11 For example, the following function can be used as a middleware because it receives the ``app`` kwarg and returns
12 an ``ASGIApp``:
13
14 .. code-block:: python
15
16 from litestar.types import ASGIApp, Scope, Receive, Send
17
18
19 def middleware_factory(app: ASGIApp) -> ASGIApp:
20 async def my_middleware(scope: Scope, receive: Receive, send: Send) -> None:
21 # do something here
22 ...
23 await app(scope, receive, send)
24
25 return my_middleware
26
27 We can then pass this middleware to the :class:`Litestar <.app.Litestar>` instance, where it will be called on
28 every request:
29
30 .. code-block:: python
31
32 from litestar.types import ASGIApp, Scope, Receive, Send
33 from litestar import Litestar
34
35
36 def middleware_factory(app: ASGIApp) -> ASGIApp:
37 async def my_middleware(scope: Scope, receive: Receive, send: Send) -> None:
38 # do something here
39 ...
40 await app(scope, receive, send)
41
42 return my_middleware
43
44
45 app = Litestar(route_handlers=[...], middleware=[middleware_factory])
46
47 In the above example, Litestar will call the ``middleware_factory`` function and pass to it ``app``. It's important to
48 understand that this kwarg does not designate the Litestar application but rather the next ``ASGIApp`` in the stack. It
49 will then insert the returned ``my_middleware`` function into the stack of every route in the application -
50 because we declared it on the application level.
51
52 .. admonition:: Layered architecture
53 :class: seealso
54
55 Middlewares are part of Litestar's layered architecture* which means you can
56 set them on every layer of the application.
57
58 You can read more about this here: :ref:`usage/applications:layered architecture`
59
60
61 Middleware Call Order
62 ---------------------
63
64 Since it's also possible to define multiple middlewares on every layer, the call order for
65 middlewares will be **top to bottom** and **left to right**. This means for each layer, the
66 middlewares will be called in the order they have been passed, while the layers will be
67 traversed in the usual order:
68
69 .. mermaid::
70
71 flowchart LR
72 Application --> Router --> Controller --> Handler
73
74
75 .. literalinclude:: /examples/middleware/call_order.py
76 :language: python
77
78
79
80 Middlewares and Exceptions
81 --------------------------
82
83 When an exception is raised by a route handler or a :doc:`dependency </usage/dependency-injection>`
84 it will be transformed into a response by an :ref:`exception handler <usage/exceptions:exception handling>`.
85 This response will follow the normal "flow" of the application and therefore, middlewares are
86 still applied to it.
87
88 As with any good rule, there are exceptions to it. In this case they are two exceptions
89 raised by Litestar's ASGI router:
90
91
92 * :class:`NotFoundException <litestar.exceptions.http_exceptions.NotFoundException>`
93 * :class:`MethodNotAllowedException <litestar.exceptions.http_exceptions.MethodNotAllowedException>`
94
95 They are raised **before the middleware stack is called** and will only be handled by exception
96 handlers defined on the ``Litestar`` instance itself. If you wish to modify error responses generated
97 from these exception, you will have to use an application layer exception handler.