WebSocket/Handshake.pm

filter: Statementstmt 78.2% 90 / 115 Branchbran 65.3% 34 / 52 Conditioncond 66.6% 2 / 3 MC/DCmcdc 50.0% 1 / 2 Subroutinesub 89.4% 17 / 19 Podpod 100% 5 / 5 totaltotal 76.0% 149 / 196 CC 34 SCAR 21.0
CC
34
Cov
74%
_consume_sec_websocket_extensions_header
20.0
_consume_generic_header
17.1
_encode_extensions
6.6
CRAP 8.2
« WebSocket/Frame/close.pm ↑ Summary WebSocket/Frame.pm »
1 package Net::WebSocket::Handshake;
2  
3 5 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 5 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 =encoding utf-8
7  
8 =head1 NAME
9  
10 Net::WebSocket::Handshake - base class for handshake objects
11  
12 =head1 DESCRIPTION
13  
14 This base class’s L<Net::WebSocket::Handshake::Server> and
15 L<Net::WebSocket::Handshake::Client> subclasses implement
16 WebSocket’s handshake logic. They handle the basics of a WebSocket
17 handshake and, optionally, subprotocol and extension negotiation.
18  
19 This base class is NOT directly instantiable.
20  
21 =cut
22  
23 5 ▶use Digest::SHA1 ();
Subroutine BEGIN: called CC=1 SCAR=0.0
24 5 ▶use HTTP::Headers::Util ();
Subroutine BEGIN: called CC=1 SCAR=0.0
25  
26 5 ▶use Net::WebSocket::HTTP ();
Subroutine BEGIN: called CC=1 SCAR=0.0
27 5 ▶use Net::WebSocket::X ();
Subroutine BEGIN: called CC=1 SCAR=0.0
28  
29 5 ▶use constant {
Subroutine BEGIN: called CC=1 SCAR=0.0
30 5 _WS_MAGIC_CONSTANT => '258EAFA5-E914-47DA-95CA-C5AB0DC85B11',
31 CRLF => "\x0d\x0a",
32 5 };
33  
34 #----------------------------------------------------------------------
35  
36 =head1 METHODS
37  
38 =head2 I<CLASS>->new( %OPTS )
39  
40 Returns an instance of the relevant subclass
41 (L<Net::WebSocket::Handshake::Client|::Client> or
42 L<Net::WebSocket::Handshake::Server|::Server>).
43 The following are common options for both:
44  
45 =over
46  
47 =item * C<subprotocols> - A list of HTTP tokens (e.g., C<wamp.2.json>)
48 that stand for subprotocols that this endpoint can use via the WebSocket
49 connection.
50  
51 =item * C<extensions> - A list of extension objects that the Handshake
52 object will interact with to determine extension support.
53  
54 =back
55  
56 =head1 COMMON EXTENSION INTERFACE
57  
58 Each object in the C<extensions> array must implement the following methods:
59  
60 =over
61  
62 =item * C<token()> The extension’s token. (e.g., C<permessage-deflate>)
63  
64 =item * C<get_handshake_object()> Returns an instance of
65 L<Net::WebSocket::Handshake::Extension> to represent the extension and
66 its parameters in the HTTP headers.
67  
68 =item * C<consume_parameters(..)> Receives the extension parameters
69 (in the format that C<Net::WebSocket::Handshake::Extension::parameters()>
70 returns). This operation should configure the object to return the proper
71 value from its C<ok_to_use()> method.
72  
73 =item * C<ok_to_use()> A boolean that indicates whether the peer indicates
74 proper support for the extension. This should not be called until after
75 C<consume_parameters()>.
76  
77 =back
78  
79 =cut
80  
81 15 ▶sub new {
Subroutine new: called CC=2 SCAR=6.9
Pod documented
82 15 my ($class, %opts) = @_;
83  
84 15 ▶ if ($opts{'extensions'}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($opts{"extensions"}) 1 14 15
85 1 $opts{'_extension_tokens'} = { map { $_->token() => $_ } @{ $opts{'extensions'} } };
86 }
87  
88 15 return bless \%opts, $class;
89 }
90  
91 =head2 $sp_token = I<OBJ>->get_subprotocol()
92  
93 Returns the negotiated subprotocol’s token (e.g., C<wamp.2.json>).
94  
95 =cut
96  
97 2 ▶sub get_subprotocol {
Subroutine get_subprotocol: called CC=2 SCAR=7.6
Pod documented
98 2 my $self = shift;
99  
100 2 ▶ if (!$self->{'_no_use_legacy'}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->{"_no_use_legacy"}) 0 2 2
101 0 die 'Must call consume_headers() first!';
102 }
103  
104 2 return $self->{'_subprotocol'};
105 }
106  
107 =head2 I<OBJ>->consume_headers( HDR1 => VAL1, HDR2 => VAL2, .. )
108  
109 The “workhorse” method of this base class. Takes in the HTTP headers
110 and verifies that the look as they should, setting this object’s own
111 internals as appropriate.
112  
113 This will throw an appropriate exception if any header is missing
114 or otherwise invalid.
115  
116 =cut
117  
118 11 ▶sub consume_headers {
Subroutine consume_headers: called CC=3 SCAR=11.0
Pod documented
119 11 my ($self, @kv_pairs) = @_;
120  
121 11 $self->{'_no_use_legacy'} = 1;
122  
123 11 ▶ while ( my ($k => $v) = splice( @kv_pairs, 0, 2 ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = splice(@kv_pairs, 0, 2)) 36 6 42
124 36 ▶ next if !defined $v;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $v 0 36 36
125 36 $self->_consume_peer_header($k => $v);
126 }
127  
128 6 $self->_die_if_missing_headers();
129  
130 5 return;
131 }
132  
133 =head2 my $hdrs_txt = I<OBJ>->to_string( %OPTS )
134  
135 The text of the HTTP headers to send, with the 2nd trailing CR/LF
136 that ends the headers portion of an HTTP message.
137  
138 If you use this object
139 to negotiate a subprotocol and/or extensions, those will be included
140 in the output from this method.
141  
142 %OPTS can be:
143  
144 =over
145  
146 =item * C<headers> - an array reference of key/value pairs. For example:
147  
148 [
149 Authorization => 'Basic Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==',
150 'X-Custom' => 'some value',
151 ]
152  
153 =back
154  
155 =cut
156  
157 5 ▶sub to_string {
Subroutine to_string: called CC=3 SCAR=15.0
Pod documented
158 5 my ($self, %opts) = @_;
159  
160 5 my @extra_lines;
161  
162 5 ▶ if (my $hdrs_ar = $opts{'headers'}) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $hdrs_ar = $opts{"headers"}) 0 5 5
163 0 $hdrs_ar = [ @$hdrs_ar ];
164  
165 0 ▶ while ( my ($key, $val) = splice( @$hdrs_ar, 0, 2 ) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = splice(@$hdrs_ar, 0, 2)) 0 0 0
166 0 push @extra_lines, "$key: $val";
167 }
168 }
169  
170 5 return join(
171 CRLF(),
172 $self->_create_header_lines(),
173 @extra_lines,
174 q<>, q<>,
175 );
176 }
177  
178 =head1 LEGACY INTERFACE
179  
180 Prior to version 0.5 this module was a great deal less “helpful”:
181 it required callers to parse out and write WebSocket headers,
182 doing most of the validation manually. Version 0.5 added a generic
183 interface for entering in HTTP headers, which allows Net::WebSocket to
184 handle the parsing and creation of HTTP headers as well as subprotocol
185 and extension negotiation.
186  
187 For now the legacy functionality is being left in; however,
188 it is considered DEPRECATED and will be removed eventually.
189  
190 =head2 my $hdrs_txt = I<OBJ>->create_header_text()
191  
192 The same output as C<to_string()> but minus the 2nd trailing
193 CR/LF. (This was intended to facilitate adding other headers; however,
194 that’s done easily enough with the newer C<to_string()>.)
195  
196 =cut
197  
198 0 ▶sub create_header_text {
Subroutine create_header_text: not called CC=1 SCAR=6.9
Pod documented
199 0 my $self = shift;
200  
201 0 return join( CRLF(), $self->_create_header_lines(), q<> );
202 }
203  
204 =head1 SEE ALSO
205  
206 =over
207  
208 =item * L<Net::WebSocket::Handshake::Client>
209  
210 =item * L<Net::WebSocket::Handshake::Server>
211  
212 =back
213  
214 =cut
215  
216 #----------------------------------------------------------------------
217  
218 5 ▶sub _get_accept {
Subroutine _get_accept: called CC=2 SCAR=7.1
219 5 my ($self) = @_;
220  
221 5 ▶ my $key_b64 = $self->{'key'} or do {
Branch: 1 branch
BranchTrueFalseTotal
my $key_b64 = $self->{"key"} or do { die "Net::WebSocket::X"->create("BadArg", "key", $self->{"key"}) } 5 0 5
222 0 die Net::WebSocket::X->create('BadArg', key => $self->{'key'});
223 };
224  
225 5 $key_b64 =~ s<\A\s+|\s+\z><>g;
226  
227 5 my $accept = Digest::SHA1::sha1_base64( $key_b64 . _WS_MAGIC_CONSTANT() );
228  
229 #pad base64
230 5 $accept .= '=' x (4 - (length($accept) % 4));
231  
232 5 return $accept;
233 }
234  
235 #Post-legacy, move this to Client and have the Server use logic
236 #that allows only one.
237 5 ▶sub _encode_subprotocols {
Subroutine _encode_subprotocols: called CC=3 SCAR=11.0
238 5 my ($self) = @_;
239  
240 3 return ( $self->{'subprotocols'} && @{ $self->{'subprotocols'} }
241 5 ▶ ? ( 'Sec-WebSocket-Protocol: ' . join(', ', @{ $self->{'subprotocols'} } ) )
Branch: 1 branch
BranchTrueFalseTotal
$self->{'subprotocols'} && @{$self->{'subprotocols'};} ? : 3 2 5
Condition66%2/3
$self->{"subprotocols"} and @{$self->{"subprotocols"};}
!ll&&!rl&&r
203
MC/DC50%1/2
$self->{"subprotocols"} and @{$self->{"subprotocols"};}
$self->{"subprotocols"} @{$self->{"subprotocols"};}
Truth table66%2/3
A and B
A= $self->{"subprotocols"}B= @{$self->{"subprotocols"};}
ABresult
0X0
100
111
242 : ()
243 );
244 }
245  
246 5 ▶sub _encode_extensions {
Subroutine _encode_extensions: called CC=6 SCAR=18.8
247 5 my ($self) = @_;
248  
249 5 ▶ return if !$self->{'extensions'};
Branch: 1 branch
BranchTrueFalseTotal
unless $self->{"extensions"} 4 1 5
250  
251 1 my @handshake_xtns;
252 1 for my $xtn ( @{ $self->{'extensions'} } ) {
253 2 ▶ if ( $xtn->isa('Net::WebSocket::Handshake::Extension') ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($xtn->isa('Net::WebSocket::Handshake::Extension')) { } 2 0 2
elsif ($self->_should_include_extension_in_headers($xtn)) { } 0 0 0
254 2 $self->_warn_legacy();
255 2 push @handshake_xtns, $xtn;
256 }
257 elsif ( $self->_should_include_extension_in_headers($xtn) ) {
258 0 push @handshake_xtns, $xtn->get_handshake_object();
259 }
260 }
261  
262 1 ▶ return if !@handshake_xtns;
Branch: 1 branch
BranchTrueFalseTotal
unless @handshake_xtns 0 1 1
263  
264 1 my ($first, @others) = @handshake_xtns;
265  
266 1 return 'Sec-WebSocket-Extensions: ' . $first->to_string(@others);
267 }
268  
269 2 ▶sub _warn_legacy {
Subroutine _warn_legacy: called CC=2 SCAR=6.9
270 2 my ($self) = @_;
271  
272 2 ▶ if (!$self->{'_warned_legacy'}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->{"_warned_legacy"}) 1 1 2
273 1 my $ref = ref $self;
274 1 warn "You are using $ref’s legacy interface. This interface will eventually be removed from $ref entirely, so please update your application to the newer interface. (The update should simplify your code.)";
275  
276 1 $self->{'_warned_legacy'}++;
277 }
278  
279 2 return;
280 }
281  
282 6 ▶sub _missing_generic_headers {
Subroutine _missing_generic_headers: called CC=3 SCAR=11.0
283 6 my ($self) = @_;
284  
285 6 my @missing;
286 6 ▶ push @missing, 'Connection' if !$self->{'_connection_header_ok'};
Branch: 1 branch
BranchTrueFalseTotal
unless $self->{"_connection_header_ok"} 1 5 6
287 6 ▶ push @missing, 'Upgrade' if !$self->{'_upgrade_header_ok'};
Branch: 1 branch
BranchTrueFalseTotal
unless $self->{"_upgrade_header_ok"} 1 5 6
288  
289 6 return @missing;
290 }
291  
292 0 ▶sub _consume_sec_websocket_extensions_header {
Subroutine _consume_sec_websocket_extensions_header: not called CC=4 SCAR=30.0
293 0 my ($self, $value) = @_;
294  
295 0 require Net::WebSocket::Handshake::Extension;
296  
297 0 for my $xtn ( Net::WebSocket::Handshake::Extension->parse_string($value) ) {
298 0 my $xtn_token = $xtn->token();
299 0 my $xtn_handler = $self->{'_extension_tokens'}{ $xtn_token };
300 0 ▶ if ($xtn_handler) {
Branch: 1 branch
BranchTrueFalseTotal
if ($xtn_handler) { } 0 0 0
301 0 $xtn_handler->consume_parameters($xtn->parameters());
302  
303 0 ▶ if ($xtn_handler->ok_to_use()) {
Branch: 1 branch
BranchTrueFalseTotal
if ($xtn_handler->ok_to_use) 0 0 0
304 0 $self->{'_match_extensions'}{ $xtn_token } = $xtn_handler;
305 }
306 }
307 else {
308 0 $self->_handle_unrecognized_extension($xtn);
309 }
310 }
311  
312 0 return;
313 }
314  
315 18 ▶sub _consume_generic_header {
Subroutine _consume_generic_header: called CC=14 SCAR=28.4
316 18 my ($self, $hname, $value) = @_;
317  
318 18 tr<A-Z><a-z> for ($hname);
319  
320 18 ▶ if ($hname eq 'connection') {
Branch: 4 branches
BranchTrueFalseTotal
if ($hname eq 'connection') { } 9 9 18
elsif ($hname eq 'upgrade') { } 8 1 9
elsif ($hname eq 'sec-websocket-protocol') { } 0 1 1
elsif ($hname eq 'sec-websocket-extensions') { } 0 1 1
321 9 $value =~ tr<A-Z><a-z>;
322 9 for my $t ( Net::WebSocket::HTTP::split_tokens($value) ) {
323 9 ▶ if ($t eq 'upgrade') {
Branch: 1 branch
BranchTrueFalseTotal
if ($t eq "upgrade") 8 1 9
324 8 $self->{'_connection_header_ok'} = 1;
325 }
326 }
327  
328 9 ▶ if (!$self->{'_connection_header_ok'}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->{"_connection_header_ok"}) 1 8 9
329 1 die Net::WebSocket::X->create('BadHeader', 'Connection' => $value, 'Must contain “upgrade”');
330 }
331 }
332 elsif ($hname eq 'upgrade') {
333 8 $value =~ tr<A-Z><a-z>;
334 8 for my $t ( Net::WebSocket::HTTP::split_tokens($value) ) {
335 8 ▶ if ($t eq 'websocket') {
Branch: 1 branch
BranchTrueFalseTotal
if ($t eq "websocket") 7 1 8
336 7 $self->{'_upgrade_header_ok'} = 1;
337 }
338 }
339  
340 8 ▶ if (!$self->{'_upgrade_header_ok'}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->{"_upgrade_header_ok"}) 1 7 8
341 1 die Net::WebSocket::X->create('BadHeader', 'Upgrade' => $value, 'Must contain “websocket”');
342 }
343 }
344 elsif ($hname eq 'sec-websocket-protocol') {
345 0 for my $token ( Net::WebSocket::HTTP::split_tokens($value) ) {
346 0 ▶ if (!defined $self->{'_match_protocol'}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $self->{"_match_protocol"}) 0 0 0
347 0 ($self->{'_match_protocol'}) = grep { $_ eq $token } @{ $self->{'subprotocols'} };
348 }
349 }
350 }
351 elsif ($hname eq 'sec-websocket-extensions') {
352 0 $self->_consume_sec_websocket_extensions_header($value);
353 }
354  
355 16 return;
356 }
357  
358 5 1;
« WebSocket/Frame/close.pm ↑ Summary WebSocket/Frame.pm »