Mojo/WebSocket.pm

filter: Statementstmt 100% 92 / 92 Branchbran 83.3% 50 / 60 Conditioncond 45.4% 5 / 11 MC/DCmcdc 0.0% 0 / 5 Subroutinesub 100% 14 / 14 Podpod 100% 5 / 5 totaltotal 88.7% 166 / 187 CC 36 SCAR 21.9
CC
36
Cov
90%
parse_frame
16.0
build_frame
11.0
client_handshake
5.4
CRAP 9.0
« Mojo/Transaction.pm ↑ Summary Mojo/JSON/Pointer.pm »
1 package Mojo::WebSocket;
2 25 ▶use Mojo::Base -strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3  
4 25 ▶use Config;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 25 ▶use Exporter qw(import);
Subroutine BEGIN: called CC=1 SCAR=0.0
6 25 ▶use Mojo::Util qw(b64_encode dumper sha1_bytes xor_encode);
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 25 ▶use constant DEBUG => $ENV{MOJO_WEBSOCKET_DEBUG} || 0;
Subroutine BEGIN: called CC=2 SCAR=7.1
Condition50%1/2
$ENV{'MOJO_WEBSOCKET_DEBUG'} || 0
l!l
025
MC/DC0%0/1
$ENV{'MOJO_WEBSOCKET_DEBUG'} || 0
$ENV{'MOJO_WEBSOCKET_DEBUG'}
Truth table50%1/2
A
A= $ENV{'MOJO_WEBSOCKET_DEBUG'}
Aresult
11
00
9  
10 # Unique value from RFC 6455
11 25 ▶use constant GUID => '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13 # Perl with support for quads
14 25 ▶use constant MODERN => (($Config{use64bitint} // '') eq 'define' || $Config{longsize} >= 8);
Subroutine BEGIN: called CC=3 SCAR=12.5
Condition40%2/5
($Mojo::WebSocket::Config{'use64bitint'} // '') eq 'define' || $Mojo::WebSocket::Config{'longsize'} >= 8
l!l&&r!l&&!r
2500
$Mojo::WebSocket::Config{"use64bitint"} // ""
l!l
250
MC/DC0%0/2
($Mojo::WebSocket::Config{'use64bitint'} // '') eq 'define' || $Mojo::WebSocket::Config{'longsize'} >= 8
$Mojo::WebSocket::Config{"use64bitint"} $Mojo::WebSocket::Config{'longsize'} >= 8
Truth table33%1/3
A || B
A= $Mojo::WebSocket::Config{"use64bitint"}B= $Mojo::WebSocket::Config{'longsize'} >= 8
ABresult
1X1
011
000
15  
16 # Opcodes
17 25 ▶use constant {WS_CONTINUATION => 0x0, WS_TEXT => 0x1, WS_BINARY => 0x2, WS_CLOSE => 0x8, WS_PING => 0x9,
Subroutine BEGIN: called CC=1 SCAR=0.0
18 25 WS_PONG => 0xa};
19  
20 25 our @EXPORT_OK = (
21 qw(WS_BINARY WS_CLOSE WS_CONTINUATION WS_PING WS_PONG WS_TEXT build_frame challenge client_handshake parse_frame),
22 qw(server_handshake)
23 );
24  
25 42 ▶sub build_frame {
Subroutine build_frame: called CC=11 SCAR=24.0
Pod documented
26 42 my ($masked, $fin, $rsv1, $rsv2, $rsv3, $op, $payload) = @_;
27 42 warn "-- Building frame ($fin, $rsv1, $rsv2, $rsv3, $op)\n" if DEBUG;
28  
29 # Head
30 42 ▶ my $head = $op + ($fin ? 128 : 0);
Branch: 1 branch
BranchTrueFalseTotal
$fin ? : 40 2 42
31 42 ▶ $head |= 0b01000000 if $rsv1;
Branch: 1 branch
BranchTrueFalseTotal
if $rsv1 4 38 42
32 42 ▶ $head |= 0b00100000 if $rsv2;
Branch: 1 branch
BranchTrueFalseTotal
if $rsv2 4 38 42
33 42 ▶ $head |= 0b00010000 if $rsv3;
Branch: 1 branch
BranchTrueFalseTotal
if $rsv3 4 38 42
34 42 my $frame = pack 'C', $head;
35  
36 # Small payload
37 42 my $len = length $payload;
38 42 ▶ if ($len < 126) {
Branch: 2 branches
BranchTrueFalseTotal
if ($len < 126) { } 38 4 42
elsif ($len < 65536) { } 2 2 4
39 38 warn "-- Small payload ($len)\n@{[dumper $payload]}" if DEBUG;
40 38 ▶ $frame .= pack 'C', $masked ? ($len | 128) : $len;
Branch: 1 branch
BranchTrueFalseTotal
$masked ? : 6 32 38
41 }
42  
43 # Extended payload (16-bit)
44 elsif ($len < 65536) {
45 2 warn "-- Extended 16-bit payload ($len)\n@{[dumper $payload]}" if DEBUG;
46 2 ▶ $frame .= pack 'Cn', $masked ? (126 | 128) : 126, $len;
Branch: 1 branch
BranchTrueFalseTotal
$masked ? : 0 2 2
47 }
48  
49 # Extended payload (64-bit with 32-bit fallback)
50 else {
51 2 warn "-- Extended 64-bit payload ($len)\n@{[dumper $payload]}" if DEBUG;
52 2 ▶ $frame .= pack 'C', $masked ? (127 | 128) : 127;
Branch: 1 branch
BranchTrueFalseTotal
$masked ? : 0 2 2
53 2 $frame .= MODERN ? pack('Q>', $len) : pack('NN', 0, $len & 0xffffffff);
54 }
55  
56 # Mask payload
57 42 ▶ if ($masked) {
Branch: 1 branch
BranchTrueFalseTotal
if ($masked) 6 36 42
58 6 my $mask = pack 'N', int(rand 9 x 7);
59 6 $payload = $mask . xor_encode($payload, $mask x 128);
60 }
61  
62 42 return $frame . $payload;
63 }
64  
65 2 ▶sub challenge {
Subroutine challenge: called CC=3 SCAR=11.4
Pod documented
66 2 my $tx = shift;
67  
68 # "permessage-deflate" extension
69 2 my $headers = $tx->res->headers;
70 2 ▶ $tx->compressed(1) if ($headers->sec_websocket_extensions // '') =~ /permessage-deflate/;
Branch: 1 branch
BranchTrueFalseTotal
if ($headers->sec_websocket_extensions // "") =~ /permessage-deflate/u 0 2 2
Condition50%1/2
$headers->sec_websocket_extensions // ""
l!l
02
MC/DC0%0/1
$headers->sec_websocket_extensions // ""
$headers->sec_websocket_extensions
Truth table50%1/2
A
A= $headers->sec_websocket_extensions
Aresult
11
00
71  
72 2 return _challenge($tx->req->headers->sec_websocket_key) eq $headers->sec_websocket_accept;
73 }
74  
75 11 ▶sub client_handshake {
Subroutine client_handshake: called CC=5 SCAR=16.8
Pod documented
76 11 my $tx = shift;
77  
78 11 my $headers = $tx->req->headers;
79 11 ▶ $headers->upgrade('websocket') unless $headers->upgrade;
Branch: 1 branch
BranchTrueFalseTotal
unless $headers->upgrade 11 0 11
80 11 ▶ $headers->connection('Upgrade') unless $headers->connection;
Branch: 1 branch
BranchTrueFalseTotal
unless $headers->connection 11 0 11
81 11 ▶ $headers->sec_websocket_version(13) unless $headers->sec_websocket_version;
Branch: 1 branch
BranchTrueFalseTotal
unless $headers->sec_websocket_version 11 0 11
82  
83 # Generate 16 byte WebSocket challenge
84 11 my $challenge = b64_encode sprintf('%16u', int(rand 9 x 16)), '';
85 11 ▶ $headers->sec_websocket_key($challenge) unless $headers->sec_websocket_key;
Branch: 1 branch
BranchTrueFalseTotal
unless $headers->sec_websocket_key 11 0 11
86  
87 11 return $tx;
88 }
89  
90 30 ▶sub parse_frame {
Subroutine parse_frame: called CC=16 SCAR=27.7
Pod documented
91 30 my ($buffer, $max) = @_;
92  
93 # Head
94 30 ▶ return undef unless length $$buffer >= 2;
Branch: 1 branch
BranchTrueFalseTotal
unless length $$buffer >= 2 6 24 30
95 24 my ($first, $second) = unpack 'C2', $$buffer;
96  
97 # FIN
98 24 ▶ my $fin = ($first & 0b10000000) == 0b10000000 ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
($first & 128) == 128 ? : 23 1 24
99  
100 # RSV1-3
101 24 ▶ my $rsv1 = ($first & 0b01000000) == 0b01000000 ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
($first & 64) == 64 ? : 2 22 24
102 24 ▶ my $rsv2 = ($first & 0b00100000) == 0b00100000 ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
($first & 32) == 32 ? : 2 22 24
103 24 ▶ my $rsv3 = ($first & 0b00010000) == 0b00010000 ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
($first & 16) == 16 ? : 2 22 24
104  
105 # Opcode
106 24 my $op = $first & 0b00001111;
107 24 warn "-- Parsing frame ($fin, $rsv1, $rsv2, $rsv3, $op)\n" if DEBUG;
108  
109 # Small payload
110 24 my ($hlen, $len) = (2, $second & 0b01111111);
111 24 ▶ if ($len < 126) { warn "-- Small payload ($len)\n" if DEBUG }
Branch: 3 branches
BranchTrueFalseTotal
if ($len < 126) { } 22 2 24
elsif ($len == 126) { } 1 1 2
elsif ($len == 127) { } 1 0 1
112  
113 # Extended payload (16-bit)
114 elsif ($len == 126) {
115 1 ▶ return undef unless length $$buffer > 4;
Branch: 1 branch
BranchTrueFalseTotal
unless length $$buffer > 4 0 1 1
116 1 $hlen = 4;
117 1 $len = unpack 'x2n', $$buffer;
118 1 warn "-- Extended 16-bit payload ($len)\n" if DEBUG;
119 }
120  
121 # Extended payload (64-bit with 32-bit fallback)
122 elsif ($len == 127) {
123 1 ▶ return undef unless length $$buffer > 10;
Branch: 1 branch
BranchTrueFalseTotal
unless length $$buffer > 10 0 1 1
124 1 $hlen = 10;
125 1 $len = MODERN ? unpack('x2Q>', $$buffer) : unpack('x2x4N', $$buffer);
126 1 warn "-- Extended 64-bit payload ($len)\n" if DEBUG;
127 }
128  
129 # Check message size
130 24 ▶ return 1 if $len > $max;
Branch: 1 branch
BranchTrueFalseTotal
if $len > $max 1 23 24
131  
132 # Check if whole packet has arrived
133 23 ▶ $len += 4 if my $masked = $second & 0b10000000;
Branch: 1 branch
BranchTrueFalseTotal
if my $masked = $second & 128 5 18 23
134 23 ▶ return undef if length $$buffer < ($hlen + $len);
Branch: 1 branch
BranchTrueFalseTotal
if length $$buffer < $hlen + $len 1 22 23
135 22 substr $$buffer, 0, $hlen, '';
136  
137 # Payload
138 22 ▶ my $payload = $len ? substr($$buffer, 0, $len, '') : '';
Branch: 1 branch
BranchTrueFalseTotal
$len ? : 19 3 22
139 22 ▶ $payload = xor_encode($payload, substr($payload, 0, 4, '') x 128) if $masked;
Branch: 1 branch
BranchTrueFalseTotal
if $masked 5 17 22
140 22 warn dumper $payload if DEBUG;
141  
142 22 return [$fin, $rsv1, $rsv2, $rsv3, $op, $payload];
143 }
144  
145 2 ▶sub server_handshake {
Subroutine server_handshake: called CC=1 SCAR=0.0
Pod documented
146 2 my $tx = shift;
147  
148 2 my $headers = $tx->res->headers;
149 2 $headers->upgrade('websocket')->connection('Upgrade');
150 2 $headers->sec_websocket_accept(_challenge($tx->req->headers->sec_websocket_key));
151  
152 2 return $tx;
153 }
154  
155 4 ▶sub _challenge { b64_encode(sha1_bytes(($_[0] || '') . GUID), '') }
Subroutine _challenge: called CC=2 SCAR=7.6
Condition50%1/2
$_[0] || ''
l!l
40
MC/DC0%0/1
$_[0] || ''
$_[0]
Truth table50%1/2
A
A= $_[0]
Aresult
11
00
156  
157 25 1;
158  
159 =encoding utf8
160  
161 =head1 NAME
162  
163 Mojo::WebSocket - The WebSocket protocol
164  
165 =head1 SYNOPSIS
166  
167 use Mojo::WebSocket qw(WS_TEXT build_frame parse_frame);
168  
169 my $bytes = build_frame 0, 1, 0, 0, 0, WS_TEXT, 'Hello World!';
170 my $frame = parse_frame \$bytes, 262144;
171  
172 =head1 DESCRIPTION
173  
174 L<Mojo::WebSocket> implements the WebSocket protocol as described in L<RFC 6455|https://tools.ietf.org/html/rfc6455>.
175 Note that 64-bit frames require a Perl with support for quads or they are limited to 32-bit.
176  
177 =head1 FUNCTIONS
178  
179 L<Mojo::WebSocket> implements the following functions, which can be imported individually.
180  
181 =head2 build_frame
182  
183 my $bytes = build_frame $masked, $fin, $rsv1, $rsv2, $rsv3, $op, $payload;
184  
185 Build WebSocket frame.
186  
187 # Masked binary frame with FIN bit and payload
188 say build_frame 1, 1, 0, 0, 0, WS_BINARY, 'Hello World!';
189  
190 # Text frame with payload but without FIN bit
191 say build_frame 0, 0, 0, 0, 0, WS_TEXT, 'Hello ';
192  
193 # Continuation frame with FIN bit and payload
194 say build_frame 0, 1, 0, 0, 0, WS_CONTINUATION, 'World!';
195  
196 # Close frame with FIN bit and without payload
197 say build_frame 0, 1, 0, 0, 0, WS_CLOSE, '';
198  
199 # Ping frame with FIN bit and payload
200 say build_frame 0, 1, 0, 0, 0, WS_PING, 'Test 123';
201  
202 # Pong frame with FIN bit and payload
203 say build_frame 0, 1, 0, 0, 0, WS_PONG, 'Test 123';
204  
205 =head2 challenge
206  
207 my $bool = challenge Mojo::Transaction::WebSocket->new;
208  
209 Check WebSocket handshake challenge.
210  
211 =head2 client_handshake
212  
213 my $tx = client_handshake Mojo::Transaction::HTTP->new;
214  
215 Perform WebSocket handshake client-side.
216  
217 =head2 parse_frame
218  
219 my $frame = parse_frame \$bytes, $limit;
220  
221 Parse WebSocket frame.
222  
223 # Parse single frame and remove it from buffer
224 my $frame = parse_frame \$buffer, 262144;
225 say "FIN: $frame->[0]";
226 say "RSV1: $frame->[1]";
227 say "RSV2: $frame->[2]";
228 say "RSV3: $frame->[3]";
229 say "Opcode: $frame->[4]";
230 say "Payload: $frame->[5]";
231  
232 =head2 server_handshake
233  
234 my $tx = server_handshake Mojo::Transaction::HTTP->new;
235  
236 Perform WebSocket handshake server-side.
237  
238 =head1 CONSTANTS
239  
240 L<Mojo::WebSocket> implements the following constants, which can be imported individually.
241  
242 =head2 WS_BINARY
243  
244 Opcode for C<Binary> frames.
245  
246 =head2 WS_CLOSE
247  
248 Opcode for C<Close> frames.
249  
250 =head2 WS_CONTINUATION
251  
252 Opcode for C<Continuation> frames.
253  
254 =head2 WS_PING
255  
256 Opcode for C<Ping> frames.
257  
258 =head2 WS_PONG
259  
260 Opcode for C<Pong> frames.
261  
262 =head2 WS_TEXT
263  
264 Opcode for C<Text> frames.
265  
266 =head1 DEBUGGING
267  
268 You can set the C<MOJO_WEBSOCKET_DEBUG> environment variable to get some advanced diagnostics information printed to
269 C<STDERR>.
270  
271 MOJO_WEBSOCKET_DEBUG=1
272  
273 =head1 SEE ALSO
274  
275 L<Mojolicious>, L<Mojolicious::Guides>, L<https://mojolicious.org>.
276  
277 =cut
« Mojo/Transaction.pm ↑ Summary Mojo/JSON/Pointer.pm »