<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;">=encoding utf-8

=head1 NAME

Net::WebSocket - WebSocket in Perl

=head1 SYNOPSIS

    use Net::WebSocket::Handshake::Client ();
    use Net::WebSocket::HTTP_R ();

    my $handshake = Net::WebSocket::Handshake::Client-&gt;new(
        uri =&gt; $uri,
    );

    syswrite $inet, $handshake-&gt;to_string() or die $!;

    #You can parse HTTP headers however you want;
    #Net::WebSocket makes no assumptions about this.
    my $resp = HTTP::Response-&gt;parse($hdrs_txt);

    #If you use an interface thatâs compatible with HTTP::Response,
    #then you can take advantage of this convenience function;
    #otherwise youâll need to do a bit more work.
    Net::WebSocket::HTTP_R::handshake_parse_response( $handshake, $resp );

    #See below about IO::Framed
    my $parser = Net::WebSocket::Parser-&gt;new(
        IO::Framed-&gt;new($inet),
    );

    my $iof_w = IO::Framed-&gt;new($inet);

    my $ept = Net::WebSocket::Endpoint::Client-&gt;new(
        parser =&gt; $parser,
        out =&gt; $iof_w,
    );

    $iof_w-&gt;write(
        Net::WebSocket::Frame::text-&gt;new( payload =&gt; 'Hello, world' )
    );

    #Determine that $inet can be read from âŚ

    my $msg = $ept-&gt;get_next_message();

    #âŚ or, if we timeout while waiting for $inet to be ready for reading:

    $ept-&gt;check_heartbeat();
    exit if $ept-&gt;is_closed();

=head1 BETA QUALITY

This is a beta release. It should be safe for production, but there could
still be small changes to the API. Please check the changelog before
upgrading.

=head1 DESCRIPTION

This distribution provides a set of fundamental tools for communicating via
L&lt;WebSocket|https://tools.ietf.org/html/rfc6455&gt;.
It is only concerned with the protocol itself;
the underlying transport mechanism is up to you: it could be a file,
a UNIX socket, ordinary TCP/IP, some funky C&lt;tie()&gt;d object, or whatever.

Net::WebSocket also âhas no opinionsâ about how you should do I/O or HTTP
headers. There are too many different ways to accomplish HTTP header
management in particular for it to be sensible for a WebSocket library to
impose any one approach. As a result of this, Net::WebSocket can probably
fit your project with minimal overhead. There are some examples
of how you might write complete applications (client or server)
in the distributionâs F&lt;demo/&gt; directory.

Net::WebSocket emphasizes flexibility and lightness rather than the more
monolithic approach in modules like L&lt;Mojolicious&gt;.
Net::WebSocket should support anything
that the WebSocket protocol itself can do, as lightly as possible and without
prejudice as to how you want to do it: extensions, blocking/non-blocking I/O,
arbitrary HTTP headers, etc. Net::WebSocket will likely require more of an
investment up-front, but the end result should be a clean, light
implementation that will grow (or shrink!) as your needs dictate.

=head1 OVERVIEW

Here are the main modules:

=over

=item L&lt;Net::WebSocket::Handshake::Server&gt;

=item L&lt;Net::WebSocket::Handshake::Client&gt;

Logic for handshakes. Every application needs one of these. As of version
0.5 this handles all headers and can also do
subprotocol and extension negotiation for you.

=item L&lt;Net::WebSocket::HTTP_R&gt;

A thin convenience wrapper for L&lt;HTTP::Request&gt; and L&lt;HTTP::Response&gt;,
CPANâs âstandardâ classes to represent HTTP requests and responses.
Net::WebSocket::HTTP_R should also work with other classes whose
interfaces are compatible with these âstandardâ ones.

=item L&lt;Net::WebSocket::Endpoint::Server&gt;

=item L&lt;Net::WebSocket::Endpoint::Client&gt;

A high-level abstraction to parse input
and respond to control frames and timeouts. You can use this to receive
streamed (i.e., fragmented) transmissions as well. You donât have to use
this module, but it will make your life easier.

=item L&lt;Net::WebSocket::Parser&gt;

Translate WebSocket frames out of a filehandle into useful data for
your application.

=item Net::WebSocket::Frame::*

Useful for creating raw frames. For data frames (besides continuation),
these will be your bread-and-butter. See L&lt;Net::WebSocket::Frame::text&gt;
for sample usage.

=item L&lt;Net::WebSocket::Streamer::Server&gt;

=item L&lt;Net::WebSocket::Streamer::Client&gt;

Useful for sending streamed (fragmented) data rather than
a full message in a single frame.

=back

=head1 IMPLEMENTATION NOTES

=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&lt;Net::WebSocket::HTTP_R&gt; might
be able to do this for you.)

=head2 Masking

As per L&lt;the specification|https://tools.ietf.org/html/rfc6455#section-5.1&gt;,
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&lt;Bytes::Random::Secure::Tiny&gt;, 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&lt;rand()&gt;
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&lt;IO::Framed&gt;

CPANâs L&lt;IO::Framed&gt; 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&lt;IO::Framed&gt; 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&lt;Net::WebSocket::Frame&gt;.) This is used, e.g., in the
L&lt;permessage-deflate extension|https://tools.ietf.org/html/rfc7692&gt;.

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

B&lt;THIS IS NOT WELL TESTED.&gt; 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&lt;Net::WebSocket::PMCE::deflate&gt; 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&lt;Mojolicious&gt; is probably CPANâs easiest WebSocket implementation to get
a server up and running. If youâre building a project from scratch, you
may find this to be a better fit for you than Net::WebSocket.

L&lt;Protocol::WebSocket&gt; 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&lt;Net::WebSocket::Server&gt; implements only server behaviors and
gives you more automation than P::WS.

L&lt;Net::WebSocket::EV&gt; uses XS to call a C library.

=head1 REPOSITORY

L&lt;https://github.com/FGasper/p5-Net-WebSocket&gt;

=head1 AUTHOR

Felipe Gasper (FELIPE)

=head1 COPYRIGHT

Copyright 2017 by L&lt;Gasper Software Consulting, LLC|http://gaspersoftware.com&gt;

=head1 LICENSE

This distribution is released under the same license as Perl.

</pre></body></html>