Debian Codegraph @

docs/usage/middleware/creating-middleware.rst

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