| 1 | package Net::WebSocket::Handshake::Server; | ||||||||||||||||||
| 2 | |||||||||||||||||||
| 3 | =encoding utf-8 | ||||||||||||||||||
| 4 | |||||||||||||||||||
| 5 | =head1 NAME | ||||||||||||||||||
| 6 | |||||||||||||||||||
| 7 | Net::WebSocket::Handshake::Server | ||||||||||||||||||
| 8 | |||||||||||||||||||
| 9 | =head1 SYNOPSIS | ||||||||||||||||||
| 10 | |||||||||||||||||||
| 11 | my $hsk = Net::WebSocket::Handshake::Server->new( | ||||||||||||||||||
| 12 | |||||||||||||||||||
| 13 | #optional | ||||||||||||||||||
| 14 | subprotocols => [ 'echo', 'haha' ], | ||||||||||||||||||
| 15 | |||||||||||||||||||
| 16 | #optional | ||||||||||||||||||
| 17 | extensions => \@extension_objects, | ||||||||||||||||||
| 18 | ); | ||||||||||||||||||
| 19 | |||||||||||||||||||
| 20 | $hsk->valid_method_or_die( $http_method ); #optional | ||||||||||||||||||
| 21 | |||||||||||||||||||
| 22 | $hsk->consume_headers(@headers_kv_pairs); | ||||||||||||||||||
| 23 | |||||||||||||||||||
| 24 | my $resp_hdr = $hsk->to_string(); | ||||||||||||||||||
| 25 | |||||||||||||||||||
| 26 | =head1 DESCRIPTION | ||||||||||||||||||
| 27 | |||||||||||||||||||
| 28 | This class implements WebSocket handshake logic for a server. | ||||||||||||||||||
| 29 | It handles the basics of handshaking and, optionally, subprotocol | ||||||||||||||||||
| 30 | and extension negotiation. | ||||||||||||||||||
| 31 | |||||||||||||||||||
| 32 | =cut | ||||||||||||||||||
| 33 | |||||||||||||||||||
| 34 | 5 | ▶ | use strict; | ||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||
| 35 | 5 | ▶ | use warnings; | ||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||
| 36 | |||||||||||||||||||
| 37 | 5 | ▶ | use parent qw( Net::WebSocket::Handshake ); | ||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||
| 38 | |||||||||||||||||||
| 39 | 5 | ▶ | use Call::Context (); | ||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||
| 40 | |||||||||||||||||||
| 41 | 5 | ▶ | use Net::WebSocket::Constants (); | ||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||
| 42 | 5 | ▶ | use Net::WebSocket::X (); | ||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||
| 43 | |||||||||||||||||||
| 44 | #no-op | ||||||||||||||||||
| 45 | 5 | ▶ | use constant _handle_unrecognized_extension => (); | ||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||
| 46 | |||||||||||||||||||
| 47 | =head2 I<CLASS>->new( %OPTS ) | ||||||||||||||||||
| 48 | |||||||||||||||||||
| 49 | Returns an instance of this class. %OPTS is as described in the base class; | ||||||||||||||||||
| 50 | there are no options specific to this class. | ||||||||||||||||||
| 51 | |||||||||||||||||||
| 52 | =head2 I<OBJ>->valid_protocol_or_die( PROTOCOL ) | ||||||||||||||||||
| 53 | |||||||||||||||||||
| 54 | Throws an exception if the given PROTOCOL isn’t the HTTP protocol (HTTP/1.1) | ||||||||||||||||||
| 55 | that WebSocket requires for all requests. | ||||||||||||||||||
| 56 | |||||||||||||||||||
| 57 | You only need this if if you’re not using a request-parsing interface | ||||||||||||||||||
| 58 | that’s compatible with L<HTTP::Request>; otherwise, | ||||||||||||||||||
| 59 | L<Net::WebSocket::HTTP_R>’s C<handshake_consume_request()> function | ||||||||||||||||||
| 60 | will do this (and other niceties) for you. | ||||||||||||||||||
| 61 | |||||||||||||||||||
| 62 | =cut | ||||||||||||||||||
| 63 | |||||||||||||||||||
| 64 | 4 | ▶ | sub valid_protocol_or_die { | ||||||||||||||||
|
Subroutine
valid_protocol_or_die: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||
| 65 | 4 | my ($self, $protocol) = @_; | |||||||||||||||||
| 66 | |||||||||||||||||||
| 67 | 4 | ▶ | if ($protocol ne Net::WebSocket::Constants::REQUIRED_REQUEST_PROTOCOL()) { | ||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||
| 68 | 2 | die Net::WebSocket::X->create('BadRequestProtocol', $protocol); | |||||||||||||||||
| 69 | } | ||||||||||||||||||
| 70 | |||||||||||||||||||
| 71 | 2 | return; | |||||||||||||||||
| 72 | } | ||||||||||||||||||
| 73 | |||||||||||||||||||
| 74 | =head2 I<OBJ>->valid_method_or_die( METHOD ) | ||||||||||||||||||
| 75 | |||||||||||||||||||
| 76 | Throws an exception if the given METHOD isn’t the HTTP method (GET) that | ||||||||||||||||||
| 77 | WebSocket requires for all requests. | ||||||||||||||||||
| 78 | |||||||||||||||||||
| 79 | As with C<valid_protocol_or_die()>, L<Net::WebSocket::HTTP_R> might | ||||||||||||||||||
| 80 | call this method for you. | ||||||||||||||||||
| 81 | |||||||||||||||||||
| 82 | =cut | ||||||||||||||||||
| 83 | |||||||||||||||||||
| 84 | 4 | ▶ | sub valid_method_or_die { | ||||||||||||||||
|
Subroutine
valid_method_or_die: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||
| 85 | 4 | my ($self, $method) = @_; | |||||||||||||||||
| 86 | |||||||||||||||||||
| 87 | 4 | ▶ | if ($method ne Net::WebSocket::Constants::REQUIRED_HTTP_METHOD()) { | ||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||
| 88 | 2 | die Net::WebSocket::X->create('BadHTTPMethod', $method); | |||||||||||||||||
| 89 | } | ||||||||||||||||||
| 90 | |||||||||||||||||||
| 91 | 2 | return; | |||||||||||||||||
| 92 | } | ||||||||||||||||||
| 93 | |||||||||||||||||||
| 94 | 29 | ▶ | sub _consume_peer_header { | ||||||||||||||||
|
Subroutine
_consume_peer_header: called CC=8 SCAR=20.8
| |||||||||||||||||||
| 95 | 29 | my ($self, $name => $value) = @_; | |||||||||||||||||
| 96 | |||||||||||||||||||
| 97 | 29 | $name =~ tr<A-Z><a-z>; #case insensitive | |||||||||||||||||
| 98 | |||||||||||||||||||
| 99 | 29 | ▶ | if ($name eq 'sec-websocket-version') { | ||||||||||||||||
|
Branch: 3 branches
| |||||||||||||||||||
| 100 | 7 | ▶ | if ( $value ne Net::WebSocket::Constants::PROTOCOL_VERSION() ) { | ||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||
| 101 | 2 | die Net::WebSocket::X->create('UnsupportedProtocolVersion', $value); | |||||||||||||||||
| 102 | } | ||||||||||||||||||
| 103 | |||||||||||||||||||
| 104 | 5 | $self->{'_version_ok'} = 1; | |||||||||||||||||
| 105 | } | ||||||||||||||||||
| 106 | elsif ($name eq 'sec-websocket-key') { | ||||||||||||||||||
| 107 | 7 | ▶ | if ($value !~ m<\A[A-Za-z0-9/\+]{22}==\z>) { | ||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||
| 108 | 1 | die Net::WebSocket::X->create('BadHeader', 'Sec-WebSocket-Key' => $value); | |||||||||||||||||
| 109 | } | ||||||||||||||||||
| 110 | |||||||||||||||||||
| 111 | 6 | $self->{'key'} = $value; | |||||||||||||||||
| 112 | } | ||||||||||||||||||
| 113 | elsif ($name eq 'sec-websocket-protocol') { | ||||||||||||||||||
| 114 | 1 | require Net::WebSocket::HTTP; | |||||||||||||||||
| 115 | |||||||||||||||||||
| 116 | 1 | for my $token ( Net::WebSocket::HTTP::split_tokens($value) ) { | |||||||||||||||||
| 117 | 3 | ▶ | if (!defined $self->{'_subprotocol'}) { | ||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||
| 118 | 2 | ($self->{'_subprotocol'}) = grep { $_ eq $token } @{ $self->{'subprotocols'} }; | |||||||||||||||||
| 119 | } | ||||||||||||||||||
| 120 | } | ||||||||||||||||||
| 121 | } | ||||||||||||||||||
| 122 | else { | ||||||||||||||||||
| 123 | 14 | $self->_consume_generic_header($name => $value); | |||||||||||||||||
| 124 | } | ||||||||||||||||||
| 125 | |||||||||||||||||||
| 126 | 24 | return; | |||||||||||||||||
| 127 | } | ||||||||||||||||||
| 128 | |||||||||||||||||||
| 129 | #Send only those extensions that we’ve deduced the client can actually use. | ||||||||||||||||||
| 130 | 0 | ▶ | sub _should_include_extension_in_headers { | ||||||||||||||||
|
Subroutine
_should_include_extension_in_headers: not called CC=1 SCAR=6.9
| |||||||||||||||||||
| 131 | 0 | my ($self, $xtn) = @_; | |||||||||||||||||
| 132 | |||||||||||||||||||
| 133 | 0 | return $xtn->ok_to_use(); | |||||||||||||||||
| 134 | } | ||||||||||||||||||
| 135 | |||||||||||||||||||
| 136 | 2 | ▶ | sub _encode_subprotocols { | ||||||||||||||||
|
Subroutine
_encode_subprotocols: called CC=3 SCAR=11.1
| |||||||||||||||||||
| 137 | 2 | my ($self) = @_; | |||||||||||||||||
| 138 | |||||||||||||||||||
| 139 | 2 | ▶ | local $self->{'subprotocols'} = defined($self->{'_subprotocol'}) ? [ $self->{'_subprotocol'} ] : undef if $self->{'_no_use_legacy'}; | ||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||
| 140 | |||||||||||||||||||
| 141 | 2 | return $self->SUPER::_encode_subprotocols(); | |||||||||||||||||
| 142 | } | ||||||||||||||||||
| 143 | |||||||||||||||||||
| 144 | 4 | ▶ | sub _die_if_missing_headers { | ||||||||||||||||
|
Subroutine
_die_if_missing_headers: called CC=4 SCAR=13.9
| |||||||||||||||||||
| 145 | 4 | my ($self) = @_; | |||||||||||||||||
| 146 | |||||||||||||||||||
| 147 | 4 | my @needed = $self->_missing_generic_headers(); | |||||||||||||||||
| 148 | |||||||||||||||||||
| 149 | 4 | ▶ | push @needed, 'Sec-WebSocket-Version' if !$self->{'_version_ok'}; | ||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||
| 150 | 4 | ▶ | push @needed, 'Sec-WebSocket-Key' if !$self->{'key'}; | ||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||
| 151 | |||||||||||||||||||
| 152 | 4 | ▶ | if (@needed) { | ||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||
| 153 | 1 | die Net::WebSocket::X->create('MissingHeaders', @needed); | |||||||||||||||||
| 154 | } | ||||||||||||||||||
| 155 | |||||||||||||||||||
| 156 | 3 | return; | |||||||||||||||||
| 157 | } | ||||||||||||||||||
| 158 | |||||||||||||||||||
| 159 | 2 | ▶ | sub _create_header_lines { | ||||||||||||||||
|
Subroutine
_create_header_lines: called CC=1 SCAR=0.0
| |||||||||||||||||||
| 160 | 2 | my ($self) = @_; | |||||||||||||||||
| 161 | |||||||||||||||||||
| 162 | 2 | Call::Context::must_be_list(); | |||||||||||||||||
| 163 | |||||||||||||||||||
| 164 | return ( | ||||||||||||||||||
| 165 | 2 | 'HTTP/1.1 101 Switching Protocols', | |||||||||||||||||
| 166 | |||||||||||||||||||
| 167 | #For now let’s assume no one wants any other Upgrade: | ||||||||||||||||||
| 168 | #or Connection: values than the ones WebSocket requires. | ||||||||||||||||||
| 169 | 'Upgrade: websocket', | ||||||||||||||||||
| 170 | 'Connection: Upgrade', | ||||||||||||||||||
| 171 | |||||||||||||||||||
| 172 | 'Sec-WebSocket-Accept: ' . $self->get_accept(), | ||||||||||||||||||
| 173 | |||||||||||||||||||
| 174 | $self->_encode_subprotocols(), | ||||||||||||||||||
| 175 | |||||||||||||||||||
| 176 | $self->_encode_extensions(), | ||||||||||||||||||
| 177 | ); | ||||||||||||||||||
| 178 | } | ||||||||||||||||||
| 179 | |||||||||||||||||||
| 180 | #---------------------------------------------------------------------- | ||||||||||||||||||
| 181 | |||||||||||||||||||
| 182 | =head1 LEGACY INTERFACE: SYNOPSIS | ||||||||||||||||||
| 183 | |||||||||||||||||||
| 184 | #...Parse the request’s headers yourself... | ||||||||||||||||||
| 185 | |||||||||||||||||||
| 186 | my $hsk = Net::WebSocket::Handshake::Server->new( | ||||||||||||||||||
| 187 | |||||||||||||||||||
| 188 | #base 64, gotten from request | ||||||||||||||||||
| 189 | key => '..', | ||||||||||||||||||
| 190 | |||||||||||||||||||
| 191 | #optional - same as in non-legacy interface | ||||||||||||||||||
| 192 | subprotocols => [ 'echo', 'haha' ], | ||||||||||||||||||
| 193 | |||||||||||||||||||
| 194 | #optional, instances of Net::WebSocket::Handshake::Extension | ||||||||||||||||||
| 195 | extensions => \@extension_objects, | ||||||||||||||||||
| 196 | ); | ||||||||||||||||||
| 197 | |||||||||||||||||||
| 198 | #Note the need to conclude the header text manually. | ||||||||||||||||||
| 199 | print $hsk->create_header_text() . "\x0d\x0a"; | ||||||||||||||||||
| 200 | |||||||||||||||||||
| 201 | =cut | ||||||||||||||||||
| 202 | |||||||||||||||||||
| 203 | 5 | *get_accept = __PACKAGE__->can('_get_accept'); | |||||||||||||||||
| 204 | |||||||||||||||||||
| 205 | 5 | 1; | |||||||||||||||||