1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
|
Extensions
==========
.. currentmodule:: websockets
The WebSocket protocol supports extensions_.
At the time of writing, there's only one `registered extension`_, WebSocket
Per-Message Deflate, specified in :rfc:`7692`.
.. _extensions: https://tools.ietf.org/html/rfc6455#section-9
.. _registered extension: https://www.iana.org/assignments/websocket/websocket.xhtml#extension-name
Per-Message Deflate
-------------------
:func:`~server.serve()` and :func:`~client.connect` enable the Per-Message
Deflate extension by default. You can disable this with ``compression=None``.
You can also configure the Per-Message Deflate extension explicitly if you
want to customize its parameters.
.. _per-message-deflate-configuration-example:
Here's an example on the server side::
import websockets
from websockets.extensions import permessage_deflate
websockets.serve(
...,
extensions=[
permessage_deflate.ServerPerMessageDeflateFactory(
server_max_window_bits=11,
client_max_window_bits=11,
compress_settings={'memLevel': 4},
),
],
)
Here's an example on the client side::
import websockets
from websockets.extensions import permessage_deflate
websockets.connect(
...,
extensions=[
permessage_deflate.ClientPerMessageDeflateFactory(
server_max_window_bits=11,
client_max_window_bits=11,
compress_settings={'memLevel': 4},
),
],
)
Refer to the API documentation of
:class:`~extensions.permessage_deflate.ServerPerMessageDeflateFactory` and
:class:`~extensions.permessage_deflate.ClientPerMessageDeflateFactory` for
details.
Writing an extension
--------------------
During the opening handshake, WebSocket clients and servers negotiate which
extensions will be used with which parameters. Then each frame is processed by
extensions before it's sent and after it's received.
As a consequence writing an extension requires implementing several classes:
1. Extension Factory: it negotiates parameters and instantiates the extension.
Clients and servers require separate extension factories with distinct APIs.
2. Extension: it decodes incoming frames and encodes outgoing frames. If the
extension is symmetrical, clients and servers can use the same class.
``websockets`` provides abstract base classes for extension factories and
extensions.
.. autoclass:: websockets.extensions.base.ServerExtensionFactory
:members:
.. autoclass:: websockets.extensions.base.ClientExtensionFactory
:members:
.. autoclass:: websockets.extensions.base.Extension
:members:
|
