The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WebSocket-v0.1.2
River stage zero No dependents
2 ++
/ WebSocket::Connection

NAME

WebSocket::Connection - WebSocket Server Connection

SYNOPSIS

    use WebSocket qw( :ws );
    use WebSocket::Connection;
    my $conn = WebSocket::Connection->new(
        max_recv_size   => 65536,
        max_send_size   => 65536,
        nodelay         => 1,
        on_binary       => \&on_binary_message,
        on_disconnect   => \&on_close,
        on_handshake    => \&on_handshake,
        on_origin       => \&on_origin,
        on_pong         => \&on_pong,
        on_ready        => \&on_ready,
        on_utf8         => \&on_utf8_message,
        # required
        server          => $websocket_server_object,
        # required
        socket          => $net_socket_object,
    ) || die( WebSocket::Connection->error, "\n" );

    $conn->disconnect( WS_INTERNAL_SERVER_ERROR, 'Something bad happened' );

VERSION

    v0.1.0

DESCRIPTION

Class initiated by WebSocket::Server for each connection received.

METHODS

disconnect

    $conn->disconnect( WS_INTERNAL_SERVER_ERROR, 'Something bad happened' );

Provided with a code and a reason, and this will disconnect from the WebSocket and terminate the client connection.

It returns the current object.

disconnected

Set or get a boolean value representing the connection status to the remote client socket.

There are 2 status: disconnecting and disconnected. The former is set when the server has issued a disconnection message to the remote client and is waiting for the client to acknowledge it, as per the WebSocket protocol, and the latter is set when the connection is effectively shut down.

disconnecting

Set or get the boolean value indicating the connection is disconnecting.

frame

Returns the connection frame object.

handshake

Set or get the handshake object (WebSocket::Handshake::Server)

This object is instantiated upon instantiation of connection object, so there is no need to create it.

http_error

    $conn->http_error( 426 );
    $conn->http_error( 426, "Upgrade Required" );
    $conn->http_error( 426, "Upgrade Required", "Oh no!" );
    $conn->http_error( 426, "Upgrade Required", "Oh no!", [] );
    $conn->http_error( 426, "Upgrade Required", "Oh no!",
        HTTP::Headers->new(
            Content_Language => "en_GB",
            Cache_Control    => "no-cache"
        )
    );

Provided with an http status code, an optional status line, some optional content and some optional headers and this will push out on the socket the server error.

This method is meant to respond to the client handshake with a proper http error when required, such as if the version or host is missing in the request.

It will return an error if this method is called after a successful handshake has occurred. Otherwise, it returns the return value from "syswrite" in perlfunc which is the number of bytes writen

ip

Set or get the remote ip address of the client connected.

is_ready

Returns true once the handshake has been performed, false otherwise.

max_recv_size

Set or get the maximum bytes that can be received in one time.

max_send_size

Set or get the maximum bytes that can be sent in one time.

needs_ssl

Returns true if the server is using ssl, false otherwise.

nodelay

Set the client socket option TCP_NODELAY to true or false.

Returns the currently set boolean value.

on

Provided with an array or array reference of event name and core reference pairs and this will set those event handlers.

It returns the current object.

on_binary

Set or get the code reference that is triggered when a binary message is received from the client.

The event handler is then passed the current connection object and the message itself.

on_disconnect

Set or get the code reference that is triggered when the connection is closed.

The event handler is then passed the current connection object.

on_handshake

Event handler called after the handshake between the client and the server has been performed.

The handler is passed this connection object (WebSocket::Connection and the handshake object (WebSocket::Handshake)

You can get the requested uri using "request_uri", which will return a URI object.

on_origin

Event handler called during the handshake between the client and the server. This is a convenient handler so that the caller can be called with the client submitted origin and decide to accept it by returning true, or reject it by return false.

on_pong

Event handler called when a ping is received from the client.

The event handler is then passed the current connection object.

See rfc6455 for more on this

on_ready

Event handler called when the connection is ready.

The event handler is then passed the current connection object.

on_utf8

Event handler called when a text message is received from the client.

The event handler is then passed the current connection object and the message itself, after having been utf8 decoded.

origin

Set or get the origin of the client as set in the request header.

port

Set or get the port number on which the remote client is connected.

recv

Attempts to read chunks of 8192 bytes of data from the client "socket"

If the handshake has not been done yet, it will be performed and the "on_handshake" handler called and the "on_ready" handler as well.

Then, based on the type of data received, it will trigger the "on_binary" for binary message, "on_utf8" for text message, "on_pong" if this is a pong.

request_uri

Returns a URI object representing the uri been requested by the client. For example, a request such as:

    GET /?csrf=7a292e3.1631279571 HTTP/1.1
    Upgrade: WebSocket
    Connection: Upgrade
    Host: localhost:8080
    Origin: http://localhost:8082
    Sec-WebSocket-Key: XcCcHD+q7fmfqRSnPJA9Lg==
    Sec-WebSocket-Version: 13

would result maybe in the uri being wss://localhost:8080/?csrf=7a292e3.1631279571 assuming the server is using SSL.

send

Sends data to the client socket.

Be careful this will return an error if you attempt to send data before the handshake is completed, so you need to check "is_ready"

It returns the number of bytes actually written to the socket.

send_binary

Provided with some data, and this will send the binary message to the client socket.

send_utf8

Provided with some text message, and this will utf8 encode it using "encode" in Encode and send it to the client socket.

server

Set or get the WebSocket::Server object.

shutdown

Terminate the client connection by calling "disconnect" in WebSocket::Server passing it the current connection socket. This does not terminate the server connection itself. For this, check "shutdown" in WebSocket::Server.

socket

Set or get the IO::Socket (or one of its inheriting package such as IO::Socket::INET) object.

subprotocol

Set or get an array object of WebSocket protocols and set the WebSocket header Sec-WebSocket-Protocol.

Returns a Module::Generic::Array object.

See rfc6455 for more information

CREDITS

Graham Ollis for AnyEvent::WebSocket::Client, Eric Wastl for Net::WebSocket::Server, Vyacheslav Tikhanovsky aka VTI for Protocol::WebSocket

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

perl

COPYRIGHT & LICENSE

Copyright(c) 2021 DEGUEST Pte. Ltd. DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.