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.

my $hdrs_txt = OBJ->to_string()

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.

To append custom headers, do the following with the result of this method:

substr($hdrs_txt, -2, 0) = '..';

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