| 1 |
|
| 2 |
Creating Middleware |
| 3 |
=================== |
| 4 |
|
| 5 |
As mentioned in :ref:`using middleware <using-middleware>`, a middleware in Litestar |
| 6 |
is **any callable** that takes a kwarg called ``app``, which is the next ASGI handler, i.e. an |
| 7 |
:class:`~litestar.types.ASGIApp`, and returns an ``ASGIApp``. |
| 8 |
|
| 9 |
The example previously given was using a factory function, i.e.: |
| 10 |
|
| 11 |
.. code-block:: python |
| 12 |
|
| 13 |
from litestar.types import ASGIApp, Scope, Receive, Send |
| 14 |
|
| 15 |
|
| 16 |
def middleware_factory(app: ASGIApp) -> ASGIApp: |
| 17 |
async def my_middleware(scope: Scope, receive: Receive, send: Send) -> None: |
| 18 |
# do something here |
| 19 |
... |
| 20 |
await app(scope, receive, send) |
| 21 |
|
| 22 |
return my_middleware |
| 23 |
|
| 24 |
|
| 25 |
Extending ``ASGIMiddleware`` |
| 26 |
---------------------------- |
| 27 |
|
| 28 |
While using functions is a perfectly viable approach, the recommended way to handle this |
| 29 |
is by using the :class:`~litestar.middleware.ASGIMiddleware` abstract base class, which |
| 30 |
also includes functionality to dynamically skip the middleware based on ASGI |
| 31 |
``scope["type"]``, handler ``opt`` keys or path patterns and a simple way to pass |
| 32 |
configuration to middlewares; It does not implement an ``__init__`` method, so |
| 33 |
subclasses are free to use it to customize the middleware's configuration. |
| 34 |
|
| 35 |
|
| 36 |
Modifying Requests and Responses |
| 37 |
++++++++++++++++++++++++++++++++ |
| 38 |
|
| 39 |
Middlewares can not only be used to execute *around* other ASGI callable, they can also |
| 40 |
intercept and modify both incoming and outgoing data in a request / response cycle by |
| 41 |
"wrapping" the respective ``receive`` and ``send`` ASGI callables. |
| 42 |
|
| 43 |
The following demonstrates how to add a request timing header with a timestamp to all |
| 44 |
outgoing responses: |
| 45 |
|
| 46 |
.. literalinclude:: /examples/middleware/request_timing.py |
| 47 |
:language: python |
| 48 |
|
| 49 |
|
| 50 |
|
| 51 |
Migrating from ``MiddlewareProtocol`` / ``AbstractMiddleware`` |
| 52 |
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| 53 |
|
| 54 |
:class:`~litestar.middleware.ASGIMiddleware` was introduced in Litestar 2.15. If you've |
| 55 |
been using ``MiddlewareProtocol`` / ``AbstractMiddleware`` to implement your middlewares |
| 56 |
before, there's a simple migration path to using ``ASGIMiddleware``. |
| 57 |
|
| 58 |
**From MiddlewareProtocol** |
| 59 |
|
| 60 |
.. tab-set:: |
| 61 |
|
| 62 |
.. tab-item:: MiddlewareProtocol |
| 63 |
|
| 64 |
.. literalinclude:: /examples/middleware/middleware_protocol_migration_old.py |
| 65 |
:language: python |
| 66 |
|
| 67 |
.. tab-item:: ASGIMiddleware |
| 68 |
|
| 69 |
.. literalinclude:: /examples/middleware/middleware_protocol_migration_new.py |
| 70 |
:language: python |
| 71 |
|
| 72 |
|
| 73 |
|
| 74 |
**From AbstractMiddleware** |
| 75 |
|
| 76 |
.. tab-set:: |
| 77 |
|
| 78 |
.. tab-item:: MiddlewareProtocol |
| 79 |
|
| 80 |
.. literalinclude:: /examples/middleware/abstract_middleware_migration_old.py |
| 81 |
:language: python |
| 82 |
|
| 83 |
.. tab-item:: ASGIMiddleware |
| 84 |
|
| 85 |
.. literalinclude:: /examples/middleware/abstract_middleware_migration_new.py |
| 86 |
:language: python |
| 87 |
|
| 88 |
|
| 89 |
|
| 90 |
|
| 91 |
|
| 92 |
|
| 93 |
Using MiddlewareProtocol |
| 94 |
------------------------ |
| 95 |
|
| 96 |
The :class:`~litestar.middleware.base.MiddlewareProtocol` class is a |
| 97 |
`PEP 544 Protocol <https://peps.python.org/pep-0544/>`_ that specifies the minimal implementation of a middleware as |
| 98 |
follows: |
| 99 |
|
| 100 |
.. code-block:: python |
| 101 |
|
| 102 |
from typing import Protocol, Any |
| 103 |
from litestar.types import ASGIApp, Scope, Receive, Send |
| 104 |
|
| 105 |
|
| 106 |
class MiddlewareProtocol(Protocol): |
| 107 |
def __init__(self, app: ASGIApp, **kwargs: Any) -> None: ... |
| 108 |
|
| 109 |
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: ... |
| 110 |
|
| 111 |
The ``__init__`` method receives and sets "app". *It's important to understand* that app is not an instance of Litestar in |
| 112 |
this case, but rather the next middleware in the stack, which is also an ASGI app. |
| 113 |
|
| 114 |
The ``__call__`` method makes this class into a ``callable``, i.e. once instantiated this class acts like a function, that |
| 115 |
has the signature of an ASGI app: The three parameters, ``scope, receive, send`` are specified |
| 116 |
by `the ASGI specification <https://asgi.readthedocs.io/en/latest/index.html>`_, and their values originate with the ASGI |
| 117 |
server (e.g. ``uvicorn``\ ) used to run Litestar. |
| 118 |
|
| 119 |
To use this protocol as a basis, simply subclass it - as you would any other class, and implement the two methods it |
| 120 |
specifies: |
| 121 |
|
| 122 |
.. code-block:: python |
| 123 |
|
| 124 |
import logging |
| 125 |
|
| 126 |
from litestar.types import ASGIApp, Receive, Scope, Send |
| 127 |
from litestar import Request |
| 128 |
from litestar.middleware.base import MiddlewareProtocol |
| 129 |
|
| 130 |
logger = logging.getLogger(__name__) |
| 131 |
|
| 132 |
|
| 133 |
class MyRequestLoggingMiddleware(MiddlewareProtocol): |
| 134 |
def __init__(self, app: ASGIApp) -> None: # can have other parameters as well |
| 135 |
self.app = app |
| 136 |
|
| 137 |
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: |
| 138 |
if scope["type"] == "http": |
| 139 |
request = Request(scope) |
| 140 |
logger.info("Got request: %s - %s", request.method, request.url) |
| 141 |
await self.app(scope, receive, send) |
| 142 |
|
| 143 |
.. important:: |
| 144 |
|
| 145 |
Although ``scope`` is used to create an instance of request by passing it to the |
| 146 |
:class:`~litestar.connection.Request` constructor, which makes it simpler to access because it does some parsing |
| 147 |
for you already, the actual source of truth remains ``scope`` - not the request. If you need to modify the data of |
| 148 |
the request you must modify the scope object, not any ephemeral request objects created as in the above. |
| 149 |
|
| 150 |
|
| 151 |
Responding using the MiddlewareProtocol |
| 152 |
+++++++++++++++++++++++++++++++++++++++ |
| 153 |
|
| 154 |
Once a middleware finishes doing whatever its doing, it should pass ``scope``, ``receive``, and ``send`` to an ASGI app |
| 155 |
and await it. This is what's happening in the above example with: ``await self.app(scope, receive, send)``. Let's |
| 156 |
explore another example - redirecting the request to a different url from a middleware: |
| 157 |
|
| 158 |
.. code-block:: python |
| 159 |
|
| 160 |
from litestar.types import ASGIApp, Receive, Scope, Send |
| 161 |
|
| 162 |
from litestar.response.redirect import ASGIRedirectResponse |
| 163 |
from litestar import Request |
| 164 |
from litestar.middleware.base import MiddlewareProtocol |
| 165 |
|
| 166 |
|
| 167 |
class RedirectMiddleware(MiddlewareProtocol): |
| 168 |
def __init__(self, app: ASGIApp) -> None: |
| 169 |
self.app = app |
| 170 |
|
| 171 |
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: |
| 172 |
if Request(scope).session is None: |
| 173 |
response = ASGIRedirectResponse(path="/login") |
| 174 |
await response(scope, receive, send) |
| 175 |
else: |
| 176 |
await self.app(scope, receive, send) |
| 177 |
|
| 178 |
As you can see in the above, given some condition (``request.session`` being ``None``) we create a |
| 179 |
:class:`~litestar.response.redirect.ASGIRedirectResponse` and then await it. Otherwise, we await ``self.app`` |
| 180 |
|
| 181 |
Modifying ASGI Requests and Responses using the MiddlewareProtocol |
| 182 |
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| 183 |
|
| 184 |
.. important:: |
| 185 |
|
| 186 |
If you'd like to modify a :class:`~litestar.response.Response` object after it was created for a route |
| 187 |
handler function but before the actual response message is transmitted, the correct place to do this is using the |
| 188 |
special life-cycle hook called :ref:`after_request <after_request>`. The instructions in this section are for how to |
| 189 |
modify the ASGI response message itself, which is a step further in the response process. |
| 190 |
|
| 191 |
Using the :class:`~litestar.middleware.base.MiddlewareProtocol` you can intercept and modifying both the |
| 192 |
incoming and outgoing data in a request / response cycle by "wrapping" that respective ``receive`` and ``send`` ASGI |
| 193 |
functions. |
| 194 |
|
| 195 |
To demonstrate this, let's say we want to append a header with a timestamp to all outgoing responses. We could achieve |
| 196 |
this by doing the following: |
| 197 |
|
| 198 |
.. code-block:: python |
| 199 |
|
| 200 |
import time |
| 201 |
|
| 202 |
from litestar.datastructures import MutableScopeHeaders |
| 203 |
from litestar.types import Message, Receive, Scope, Send |
| 204 |
from litestar.middleware.base import MiddlewareProtocol |
| 205 |
from litestar.types import ASGIApp |
| 206 |
|
| 207 |
|
| 208 |
class ProcessTimeHeader(MiddlewareProtocol): |
| 209 |
def __init__(self, app: ASGIApp) -> None: |
| 210 |
super().__init__(app) |
| 211 |
self.app = app |
| 212 |
|
| 213 |
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: |
| 214 |
if scope["type"] == "http": |
| 215 |
start_time = time.monotonic() |
| 216 |
|
| 217 |
async def send_wrapper(message: Message) -> None: |
| 218 |
if message["type"] == "http.response.start": |
| 219 |
process_time = time.monotonic() - start_time |
| 220 |
headers = MutableScopeHeaders.from_message(message=message) |
| 221 |
headers["X-Process-Time"] = str(process_time) |
| 222 |
await send(message) |
| 223 |
|
| 224 |
await self.app(scope, receive, send_wrapper) |
| 225 |
else: |
| 226 |
await self.app(scope, receive, send) |
| 227 |
|
| 228 |
Inheriting AbstractMiddleware |
| 229 |
----------------------------- |
| 230 |
|
| 231 |
Litestar offers an :class:`~litestar.middleware.base.AbstractMiddleware` class that can be extended to |
| 232 |
create middleware: |
| 233 |
|
| 234 |
.. code-block:: python |
| 235 |
|
| 236 |
import time |
| 237 |
|
| 238 |
from litestar.enums import ScopeType |
| 239 |
from litestar.middleware import AbstractMiddleware |
| 240 |
from litestar.datastructures import MutableScopeHeaders |
| 241 |
from litestar.types import Message, Receive, Scope, Send |
| 242 |
|
| 243 |
|
| 244 |
class MyMiddleware(AbstractMiddleware): |
| 245 |
scopes = {ScopeType.HTTP} |
| 246 |
exclude = ["first_path", "second_path"] |
| 247 |
exclude_opt_key = "exclude_from_middleware" |
| 248 |
|
| 249 |
async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: |
| 250 |
start_time = time.monotonic() |
| 251 |
|
| 252 |
async def send_wrapper(message: "Message") -> None: |
| 253 |
if message["type"] == "http.response.start": |
| 254 |
process_time = time.monotonic() - start_time |
| 255 |
headers = MutableScopeHeaders.from_message(message=message) |
| 256 |
headers["X-Process-Time"] = str(process_time) |
| 257 |
await send(message) |
| 258 |
|
| 259 |
await self.app(scope, receive, send_wrapper) |
| 260 |
|
| 261 |
The three class variables defined in the above example ``scopes``, ``exclude``, and ``exclude_opt_key`` can be used to |
| 262 |
fine-tune for which routes and request types the middleware is called: |
| 263 |
|
| 264 |
|
| 265 |
- The scopes variable is a set that can include either or both : ``ScopeType.HTTP`` and ``ScopeType.WEBSOCKET`` , with the default being both. |
| 266 |
- ``exclude`` accepts either a single string or list of strings that are compiled into a regex against which the request's ``path`` is checked. |
| 267 |
- ``exclude_opt_key`` is the key to use for in a route handler's :class:`Router.opt <litestar.router.Router>` dict for a boolean, whether to omit from the middleware. |
| 268 |
|
| 269 |
Thus, in the following example, the middleware will only run against the handler called ``not_excluded_handler`` for ``/greet`` route: |
| 270 |
|
| 271 |
.. literalinclude:: /examples/middleware/base.py |
| 272 |
:language: python |
| 273 |
|
| 274 |
.. danger:: |
| 275 |
|
| 276 |
Using ``/`` as an exclude pattern, will disable this middleware for all routes, |
| 277 |
since, as a regex, it matches *every* path |
| 278 |
|
| 279 |
|
| 280 |
Using DefineMiddleware to pass arguments |
| 281 |
---------------------------------------- |
| 282 |
|
| 283 |
Litestar offers a simple way to pass positional arguments (``*args``) and keyword arguments (``**kwargs``) to middleware |
| 284 |
using the :class:`~litestar.middleware.base.DefineMiddleware` class. Let's extend |
| 285 |
the factory function used in the examples above to take some args and kwargs and then use ``DefineMiddleware`` to pass |
| 286 |
these values to our middleware: |
| 287 |
|
| 288 |
.. code-block:: python |
| 289 |
|
| 290 |
from litestar.types import ASGIApp, Scope, Receive, Send |
| 291 |
from litestar import Litestar |
| 292 |
from litestar.middleware import DefineMiddleware |
| 293 |
|
| 294 |
|
| 295 |
def middleware_factory(my_arg: int, *, app: ASGIApp, my_kwarg: str) -> ASGIApp: |
| 296 |
async def my_middleware(scope: Scope, receive: Receive, send: Send) -> None: |
| 297 |
# here we can use my_arg and my_kwarg for some purpose |
| 298 |
... |
| 299 |
await app(scope, receive, send) |
| 300 |
|
| 301 |
return my_middleware |
| 302 |
|
| 303 |
|
| 304 |
app = Litestar( |
| 305 |
route_handlers=[...], |
| 306 |
middleware=[DefineMiddleware(middleware_factory, 1, my_kwarg="abc")], |
| 307 |
) |
| 308 |
|
| 309 |
The ``DefineMiddleware`` is a simple container - it takes a middleware callable as a first parameter, and then any |
| 310 |
positional arguments, followed by key word arguments. The middleware callable will be called with these values as well |
| 311 |
as the kwarg ``app`` as mentioned above. |