WebSocket::Version - WebSocket Version
use WebSocket::Version; my $ver = WebSocket::Version->new( 'draft-ietf-hybi-17' ) || die( WebSocket::Version->error, "\n" ); my $ver = WebSocket::Version->new(13) || die( WebSocket::Version->error, "\n" ); my $ver = WebSocket::Version->new_from_request( $req ) || die( WebSocket::Version->error, "\n" ); print( $ver->numify, "\n" ); print( $ver->draft, "\n" ); print( "Version is: $ver\n" ); # Version is: 13
v0.1.0
A WebSocket class representing the version of the protocol used.
Version numbering used in the protocol headers started to be used since version 4, thus to allow numeric comparison this class uses an internal version number as a simple increment.
rfc6455 is also known as draft-ietf-hybi-17 (version 13).
Takes an integer representing a WebSocket protocol version (the latest being 13), or a draft version such as draft-ietf-hybi-17 and this will return a new object.
draft-ietf-hybi-17
It can take also an hash or hash reference of optional parameters with the only one being debug. You can provide it an integer value to set the level of debugging. Nothing meaningful is displayed below 3.
debug
Returns the numeric value of the version. However, note that IETF drafts before revision 00, i.e. of type hixie do not have version number, so this method will return undef then.
00
hixie
undef
Returns the draft version such as draft-ietf-hybi-17, as a scalar object (Module::Generic::Scalar)
Returns the draft expiration date as a DateTime object.
Takes an hash or hash reference of options and returns a dictionary hash containing all the attributes for the draft found.
Current supported options are:
draft
The draft version, such as draft-ietf-hybi-17
revision
The draft revision number such as 17. This is used in conjunction with the type option
17
serial
The serial number to search for. This is an internal number not part of the rfc6455https://datatracker.ietf.org/doc/html/rfc6455.
type
The draft type, which is either hiby or hixie. This is used in conjunction with the revision option
hiby
version
Its value is an integer representing the WebSocket protocol version. For example 13, the latest version.
13
If none of those options are provided, undef is return and an error is set.
Returns the draft issue date as a DateTime object.
Given a WebSocket::Request object, this will analyse the request headers and based on the information found, it will infer a WebSocket protocol version and return the corresponding most recent object matching that version.
Returns the next version object. For example, if the current object is the draft draft-ietf-hybi-16, calling next will return a version object matching the draft version draft-ietf-hybi-17.
draft-ietf-hybi-16
next
Note that some draft version share the same protocol version. For example, draft-ietf-hybi-13 to draft-ietf-hybi-17 all use protocol version 13.
draft-ietf-hybi-13
Also note that version prior to draft-ietf-hybi-00, such as draft-hixie-76 to draft-hixie-00 have no version number and thus the stringification of the object returns undef.
draft-ietf-hybi-00
draft-hixie-76
draft-hixie-00
Returns the numeric representation of the version as a Module::Generic::Number object. For example, 13 which is the latest version of the WebSocket protocol.
Returns the offset position of the object in the repository of all IETF drafts for the WebSocket protocol.
Alias for "previous".
Returns the previous version object. For example, if the current object is the draft draft-ietf-hybi-16, calling next will return a version object matching the draft version draft-ietf-hybi-15
draft-ietf-hybi-15
Returns the draft revision number. For example in draft-ietf-hybi-17, the revision number is 17
Returns the internal serial number used to identify and manipulate the version objects. This value is used by internal private methods to handle overloading. See "OPERATIONS"
Returns the status as scalar object (Module::Generic::Scalar). Typical status is draft, obsolete
obsolete
Returns the type as scalar object (Module::Generic::Scalar). Possible types are: hybi or hixie
hybi
Returns the WebSocket protocol version. Below is a summary table[1] of the IETF drafts and their version.
[1] Courtesy of Table Generator
The WebSocket::Version object supports the following overloaded operators: "", -, +, *, /, %, <, <=, >, >=, <=>, ==, !=, eq, ne, cmp, bool
my $v = WebSocket::Version->new(13); # Now draft version draft-ietf-hybi-17, which is the latest # draft version for protocol version 13 my $v16 = $v - 1; # Now draft version draft-ietf-hybi-16
But be careful that, if as a result of an operation, the product yields a version out of bound, i.e. above the latest draft-ietf-hybi-17 or prior to draft-hixie-00, then it will return undef. For example:
my $non_existing = $v16 * 2; # $non_existing is undef because there is no draft version 32
Likewise, if a product yields a fractional number, it will return undef. For example:
my $undef_too = $v / 2; # This would yield 8.5, which is not usable and thus returns undef
Below is a table of the availability of headers by IETF draft revision number.
"all" means all the versions that are relevant and listed below after the table. Other earlier versions such as drafts Hixie 0 to 74 are not meaningful nor relevant, thus, 75 means draft-hixie-75, otherwise those revisions are from drafts draft-ietf-hybi-00 to draft-ietf-hybi-17
0
74
75
draft-hixie-75
Request:
GET /chat HTTP/1.1 Host: server.example.com Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Origin: http://example.com Sec-WebSocket-Protocol: chat, superchat Sec-WebSocket-Version: 13
Response:
HTTP/1.1 101 Switching Protocols Upgrade: websocket Connection: Upgrade Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= Sec-WebSocket-Protocol: chat
Date: 2011-09-30
Reference
Diff from HyBi 16
Only editorial changes
Sec-WebSocket-Version value is still 13 and this must be the version for RFC
Date: 2011-09-27
Diff from HyBi 15
Date: 2011-09-17
Diff from HyBi 14
Sec-WebSocket-Version is still 13.
Editorial changes only.
If servers doesn't support the requested version, they MUST respond with Sec-WebSocket-Version headers containing all available versions.
The servers MUST close the connection upon receiving a non-masked frame with status code of 1002.
The clients MUST close the connection upon receiving a masked frame with status code of 1002.
Date: 2011-09-08
Diff from HyBi 13
Version negotiation
The following example demonstrates version negotiation:
GET /chat HTTP/1.1 Host: server.example.com Upgrade: websocket Connection: Upgrade ... Sec-WebSocket-Version: 25
The response from the server might look as follows:
HTTP/1.1 400 Bad Request ... Sec-WebSocket-Version: 13, 8, 7
Note that the last response from the server might also look like:
HTTP/1.1 400 Bad Request ... Sec-WebSocket-Version: 13 Sec-WebSocket-Version: 8, 7
The client now repeats the handshake that conforms to version 13:
GET /chat HTTP/1.1 Host: server.example.com Upgrade: websocket Connection: Upgrade ... Sec-WebSocket-Version: 13
Extension values in extension-param could be quoted-string in addition to token.
Clarify the way to support multiple versions of WebSocket protocol.
Payload length MUST be encoded in minimal number of bytes.
WebSocket MUST support TLS.
Sec-WebSocket-Key and Sec-WebSocketAccept header field MUST NOT appear more than once.
Sec-WebSocket-Extensions and Sec-WebSocket-Protocol header filed MAY appear multiple times in requests, but it MUST NOT appear more than once in responses. See rfc6455 section 11.3.2 for more information
Sec-WebSocket-Version header filed MAY appear multiple times in responses, but it MUST NOT appear more than once in requests.
Status code 1007 was changed.
Date: 2011-08-31
Diff from HyBi 12
Now spec allow to use WWW-Authenticate header and 401 status explicitly.
Servers might redirect the client using a 3xx status code, but client are not required to follow them.
Clients' reconnection on abnormal closure must be delayed (between 0 and 5 seconds is a reasonable initial delay, and subsequent reconnection should be delayed longer by exponential backoff.
Sec-WebSocket-Version is 13.
Clients must fail the connection on receiving a subprotocol indication that was not present in the client requests in the opening handshake.
Status Codes was changes (Change 1004 as reserved, and add 1008, 1009, 1010).
GET /chat HTTP/1.1 Host: server.example.com Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Origin: http://example.com Sec-WebSocket-Protocol: chat, superchat Sec-WebSocket-Version: 8
Date: 2011-08-24
Diff from HyBi 11
Sec-WebSocket-Version value is still 8.
Date: 2011-08-23
Diff from HyBi 10
Sec-WebSocket-Version value is still 8, and 9/10/11 were reserved but were not and will not be used.
Sec-WebSocket-Origin -> Origin
Servers send all supported protocol numbers in Sec-WebSocket-Version header.
GET /chat HTTP/1.1 Host: server.example.com Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Sec-WebSocket-Origin: http://example.com Sec-WebSocket-Protocol: chat, superchat Sec-WebSocket-Version: 8
Date: 2011-07-11
Diff from HyBi 09
Status code 1007.
Receiving strings including invalid UTF-8 result in Fail.
Date: 2011-06-13
Diff from HyBi 08
On receiving a frame with any of RSV1-3 raised but no extension negotiated, Fail the WebSocket Connection.
Date: 2011-06-07
Diff from HyBi 07
Absolute path is now allowed for resource.
extension parameter is token.
Sec-WebSocket-Protocol from server to client is token.
Status code 1005 and 1006 are added, and all codes are unsigned.
Internal error results in 1006.
HTTP fallback status codes are clarified.
The value of Sec-WebSocket-Version is now 8
GET /chat HTTP/1.1 Host: server.example.com Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Sec-WebSocket-Origin: http://example.com Sec-WebSocket-Protocol: chat, superchat Sec-WebSocket-Version: 7
Date: 2011-04-22
Diff from HyBi 06
GET /chat HTTP/1.1 Host: server.example.com Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Sec-WebSocket-Origin: http://example.com Sec-WebSocket-Protocol: chat, superchat Sec-WebSocket-Version: 6
Date: 2011-02-25
Diff from HyBi 05
The closing handshake was clarified and re-written. See rfc6455 changelog
Removed Sec-WebSocket-Nonce
Sec-WebSocket-Nonce
Sec-WebSocket-Origin is optional for non-browser clients.
Sec-WebSocket-Origin
Connection header must INCLUDE Upgrade, rather than is equal to Upgrade
Connection
Upgrade
Editorial changes
GET /chat HTTP/1.1 Host: server.example.com Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Sec-WebSocket-Origin: http://example.com Sec-WebSocket-Protocol: chat, superchat Sec-WebSocket-Version: 5
HTTP/1.1 101 Switching Protocols Upgrade: websocket Connection: Upgrade Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo= Sec-WebSocket-Nonce: AQIDBAUGBwgJCgsMDQ4PEC== Sec-WebSocket-Protocol: chat
Date: 2011-02-08
Diff from HyBi 04
Changed masking : SHA-1, client nonce, server nonce, CSPRNG -> CSPRNG only
Specified the body of close frame explicitly
ABNF fix for origin and protocol
Added detailed Sec-WebSocket-Extensions format specification
Sec-WebSocket-Extensions
Removed all occurrence of Sec-WebSocket-Location
Added IANA Sec-WebSocket-Accept section
Sec-WebSocket-Accept
The value of Sec-WebSocket-Version is now 5
Sec-WebSocket-Version
GET /chat HTTP/1.1 Host: server.example.com Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Sec-WebSocket-Origin: http://example.com Sec-WebSocket-Protocol: chat, superchat Sec-WebSocket-Version: 4
HTTP/1.1 101 Switching Protocols Upgrade: websocket Connection: Upgrade Sec-WebSocket-Accept: me89jWimTRKTWwrS3aRrL53YZSo= Sec-WebSocket-Nonce: AQIDBAUGBwgJCgsMDQ4PEC== Sec-WebSocket-Protocol: chat
Date: 2011-01-11
Diff from HyBi 03
Requires BASE64 and SHA-1
Added frame masking
Changed opening handshake (Sec-WebSocket-Key1, Sec-WebSocket-Key2, key3, response -> Sec-WebSocket-Key, Sec-WebSocket-Nonce, Sec-WebSocket-Accept)
Sec-WebSocket-Key1
Sec-WebSocket-Key2
Sec-WebSocket-Key
No more challenge and checksum in request and response body
Sec-WebSocket-Nonce containing a base64 16 bytes nonce in server response (see section 5.2.2)
Added Sec-WebSocket-Extensions for extension negotiation
Upgrade header is now case-insensitive (HTTP compliant)
Value of response header Upgrade is changed from WebSocket to websocket (all lower case)
WebSocket
websocket
Flipped MORE bit and renamed it to FIN bit
Renamed Sec-WebSocket-Draft to Sec-WebSocket-Version
Sec-WebSocket-Draft
Renamed Origin to Sec-WebSocket-Origin
Added ABNF (one used in HTTP RFC2616) clarification to Sec-WebSocket-Protocol
Sec-WebSocket-Protocol
Changed subprotocols separator from SP to ‘,’
Removed Sec-WebSocket-Location
Sec-WebSocket-Location
GET /demo HTTP/1.1 Host: example.com Connection: Upgrade Sec-WebSocket-Key2: 12998 5 Y3 1 .P00 Sec-WebSocket-Protocol: sample Upgrade: WebSocket Sec-WebSocket-Key1: 4 @1 46546xW%0l 1 5 Origin: http://example.com ^n:ds[4U
HTTP/1.1 101 WebSocket Protocol Handshake Upgrade: WebSocket Connection: Upgrade Sec-WebSocket-Origin: http://example.com Sec-WebSocket-Location: ws://example.com/demo Sec-WebSocket-Protocol: sample 8jKS'y:G*Co,Wxa-
Date: 2010-10-17
The value of Sec-WebSocket-Draft is still 2
Added one known extension “compression”
Added close frame body matching step to closing handshake
Date: 2010-09-24
Added /defer cookies/ flag
Added Sec-WebSocket-Draft with a value of 2
Date: 2010-08-31
Changed frame format
Added extension mechanism (no negotiation yet)
Date: 2010-05-06
Reference HyBi 00
Reference Hixie 76
Requires Digest::MD5
Added challenge/response handshaking using binary data with header fields Sec-WebSocket-Key1 and Sec-WebSocket-Key2
Added closing handshake
Date: 2010-02-04
From version 10 to 75 there is an optional WebSocket-Protocol header field, but from version 0 to 7, there is none at all. Note that version 8 and 9 are skipped.
WebSocket-Protocol
GET /demo HTTP/1.1 Upgrade: WebSocket Connection: Upgrade Host: example.com Origin: http://example.com WebSocket-Protocol: sample
HTTP/1.1 101 Web Socket Protocol Handshake Upgrade: WebSocket Connection: Upgrade WebSocket-Origin: http://example.com WebSocket-Location: ws://example.com/demo WebSocket-Protocol: sample
Jacques Deguest <jack@deguest.jp>
perl
Copyright(c) 2021-2023 DEGUEST Pte. Ltd.
You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.
To install WebSocket, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WebSocket
CPAN shell
perl -MCPAN -e shell install WebSocket
For more information on module installation, please visit the detailed CPAN module installation guide.