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:

* "ClientExtensionFactory" and class:*ServerExtensionFactory* for
  :extension factories,

* "Extension" for extensions.
