WebSocket/Parser.pm

filter: Statementstmt 92.3% 85 / 92 Branchbran 78.0% 39 / 50 Conditioncond 80.0% 4 / 5 MC/DCmcdc 33.3% 1 / 3 Subroutinesub 100% 10 / 10 Podpod 50.0% 1 / 2 totaltotal 86.4% 140 / 162 CC 30 SCAR 27.8
CC
30
Cov
87%
get_next_frame
25.5
_append_chunk
4.0
_read_with_buffer
4.0
CRAP 16.1
↑ Summary WebSocket/X/ReceivedClose.pm »
1 package Net::WebSocket::Parser;
2  
3 =encoding utf-8
4  
5 =head1 NAME
6  
7 Net::WebSocket::Parser - Parse WebSocket from a filehandle
8  
9 =head1 SYNOPSIS
10  
11 my $iof = IO::Framed->new($fh);
12  
13 my $parse = Net::WebSocket::Parser->new($iof);
14  
15 #See below for error responses
16 my $frame = $parse->get_next_frame();
17  
18 C<$iof> should normally be an instance of L<IO::Framed::Read>. You’re free to
19 pass in anything with a C<read()> method, but that method must implement
20 the same behavior as C<IO::Framed::Read::read()>.
21  
22 =head1 METHODS
23  
24 =head2 I<OBJ>->get_next_frame()
25  
26 A call to this method yields one of the following:
27  
28 =over
29  
30 =item * If a frame can be read, it will be returned.
31  
32 =item * If we hit an empty read (i.e., indicative of end-of-file),
33 empty string is returned.
34  
35 =item * If only a partial frame is ready, undef is returned.
36  
37 =back
38  
39 =head1 I/O DETAILS
40  
41 L<IO::Framed> was born out of work on this module; see that module’s
42 documentation for the particulars of working with it. In particular,
43 note the exceptions L<IO::Framed::X::EmptyRead> and
44 L<IO::Framed::X::ReadError>.
45  
46 Again, you can use an equivalent interface for frame chunking if you wish.
47  
48 =head1 CONCERNING EMPTY READS
49  
50 An empty read is how we detect that a file handle (or socket, etc.) has no
51 more data to read. Generally we shouldn’t get this in WebSocket since it
52 means that a peer endpoint has gone away without sending a close frame.
53 It is thus recommended that applications regard an empty read on a WebSocket
54 stream as an error condition; e.g., if you’re using L<IO::Framed::Read>,
55 you should NOT enable the C<allow_empty_read()> behavior.
56  
57 Nevertheless, this module (and L<Net::WebSocket::Endpoint>) do work when
58 that flag is enabled.
59  
60 =head1 CUSTOM FRAMES SUPPORT
61  
62 To support reception of custom frame types you’ll probably want to subclass
63 this module and define a specific custom constant for each supported opcode,
64 e.g.:
65  
66 package My::WebSocket::Parser;
67  
68 use parent qw( Net::WebSocket::Parser );
69  
70 use constant OPCODE_CLASS_3 => 'My::WebSocket::Frame::booya';
71  
72 … where C<My::WebSocket::Frame::booya> is itself a subclass of
73 C<Net::WebSocket::Base::DataFrame>.
74  
75 You can also use this to override the default
76 classes for built-in frame types; e.g., C<OPCODE_CLASS_10()> will override
77 L<Net::WebSocket::Frame::pong> as the class will be used for pong frames
78 that this module receives. That could be useful, e.g., for compression
79 extensions, where you might want the C<get_payload()> method to
80 decompress so that that detail is abstracted away.
81  
82 =cut
83  
84 16 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
85 16 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
86  
87 16 ▶use Module::Runtime ();
Subroutine BEGIN: called CC=1 SCAR=0.0
88  
89 16 ▶use Net::WebSocket::Constants ();
Subroutine BEGIN: called CC=1 SCAR=0.0
90 16 ▶use Net::WebSocket::X ();
Subroutine BEGIN: called CC=1 SCAR=0.0
91  
92 16 ▶use constant {
Subroutine BEGIN: called CC=1 SCAR=0.0
93 16 OPCODE_CLASS_0 => 'Net::WebSocket::Frame::continuation',
94 OPCODE_CLASS_1 => 'Net::WebSocket::Frame::text',
95 OPCODE_CLASS_2 => 'Net::WebSocket::Frame::binary',
96 OPCODE_CLASS_8 => 'Net::WebSocket::Frame::close',
97 OPCODE_CLASS_9 => 'Net::WebSocket::Frame::ping',
98 OPCODE_CLASS_10 => 'Net::WebSocket::Frame::pong',
99 16 };
100  
101 40 ▶sub new {
Subroutine new: called CC=2 SCAR=7.6
Pod undocumented
102 40 my ($class, $reader) = @_;
103  
104 40 ▶ if (!(ref $reader)->can('read')) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref($reader)->can("read")) 0 40 40
105 0 die "“$reader” needs a read() method!";
106 }
107  
108 40 return bless {
109 _reader => $reader,
110 _partial_frame => q<>,
111 }, $class;
112 }
113  
114 #Create these out here so that we don’t create/destroy them on each frame.
115 #As long as we don’t access them prior to writing to them this is fine.
116 16 my ($oct1, $oct2, $len, $mask_size, $len_len, $longs, $long);
117  
118 65936 ▶sub get_next_frame {
Subroutine get_next_frame: called CC=23 SCAR=32.4
Pod documented
119 65936 my ($self) = @_;
120  
121 65936 local $@;
122  
123 #It is really, really inconvenient that Perl has no “or” operator
124 #that considers q<> falsey but '0' truthy. :-/
125 #That aside, if indeed all we read is '0', then we know that’s not
126 #enough, and we can return.
127 65936 my $first2 = $self->_read_with_buffer(2);
128 65936 ▶ if (!$first2) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($first2) 7 65929 65936
129 7 ▶ return defined($first2) ? q<> : undef;
Branch: 1 branch
BranchTrueFalseTotal
defined $first2 ? : 3 4 7
130 }
131  
132 65929 ($oct1, $oct2) = unpack('CC', $first2 );
133  
134 65929 $len = $oct2 & 0x7f;
135  
136 65929 ▶ $mask_size = ($oct2 & 0x80) && 4;
Condition100%2/2
$oct2 & 128 && 4
!ll
6585772
MC/DC100%1/1
$oct2 & 128 && 4
$oct2 & 128
Truth table100%2/2
A
A= $oct2 & 128
Aresult
00
11
137  
138 65929 ▶ $len_len = ($len == 0x7e) ? 2 : ($len == 0x7f) ? 8 : 0;
Branch: 2 branches
BranchTrueFalseTotal
$len == 126 ? : 261 65668 65929
$len == 127 ? : 65549 119 65668
139  
140 65929 my ($len_buf, $mask_buf);
141  
142 65929 ▶ if ($len_len) {
Branch: 1 branch
BranchTrueFalseTotal
if ($len_len) { } 65810 119 65929
143 65810 $len_buf = $self->_read_with_buffer($len_len);
144  
145 65810 ▶ if (!$len_buf) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($len_buf) 10 65800 65810
146 10 substr( $self->{'_partial_frame'}, 0, 0, $first2 );
147 10 ▶ return defined($len_buf) ? q<> : undef;
Branch: 1 branch
BranchTrueFalseTotal
defined $len_buf ? : 0 10 10
148 };
149  
150 65800 ▶ if ($len_len == 2) {
Branch: 1 branch
BranchTrueFalseTotal
if ($len_len == 2) { } 259 65541 65800
151 259 ($longs, $long) = ( 0, unpack('n', $len_buf) );
152 }
153 else {
154  
155 #Do it this way to support 32-bit systems.
156 65541 ($longs, $long) = ( unpack('NN', $len_buf) );
157 }
158 }
159 else {
160 119 ($longs, $long) = ( 0, $len );
161 119 $len_buf = q<>;
162 }
163  
164 65919 ▶ if ($mask_size) {
Branch: 1 branch
BranchTrueFalseTotal
if ($mask_size) { } 72 65847 65919
165 72 $mask_buf = $self->_read_with_buffer($mask_size);
166 72 ▶ if (!$mask_buf) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($mask_buf) 4 68 72
167 4 substr( $self->{'_partial_frame'}, 0, 0, $first2 . $len_buf );
168 4 ▶ return defined($mask_buf) ? q<> : undef;
Branch: 1 branch
BranchTrueFalseTotal
defined $mask_buf ? : 0 4 4
169 };
170 }
171 else {
172 65847 $mask_buf = q<>;
173 }
174  
175 65915 my $payload = q<>;
176  
177 65915 for ( 1 .. $longs ) {
178  
179 #32-bit systems don’t know what 2**32 is.
180 #MacOS, at least, also chokes on sysread( 2**31, … )
181 #(Is their size_t signed??), even on 64-bit.
182 0 for ( 1 .. 4 ) {
183 0 my $append_ok = $self->_append_chunk( 2**30, \$payload );
184 0 ▶ if (!$append_ok) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($append_ok) 0 0 0
185 0 substr( $self->{'_partial_frame'}, 0, 0, $first2 . $len_buf . $mask_buf . $payload );
186 0 ▶ return defined($append_ok) ? q<> : undef;
Branch: 1 branch
BranchTrueFalseTotal
defined $append_ok ? : 0 0 0
187 };
188 }
189 }
190  
191 65915 ▶ if ($long) {
Branch: 1 branch
BranchTrueFalseTotal
if ($long) 65905 10 65915
192 65905 my $append_ok = $self->_append_chunk( $long, \$payload );
193 65905 ▶ if (!$append_ok) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($append_ok) 65806 99 65905
194 65806 substr( $self->{'_partial_frame'}, 0, 0, $first2 . $len_buf . $mask_buf . $payload );
195 65806 ▶ return defined($append_ok) ? q<> : undef;
Branch: 1 branch
BranchTrueFalseTotal
defined $append_ok ? : 0 65806 65806
196 }
197 }
198  
199 109 $self->{'_partial_frame'} = q<>;
200  
201 109 my $opcode = $oct1 & 0xf;
202  
203 109 ▶ my $frame_class = $self->{'_opcode_class'}{$opcode} ||= do {
Condition66%2/3
$self->{"_opcode_class"}{$opcode} ||= do { my $class; if (my $cr = $self->can("OPCODE_CLASS_$opcode")) { $class = &$cr(); } else { die "${self}: Unrecognized frame opcode: \342\200\234$opcode\342\200\235"; } ; &Module::Runtime::require_module($class) unless $class->can("new"); $class }
l!l&&r!l&&!r
63460
MC/DC0%0/2
$self->{"_opcode_class"}{$opcode} ||= do { my $class; if (my $cr = $self->can("OPCODE_CLASS_$opcode")) { $class = &$cr(); } else { die "${self}: Unrecognized frame opcode: \342\200\234$opcode\342\200\235"; } ; &Module::Runtime::require_module($class) unless $class->can("new"); $class }
$self->{"_opcode_class"}{$opcode} do { my $class; if (my $cr = $self->can("OPCODE_CLASS_$opcode")) { $class = &$cr(); } else { die "${self}: Unrecognized frame opcode: \342\200\234$opcode\342\200\235"; } ; &Module::Runtime::require_module($class) unless $class->can("new"); $class }
Truth table66%2/3
A ||= B
A= $self->{"_opcode_class"}{$opcode}B= do { my $class; if (my $cr = $self->can("OPCODE_CLASS_$opcode")) { $class = &$cr(); } else { die "${self}: Unrecognized frame opcode: \342\200\234$opcode\342\200\235"; } ; &Module::Runtime::require_module($class) unless $class->can("new"); $class }
ABresult
1X1
011
000
204 46 my $class;
205 46 ▶ if (my $cr = $self->can("OPCODE_CLASS_$opcode")) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $cr = $self->can("OPCODE_CLASS_$opcode")) { } 46 0 46
206 46 $class = $cr->();
207 }
208 else {
209  
210 #Untyped because this is a coding error.
211 0 die "$self: Unrecognized frame opcode: “$opcode”";
212 }
213  
214 46 ▶ Module::Runtime::require_module($class) if !$class->can('new');
Branch: 1 branch
BranchTrueFalseTotal
unless $class->can("new") 8 38 46
215  
216 46 $class;
217 };
218  
219 109 return $frame_class->create_from_parse(\$first2, \$len_buf, \$mask_buf, \$payload);
220 }
221  
222 # This will only return exactly the number of bytes requested.
223 # If fewer than we want are available, then we return undef.
224 # This incorporates the partial-frame buffer, which keeps get_next_frame()
225 # a bit simpler than it otherwise might be.
226 #
227 197723 ▶sub _read_with_buffer {
Subroutine _read_with_buffer: called CC=4 SCAR=13.9
228 197723 my ($self, $length) = @_;
229  
230 # Prioritize the case where we have everything we need.
231 # This will happen if, e.g., we got a partial frame on first read
232 # and a subsequent read has to pick back up.
233  
234 197723 ▶ if ( length($self->{'_partial_frame'}) < $length ) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $self->{"_partial_frame"} < $length) 66104 131619 197723
235 66104 my $deficit = $length - length($self->{'_partial_frame'});
236 66104 my $read = $self->{'_reader'}->read($deficit);
237  
238 66104 ▶ if (!defined $read) {
Branch: 2 branches
BranchTrueFalseTotal
if (not defined $read) { } 65824 280 66104
elsif (not length $read) { } 3 277 280
239 65824 return undef;
240 }
241 elsif (!length $read) {
242 3 return q<>;
243 }
244  
245 277 return substr($self->{'_partial_frame'}, 0, length($self->{'_partial_frame'}), q<>) . $read;
246 }
247  
248 131619 return substr( $self->{'_partial_frame'}, 0, $length, q<> );
249 }
250  
251 65905 ▶sub _append_chunk {
Subroutine _append_chunk: called CC=4 SCAR=13.9
252 65905 my ($self, $length, $buf_sr) = @_;
253  
254 65905 my $start_buf_len = length $$buf_sr;
255  
256 65905 my $cur_buf;
257  
258 65905 while (1) {
259 65905 my $read_so_far = length($$buf_sr) - $start_buf_len;
260  
261 65905 $cur_buf = $self->_read_with_buffer($length - $read_so_far);
262 65905 ▶ return undef if !defined $cur_buf;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $cur_buf 65806 99 65905
263  
264 99 ▶ return q<> if !length $cur_buf;
Branch: 1 branch
BranchTrueFalseTotal
unless length $cur_buf 0 99 99
265  
266 99 $$buf_sr .= $cur_buf;
267  
268 99 ▶ last if (length($$buf_sr) - $start_buf_len) >= $length;
Branch: 1 branch
BranchTrueFalseTotal
if length($$buf_sr) - $start_buf_len >= $length 99 0 99
269 }
270  
271 99 return 1;
272 }
273  
274 16 1;
↑ Summary WebSocket/X/ReceivedClose.pm »