duck.contrib.websockets.extensions

WebSocket Extensions module.

Provides base and concrete implementations for WebSocket frame extensions, including permessage-deflate compression as defined in RFC 7692.

Module Contents

Classes

Extension

Base class for WebSocket extensions.

PerMessageDeflate

Per-message Deflate Extension (RFC 7692).

API

class duck.contrib.websockets.extensions.Extension(name: str)

Base class for WebSocket extensions.

Extensions allow for modification of WebSocket frames during encoding (sending) or decoding (receiving), such as compression or encryption.

Initialization

Initialize the extension with a valid name.

Parameters:

name – The name of the extension as it should appear in the Sec-WebSocket-Extensions header.

Raises:

ValueError – If the name is not a non-empty string.

check_frame(frame)

Validates that the given object is a Frame instance.

Parameters:

frame – The frame object to validate.

Raises:

ExtensionError – If the object is not an instance of Frame.

abstractmethod decode(frame) → Frame

Applies the extension to decode (transform) an incoming frame.

Parameters:

frame – The frame to decode.

Raises:

NotImplementedError – If not implemented by a subclass.

Returns:

The decoded frame, typically the same frame but decoded.

Return type:

Frame

abstractmethod encode(frame) → Frame

Applies the extension to encode (transform) an outgoing frame.

Parameters:

frame – The frame to encode.

Raises:

NotImplementedError – If not implemented by a subclass.

Returns:

The encoded frame, typically the same frame but encoded.

Return type:

Frame

class duck.contrib.websockets.extensions.PerMessageDeflate(name: str, client_no_context_takeover: bool = False, server_no_context_takeover: bool = False, client_max_window_bits: int = 15)

Bases: duck.contrib.websockets.extensions.Extension

Per-message Deflate Extension (RFC 7692).

Provides compression for non-control WebSocket frames using DEFLATE. Supports options for context takeover and window size.

Parameters:

  • client_no_context_takeover – Whether to disable decompression context reuse.

  • server_no_context_takeover – Whether to disable compression context reuse.

  • client_max_window_bits – Maximum window bits for client decompression (8-15). Defaults to 15, which means 32K LZ77 history buffer.

Initialization

Initialize the extension with a valid name.

Parameters:

name – The name of the extension as it should appear in the Sec-WebSocket-Extensions header.

Raises:

ValueError – If the name is not a non-empty string.

__repr__()

Returns a debug-friendly string representation of the extension.

decode(frame) → Frame

Decompresses the payload of the given frame using DEFLATE.

Skips control frames. Appends the 4-byte tail removed during encoding. Unsets RSV1 after decoding.

Parameters:

frame – A Frame instance to decode.

Raises:

ExtensionError – If the input is not a valid Frame.

Returns:

The decoded frame, typically the same frame but decoded.

Return type:

Frame

encode(frame) → Frame

Compresses the payload of the given frame using DEFLATE.

Skips control frames. Appends Z_SYNC_FLUSH marker and strips final 4-byte tail as required by RFC 7692. Sets RSV1 on first frame of a message.

Parameters:

frame – A Frame instance to encode.

Raises:

ExtensionError – If the input is not a valid Frame.

Returns:

The encoded frame, typically the same frame but encoded.

Return type:

Frame