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.

cpanm Protocol::WebSocket::Fast

perl -MCPAN -e shell
install Protocol::WebSocket::Fast