Net::WebSocket::Parser - Parse WebSocket from a filehandle
my $iof = IO::Framed->new($fh); my $parse = Net::WebSocket::Parser->new($iof); #See below for error responses my $frame = $parse->get_next_frame();
$iof should normally be an instance of IO::Framed::Read. You’re free to pass in anything with a read() method, but that method must implement the same behavior as IO::Framed::Read::read().
$iof
read()
IO::Framed::Read::read()
A call to this method yields one of the following:
If a frame can be read, it will be returned.
If we hit an empty read (i.e., indicative of end-of-file), empty string is returned.
If only a partial frame is ready, undef is returned.
IO::Framed was born out of work on this module; see that module’s documentation for the particulars of working with it. In particular, note the exceptions IO::Framed::X::EmptyRead and IO::Framed::X::ReadError.
Again, you can use an equivalent interface for frame chunking if you wish.
An empty read is how we detect that a file handle (or socket, etc.) has no more data to read. Generally we shouldn’t get this in WebSocket since it means that a peer endpoint has gone away without sending a close frame. It is thus recommended that applications regard an empty read on a WebSocket stream as an error condition; e.g., if you’re using IO::Framed::Read, you should NOT enable the allow_empty_read() behavior.
allow_empty_read()
Nevertheless, this module (and Net::WebSocket::Endpoint) do work when that flag is enabled.
To support reception of custom frame types you’ll probably want to subclass this module and define a specific custom constant for each supported opcode, e.g.:
package My::WebSocket::Parser; use parent qw( Net::WebSocket::Parser ); use constant OPCODE_CLASS_3 => 'My::WebSocket::Frame::booya';
… where My::WebSocket::Frame::booya is itself a subclass of Net::WebSocket::Base::DataFrame.
My::WebSocket::Frame::booya
Net::WebSocket::Base::DataFrame
You can also use this to override the default classes for built-in frame types; e.g., OPCODE_CLASS_10() will override Net::WebSocket::Frame::pong as the class will be used for pong frames that this module receives. That could be useful, e.g., for compression extensions, where you might want the get_payload() method to decompress so that that detail is abstracted away.
OPCODE_CLASS_10()
get_payload()
To install Net::WebSocket, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::WebSocket
CPAN shell
perl -MCPAN -e shell install Net::WebSocket
For more information on module installation, please visit the detailed CPAN module installation guide.