view release on metacpan or  search on metacpan

lib/Net/WebSocket/Handshake/Client.pm  view on Meta::CPAN

    $hsk->consume_headers( NAME1 => VALUE1, .. );

=head1 DESCRIPTION

This class implements WebSocket handshake logic for a client.
It handles the basics of handshaking and, optionally, subprotocol
and extension negotiation.

It is a subclass of L<Net::WebSocket::Handshake>.

=cut

use strict;
use warnings;

use parent qw( Net::WebSocket::Handshake );

use URI::Split ();

use Net::WebSocket::Constants ();
use Net::WebSocket::X ();

use constant SCHEMAS => (
    'ws', 'wss',
    'http', 'https',
);

=head1 METHODS

=head2 I<OBJ>->new( %OPTS )

Returns an instance of the class; %OPTS includes the options from
L<Net::WebSocket::Handshake> as well as:

=over

=item * C<uri> - (required) The full URI you’re connecting to.

=item * C<origin> - (optional) The HTTP Origin header’s value. Useful
for imitating a web browser.

=back

=cut

sub new {
    my ($class, %opts) = @_;

    if (length $opts{'uri'}) {
        @opts{ 'uri_schema', 'uri_auth', 'uri_path', 'uri_query' } = URI::Split::uri_split($opts{'uri'});
    }

    if (!$opts{'uri_schema'} || !grep { $_ eq $opts{'uri_schema'} } SCHEMAS()) {
        die Net::WebSocket::X->create('BadArg', uri => $opts{'uri'});
    }

    if (!length $opts{'uri_auth'}) {
        die Net::WebSocket::X->create('BadArg', uri => $opts{'uri'});
    }

    @opts{ 'uri_host', 'uri_port' } = split m<:>, $opts{'uri_auth'};

    $opts{'key'} ||= _create_key();

    return $class->SUPER::new(%opts);
}

=head2 I<OBJ>->valid_status_or_die( CODE, REASON )

Throws an exception if the given CODE isn’t the HTTP status code (101)
that WebSocket requires in response to all requests. (REASON is included
with the exception on error; otherwise it’s unused.)

You only need this if if you’re not using a request-parsing interface
that’s compatible with L<HTTP::Response>; otherwise,
L<Net::WebSocket::HTTP_R>’s C<handshake_consume_response()> function
will do this (and other niceties) for you.

=cut

sub valid_status_or_die {
    my ($self, $code, $reason) = @_;

    if ($code ne Net::WebSocket::Constants::REQUIRED_HTTP_STATUS()) {
        die Net::WebSocket::X->create('BadHTTPStatus', $code, $reason);
    }

    return;
}

#Shouldn’t be needed?
sub get_key {
    my ($self) = @_;

    return $self->{'key'};
}

#----------------------------------------------------------------------
#Legacy:

=head1 LEGACY INTERFACE: SYNOPSIS

    my $hsk = Net::WebSocket::Handshake::Client->new(

        #..same as the newer interface, except:

        #optional
        extensions => \@extension_objects,
    );

    print $hsk->create_header_text() . "\x0d\x0a";

    #...Parse the response’s headers yourself...

    #Validates the value of the “Sec-WebSocket-Accept” header;
    #throws Net::WebSocket::X::BadAccept if not.
    $hsk->validate_accept_or_die($accept_value);

=cut

sub validate_accept_or_die {