| 1 | package Net::WebSocket::Handshake::Extension; | ||
| 2 | |||
| 3 | 5 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 4 | 5 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 5 | |||
| 6 | 5 | ▶ | use Call::Context (); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 7 | |||
| 8 | #We use this because it’s light; there seems little reason why | ||
| 9 | #we’d want to use anything else? | ||
| 10 | 5 | ▶ | use HTTP::Headers::Util (); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 11 | |||
| 12 | =encoding utf-8 | ||
| 13 | |||
| 14 | =head1 NAME | ||
| 15 | |||
| 16 | Net::WebSocket::Handshake::Extension - WebSocket extension handshake | ||
| 17 | |||
| 18 | =head1 SYNOPSIS | ||
| 19 | |||
| 20 | #Returns a list of instances of this class | ||
| 21 | my @exts = Net::WebSocket::Handshake::Extension->parse_string( | ||
| 22 | $value_of_sec_websocket_extensions | ||
| 23 | ); | ||
| 24 | |||
| 25 | my $ext = Net::WebSocket::Handshake::Extension->new( | ||
| 26 | 'extension-name', | ||
| 27 | param1 => 'value1', | ||
| 28 | #... | ||
| 29 | ); | ||
| 30 | |||
| 31 | my $name = $ext->token(); #e.g., 'extension-name' | ||
| 32 | |||
| 33 | my @params = $ext->parameters(); | ||
| 34 | |||
| 35 | #@others is an array of instances of this class | ||
| 36 | my $str = $ext->to_string(@others); | ||
| 37 | |||
| 38 | =head1 DESCRIPTION | ||
| 39 | |||
| 40 | This module handles the handshake component of WebSocket extensions: | ||
| 41 | specifically, it translates between an extension name and parameters | ||
| 42 | as an object and as actually represented in the values of HTTP headers. | ||
| 43 | |||
| 44 | It’s flexible enough that you can determine how you want extensions | ||
| 45 | divided among multiple C<Sec-WebSocket-Extensions> headers. | ||
| 46 | |||
| 47 | Note that a server, as per the protocol specification, “MUST NOT” | ||
| 48 | include more than one C<Sec-WebSocket-Extensions> header in its | ||
| 49 | handshake response. | ||
| 50 | |||
| 51 | =head1 METHODS | ||
| 52 | |||
| 53 | =head2 @objects = I<CLASS>->parse_string( HEADER_VALUE ) | ||
| 54 | |||
| 55 | Parses the value of the C<Sec-WebSocket-Extensions> header (i.e., HEADER_VALUE) | ||
| 56 | into one or more instances of this class. | ||
| 57 | |||
| 58 | =cut | ||
| 59 | |||
| 60 | 0 | ▶ | sub parse_string { |
|
Subroutine
parse_string: not called CC=2 SCAR=17.9
Pod
documented
| |||
| 61 | 0 | my ($class, $str) = @_; | |
| 62 | |||
| 63 | 0 | Call::Context::must_be_list(); | |
| 64 | |||
| 65 | 0 | my @pieces = HTTP::Headers::Util::split_header_words($str); | |
| 66 | 0 | splice(@$_, 1, 1) for @pieces; | |
| 67 | |||
| 68 | 0 | return map { $class->new(@$_) } @pieces; | |
| 69 | } | ||
| 70 | |||
| 71 | =head2 I<CLASS>->new( NAME, PARAMS_KV ) | ||
| 72 | |||
| 73 | Returns an instance of the class, with NAME as the C<token()> value and | ||
| 74 | PARAMS_KV as C<parameters()>. Probably less useful than C<parse_string()>. | ||
| 75 | |||
| 76 | =cut | ||
| 77 | |||
| 78 | 6 | ▶ | sub new { |
|
Subroutine
new: called CC=1 SCAR=0.0
Pod
documented
| |||
| 79 | 6 | my ($class, @name_and_params) = @_; | |
| 80 | |||
| 81 | 6 | return bless \@name_and_params, $class; | |
| 82 | } | ||
| 83 | |||
| 84 | =head2 I<OBJ>->token() | ||
| 85 | |||
| 86 | Returns the token as given in the C<Sec-WebSocket-Extensions> header. | ||
| 87 | |||
| 88 | =cut | ||
| 89 | |||
| 90 | 2 | ▶ | sub token { return $_[0][0] } |
|
Subroutine
token: called CC=1 SCAR=0.0
Pod
documented
| |||
| 91 | |||
| 92 | =head2 %params = I<OBJ>->parameters() | ||
| 93 | |||
| 94 | Returns the parameters as given in the C<Sec-WebSocket-Extensions> header. | ||
| 95 | The parameters are a list of key/value pairs, suitable for representation | ||
| 96 | as a hash. Parameters that have no value (e.g., the C<permessage-deflate> | ||
| 97 | extension’s C<client_no_context_takeover> parameter) are given undef as a | ||
| 98 | Perl value. | ||
| 99 | |||
| 100 | =cut | ||
| 101 | |||
| 102 | 4 | ▶ | sub parameters { |
|
Subroutine
parameters: called CC=1 SCAR=0.0
Pod
documented
| |||
| 103 | 4 | Call::Context::must_be_list(); | |
| 104 | 4 | return @{ $_[0] }[ 1 .. $#{ $_[0] } ]; | |
| 105 | } | ||
| 106 | |||
| 107 | =head2 I<OBJ>->to_string( OTHER_EXTENSIONS ) | ||
| 108 | |||
| 109 | Returns a string that represents the extension (and any others) as a | ||
| 110 | C<Sec-WebSocket-Extensions> header value. Other extensions are to be given | ||
| 111 | as instances of this class. | ||
| 112 | |||
| 113 | =cut | ||
| 114 | |||
| 115 | 1 | ▶ | sub to_string { |
|
Subroutine
to_string: called CC=1 SCAR=0.0
Pod
documented
| |||
| 116 | 1 | my ($self, @others) = @_; | |
| 117 | |||
| 118 | return HTTP::Headers::Util::join_header_words( | ||
| 119 | 1 | ( map { $_->_to_arrayref() } $self, @others ), | |
| 120 | ); | ||
| 121 | } | ||
| 122 | |||
| 123 | #---------------------------------------------------------------------- | ||
| 124 | |||
| 125 | 2 | ▶ | sub _to_arrayref { |
|
Subroutine
_to_arrayref: called CC=1 SCAR=0.0
| |||
| 126 | 2 | return [ $_[0][0] => undef, @{ $_[0] }[ 1 .. $#{ $_[0] } ] ]; | |
| 127 | } | ||
| 128 | |||
| 129 | 5 | 1; | |