NAME
Net::WebSocket::PMCE::deflate - WebSocket’s permessage-deflate extension
SYNOPSIS
See Net::WebSocket::PMCE::deflate::Server or Net::WebSocket::PMCE::deflate::Client for usage examples.
DESCRIPTION
This class implements permessage-deflate as defined in RFC 7692.
This is a base class, not to be instantiated directly.
This class implements a Net::WebSocket::Handshake-compatible extension interface.
STATUS
This module is an ALPHA release. Changes to the API are not unlikely; be sure to check the changelog before updating, and please report any issues you find.
METHODS
CLASS->new( %OPTS )
Returns a new instance of this class.
%OPTS is:
deflate_max_window_bits- optional; the maximum number of window bits that this endpoint will use to compress messages. Seeclient_max_window_bitsin RFC 7692 for valid values.inflate_max_window_bits- optional; the number of window bits to use to decompress messages. Valid values are the same as fordeflate_max_window_bits.deflate_no_context_takeover- boolean; whether the compressor will forgo context takeover. (See below.)inflate_no_context_takeover- boolean; whether the decompressor can forgo context takeover.
This interface uses deflate_*/inflate_* prefixes rather than client_*/server_* as the RFC uses because the module author has found deflate_*/inflate_* easier to conceptualize.
CONTEXT TAKEOVER: THE MISSING EXPLANATION
As best I can tell, the term “context takeover” is indigenous to permessage-deflate. The term appears all over the RFC but isn’t explained very clearly, in my opinion. Here, then, is an attempt to provide that explanation.
As a DEFLATE compressor receives bytes of the stream, it “remembers” common sequences of past parts of the stream in a “window” that “slides” along with the data stream: this is the LZ77 ”sliding window”.
By default, permessage-deflate retains the previous message’s sliding window and uses it to compress the start of the next message; this is called “context takeover” because the new message “takes over” the “context” (i.e., sliding window) from the previous message. Setting one or the other peer to “no context takeover” mode, then, tells that peer to empty out its sliding window at the end of each message. This means that peer won’t need to retain the sliding window between messages, which can reduce memory consumption.
In DEFLATE terms, a compressor does a SYNC flush at the end of each message when using context takeover; otherwise the compressor does a FULL flush.
Maybe a better term for this behavior would have been “window retention”. Anyway, there it is.
OBJ->deflate_max_window_bits()
The effective value of this setting. If unspecified or if the peer doesn’t support this feature, the returned value will be the RFC’s default value.
OBJ->inflate_max_window_bits()
The effective value of this setting. If unspecified or if the peer doesn’t support this feature, the returned value will be the RFC’s default value.
OBJ->deflate_no_context_takeover()
Whether to drop the LZ77 sliding window between messages (i.e., to do a full DEFLATE flush with each FIN frame).
OBJ->inflate_no_context_takeover()
Whether to ask the peer drop the LZ77 sliding window between messages.
OBJ->create_data_object()
A convenience method that returns an instance of the appropriate subclass of Net::WebSocket::PMCE::deflate::Data.
OBJ->token()
As described in Net::WebSocket::Handshake’s documentation.
OBJ->get_handshake_object()
As described in Net::WebSocket::Handshake’s documentation.
OBJ->consume_parameters( KEY1 => VALUE1, .. )
As described in Net::WebSocket::Handshake’s documentation. After this function runs, you can inspect the OBJ to ensure that the configuration that the peer allows is one that your application finds acceptable. (It likely is, but hey.)
See this module’s subclasses’ documentation for more details about how they handle each parameter.
OBJ->ok_to_use()
As described in Net::WebSocket::Handshake’s documentation.
REPOSITORY
https://github.com/FGasper/p5-Net-WebSocket
AUTHOR
Felipe Gasper (FELIPE)
COPYRIGHT
Copyright 2017 by Gasper Software Consulting, LLC
LICENSE
This distribution is released under the same license as Perl.