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¶
Base class for WebSocket extensions. |
|
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.
- 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.ExtensionPer-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:
- 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: