view release on metacpan or  search on metacpan

README.pod  view on Meta::CPAN

=head2 Handshakes

WebSocket uses regular HTTP headers for its handshakes. Because there are
many different solutions around for parsing HTTP headers, Net::WebSocket
is “agnostic” about how that’s done. The advantage is that if you’ve got
a custom solution for parsing headers then Net::WebSocket can fit into
that quite easily.

The liability of this is that you, the library user, must give headers
directly to your Handshake object. (NB: L<Net::WebSocket::HTTP_R> might
be able to do this for you.)

=head2 Masking

As per L<the specification|https://tools.ietf.org/html/rfc6455#section-5.1>,
client serializers “MUST” mask the data randomly, whereas server serializers
“MUST NOT” do this. Net::WebSocket does this for you automatically,
but you need to distinguish
between client serializers—which mask their payloads—and server serializers,
which don’t mask.

This module used to do this with L<Bytes::Random::Secure::Tiny>, but
that seems like overkill given that the masking is only there to accommodate
peculiarities of certain proxies. We now just use Perl’s C<rand()>
built-in.

(You should probably use TLS if cryptographically secure masking is something
you actually care about?)

=head2 Text vs. Binary

Recall that in some languages—like JavaScript!—the difference between
“text” and “binary” is much more significant than for us in Perl.

=head2 Use of L<IO::Framed>

CPAN’s L<IO::Framed> provides a straightforward interface for chunking up
data from byte streams into frames. It also provides a write buffer for
non-blocking writes, and it retries on EINTR. You don’t have to use it
(which is why it’s not listed as a requirement), but you’ll need to provide
a compatible interface if you don’t.

See the demo scripts that use L<IO::Framed> for an example of when you may
need a different solution here.

=head1 EXTENSION SUPPORT

The WebSocket specification describes several methods of extending the
protocol, all of which Net::WebSocket supports:

=over

=item * The three reserved bits in each frame’s header.
(See L<Net::WebSocket::Frame>.) This is used, e.g., in the
L<permessage-deflate extension|https://tools.ietf.org/html/rfc7692>.

=item * Additional opcodes: 3-7 and 11-15. You’ll need to subclass
L<Net::WebSocket::Frame> for this, and you will likely want to subclass
L<Net::WebSocket::Parser>.
If you’re using the custom classes for streaming, then you can
also subclass L<Net::WebSocket::Streamer>. See each of those modules for
more information on doing this.

B<THIS IS NOT WELL TESTED.> Proceed with caution, and please file bug
reports as needed. (I personally don’t know of any applications that
actually use this.)

=item * Apportion part of the payload data for the extension. This you
can do in your application.

=back

=head2 permessage-deflate

Net::WebSocket 0.5 introduces support for the permessage-delate extension
to allow compressed messages over WebSocket. See
L<Net::WebSocket::PMCE::deflate> for more details.

=head1 TODO

At this point Net::WebSocket should support every widely implemented
WebSocket feature.

=over

=item * Add more tests.

=back

=head1 SEE ALSO

L<Mojolicious> has a WebSocket implementation. It’s not as complete as
Net::WebSocket, but if you’re using Mojolicious, you might try this first.

L<Protocol::WebSocket> is an older module that supports
pre-standard versions of the WebSocket protocol. It’s similar to this one
in that it gives you just the protocol itself, but it doesn’t give you
things like automatic ping/pong/close, classes for each message type, etc.

L<Net::WebSocket::Server> implements only server behaviors and
gives you more automation than P::WS.

L<Net::WebSocket::EV> uses XS to call L<wslay|http://wslay.sourceforge.net>.
As of this writing it lacks support for handshake logic.

=head1 REPOSITORY

L<https://github.com/FGasper/p5-Net-WebSocket>

=head1 AUTHOR

Felipe Gasper (FELIPE)

=head1 COPYRIGHT

Copyright 2017 by L<Gasper Software Consulting|http://gaspersoftware.com>

=head1 LICENSE

This distribution is released under the same license as Perl.