The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
WebSocket-v0.2.0
River stage zero No dependents
/ WebSocket::Request

NAME

WebSocket::Request - WebSocket Request

SYNOPSIS

    use WebSocket::Request;
    my $req = WebSocket::Request->new(
        host        => 'example.com',
        uri         => '/demo'
        protocol    => 'com.example.chat',
    ) || die( WebSocket::Request->error, "\n" );
    # or
    my $req = WebSocket::Request->new( $headers, $buffer, host => 'example.com', origin => 'https://example.com');
    my $req = WebSocket::Request->new( $headers, $buffer, { host => 'example.com', origin => 'https://example.com' });
    my $req = WebSocket::Request->new( $headers, host => 'example.com', origin => 'https://example.com');
    my $req = WebSocket::Request->new( $headers, { host => 'example.com', origin => 'https://example.com' });
    $req->as_string;
    # GET /demo HTTP/1.1
    # Upgrade: WebSocket
    # Connection: Upgrade
    # Host: example.com
    # Origin: http://example.com
    # Sec-WebSocket-Key1: 32 0  3lD& 24+<    i u4  8! -6/4
    # Sec-WebSocket-Key2: 2q 4  2  54 09064
    # Set-WebSocket-Version: 13
    #
    # x#####

    # Parser
    my $req = WebSocket::Request->new;
    $req->parse( <<EOT );
    GET /demo HTTP/1.1
    Upgrade: WebSocket
    Connection: Upgrade
    Host: example.com
    Origin: http://example.com
    Sec-WebSocket-Key1: 18x 6]8vM;54 *(5:  {   U1]8  z [  8
    Sec-WebSocket-Key2: 1_ tx7X d  <  nw  334J702) 7]o}` 0
    Set-WebSocket-Version: 13
    
    Tm[K T2u
    EOT

VERSION

    v0.1.1

DESCRIPTION

Class to build or parse a WebSocket request. It inherits all the methods from WebSocket::Common. For convenience, they are all listed here.

CONSTRUCTOR

new

    my $req = WebSocket::Request->new( $headers, $buffer,
        uri => 'wss://example.com/chat',
        subprotocol => 'com.example.chat'
    );
    my $req = WebSocket::Request->new( $headers, $buffer, {
        uri => 'wss://example.com/chat',
        subprotocol => 'com.example.chat'
    });
    my $req = WebSocket::Request->new( $headers,
        uri => 'wss://example.com/chat',
        subprotocol => 'com.example.chat'
    );
    my $req = WebSocket::Request->new( $headers, {
        uri => 'wss://example.com/chat',
        subprotocol => 'com.example.chat'
    });

Provided with an optional set of headers, as either an array reference or a HTTP::Headers object, some optional content and an hash or hash reference of parameters, and this instantiates a new WebSocket::Request object. The supported parameters are as follow. Each parameter can be set or changed later using the method with the same name:

buffer

Content buffer

cookies

A Cookie request header string. The string provided must be already properly formatted and encoded and will be added as is. For example:

    WebSocket::Request->new(
        cookies => q{lang=en-GB; access_token=eyJwMnMiOiJtaGpZQ3ZqeHZ3TVJrTFY1WGREaHJ3jiwiZXhwIjoxNjMxOTQ5NTc5LCJwMmMiOjUwMDAsImFsZyI6IlBCRVMyLUhTMjy2K0ExMjhLVyIsImVuYyI6IkExMjhlQ00ifQ.E522SASh8v_TIwVLO4RmIS3D76iO0Lqr.29IifZxeNjEoqRjw.x5_em7jOCABhXRJKN8-IFk0YLLXPGZecmWJujQxmTzgaCf9y-6AZhzRWoIfwUkjeZvqfTwvUJwrcHxePznJ7_HYCLUmEjRgHJMQ0c9OBStSJhSSKYtzwR3J3N_PpmcdEtWRWN1SPlnHp9aoLHHgmBSKQpuqNb9Rdkw7-XhAyznx9bMEehZUae1rmBtNRzlGtKyInBUF9iv03zETrCkdfVt2-0IGkkQ.qMayqY2qoKybazs6pntIpw},
        host    => 'example.com'
    );
headers

Either an array reference of header-value pairs, or an HTTP::Headers object.

If an array reference is provided, an HTTP::Headers object will be instantiated with it.

host

The Host header value.

max_message_size

Integer. Defaults to 20Kb. This is the maximum payload size.

number1

Value for key1 as used in protocol version 0 to 3 of WebSocket requests.

number2

Value for key2 as used in protocol version 0 to 3 of WebSocket requests.

origin

The Origin header value.

See rfc6454

protocol

HTTP/1.1. This is the only version supported by rfc6455

secure

Boolean. This is set to true when the connection is using ssl (i.e. wss), false otherwise.

subprotocol

The optional subprotocol which consists of multiple arbitrary identifiers that need to be recognised and supported by the server.

    WebSocket::Request->new(
        subprotocol => 'com.example.chat',
    );
    # or
    WebSocket::Request->new(
        subprotocol => [qw( com.example.chat com.example.internal )],
    );

See rfc6455

uri

The request uri, such as /chat or it could also be a fully qualified uri such as wss://example.com/chat?csrf_token=7a292e44341dc0a052d717980563fa4528dc254bc80f3e735303ed710b764143.1631279571

version

The WebSocket protocol version. Defaults to draft-ietf-hybi-17

See rfc6455

METHODS

as_string

Provided with an optional line terminator and this returns a string version of the request, based on all the parameters set in the object.

buffer

Set or get the content buffer.

challenge

Sets or gets the challenge returned to the client.

checksum

Sets or gets the checksum. If a checksum is provided, it returns the current object.

If no checksum is provided, it will compute one based on the value of "number1", "number2" and "challenge". It returns the checksum as a regular string.

connection

Set or get the Connection header value, which should typically be Upgrade.

This method serves to contain a cookie jar object of client-sent cookies, i.e. the ones returned by the web browser.

You can set whatever class object you want.

If no class object is provided, then this will try to load Cookie::Jar if it is installed and will load into it all cookies found in the current request.

It returns the current value set, and if no cookie jar object was set, but this method is called in object context (such as chaining), then this will return a Module::Generic::Null object to avoid a perl error.

cookies

Set or get the cookies string to be used in the Cookie request header.

This is a short-cut for "header" in WebSocket::Headers

headers

Set or get the HTTP::Headers object. If none is set, and this method is accessed, a new one will be instantiated.

headers_as_string

Calls as_string on HTTP::Headers and returns its value.

host

Set or get the Host header value.

is_done

Set or get the boolean value. This is set to signal the parsing is complete.

key

Value of header Sec-WebSocket-Key available in protocol version 4 to 17.

key1

Value of header Sec-WebSocket-Key1 available in protocol version 0 to 3.

key2

Value of header Sec-WebSocket-Key2 available in protocol version 0 to 3.

method

The http method used, such as GET

number1

This is a default method to store a number used for the checksum challenge sent to the client.

number2

This is a default method to store a number used for the checksum challenge sent to the client.

origin

Set or get the Origin header value.

See rfc6455 section 1.3 for more information and section 4.1, paragraph 8

parse

    my $rv = $req->parse( $some_request_data ) ||
        die( $req->error );

Provided with some request content buffer and this will parse it using HTTP::Headers for the headers and the body with this module.

It returns undef and set an error object upon failure, and returns the current object on success.

parse_body

This method is kind of a misnomer because it actually performs header-parsing post processing mostly. It does some body processing for earlier version of the protocol when the handshake challenge was in the body rather than in the header.

It also tries to find out the protocol version used by the other party.

Returns the current object used.

protocol

Set or get the protocol used. Typically HTTP/1.1. This is set upon parsing. You should not have to set this yourself.

secure

Boolean value. True if the connection is using ssl, i.e. wss

subprotocol

Set or get an array object (Module::Generic::Array) of subprotocols.

See rfc6455 for more information

upgrade

Set or get the Upgrade request header value, which should typically be websocket

uri

Set or get the request uri. This returns a URI object.

version

Set the protocol version.

See rfc6455 section 4.1 for more information

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

WebSocket::Response, WebSocket::Headers, WebSocket::Common

COPYRIGHT & LICENSE

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.