Debian Codegraph @

docs/usage/websockets.rst

raw
1 WebSockets
2 ==========
3
4 There are three ways to handle WebSockets in Litestar:
5
6 1. The low-level :class:`~litestar.handlers.websocket` route handler, providing basic
7 abstractions over the ASGI WebSocket interface
8 2. :class:`~litestar.handlers.websocket_listener` and :class:`~litestar.handlers.WebsocketListener`\ :
9 Reactive, event-driven WebSockets with full serialization and DTO support and support
10 for a synchronous interface
11 3. :class:`~litestar.handlers.websocket_stream`:
12 Proactive, stream oriented WebSockets with full serialization and DTO support
13 4. :func:`~litestar.handlers.send_websocket_stream`:
14 Proactive, stream oriented WebSockets
15
16
17 The main difference between the low and high level interfaces is that, dealing with low
18 level interface requires, setting up a loop and listening for incoming data, handling
19 exceptions, client disconnects, and parsing incoming and serializing outgoing data.
20
21
22
23 WebSocket Listeners
24 --------------------
25
26 WebSocket Listeners can be used to interact with a WebSocket in an event-driven manner,
27 using a callback style interface. They treat a WebSocket handler like any other route
28 handler: A callable that takes in incoming data in an already pre-processed form and
29 returns data to be serialized and sent over the connection. The low level details will
30 be handled behind the curtains.
31
32
33 .. code-block:: python
34
35 from litestar import Litestar
36 from litestar.handlers.websocket_handlers import websocket_listener
37
38
39 @websocket_listener("/")
40 async def handler(data: str) -> str:
41 return data
42
43
44 app = Litestar([handler])
45
46
47 This handler will accept connections on ``/``, and wait to receive data. Once a message
48 has been received, it will be passed into the handler function defined, via the ``data``
49 parameter. This works like a regular route handler, so it's possible to specify the
50 type of data which should be received, and it will be converted accordingly.
51
52 .. note::
53 Contrary to WebSocket route handlers, functions decorated with
54 :class:`websocket_listener <.handlers.websocket_listener>` don't have to be
55 asynchronous.
56
57
58
59 Receiving data
60 ++++++++++++++
61
62 Data can be received in the listener via the ``data`` parameter. The data passed to this
63 will be converted / parsed according to the given type annotation and supports
64 :class:`str`, :class:`bytes`, or arbitrary :class:`dict` / or :class:`list` in the
65 form of JSON.
66 .. important::
67
68 The listeners will default to JSON unless `data` is annotated with `str` or `bytes`
69
70
71 .. tab-set::
72
73 .. tab-item:: JSON
74
75 .. literalinclude:: /examples/websockets/receive_json.py
76 :language: python
77
78
79 .. tab-item:: Text
80
81 .. literalinclude:: /examples/websockets/receive_str.py
82 :language: python
83
84
85 .. tab-item:: Bytes
86
87 .. literalinclude:: /examples/websockets/receive_bytes.py
88 :language: python
89
90
91 .. important::
92
93 Contrary to route handlers, JSON data will only be parsed but not validated. This
94 is a limitation of the current implementation and will change in future versions.
95
96
97 Sending data
98 +++++++++++++
99
100 Sending data is done by simply returning the value to be sent from the handler function.
101 Similar to receiving data, type annotations configure how the data is being handled.
102 Values that are not :class:`str` or :class:`bytes` are assumed to be JSON encodable and
103 will be serialized accordingly before being sent. This serialization is available for
104 all data types currently supported by Litestar (
105 :doc:`dataclasses <python:library/dataclasses>`\ , :class:`TypedDict <typing.TypedDict>`,
106 :class:`NamedTuple <typing.NamedTuple>`, :class:`msgspec.Struct`, etc.), including
107 DTOs.
108
109
110 .. tab-set::
111
112 .. tab-item:: Text
113
114 .. literalinclude:: /examples/websockets/sending_str.py
115 :language: python
116
117 .. tab-item:: Bytes
118
119 .. literalinclude:: /examples/websockets/sending_bytes.py
120 :language: python
121
122 .. tab-item:: Dict as JSON
123
124 .. literalinclude:: /examples/websockets/sending_json_dict.py
125 :language: python
126
127
128 .. tab-item:: Dataclass as JSON
129
130 .. literalinclude:: /examples/websockets/sending_json_dataclass.py
131 :language: python
132
133
134 Setting transport modes
135 +++++++++++++++++++++++
136
137
138 Receive mode
139 ~~~~~~~~~~~~
140
141 .. tab-set::
142
143 .. tab-item:: Text mode
144
145 ``text`` is the default mode and is appropriate for most messages, including
146 structured data such as JSON.
147
148 .. literalinclude:: /examples/websockets/mode_receive_text.py
149 :language: python
150
151
152 .. tab-item:: Binary mode
153
154 .. literalinclude:: /examples/websockets/mode_receive_binary.py
155 :language: python
156
157
158 .. important::
159 Once configured with a mode, a listener will only listen to socket events of the
160 appropriate type. This means if a listener is configured to use ``binary`` mode,
161 it will not respond to WebSocket events sending data in the text channel.
162
163
164 Send mode
165 ~~~~~~~~~
166
167 .. tab-set::
168
169 .. tab-item:: Text mode
170
171 ``text`` is the default mode and is appropriate for most messages, including
172 structured data such as JSON.
173
174 .. literalinclude:: /examples/websockets/mode_send_text.py
175 :language: python
176
177
178 .. tab-item:: Binary mode
179
180 .. literalinclude:: /examples/websockets/mode_send_binary.py
181 :language: python
182
183
184
185
186 Dependency injection
187 ++++++++++++++++++++
188
189 :doc:`dependency-injection` is available and generally works the same as in regular
190 route handlers:
191
192 .. literalinclude:: /examples/websockets/dependency_injection_simple.py
193 :language: python
194
195
196 .. important::
197 Injected dependencies work on the level of the underlying **route handler**. This
198 means they won't be re-evaluated every time the listener function is called.
199
200 The following example makes use of :ref:`yield dependencies <yield_dependencies>` and
201 the fact that dependencies are only evaluated once for every connection; The step after
202 the ``yield`` will only be executed after the connection has been closed.
203
204
205 .. literalinclude:: /examples/websockets/dependency_injection_yield.py
206 :language: python
207
208
209
210 Interacting with the WebSocket directly
211 +++++++++++++++++++++++++++++++++++++++
212
213 Sometimes access to the socket instance is needed, in which case the
214 :class:`WebSocket <.connection.WebSocket>` instance can be injected into the handler
215 function via the ``socket`` argument:
216
217 .. literalinclude:: /examples/websockets/socket_access.py
218 :language: python
219
220
221 .. important::
222 Since WebSockets are inherently asynchronous, to interact with the asynchronous
223 methods on :class:`WebSocket <.connection.WebSocket>`, the handler function needs
224 to be asynchronous.
225
226
227 Customising connection acceptance
228 +++++++++++++++++++++++++++++++++
229
230 By default, Litestar will accept all incoming connections by awaiting ``WebSocket.accept()`` without arguments.
231 This behavior can be customized by passing a custom ``connection_accept_handler`` function. Litestar will await this
232 function to accept the connection.
233
234 .. literalinclude:: /examples/websockets/setting_custom_connection_headers.py
235 :language: python
236
237
238 Class based WebSocket handling
239 ++++++++++++++++++++++++++++++
240
241 In addition to using a simple function as in the examples above, a class based approach
242 is made possible by extending the
243 :class:`WebSocketListener <.handlers.WebsocketListener>`. This provides
244 convenient access to socket events such as connect and disconnect, and can be used to
245 encapsulate more complex logic.
246
247
248 .. tab-set::
249
250 .. tab-item:: Sync
251
252 .. literalinclude:: /examples/websockets/listener_class_based.py
253 :language: python
254
255 .. tab-item:: Async
256
257 .. literalinclude:: /examples/websockets/listener_class_based_async.py
258 :language: python
259
260
261 Custom WebSocket
262 ++++++++++++++++
263
264 .. versionadded:: 2.7.0
265
266 Litestar supports custom ``websocket_class`` instances, which can be used to further configure the default :class:`WebSocket`.
267 The example below illustrates how to implement a custom WebSocket class for the whole application.
268
269 .. dropdown:: Example of a custom websocket at the application level
270
271 .. literalinclude:: /examples/websockets/custom_websocket.py
272 :language: python
273
274 .. admonition:: Layered architecture
275
276 WebSocket classes are part of Litestar's layered architecture, which means you can
277 set a WebSocket class on every layer of the application. If you have set a WebSocket
278 class on multiple layers, the layer closest to the route handler will take precedence.
279
280 You can read more about this in the :ref:`usage/applications:layered architecture` section
281
282
283 WebSocket Streams
284 -----------------
285
286 WebSocket streams can be used to proactively push data to a client, using an
287 asynchronous generator function. Data will be sent via the socket every time the
288 generator ``yield``\ s, until it is either exhausted or the client disconnects.
289
290 .. literalinclude:: /examples/websockets/stream_basic.py
291 :language: python
292 :caption: Streaming the current time in 0.5 second intervals
293
294
295 Serialization
296 +++++++++++++
297
298 Just like with route handlers, type annotations configure how the data is being handled.
299 :class:`str` or :class:`bytes` will be sent as-is, while everything else will be encoded
300 as JSON before being sent. This serialization is available for all data types currently
301 supported by Litestar (:doc:`dataclasses <python:library/dataclasses>`,
302 :class:`TypedDict <typing.TypedDict>`, :class:`NamedTuple <typing.NamedTuple>`,
303 :class:`msgspec.Struct`, etc.), including DTOs.
304
305
306 Dependency Injection
307 ++++++++++++++++++++
308
309 Dependency injection is available and works analogous to regular route handlers.
310
311 .. important::
312 One thing to keep in mind, especially for long-lived streams, is that dependencies
313 are scoped to the lifetime of the handler. This means that if for example a
314 database connection is acquired in a dependency, it will be held until the generator
315 stops. This may not be desirable in all cases, and acquiring resources ad-hoc inside
316 the generator itself preferable
317
318 .. literalinclude:: /examples/websockets/stream_di_hog.py
319 :language: python
320 :caption: Bad: The lock will be held until the client disconnects
321
322
323 .. literalinclude:: /examples/websockets/stream_di_hog_fix.py
324 :language: python
325 :caption: Good: The lock will only be acquired when it's needed
326
327
328 Interacting with the WebSocket directly
329 +++++++++++++++++++++++++++++++++++++++
330
331 To interact with the :class:`WebSocket <.connection.WebSocket>` directly, it can be
332 injected into the generator function via the ``socket`` argument:
333
334 .. literalinclude:: /examples/websockets/stream_socket_access.py
335 :language: python
336
337
338 Receiving data while streaming
339 ++++++++++++++++++++++++++++++
340
341 By default, a stream will listen for a client disconnect in the background, and stop
342 the generator once received. Since this requires receiving data from the socket, it can
343 lead to data loss if the application is attempting to read from the same socket
344 simultaneously.
345
346 .. tip::
347 To prevent data loss, by default, ``websocket_stream`` will raise an
348 exception if it receives any data while listening for client disconnects. If
349 incoming data should be ignored, ``allow_data_discard`` should be set to ``True``
350
351 If receiving data while streaming is desired,
352 :func:`~litestar.handlers.send_websocket_stream` can be configured to not listen for
353 disconnects by setting ``listen_for_disconnect=False``.
354
355 .. important::
356 When using ``listen_for_disconnect=False``, the application needs to ensure the
357 disconnect event is received elsewhere, otherwise the stream will only terminate
358 when the generator is exhausted
359
360
361 Combining streaming and receiving data
362 ---------------------------------------
363
364 To stream and receive data concurrently, the stream can be set up manually using
365 :func:`~litestar.handlers.send_websocket_stream` in combination with either a regular
366 :class:`~litestar.handlers.websocket` handler or a WebSocket listener.
367
368 .. tab-set::
369
370 .. tab-item:: websocket_listener
371
372 .. tab-set::
373
374 .. tab-item:: example
375
376 .. literalinclude:: /examples/websockets/stream_and_receive_listener.py
377 :language: python
378
379 .. tab-item:: how to test
380
381 .. literalinclude:: ../../tests/examples/test_websockets.py
382 :language: python
383 :lines: 18-25
384
385
386 .. tab-item:: websocket handler
387
388 .. tab-set::
389
390 .. tab-item:: example
391
392 .. literalinclude:: /examples/websockets/stream_and_receive_raw.py
393 :language: python
394
395 .. tab-item:: how to test
396
397 .. literalinclude:: ../../tests/examples/test_websockets.py
398 :language: python
399 :lines: 28-35
400
401 Transport modes
402 ---------------
403
404 WebSockets have two transport modes: ``text`` and ``binary``. They dictate how bytes are
405 transferred over the wire and can be set independently from another, i.e. a socket can
406 send ``binary`` and receive ``text``
407
408
409 It may seem intuitive that ``text`` and ``binary`` should map to :class:`str` and
410 :class:`bytes` respectively, but this is not the case. WebSockets can receive and
411 send data in any format, independently of the mode. The mode only affects how the
412 bytes are handled during transport (i.e. on the protocol level). In most cases the
413 default mode - ``text`` - is all that's needed. Binary transport is usually employed
414 when sending binary blobs that don't have a meaningful string representation, such
415 as images.