/ 
Protocol-WebSocket-Fast-1.2.4
River stage one • 1 direct dependent • 1 total dependent
/ Protocol::WebSocket::Fast

NAME

Protocol::WebSocket::Fast - very fast WebSocket protocol implementation

SYNOPSIS

use Protocol::WebSocket::Fast::ClientParser;
use Protocol::WebSocket::Fast::ServerParser;

my $client = Protocol::WebSocket::Fast::ClientParser->new;
my $req_str = $client->connect_request({
    uri           => "ws://example.com/",
    ws_protocol   => "chat",
    ws_extensions => [ [ 'permessage-deflate'] ],
});

my $server = Protocol::WebSocket::Fast::ServerParser->new;
my $req    = $server->accept($req_str);

my $accept_reply_str = $req->error ? $server->accept_error : $server->accept_response;
my $reply = $client->connect($accept_reply_str);   # => isa 'Protocol::WebSocket::Fast::ConnectResponse'
$client->established;
$client->is_deflate_active;

# control frames
my $data = $client->send_control(OPCODE_PING, "hello");
my ($frame) = $server->get_frames($data);

$frame->payload;        # 'hello'
$frame->payload_length; # 5
$frame->is_control;     # true
$frame->opcode;         # OPCODE_PING
$frame->final;          # true

# send message split by frame
my $sender = $server->start_message(opcode => OPCODE_TEXT, final => 0, deflate => 0);
my $data1 = $sender->send("Lorem ");
my $data2 = $sender->send("ipsum ");
my $data3 = $sender->send("dolor ", 1); # final frame

my ($message) = $client->get_messages($data);

$message->opcode;                         # OPCODE_TEXT
$message->is_control;                     # 0
$message->payload_length;                 # 18
$message->payload;                        # 'Lorem ipsum dolor '
$message->frame_count;                    # 3

# convenient way just to send message
my $data = $client->send_message(deflate => 1, payload => 'sit amet, ');

# pieces merged into single frame/message
my $data = $client->send_message(deflate => 0, payload => ['consectetur ', 'adipiscing ', 'elit.']);

# iterator api
my $it = $server->get_frames($data);
while (my $frame = $it->next) { ... }

# pieces are send as frames; a bit faster, when you already have your data and compression is turned off
my $data = $client->send_message_multiframe(deflate => 0, payload => \@data);
my $it = $server->get_messages($data_7);
my $message = $it->next;
$message->frame_count; # 3

# server/client configuration
$client->configure({
    max_frame_size     => 1024 * 10,
    max_message_size   => 1024 * 100,
    max_handshake_size => 1024 * 5,
    deflate            => {             # always on by default
        compression_threshold => 0,     # compress all TEXT-frames
    },
});

# completely disable compression; effective before connection establishment
$client->no_deflate;

DESCRIPTION

Protocol::WebSocket::Fast is a port of panda::protocol::websocket, extremely fast server/client zero-copy incremental WebSocket parser and serialization library (rfc6455) with Perl and C++ interface.

The library supports compression (a.k.a. per-message deflate extension, see rfc7692) via zlib C library, which is enabled by default for all text messages exceeding TCP max segment size (1410 bytes).

The module has dual Perl/C++ interface (see XS::Manifesto) so further XS-bindings can be written on the top of Protocol::WebSocket::Fast (see UniEvent::WebSocket).

Protocol::WebSocket::Fast is not drop-in replacement of <Protocol::WebSocket>, as it uses different API.

Protocol::WebSocket::Fast fully conforms to RFC and passes all autobahn tests.

PERFORMANCE

Compared to Protocol::WebSocket. Tests were performed on Xeon v3-2687W 2.9Ghz, Debian 10.

Parsing websocket packet with 200 bytes payload.

                             Rate   Protocol::WebSocket  Protocol::WebSocket::Fast
Protocol::WebSocket       68593/s                     --                    -97%
Protocol::WebSocket::Fast 2360644/s                  3342%                      --

CONSTANTS

Opcodes

OPCODE_CONTINUE
OPCODE_TEXT
OPCODE_BINARY
OPCODE_CLOSE
OPCODE_PING
OPCODE_PONG

Close codes

CLOSE_DONE
CLOSE_AWAY
CLOSE_PROTOCOL_ERROR
CLOSE_INVALID_DATA
CLOSE_UNKNOWN
CLOSE_ABNORMALLY
CLOSE_INVALID_TEXT
CLOSE_BAD_REQUEST
CLOSE_MAX_SIZE
CLOSE_EXTENSION_NEEDED
CLOSE_INTERNAL_ERROR
CLOSE_TLS

REFERENCE

Protocol::WebSocket::Fast::ClientParser

Protocol::WebSocket::Fast::ServerParser

Protocol::WebSocket::Fast::Parser

Protocol::WebSocket::Fast::ConnectRequest

Protocol::WebSocket::Fast::ConnectResponse

Protocol::WebSocket::Fast::Message

Protocol::WebSocket::Fast::MessageIterator

Protocol::WebSocket::Fast::Frame

Protocol::WebSocket::Fast::FrameIterator

Protocol::WebSocket::Fast::FrameSender

Protocol::WebSocket::Fast::Error

SEE ALSO

rfc6455

rfc7692

Protocol::HTTP

Protocol::WebSocket

AUTHOR

Pronin Oleg <syber@cpan.org>, Crazy Panda LTD

Ivan Baidakou <dmol@cpan.org>, Crazy Panda LTD

LICENSE

You may distribute this code under the same terms as Perl itself.