WebSocket::Connection - WebSocket Server Connection
use WebSocket qw( :ws ); use WebSocket::Connection; my $conn = WebSocket::Connection->new( do_pong => \&pong, 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_ping => \&on_ping, 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' );
v0.1.2
Class initiated by WebSocket::Server for each connection received.
Instantiate a new WebSocket::Connection object. It takes an hash or hash reference of options. Each option matches their corresponding method described below. See each of their documentation for more information.
$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.
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
disconnected
Set or get the boolean value indicating the connection is disconnecting.
Set or get the code reference used to issue a pong. By default this is set to "pong"
pong
Returns the connection frame object.
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.
$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
Set or get the remote ip address of the client connected.
Returns true once the handshake has been performed, false otherwise.
Set or get the maximum bytes that can be received in one time.
Set or get the maximum bytes that can be sent in one time.
Returns true if the server is using ssl, false otherwise.
Set the client socket option TCP_NODELAY to true or false.
TCP_NODELAY
Returns the currently set boolean value.
Provided with an hash or hash reference of event name and core reference pairs and this will set those event handlers.
For acceptable event name, check out the supported methods starting with on_. For example: binary, disconnect, handshake, origin, pong, ready, utf8
on_
binary
disconnect
handshake
origin
ready
utf8
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 binary message itself.
Any fatal error occurring in the callback are caught using try-catch with (Nice::Try), and if an error occurs, this method will raise a warning if warnings are enabled.
Set or get the code reference that is triggered when the connection is closed.
The event handler is then passed the current connection object.
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.
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.
The callback is provided with this connection object, the origine value and the handshake object (WebSocket::Handshake)
A code reference that will be triggered when a ping is received from the WebSocket client.
ping
See "on_ping" and Mozilla documentation on ping and pong
See also "do_pong" to set the code reference to perform a pong
A code reference that will be triggered when a pong is received from the WebSocket client, most likely as a reply to our initial ping.
See rfc6455 for more on this
Event handler called when the connection is ready.
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.
Set or get the origin of the client as set in the request header.
Send a ping to the WebSocket server and returns the value returned by "send". It passes "send" whatever extra argument was provided.
Send a pong to the WebSocket server and returns the value returned by "send". It passes "send" whatever extra argument was provided.
Set or get the port number on which the remote client is connected.
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.
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.
wss://localhost:8080/?csrf=7a292e3.1631279571
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.
Provided with some data, and this will send the binary message to the client socket.
Provided with some text message, and this will utf8 encode it using "encode" in Encode and send it to the client socket.
Set or get the WebSocket::Server object.
Returns the status message provided by the other party.
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.
Set or get the IO::Socket (or one of its inheriting package such as IO::Socket::INET) object.
Set or get an array object of WebSocket protocols and set the WebSocket header Sec-WebSocket-Protocol.
Sec-WebSocket-Protocol
Returns a Module::Generic::Array object.
See rfc6455 for more information
Graham Ollis for AnyEvent::WebSocket::Client, Eric Wastl for Net::WebSocket::Server, Vyacheslav Tikhanovsky aka VTI for Protocol::WebSocket
Jacques Deguest <jack@deguest.jp>
WebSocket::Server, WebSocket::Client
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.
To install WebSocket, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WebSocket
CPAN shell
perl -MCPAN -e shell install WebSocket
For more information on module installation, please visit the detailed CPAN module installation guide.