++ed by:
SKOLYCHEV TEAM

2 PAUSE users
1 non-PAUSE user.

Author image Felipe Gasper
and 1 contributors

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. See client_max_window_bits in 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 for deflate_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

LICENSE

This distribution is released under the same license as Perl.