NAME

Net::WebSocket::Handshake - base class for handshake objects

DESCRIPTION

This base class’s Net::WebSocket::Handshake::Server and Net::WebSocket::Handshake::Client subclasses implement WebSocket’s handshake logic. They handle the basics of a WebSocket handshake and, optionally, subprotocol and extension negotiation.

This base class is NOT directly instantiable.

METHODS

CLASS->new( %OPTS )

Returns an instance of the relevant subclass (Net::WebSocket::Handshake::Client or Net::WebSocket::Handshake::Server). The following are common options for both:

• subprotocols - A list of HTTP tokens (e.g., wamp.2.json) that stand for subprotocols that this endpoint can use via the WebSocket connection.

• extensions - A list of extension objects that the Handshake object will interact with to determine extension support.

COMMON EXTENSION INTERFACE

Each object in the extensions array must implement the following methods:

• token() The extension’s token. (e.g., permessage-deflate)

• get_handshake_object() Returns an instance of Net::WebSocket::Handshake::Extension to represent the extension and its parameters in the HTTP headers.

• consume_parameters(..) Receives the extension parameters (in the format that Net::WebSocket::Handshake::Extension::parameters() returns). This operation should configure the object to return the proper value from its ok_to_use() method.

• ok_to_use() A boolean that indicates whether the peer indicates proper support for the extension. This should not be called until after consume_parameters().

$sp_token = OBJ->get_subprotocol()

Returns the negotiated subprotocol’s token (e.g., wamp.2.json).

OBJ->consume_headers( HDR1 => VAL1, HDR2 => VAL2, .. )

The “workhorse” method of this base class. Takes in the HTTP headers and verifies that the look as they should, setting this object’s own internals as appropriate.

This will throw an appropriate exception if any header is missing or otherwise invalid.

my $hdrs_txt = OBJ->to_string( %OPTS )

The text of the HTTP headers to send, with the 2nd trailing CR/LF that ends the headers portion of an HTTP message.

If you use this object to negotiate a subprotocol and/or extensions, those will be included in the output from this method.

%OPTS can be:

• headers - an array reference of key/value pairs. For example:

      [
          Authorization => 'Basic Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==',
          'X-Custom'    => 'some value',
      ]

LEGACY INTERFACE

Prior to version 0.5 this module was a great deal less “helpful”: it required callers to parse out and write WebSocket headers, doing most of the validation manually. Version 0.5 added a generic interface for entering in HTTP headers, which allows Net::WebSocket to handle the parsing and creation of HTTP headers as well as subprotocol and extension negotiation.

For now the legacy functionality is being left in; however, it is considered DEPRECATED and will be removed eventually.

my $hdrs_txt = OBJ->create_header_text()

The same output as to_string() but minus the 2nd trailing CR/LF. (This was intended to facilitate adding other headers; however, that’s done easily enough with the newer to_string().)

SEE ALSO

• Net::WebSocket::Handshake::Client

• Net::WebSocket::Handshake::Server