| 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; |