| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 129 | 7 | ▶ | return defined($first2) ? q<> : undef; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 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
MC/DC100%1/1
$oct2 & 128 && 4
$oct2 & 128
Truth table100%2/2
A
A= $oct2 & 128
| |||||||||||||||||||||
| 137 | |||||||||||||||||||||
| 138 | 65929 | ▶ | $len_len = ($len == 0x7e) ? 2 : ($len == 0x7f) ? 8 : 0; | ||||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||||
| 139 | |||||||||||||||||||||
| 140 | 65929 | my ($len_buf, $mask_buf); | |||||||||||||||||||
| 141 | |||||||||||||||||||||
| 142 | 65929 | ▶ | if ($len_len) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 143 | 65810 | $len_buf = $self->_read_with_buffer($len_len); | |||||||||||||||||||
| 144 | |||||||||||||||||||||
| 145 | 65810 | ▶ | if (!$len_buf) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 146 | 10 | substr( $self->{'_partial_frame'}, 0, 0, $first2 ); | |||||||||||||||||||
| 147 | 10 | ▶ | return defined($len_buf) ? q<> : undef; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 148 | }; | ||||||||||||||||||||
| 149 | |||||||||||||||||||||
| 150 | 65800 | ▶ | if ($len_len == 2) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 165 | 72 | $mask_buf = $self->_read_with_buffer($mask_size); | |||||||||||||||||||
| 166 | 72 | ▶ | if (!$mask_buf) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 167 | 4 | substr( $self->{'_partial_frame'}, 0, 0, $first2 . $len_buf ); | |||||||||||||||||||
| 168 | 4 | ▶ | return defined($mask_buf) ? q<> : undef; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 187 | }; | ||||||||||||||||||||
| 188 | } | ||||||||||||||||||||
| 189 | } | ||||||||||||||||||||
| 190 | |||||||||||||||||||||
| 191 | 65915 | ▶ | if ($long) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 192 | 65905 | my $append_ok = $self->_append_chunk( $long, \$payload ); | |||||||||||||||||||
| 193 | 65905 | ▶ | if (!$append_ok) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
}
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
}
| |||||||||||||||||||||
| 204 | 46 | my $class; | |||||||||||||||||||
| 205 | 46 | ▶ | if (my $cr = $self->can("OPCODE_CLASS_$opcode")) { | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 263 | |||||||||||||||||||||
| 264 | 99 | ▶ | return q<> if !length $cur_buf; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 265 | |||||||||||||||||||||
| 266 | 99 | $$buf_sr .= $cur_buf; | |||||||||||||||||||
| 267 | |||||||||||||||||||||
| 268 | 99 | ▶ | last if (length($$buf_sr) - $start_buf_len) >= $length; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 269 | } | ||||||||||||||||||||
| 270 | |||||||||||||||||||||
| 271 | 99 | return 1; | |||||||||||||||||||
| 272 | } | ||||||||||||||||||||
| 273 | |||||||||||||||||||||
| 274 | 16 | 1; | |||||||||||||||||||