WebSocket.pm untested

filter: Statementstmt 0.0% 0 / 1 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a totaltotal 0.0% 0 / 1 SCAR -
1 package Net::WebSocket;
2  
3 our $VERSION = '0.24';
4  
5 =encoding utf-8
6  
7 =head1 NAME
8  
9 Net::WebSocket - WebSocket in Perl
10  
11 =head1 SYNOPSIS
12  
13 use Net::WebSocket::Handshake::Client ();
14 use Net::WebSocket::HTTP_R ();
15  
16 my $handshake = Net::WebSocket::Handshake::Client->new(
17 uri => $uri,
18 );
19  
20 syswrite $inet, $handshake->to_string() or die $!;
21  
22 #You can parse HTTP headers however you want;
23 #Net::WebSocket makes no assumptions about this.
24 my $resp = HTTP::Response->parse($hdrs_txt);
25  
26 #If you use an interface that’s compatible with HTTP::Response,
27 #then you can take advantage of this convenience function;
28 #otherwise you’ll need to do a bit more work.
29 Net::WebSocket::HTTP_R::handshake_parse_response( $handshake, $resp );
30  
31 #See below about IO::Framed
32 my $iof = IO::Framed->new($inet);
33  
34 my $parser = Net::WebSocket::Parser->new($iof);
35  
36 my $ept = Net::WebSocket::Endpoint::Client->new(
37 parser => $parser,
38 out => $iof,
39 );
40  
41 $iof->write(
42 $ept->create_message( 'text', 'Hello, world' )->to_bytes()
43 );
44  
45 #Determine that $inet can be read from …
46  
47 my $msg = $ept->get_next_message();
48  
49 #… or, if we timeout while waiting for $inet to be ready for reading:
50  
51 $ept->check_heartbeat();
52 exit if $ept->is_closed();
53  
54 =head1 BETA QUALITY
55  
56 This is a beta release. It should be safe for production, but there could
57 still be small changes to the API. Please check the changelog before
58 upgrading.
59  
60 =head1 DESCRIPTION
61  
62 This distribution provides a set of fundamental tools for communicating via
63 L<WebSocket|https://tools.ietf.org/html/rfc6455>.
64 It is only concerned with the protocol itself;
65 the underlying transport mechanism is up to you: it could be a file,
66 a UNIX socket, ordinary TCP/IP, some funky C<tie()>d object, or whatever.
67  
68 Net::WebSocket also “has no opinions” about how you should do I/O or HTTP
69 headers. There are too many different ways to accomplish HTTP header
70 management in particular for it to be sensible for a WebSocket library to
71 impose any one approach. As a result of this, Net::WebSocket can probably
72 fit your project with minimal overhead. There are some examples
73 of how you might write complete applications (client or server)
74 in the distribution’s F<demo/> directory.
75  
76 Net::WebSocket emphasizes flexibility and lightness rather than the more
77 monolithic approach in modules like L<Mojolicious>.
78 Net::WebSocket should support anything
79 that the WebSocket protocol itself can do, as lightly as possible and without
80 prejudice as to how you want to do it: extensions, streaming, blocking or
81 non-blocking I/O, arbitrary HTTP headers, etc. The end result should be a
82 clean, light implementation that will grow (or shrink!) as your needs
83 dictate.
84  
85 =head1 OVERVIEW
86  
87 Here are the main modules:
88  
89 =over
90  
91 =item L<Net::WebSocket::Handshake::Server>
92  
93 =item L<Net::WebSocket::Handshake::Client>
94  
95 Logic for handshakes. Every application needs one of these.
96 This handles all headers and can also negotiate
97 subprotocols and extensions for you.
98  
99 =item L<Net::WebSocket::HTTP_R>
100  
101 A thin convenience wrapper for L<HTTP::Request> and L<HTTP::Response>,
102 CPAN’s “standard” classes to represent HTTP requests and responses.
103 Net::WebSocket::HTTP_R should also work with other classes whose
104 interfaces are compatible with these “standard” ones.
105  
106 =item L<Net::WebSocket::Endpoint::Server>
107  
108 =item L<Net::WebSocket::Endpoint::Client>
109  
110 A high-level abstraction to parse input
111 and respond to control frames and timeouts. You can use this to receive
112 streamed (i.e., fragmented) transmissions as well. You don’t have to use
113 this module, but it will make your life easier.
114  
115 =item L<Net::WebSocket::Parser>
116  
117 Translate WebSocket frames out of a filehandle into useful data for
118 your application.
119  
120 =item L<Net::WebSocket::Streamer::Server>
121  
122 =item L<Net::WebSocket::Streamer::Client>
123  
124 Useful for sending streamed (fragmented) data rather than
125 a full message in a single frame.
126  
127 =item Net::WebSocket::Frame::*
128  
129 Useful for creating raw frames. You probably shouldn’t call these
130 classes directly; instead, use Endpoint’s C<create_message()> method.
131 But if you want to dig deeply, these will be your bread and butter.
132 See L<Net::WebSocket::Frame::text> for sample usage.
133  
134 =back
135  
136 =head1 IMPLEMENTATION NOTES
137  
138 =head2 Handshakes
139  
140 WebSocket uses regular HTTP headers for its handshakes. Because there are
141 many different solutions around for parsing HTTP headers, Net::WebSocket
142 is “agnostic” about how that’s done. The advantage is that if you’ve got
143 a custom solution for parsing headers then Net::WebSocket can fit into
144 that quite easily.
145  
146 The liability of this is that you, the library user, must give headers
147 directly to your Handshake object. (NB: L<Net::WebSocket::HTTP_R> might
148 be able to do this for you.)
149  
150 =head2 Masking
151  
152 As per L<the specification|https://tools.ietf.org/html/rfc6455#section-5.1>,
153 client serializers “MUST” mask the data randomly, whereas server serializers
154 “MUST NOT” do this. Net::WebSocket does this for you automatically,
155 but you need to distinguish
156 between client serializers—which mask their payloads—and server serializers,
157 which don’t mask.
158  
159 This module used to do this with L<Bytes::Random::Secure::Tiny>, but
160 that seems like overkill given that the masking is only there to accommodate
161 peculiarities of certain proxies. Moreover, TLS is widely available and
162 L<free now besides|https://letsencrypt.org>, and it will randomize the data
163 stream anyway. So, nowadays we just use Perl’s C<rand()> built-in.
164  
165 =head2 Text vs. Binary
166  
167 Recall that in some languages—like JavaScript!—the difference between
168 “text” and “binary” is much more significant than for us in Perl.
169  
170 =head2 Use of L<IO::Framed>
171  
172 CPAN’s L<IO::Framed> provides a straightforward interface for chunking up
173 data from byte streams into frames. It also provides a write buffer for
174 non-blocking writes, and it (by default) retries on EINTR. You don’t have to
175 use it (which is why it’s not listed as a requirement), but you’ll need to
176 provide a compatible interface if you don’t.
177  
178 See the demo scripts that use L<IO::Framed> for an example of when you may
179 need a different solution here.
180  
181 =head1 EXTENSION SUPPORT
182  
183 The WebSocket specification describes several methods of extending the
184 protocol, all of which Net::WebSocket supports:
185  
186 =over
187  
188 =item * The three reserved bits in each frame’s header.
189 (See L<Net::WebSocket::Frame>.) This is used, e.g., in the
190 L<permessage-deflate extension|https://tools.ietf.org/html/rfc7692>.
191 (See below for its implementation in Net::WebSocket.)
192  
193 =item * Additional opcodes: 3-7 and 11-15. You’ll need to subclass
194 L<Net::WebSocket::Frame> for this, and you will likely want to subclass
195 L<Net::WebSocket::Parser>.
196 If you’re using the custom classes for streaming, then you can
197 also subclass L<Net::WebSocket::Streamer>. See each of those modules for
198 more information on doing this.
199  
200 B<THIS IS NOT WELL TESTED.> Proceed with caution, and please file bug
201 reports as needed. (I personally don’t know of any applications that
202 actually use this.)
203  
204 =item * Apportion part of the payload data for the extension. This you
205 can do in your application.
206  
207 =back
208  
209 =head2 permessage-deflate
210  
211 Net::WebSocket fully supports the permessage-deflate (compression) extension.
212 See L<Net::WebSocket::PMCE::deflate> for details.
213  
214 =head1 TODO
215  
216 At this point Net::WebSocket seems to support everything the WebSocket
217 protocol can (usefully) do, including compression. Please file bug reports
218 for any issues that may crop up.
219  
220 =over
221  
222 =item * Add more tests.
223  
224 =back
225  
226 =head1 SEE ALSO
227  
228 L<Mojolicious> has a WebSocket implementation. It’s not as complete as
229 Net::WebSocket, but if you’re using Mojolicious, you might try this first.
230  
231 L<Protocol::WebSocket> is an older module that supports
232 pre-standard versions of the WebSocket protocol. It’s similar to this one
233 in that it gives you just the protocol itself, but it doesn’t give you
234 things like automatic ping/pong/close, classes for each message type, etc.
235  
236 L<Net::WebSocket::Server> implements only server behaviors and
237 gives you more automation than P::WS.
238  
239 L<Net::WebSocket::EV> uses XS to call L<wslay|http://wslay.sourceforge.net>.
240 As of this writing it lacks support for handshake logic.
241  
242 =head1 REPOSITORY
243  
244 L<https://github.com/FGasper/p5-Net-WebSocket>
245  
246 =head1 AUTHOR
247  
248 Felipe Gasper (FELIPE)
249  
250 =head1 COPYRIGHT
251  
252 Copyright 2018-2019 by L<Gasper Software Consulting|http://gaspersoftware.com>
253  
254 =head1 LICENSE
255  
256 This distribution is released under the same license as Perl.
257  
258 =cut
259  
260 1;