WebSocket::Client - WebSocket Client
use WebSocket::Client; my $uri = "ws://localhost:8080?csrf=token"; my $ws = WebSocket::Client->new( $uri, { on_binary => \&on_binary, on_connect => \&on_connect, on_disconnect => \&on_disconnect, on_error => \&on_error, on_utf8 => \&on_message, on_recv => \&on_recv, on_send => \&on_send, origin => 'http://localhost', debug => 3, }) || die( WebSocket::Client->error ); $ws->start() || die( $ws->error ); my $stdin = AnyEvent::Handle->new( fh => \*STDIN, on_read => sub { my $handle = shift( @_ ); my $buf = delete( $handle->{rbuf} ); $ws->send_utf8( $buf ); }, on_eof => sub { $ws->disconnect; } );
v0.1.0
This is the WebSocket client class. It contains all the methods and api to connect to a remote WebSocket server and interact with it.
The constructor takes an uri and the following options. If an uri is not provided as a first argument, it can be provided as a uri parameter; see below:
See "compression_threshold"
A Cookie http field header value. It must be properly formatted.
Cookie
Optional. One or more extension enabled for this client. For example permessage-deflate to enable message compression.
permessage-deflate
You can set this to either a string or a WebSocket::Extension object if you want, for example to set the extension parameters.
See rfc6455 section 9.1 for more information on extension.
Seel also "compression_threshold".
A code reference that will be triggered upon a binary message received from the server.
See "on_binary"
A code reference that will be triggered upon successful connection to the remote WebSocket server.
See "on_connect"
A code reference that will be triggered upon the closing of the connection with the server.
See "on_disconnect"
A code reference that will be triggered whenever an error is encountered.
See "on_error"
A code reference that will be triggered just before the handshake procedure is completed.
Be careful, the code reference must return true upon success, or else, it will trigger a handshake failure.
A code reference that will be triggered when a ping is issued.
ping
See "on_ping"
A code reference that will be triggered whenever some text or binary payload data is received from the server.
A code reference that will be triggered whenever data is sent to the remote WebSocket server.
See "on_send"
A code reference that will be triggered whenever text message is sent to the remote WebSocket server.
See "on_utf8"
The origin of the request. See rfc6455 section on opening handshake
origin
An array reference of protocols. They can be arbitrary identifiers and they are optionals.
See rfc6455 section on subprotocol
This can be changed later with "subprotocol"
The uri for the remote WebSocket server.
The version of the WebSocket protocol. For example: draft-ietf-hybi-17
draft-ietf-hybi-17
Inherited from WebSocket
Set or get the threshold in bytes above which the ut8 or binary messages will be compressed if the client and the server support compression and it is activated as an extension.
Initiate the handshake with the server and return the current object.
Before returning, this method will fork a separate process to listen to incoming messages in the background, so as to be non-blocking and return control to the caller.
my $client = WebSocket::Client->new( 'wss://chat.example.org' )->connect || die( WebSocket::Client->error ); # Listener process runs now in the background $client->send( 'Hello !' );
Set or get the Cookie header value.
Close the connection with the server, and return the current object.
Set or get a boolean value representing the connection status to the remote server socket.
There are 2 status: disconnecting and disconnected. The former is set when the client has issued a disconnection message to the remote server and is waiting for the server 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 state of connection to the remote server socket.
This is set to a true value when the client has issued a disconnection notification to the server and is awaiting a response from the server, as per the rfc6455 protocol
Set or get the frame buffer object.
Set or get the handshake object
Set or get the ip of the remote server. This is set once a connection is established.
This method is called by "connect" to listen to incoming message from the server. It is actually called twice. Once during the handshake and once the handshake is completed, the client forks a separate process in which it calls this method to listen to incoming messages.
Takes an integer and set or get the maximum fragments amount.
Takes an integer and set or get the maximum payload size.
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.
Event handler triggered when a binary message is received.
The current client object and the binary message are passed as argument to the event handler.
Event handler triggered when the connection with the server has been made and handshake performed.
The current client object is passed as argument to the event handler.
Event handler triggered when the connection with the server is closed.
Event handler triggered whenever an error occurs.
The current client object and the error message are passed as argument to the event handler.
Event handler triggered just before the handshake sequence is completed.
Be careful that this must return a true value, or else, it will fail the handshake.
Event handler triggered whenever a ping is issued to the server.
Event handler triggered whenever a binary or text payload is received from the server.
The current frame object and the payload data are passed as arguments to the event handler.
$ws->on_recv(sub { my( $frame, $payload ) = @_; if( $frame->is_binary ) { # do something } elsif( $frame->is_text ) { # do something else } });
Event handler triggered whenever a message is sent to the remote server.
The current client object and the message are passed as argument to the event handler.
Event handler triggered whenever a text message is sent to the remote server.
Set or get the origin of the request as a Module::Generic::Scalar object.
Will attempt to read data from the server socket and call all relevant event handlers. It returns the current object.
Sends data to the server socket and returns the current object. This will also trigger associated event handlers.
Returns the current object.
Sends binary data to the server socket and returns the current object. This will also trigger associated event handlers.
Sends data to the server socket after having encoded them using "encode" in Encode> and returns the current object. This will also trigger associated event handlers.
Start listening for possible events on the server socket.
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
Shut down the socket by sending a "shutdown" in IO::Socket command and sets the "disconnected" status to true.
Set or get the remote server socket. This expects the object to be a IO::Socket instance, or an inheriting package.
Set or get the timeout used when issuing messages to the remote server, such as close and waiting for the server response.
close
Returns the uri of the server uri.
See rfc6455 specification
The WebSocket protocol version being used, such as draft-ietf-hybi-17
See rfc6455 about suport for multiple versions
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, rfc6455
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.
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.