WebSocket/Frame.pm

filter: Statementstmt 88.0% 96 / 109 Branchbran 77.7% 28 / 36 Conditioncond 80.0% 4 / 5 MC/DCmcdc 66.6% 2 / 3 Subroutinesub 87.5% 21 / 24 Podpod 0.0% 0 / 14 totaltotal 79.0% 151 / 191 CC 21 SCAR 20.6
CC
21
Cov
85%
new
17.9
_validate_mask
3.6
set_rsv
2.0
CRAP 7.9
« WebSocket/Handshake.pm ↑ Summary WebSocket/Defragmenter.pm »
1 package Net::WebSocket::Frame;
2  
3 =encoding utf-8
4  
5 =head1 NAME
6  
7 Net::WebSocket::Frame
8  
9 =head1 SYNOPSIS
10  
11 #Never instantiate Net::WebSocket::Frame directly;
12 #always call new() on a subclass:
13 my $frame = Net::WebSocket::Frame::text->new(
14 fin => 0, #to start a fragmented message
15 rsv => 0b11, #RSV2 and RSV3 are on
16 mask => "\x01\x02\x03\x04 #clients MUST include; servers MUST NOT
17 payload => \'Woot!',
18 );
19  
20 $frame->get_fin();
21 $frame->get_mask_bytes();
22 $frame->get_payload();
23  
24 $frame->set_rsv();
25 $frame->get_rsv();
26  
27 $frame->to_bytes(); #for sending over the wire
28  
29 =head1 DESCRIPTION
30  
31 This is the base class for all frame objects. The interface as described
32 above should be fairly straightforward.
33  
34 =head1 EXPERIMENTAL: CUSTOM FRAME CLASSES
35  
36 You can have custom frame classes, e.g., to support WebSocket extensions that
37 use custom frame opcodes. RFC 6455 allocates opcodes 3-7 for data frames and
38 11-15 (0xb - 0xf) for control frames.
39  
40 The best way to do this is to subclass either
41 L<Net::WebSocket::Base::DataFrame> or L<Net::WebSocket::Base::ControlFrame>,
42 depending on what kind of frame you’re dealing with.
43  
44 An example of such a class is below:
45  
46 package My::Custom::Frame::booya;
47  
48 use strict;
49 use warnings;
50  
51 use parent qw( Net::WebSocket::Base::DataFrame );
52  
53 use constant get_opcode => 3;
54  
55 use constant get_type => 'booya';
56  
57 Note that L<Net::WebSocket::Parser> still won’t know how to handle such a
58 custom frame, so if you intend to receive custom frames as part of messages,
59 you’ll also need to create a custom base class of this class, then also
60 subclass L<Net::WebSocket::Parser>. You may additionally want to subclass
61 L<Net::WebSocket::Streamer::Server> (or -C<::Client>) if you do streaming.
62  
63 B<NOTE: THIS IS LARGELY UNTESTED.> I’m not familiar with any application that
64 actually requires this feature. The C<permessage-deflate> extension seems to
65 be the only one that has much widespread web browser support.
66  
67 =cut
68  
69 24 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
70 24 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
71  
72 24 ▶use parent qw(
Subroutine BEGIN: called CC=1 SCAR=0.0
73 Net::WebSocket::Base::Typed
74 24 );
75  
76 24 ▶use Net::WebSocket::Constants ();
Subroutine BEGIN: called CC=1 SCAR=0.0
77 24 ▶use Net::WebSocket::Mask ();
Subroutine BEGIN: called CC=1 SCAR=0.0
78 24 ▶use Net::WebSocket::X ();
Subroutine BEGIN: called CC=1 SCAR=0.0
79  
80 24 ▶use constant {
Subroutine BEGIN: called CC=1 SCAR=0.0
81 24 FIRST2 => 0,
82 LEN_LEN => 1,
83 MASK => 2,
84 PAYLOAD => 3,
85  
86 _RSV1 => chr(4 << 4),
87 _RSV2 => chr(2 << 4),
88 _RSV3 => chr(1 << 4),
89 24 };
90  
91 #fin, rsv, mask, payload
92 #rsv is a bitmask of the three values, with RSV1 as MOST significant bit.
93 #So, represent RSV1 and RSV2 being on via 0b110 (= 4 + 2 = 6)
94 140 ▶sub new {
Subroutine new: called CC=17 SCAR=28.8
Pod undocumented
95 140 my $class = shift;
96  
97 140 my ( $fin, $rsv, $mask, $payload_sr );
98  
99 #We loop through like this so that we can get a nice
100 #syntax for “payload” without copying the string.
101 #This logic should be equivalent to a hash.
102 140 ▶ while (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 320 140 460
103 320 my $key = shift;
104  
105 #“payload_sr” (as a named argument) is legacy
106 320 ▶ if ($key eq 'payload' || $key eq 'payload_sr') {
Branch: 4 branches
BranchTrueFalseTotal
if ($key eq 'payload' or $key eq 'payload_sr') { } 138 182 320
elsif ($key eq 'fin') { } 121 61 182
elsif ($key eq 'rsv') { } 6 55 61
elsif ($key eq 'mask') { } 55 0 55
Condition66%2/3
$key eq "payload" or $key eq "payload_sr"
l!l&&r!l&&!r
1380182
MC/DC50%1/2
$key eq "payload" or $key eq "payload_sr"
$key eq "payload" $key eq "payload_sr"
Truth table66%2/3
A or B
A= $key eq "payload"B= $key eq "payload_sr"
ABresult
1X1
011
000
107 138 ▶ if (!ref $_[0]) {
Branch: 2 branches
BranchTrueFalseTotal
if (not ref $_[0]) { } 79 59 138
elsif ('SCALAR' eq ref $_[0]) { } 59 0 59
108 79 ▶ if (defined $_[0]) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $_[0]) { } 79 0 79
109 79 $payload_sr = \shift;
110 }
111 else {
112 0 shift;
113 0 next;
114 }
115 }
116 elsif ('SCALAR' eq ref $_[0]) {
117 59 $payload_sr = shift;
118 }
119 else {
120 0 die Net::WebSocket::X->create('BadArg', $key => shift, 'Must be a scalar or SCALAR reference.');
121 }
122 }
123 elsif ($key eq 'fin') {
124 121 $fin = shift;
125 }
126 elsif ($key eq 'rsv') {
127 6 $rsv = shift;
128 }
129 elsif ($key eq 'mask') {
130 55 $mask = shift;
131 }
132 else {
133 0 warn sprintf("Unrecognized argument “%s” (%s)", $key, shift);
134 }
135 }
136  
137 140 my $type = $class->get_type();
138  
139 140 my $opcode = $class->get_opcode($type);
140  
141 140 ▶ if (!defined $fin) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $fin) 19 121 140
142 19 $fin = 1;
143 }
144  
145 140 ▶ $payload_sr ||= \do { my $v = q<> };
Condition100%2/2
$payload_sr ||= \do { my $v = "" }
l!l
1382
MC/DC100%1/1
$payload_sr ||= \do { my $v = "" }
$payload_sr
Truth table100%2/2
A
A= $payload_sr
Aresult
11
00
146  
147 140 my ($byte2, $len_len) = $class->_assemble_length($payload_sr);
148  
149 140 ▶ if (defined $mask) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $mask) { } 55 85 140
150 55 _validate_mask($mask);
151  
152 55 ▶ if (length $mask) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $mask) 55 0 55
153 55 $byte2 |= "\x80";
154 55 Net::WebSocket::Mask::apply($payload_sr, $mask);
155 }
156 }
157 else {
158 85 $mask = q<>;
159 }
160  
161 140 my $first2 = chr $opcode;
162 140 ▶ $first2 |= "\x80" if $fin;
Branch: 1 branch
BranchTrueFalseTotal
if $fin 101 39 140
163  
164 140 ▶ if ($rsv) {
Branch: 1 branch
BranchTrueFalseTotal
if ($rsv) 5 135 140
165 5 ▶ die "“rsv” must be < 0-7!" if $rsv > 7;
Branch: 1 branch
BranchTrueFalseTotal
if $rsv > 7 0 5 5
166 5 $first2 |= chr( $rsv << 4 );
167 }
168  
169 140 substr( $first2, 1, 0, $byte2 );
170  
171 140 return bless [ \$first2, \$len_len, \$mask, $payload_sr ], $class;
172 }
173  
174 # All string refs: first2, length octets, mask octets, payload
175 109 ▶sub create_from_parse {
Subroutine create_from_parse: called CC=1 SCAR=0.0
Pod undocumented
176 109 return bless \@_, shift;
177 }
178  
179 148 ▶sub get_mask_bytes {
Subroutine get_mask_bytes: called CC=1 SCAR=0.0
Pod undocumented
180 148 my ($self) = @_;
181  
182 148 return ${ $self->[MASK] };
183 }
184  
185 #To collect the goods
186 142 ▶sub get_payload {
Subroutine get_payload: called CC=2 SCAR=6.9
Pod undocumented
187 142 my ($self) = @_;
188  
189 142 my $pl = "" . ${ $self->[PAYLOAD] };
190  
191 142 ▶ if (my $mask = $self->get_mask_bytes()) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $mask = $self->get_mask_bytes) 60 82 142
192 60 Net::WebSocket::Mask::apply( \$pl, $mask );
193 }
194  
195 142 return $pl;
196 }
197  
198 #For sending over the wire
199 107 ▶sub to_bytes {
Subroutine to_bytes: called CC=1 SCAR=0.0
Pod undocumented
200 107 my ($self) = @_;
201  
202 107 return join( q<>, map { $$_ } @$self );
203 }
204  
205 9 ▶sub get_rsv {
Subroutine get_rsv: called CC=1 SCAR=0.0
Pod undocumented
206 9 my ($self) = @_;
207  
208 #0b01110000 = 0x70
209 9 return( ord( substr( ${ $self->[FIRST2] }, 0, 1 ) & "\x70" ) >> 4 );
210 }
211  
212 24 my $rsv;
213 10 ▶sub set_rsv {
Subroutine set_rsv: called CC=2 SCAR=7.0
Pod undocumented
214 10 $rsv = $_[1];
215  
216 #Consider the first byte as a vector of 4-bit segments.
217  
218 10 ▶ $rsv |= 8 if substr( ${ $_[0]->[FIRST2] }, 0, 1 ) & "\x80";
Branch: 1 branch
BranchTrueFalseTotal
if substr(${$_[0][0];}, 0, 1) & "\200" 10 0 10
219  
220 10 vec( substr( ${ $_[0]->[FIRST2] }, 0, 1 ), 1, 4 ) = $rsv;
221  
222 10 return $_[0];
223 }
224  
225 1 ▶sub set_rsv1 {
Subroutine set_rsv1: called CC=1 SCAR=0.0
Pod undocumented
226 1 ${ $_[0][FIRST2] } |= _RSV1();
227  
228 1 return $_[0];
229 }
230  
231 1 ▶sub set_rsv2 {
Subroutine set_rsv2: called CC=1 SCAR=0.0
Pod undocumented
232 1 ${ $_[0][FIRST2] } |= _RSV2();
233  
234 1 return $_[0];
235 }
236  
237 1 ▶sub set_rsv3 {
Subroutine set_rsv3: called CC=1 SCAR=0.0
Pod undocumented
238 1 ${ $_[0][FIRST2] } |= _RSV3();
239  
240 1 return $_[0];
241 }
242  
243 10 ▶sub has_rsv1 {
Subroutine has_rsv1: called CC=1 SCAR=0.0
Pod undocumented
244 10 return ("\0" ne (${ $_[0][FIRST2] } & _RSV1()));
245 }
246  
247 10 ▶sub has_rsv2 {
Subroutine has_rsv2: called CC=1 SCAR=0.0
Pod undocumented
248 10 return ("\0" ne (${ $_[0][FIRST2] } & _RSV2()));
249 }
250  
251 10 ▶sub has_rsv3 {
Subroutine has_rsv3: called CC=1 SCAR=0.0
Pod undocumented
252 10 return ("\0" ne (${ $_[0][FIRST2] } & _RSV3()));
253 }
254  
255 #pre-0.064 compatibility
256 0 ▶sub is_control_frame { return $_[0]->is_control() }
Subroutine is_control_frame: not called CC=1 SCAR=6.9
Pod undocumented
257  
258 #----------------------------------------------------------------------
259  
260 55 ▶sub _validate_mask {
Subroutine _validate_mask: called CC=3 SCAR=12.7
261 55 my ($bytes) = @_;
262  
263 55 ▶ if (length $bytes) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $bytes) 55 0 55
264 55 ▶ if (4 != length $bytes) {
Branch: 1 branch
BranchTrueFalseTotal
if (4 != length $bytes) 0 55 55
265 0 my $len = length $bytes;
266 0 die "Mask must be 4 bytes long, not $len ($bytes)!";
267 }
268 }
269  
270 55 return;
271 }
272  
273 0 ▶sub _activate_highest_bit {
Subroutine _activate_highest_bit: not called CC=1 SCAR=6.9
274 0 my ($self, $sr, $offset) = @_;
275  
276 0 substr( $$sr, $offset, 1 ) = chr( 0x80 | ord substr( $$sr, $offset, 1 ) );
277  
278 0 return;
279 }
280  
281 0 ▶sub _deactivate_highest_bit {
Subroutine _deactivate_highest_bit: not called CC=1 SCAR=6.9
282 0 my ($sr, $offset) = @_;
283  
284 0 substr( $$sr, $offset, 1 ) = chr( 0x7f & ord substr( $$sr, $offset, 1 ) );
285  
286 0 return;
287 }
288  
289 24 1;
« WebSocket/Handshake.pm ↑ Summary WebSocket/Defragmenter.pm »