WebSocket/PMCE/deflate.pm

filter: Statementstmt 83.7% 77 / 92 Branchbran 63.3% 19 / 30 Conditioncond 66.6% 4 / 6 MC/DCmcdc 0.0% 0 / 4 Subroutinesub 91.6% 22 / 24 Podpod 100% 9 / 9 totaltotal 79.3% 131 / 165 CC 18 SCAR 12.9
CC
18
Cov
78%
_get_parameter_errors
11.1
create_data_object
6.0
_create_extension_header_parts
5.0
CRAP 3.6
« WebSocket/Handshake/Server.pm ↑ Summary WebSocket/X/DuplicateHeader.pm »
1 package Net::WebSocket::PMCE::deflate;
2  
3 =encoding utf-8
4  
5 =head1 NAME
6  
7 Net::WebSocket::PMCE::deflate - WebSocket’s C<permessage-deflate> extension
8  
9 =head1 SYNOPSIS
10  
11 See L<Net::WebSocket::PMCE::deflate::Server> or
12 L<Net::WebSocket::PMCE::deflate::Client> for usage examples.
13  
14 =head1 DESCRIPTION
15  
16 This class implements C<permessage-deflate> as defined in
17 L<RFC 7692|https://tools.ietf.org/html/rfc7692>.
18  
19 This is a base class, not to be instantiated directly.
20  
21 This class implements a L<Net::WebSocket::Handshake>-compatible
22 extension interface.
23  
24 =head1 STATUS
25  
26 This module is an ALPHA release. Changes to the API are not unlikely;
27 be sure to check the changelog before updating, and please report any
28 issues you find.
29  
30 =cut
31  
32 4 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
33 4 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
34  
35 4 ▶use parent qw( Net::WebSocket::PMCE::deflate::Constants );
Subroutine BEGIN: called CC=1 SCAR=0.0
36  
37 4 ▶use Module::Runtime ();
Subroutine BEGIN: called CC=1 SCAR=0.0
38  
39 4 ▶use Net::WebSocket::Handshake::Extension ();
Subroutine BEGIN: called CC=1 SCAR=0.0
40 4 ▶use Net::WebSocket::PMCE::deflate::Constants ();
Subroutine BEGIN: called CC=1 SCAR=0.0
41 4 ▶use Net::WebSocket::X ();
Subroutine BEGIN: called CC=1 SCAR=0.0
42  
43 =head1 METHODS
44  
45 =head2 I<CLASS>->new( %OPTS )
46  
47 Returns a new instance of this class.
48  
49 C<%OPTS> is:
50  
51 =over
52  
53 =item C<deflate_max_window_bits> - optional; the maximum number of window bits
54 that this endpoint will use to compress messages. See C<client_max_window_bits>
55 in L<RFC 7692|https://tools.ietf.org/html/rfc7692> for valid values.
56  
57 =item C<inflate_max_window_bits> - optional; the number of window bits to use
58 to decompress messages. Valid values are the same as for
59 C<deflate_max_window_bits>.
60  
61 =item C<deflate_no_context_takeover> - boolean; whether the compressor
62 will forgo context takeover. (See below.)
63  
64 =item C<inflate_no_context_takeover> - boolean; whether the decompressor
65 can forgo context takeover.
66  
67 =back
68  
69 This interface uses C<deflate_*>/C<inflate_*> prefixes rather than
70 C<client_*>/C<server_*> as the RFC uses because the module author
71 has found C<deflate_*>/C<inflate_*> easier to conceptualize.
72  
73 =head1 CONTEXT TAKEOVER: THE MISSING EXPLANATION
74  
75 As best I can tell, the term “context takeover” is indigenous to
76 permessage-deflate. The term appears all over the RFC but isn’t explained
77 very clearly, in my opinion. Here, then, is an attempt to provide that
78 explanation.
79  
80 As a DEFLATE compressor receives bytes of the stream, it “remembers”
81 common sequences of past parts of the stream in a “window” that
82 “slides” along with the data stream: this is the LZ77 ”sliding window”.
83  
84 By default, permessage-deflate retains the previous message’s sliding
85 window and uses it to compress the start of the next message;
86 this is called “context takeover” because the new message “takes over”
87 the “context” (i.e., sliding window) from the previous message. Setting
88 one or the other peer to “no context takeover” mode, then, tells that
89 peer to empty out its sliding window at the end of each message. This
90 means that peer won’t need to retain the sliding window between messages,
91 which can reduce memory consumption.
92  
93 In DEFLATE terms, a compressor does a SYNC flush at the end of each
94 message when using context takeover; otherwise the compressor does a
95 FULL flush.
96  
97 Maybe a better term for this behavior would have been “window retention”.
98 Anyway, there it is.
99  
100 =cut
101  
102 25 ▶sub new {
Subroutine new: called CC=2 SCAR=6.9
Pod documented
103 25 my ($class, %opts) = @_;
104  
105 25 my @errs = $class->_get_parameter_errors(%opts);
106 25 ▶ die "@errs" if @errs;
Branch: 1 branch
BranchTrueFalseTotal
if @errs 8 17 25
107  
108 17 return bless \%opts, $class;
109 }
110  
111 =head2 I<OBJ>->deflate_max_window_bits()
112  
113 The effective value of this setting. If unspecified or if the peer doesn’t
114 support this feature, the returned value will be the RFC’s default value.
115  
116 =cut
117  
118 5 ▶sub deflate_max_window_bits {
Subroutine deflate_max_window_bits: called CC=2 SCAR=7.1
Pod documented
119 5 my ($self) = @_;
120  
121 5 ▶ return $self->{'deflate_max_window_bits'} || ( $self->VALID_MAX_WINDOW_BITS() )[-1];
Condition66%2/3
$self->{'deflate_max_window_bits'} || ($self->VALID_MAX_WINDOW_BITS)[-1]
l!l&&r!l&&!r
320
MC/DC0%0/2
$self->{'deflate_max_window_bits'} || ($self->VALID_MAX_WINDOW_BITS)[-1]
$self->{'deflate_max_window_bits'} ($self->VALID_MAX_WINDOW_BITS)[-1]
Truth table66%2/3
A || B
A= $self->{'deflate_max_window_bits'}B= ($self->VALID_MAX_WINDOW_BITS)[-1]
ABresult
1X1
011
000
122 }
123  
124 =head2 I<OBJ>->inflate_max_window_bits()
125  
126 The effective value of this setting. If unspecified or if the peer doesn’t
127 support this feature, the returned value will be the RFC’s default value.
128  
129 =cut
130  
131 7 ▶sub inflate_max_window_bits {
Subroutine inflate_max_window_bits: called CC=2 SCAR=7.1
Pod documented
132 7 my ($self) = @_;
133  
134 7 ▶ return $self->{'inflate_max_window_bits'} || ( $self->VALID_MAX_WINDOW_BITS() )[-1];
Condition66%2/3
$self->{'inflate_max_window_bits'} || ($self->VALID_MAX_WINDOW_BITS)[-1]
l!l&&r!l&&!r
520
MC/DC0%0/2
$self->{'inflate_max_window_bits'} || ($self->VALID_MAX_WINDOW_BITS)[-1]
$self->{'inflate_max_window_bits'} ($self->VALID_MAX_WINDOW_BITS)[-1]
Truth table66%2/3
A || B
A= $self->{'inflate_max_window_bits'}B= ($self->VALID_MAX_WINDOW_BITS)[-1]
ABresult
1X1
011
000
135 }
136  
137 =head2 I<OBJ>->deflate_no_context_takeover()
138  
139 Whether to drop the LZ77 sliding window between messages (i.e.,
140 to do a full DEFLATE flush with each FIN frame).
141  
142 =cut
143  
144 4 ▶sub deflate_no_context_takeover {
Subroutine deflate_no_context_takeover: called CC=1 SCAR=0.0
Pod documented
145 4 my ($self) = @_;
146  
147 4 return !!$self->{'deflate_no_context_takeover'};
148 }
149  
150 =head2 I<OBJ>->inflate_no_context_takeover()
151  
152 Whether to ask the peer drop the LZ77 sliding window between messages.
153  
154 =cut
155  
156 6 ▶sub inflate_no_context_takeover {
Subroutine inflate_no_context_takeover: called CC=1 SCAR=0.0
Pod documented
157 6 my ($self) = @_;
158  
159 6 return !!$self->{'inflate_no_context_takeover'};
160 }
161  
162 =head2 I<OBJ>->create_data_object()
163  
164 A convenience method that returns an instance of the appropriate
165 subclass of L<Net::WebSocket::PMCE::deflate::Data>.
166  
167 =cut
168  
169 0 ▶sub create_data_object {
Subroutine create_data_object: not called CC=2 SCAR=17.9
Pod documented
170 0 my ($self) = @_;
171  
172 0 my $class = __PACKAGE__ . '::Data::' . $self->_ENDPOINT_CLASS();
173 0 ▶ Module::Runtime::require_module($class) if !$class->can('new');
Branch: 1 branch
BranchTrueFalseTotal
unless $class->can("new") 0 0 0
174  
175 0 return $class->new( %$self );
176 }
177  
178 #----------------------------------------------------------------------
179  
180 =head2 I<OBJ>->token()
181  
182 As described in L<Net::WebSocket::Handshake>’s documentation.
183  
184 =cut
185  
186 #====== INHERITED from an undocumented base class
187  
188 =head2 I<OBJ>->get_handshake_object()
189  
190 As described in L<Net::WebSocket::Handshake>’s documentation.
191  
192 =cut
193  
194 4 ▶sub get_handshake_object {
Subroutine get_handshake_object: called CC=1 SCAR=0.0
Pod documented
195 4 my ($self) = @_;
196  
197 4 return Net::WebSocket::Handshake::Extension->new(
198 $self->_create_extension_header_parts(),
199 );
200 }
201  
202 =head2 I<OBJ>->consume_parameters( KEY1 => VALUE1, .. )
203  
204 As described in L<Net::WebSocket::Handshake>’s documentation. After
205 this function runs, you can inspect the I<OBJ> to ensure that the
206 configuration that the peer allows is one that your application
207 finds acceptable. (It likely is, but hey.)
208  
209 See this module’s subclasses’ documentation for more details about
210 how they handle each parameter.
211  
212 =cut
213  
214 12 ▶sub consume_parameters {
Subroutine consume_parameters: called CC=2 SCAR=7.5
Pod documented
215 12 my ($self, @params) = @_;
216  
217 12 my %opts = @params;
218  
219 12 $self->_consume_extension_options(\%opts);
220  
221 11 ▶ if (%opts) {
Branch: 1 branch
BranchTrueFalseTotal
if (%opts) 0 11 11
222 0 my $token = $self->token();
223 0 die "Unrecognized for “$token”: @params";
224 }
225  
226 11 $self->{'_use_ok'}++;
227  
228 11 return;
229 }
230  
231 =head2 I<OBJ>->ok_to_use()
232  
233 As described in L<Net::WebSocket::Handshake>’s documentation.
234  
235 =cut
236  
237 0 ▶sub ok_to_use {
Subroutine ok_to_use: not called CC=1 SCAR=6.9
Pod documented
238 0 my ($self) = @_;
239  
240 0 return !!$self->{'_use_ok'};
241 }
242  
243 #----------------------------------------------------------------------
244  
245 # 7. .. A server MUST decline an extension negotiation offer for this
246 # extension if any of the following conditions are met:
247 25 ▶sub _get_parameter_errors {
Subroutine _get_parameter_errors: called CC=6 SCAR=24.1
248 25 my ($class, @params_kv) = @_;
249  
250 25 my %params;
251  
252 my @errors;
253  
254 25 ▶ while ( my ($k, $v) = splice( @params_kv, 0, 2 ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = splice(@params_kv, 0, 2)) 23 25 48
255  
256 #The negotiation (offer/response) contains multiple extension
257 #parameters with the same name.
258 23 ▶ if ( exists $params{$k} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $params{$k}) 0 23 23
259 0 ▶ if (defined $v) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $v) { } 0 0 0
260 0 push @errors, "Duplicate parameter /$k/ ($v)";
261 }
262 else {
263 0 push @errors, "Duplicate parameter /$k/, no value";
264 }
265 }
266  
267 #The negotiation (offer/response) contains an extension parameter
268 #with an invalid value.
269 23 ▶ if ( my $cr = $class->can("_validate_$k") ) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $cr = $class->can("_validate_$k")) { } 23 0 23
270 23 push @errors, $cr->($class, $v);
271 }
272  
273 #The negotiation (offer/response) contains an extension parameter
274 #not defined for use in an (offer/response).
275 else {
276 0 ▶ if (defined $v) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $v) { } 0 0 0
277 0 push @errors, "Unknown parameter /$k/ ($v)";
278 }
279 else {
280 0 push @errors, "Unknown parameter /$k/, no value";
281 }
282 }
283 }
284  
285 25 return @errors;
286 }
287  
288 #Define these as no-ops because all we care about is their truthiness.
289 4 ▶use constant _validate_deflate_no_context_takeover => ();
Subroutine BEGIN: called CC=1 SCAR=0.0
290 4 ▶use constant _validate_inflate_no_context_takeover => ();
Subroutine BEGIN: called CC=1 SCAR=0.0
291  
292 7 ▶sub _validate_deflate_max_window_bits {
Subroutine _validate_deflate_max_window_bits: called CC=1 SCAR=0.0
293 7 return $_[0]->__validate_max_window_bits( 'deflate', $_[1] );
294 }
295  
296 10 ▶sub _validate_inflate_max_window_bits {
Subroutine _validate_inflate_max_window_bits: called CC=1 SCAR=0.0
297 10 return $_[0]->__validate_max_window_bits( 'inflate', $_[1] );
298 }
299  
300 5 ▶sub __validate_no_context_takeover {
Subroutine __validate_no_context_takeover: called CC=2 SCAR=7.6
301 5 my ($self, $endpoint, $value) = @_;
302  
303 5 ▶ if (defined $value) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $value) 0 5 5
304 0 return "/${endpoint}_no_context_takeover/ must not have a value.";
305 }
306  
307 5 return;
308 }
309  
310 23 ▶sub __validate_max_window_bits {
Subroutine __validate_max_window_bits: called CC=3 SCAR=11.0
311 23 my ($self, $ept, $bits) = @_;
312  
313 23 my @VALID_MAX_WINDOW_BITS = $self->VALID_MAX_WINDOW_BITS();
314  
315 23 ▶ if (defined $bits) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $bits) 23 0 23
316 23 ▶ return if grep { $_ eq $bits } @VALID_MAX_WINDOW_BITS;
Branch: 1 branch
BranchTrueFalseTotal
if grep {$_ eq $bits;} @VALID_MAX_WINDOW_BITS 15 8 23
317 }
318  
319 8 return Net::WebSocket::X->create( 'BadArg', "${ept}_max_window_bits" => $bits, "Must be one of: [@VALID_MAX_WINDOW_BITS]" );
320 }
321  
322 4 ▶sub _create_extension_header_parts {
Subroutine _create_extension_header_parts: called CC=5 SCAR=16.1
323 4 my ($self) = @_;
324  
325 4 my @parts = $self->token();
326  
327 4 ▶ if (defined $self->{'deflate_max_window_bits'}) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->{"deflate_max_window_bits"}) 1 3 4
328 1 push @parts, $self->_DEFLATE_MAX_WINDOW_BITS_PARAM() => $self->{'deflate_max_window_bits'};
329 }
330  
331 4 ▶ if (defined $self->{'inflate_max_window_bits'}) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $self->{"inflate_max_window_bits"}) 2 2 4
332 2 push @parts, $self->_INFLATE_MAX_WINDOW_BITS_PARAM() => $self->{'inflate_max_window_bits'};
333 }
334  
335 4 ▶ if ($self->{'deflate_no_context_takeover'}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"deflate_no_context_takeover"}) 1 3 4
336 1 push @parts, $self->_LOCAL_NO_CONTEXT_TAKEOVER_PARAM() => undef;
337 }
338 4 ▶ if ($self->{'inflate_no_context_takeover'}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"inflate_no_context_takeover"}) 3 1 4
339 3 push @parts, $self->_PEER_NO_CONTEXT_TAKEOVER_PARAM() => undef;
340 }
341  
342 4 return @parts;
343 }
344  
345 #----------------------------------------------------------------------
346  
347 4 1;
348  
349 =head1 REPOSITORY
350  
351 L<https://github.com/FGasper/p5-Net-WebSocket>
352  
353 =head1 AUTHOR
354  
355 Felipe Gasper (FELIPE)
356  
357 =head1 COPYRIGHT
358  
359 Copyright 2017 by L<Gasper Software Consulting|http://gaspersoftware.com>
360  
361 =head1 LICENSE
362  
363 This distribution is released under the same license as Perl.
« WebSocket/Handshake/Server.pm ↑ Summary WebSocket/X/DuplicateHeader.pm »