Extensions - websockets 12.0 documentation
Description: The WebSocket protocol supports extensions. At the time of writing, there’s only one registered extension with a public specification, WebSocket Per-Message Deflate. Per-Message Deflate: websockets...

Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

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

## Per-Message Deflate

`websockets.extensions.permessage_deflate` implements WebSocket Per-Message Deflate.

This extension is specified in RFC 7692.

Refer to the topic guide on compression to learn more about tuning compression settings.

class websockets.extensions.permessage_deflate.ClientPerMessageDeflateFactory(server_no_context_takeover=False, client_no_context_takeover=False, server_max_window_bits=None, client_max_window_bits=True, compress_settings=None)

  Client-side extension factory for the Per-Message Deflate extension.

  Parameters behave as described in section 7.1 of RFC 7692.

  Set them to `True` to include them in the negotiation offer without a value or to an integer value to include them with this value.

  Parameters:

    - server_no_context_takeover (bool) – prevent server from using context takeover.

    - client_no_context_takeover (bool) – prevent client from using context takeover.

    - server_max_window_bits (Optional[int]) – maximum size of the server’s LZ77 sliding window in bits, between 8 and 15.

    - client_max_window_bits (Optional[Union[int, bool]]) – maximum size of the client’s LZ77 sliding window in bits, between 8 and 15, or `True` to indicate support without setting a limit.

    - compress_settings (Optional[Dict[str, Any]]) – additional keyword arguments for `zlib.compressobj()`, excluding `wbits`.

class websockets.extensions.permessage_deflate.ServerPerMessageDeflateFactory(server_no_context_takeover=False, client_no_context_takeover=False, server_max_window_bits=None, client_max_window_bits=None, compress_settings=None, require_client_max_window_bits=False)

  Server-side extension factory for the Per-Message Deflate extension.

  Parameters behave as described in section 7.1 of RFC 7692.

  Set them to `True` to include them in the negotiation offer without a value or to an integer value to include them with this value.

  Parameters:

    - server_no_context_takeover (bool) – prevent server from using context takeover.

    - client_no_context_takeover (bool) – prevent client from using context takeover.

    - server_max_window_bits (Optional[int]) – maximum size of the server’s LZ77 sliding window in bits, between 8 and 15.

    - client_max_window_bits (Optional[int]) – maximum size of the client’s LZ77 sliding window in bits, between 8 and 15.

    - compress_settings (Optional[Dict[str, Any]]) – additional keyword arguments for `zlib.compressobj()`, excluding `wbits`.

    - require_client_max_window_bits (bool) – do not enable compression at all if client doesn’t advertise support for `client_max_window_bits`; the default behavior is to enable compression without enforcing `client_max_window_bits`.

## Base classes

`websockets.extensions` defines base classes for implementing

  extensions.

Refer to the how-to guide on extensions to learn more about writing an extension.

class websockets.extensions.Extension

  Base class for extensions.

  name: ExtensionName

    Extension identifier.

  decode(frame, *, max_size=None)

    Decode an incoming frame.

    Parameters:

      - frame (Frame) – incoming frame.

      - max_size (int | None) – maximum payload size in bytes.

    Returns:

      Decoded frame.

    Return type:

      Frame

    Raises:

      PayloadTooBig – if decoding the payload exceeds `max_size`.

  encode(frame)

    Encode an outgoing frame.

    Parameters:

      frame (Frame) – outgoing frame.

    Returns:

      Encoded frame.

    Return type:

      Frame

class websockets.extensions.ClientExtensionFactory

  Base class for client-side extension factories.

  name: ExtensionName

    Extension identifier.

  get_request_params()

    Build parameters to send to the server for this extension.

    Returns:

      Parameters to send to the server.

    Return type:

      List[ExtensionParameter]

  process_response_params(params, accepted_extensions)

    Process parameters received from the server.

    Parameters:

      - params (Sequence[ExtensionParameter]) – parameters received from the server for this extension.

      - accepted_extensions (Sequence[Extension]) – list of previously accepted extensions.

    Returns:

      An extension instance.

    Return type:

      Extension

    Raises:

      NegotiationError – if parameters aren’t acceptable.

class websockets.extensions.ServerExtensionFactory

  Base class for server-side extension factories.

  process_request_params(params, accepted_extensions)

    Process parameters received from the client.

    Parameters:

      - params (Sequence[ExtensionParameter]) – parameters received from the client for this extension.

      - accepted_extensions (Sequence[Extension]) – list of previously accepted extensions.

    Returns:

      To accept the offer, parameters to send to the client for this extension and an extension instance.

    Return type:

      Tuple[List[ExtensionParameter], Extension]

    Raises:

      NegotiationError – to reject the offer, if parameters received from the client aren’t acceptable.