Extensions

The WebSocket protocol supports extensions.

At the time of writing, there’s only one registered extension with a public specification, WebSocket Per-Message Deflate, specified in RFC 7692.

Per-Message Deflate

connect() and serve() enable the Per-Message Deflate extension by default.

If you want to disable it, set compression=None:

import websockets

websockets.connect(..., compression=None)

websockets.serve(..., compression=None)

You can also configure the Per-Message Deflate extension explicitly if you want to customize compression settings:

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},
        ),
    ],
)

websockets.serve(
    ...,
    extensions=[
        permessage_deflate.ServerPerMessageDeflateFactory(
            server_max_window_bits=11,
            client_max_window_bits=11,
            compress_settings={'memLevel': 4},
        ),
    ],
)

The window bits and memory level values chosen in these examples reduce memory usage. You can read more about optimizing compression settings.

Refer to the API documentation of ClientPerMessageDeflateFactory and ServerPerMessageDeflateFactory 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 being sent or after being received.

As a consequence, writing an extension requires implementing several classes:

  • Extension Factory: it negotiates parameters and instantiates the extension.

    Clients and servers require separate extension factories with distinct APIs.

    Extension factories are the public API of an extension.

  • Extension: it decodes incoming frames and encodes outgoing frames.

    If the extension is symmetrical, clients and servers can use the same class.

    Extensions are initialized by extension factories, so they don’t need to be part of the public API of an extension.

websockets provides abstract base classes for extension factories and extensions. See the API documentation for details on their methods: