| 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. |