Multiplex.pm

filter: Statementstmt 100% 23 / 23 Branchbran 50.0% 3 / 6 Conditioncond 33.3% 1 / 3 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 100% 5 / 5 Podpod 100% 1 / 1 totaltotal 82.5% 33 / 40 CC 5 SCAR 10.4
CC
5
Cov
84%
__ANON__
4.6
register
2.1
BEGIN
1.0
CRAP 2.8
« Multiplex/Multiplexer.pm ↑ Summary
1 package Mojolicious::Plugin::Multiplex;
2  
3 1 ▶use Mojo::Base 'Mojolicious::Plugin';
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 1 our $VERSION = '1.0';
6 1 $VERSION = eval $VERSION;
7  
8 1 ▶use Mojolicious::Plugin::Multiplex::Multiplexer;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 1 ▶use File::Share ();
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 1 ▶sub register {
Subroutine register: called CC=2 SCAR=7.2
Pod documented
13 1 my ($plugin, $app, $conf) = @_;
14  
15 1 push @{ $app->static->paths }, File::Share::dist_dir('Mojolicious-Plugin-Multiplex');
16  
17 # this is still a gray area it seems, but certainly this will be honored even
18 # if in the future they add some new preferred type
19 1 my $types = $app->types;
20 $types->type(mjs => ['application/javascript'])
21 1 ▶ unless exists $types->mapping->{mjs};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $types->mapping->{"mjs"} 1 0 1
22  
23 3 ▶ $app->helper(multiplex => sub {
Subroutine __ANON__: called CC=4 SCAR=15.2
24 3 my $c = shift;
25 3 my $tx = $c->tx;
26 3 ▶ return undef unless $tx->is_websocket;
Branch: 1 branch
BranchTrueFalseTotal
unless $tx->is_websocket 0 3 3
27 3 ▶ $c->rendered(101) unless $tx->established;
Branch: 1 branch
BranchTrueFalseTotal
unless $tx->established 3 0 3
28 3 ▶ return $c->stash->{'multiplex.multiplexer'} ||= Mojolicious::Plugin::Multiplex::Multiplexer->new(tx => $tx);
Condition33%1/3
$c->stash->{"multiplex.multiplexer"} ||= "Mojolicious::Plugin::Multiplex::Multiplexer"->new("tx", $tx)
l!l&&r!l&&!r
030
MC/DC0%0/2
$c->stash->{"multiplex.multiplexer"} ||= "Mojolicious::Plugin::Multiplex::Multiplexer"->new("tx", $tx)
$c->stash->{"multiplex.multiplexer"} "Mojolicious::Plugin::Multiplex::Multiplexer"->new("tx", $tx)
Truth table33%1/3
A ||= B
A= $c->stash->{"multiplex.multiplexer"}B= "Mojolicious::Plugin::Multiplex::Multiplexer"->new("tx", $tx)
ABresult
1X1
011
000
29 1 });
30 }
31  
32 1 1;
33  
34 =head1 NAME
35  
36 Mojolicious::Plugin::Multiplex - A websocket multiplexing layer for Mojolicious applications
37  
38 =head1 SYNOPSIS
39  
40 use Mojolicious::Lite;
41  
42 plugin 'Multiplex';
43  
44 get '/' => 'index';
45  
46 websocket '/multiplex' => sub {
47 my $c = shift;
48 my $multiplex = $c->multiplex;
49 $multiplex->on(subscribe => sub { ... });
50 $multiplex->on(message => sub { ... });
51 $multiplex->on(unsubscribe => sub { ... });
52 };
53  
54 __DATA__
55  
56 @@ index.html.ep
57  
58 %= javascript 'websocket_multiplex.js';
59 <script>
60 var ws = new WebSocket('<%= url_for('multiplex')->to_abs %>');
61 var multiplex = new WebSocketMultiplex(ws);
62 var foo = multiplex.channel('foo');
63 foo.onmessage = function (e) { console.log('foo channel got: ' + e.data) };
64 var bar = multiplex.channel('bar');
65 bar.onmessage = function (e) { console.log('bar channel got: ' + e.data) };
66 </script>
67  
68 =head1 DESCRIPTION
69  
70 L<Mojolicious::Plugin::Multiplex> implements a mechanism proposed by L<SockJS|https://github.com/sockjs/websocket-multiplex> for the multiplexing of data on a single websocket.
71 Rather than proposing both a protocol and a programmatic api to use it, they L<propose|https://www.rabbitmq.com/blog/2012/02/23/how-to-compose-apps-using-websockets/> a very simple protocol and reusing the api of the existing Javascript WebSocket api.
72 This has the immediate advantage (beyond having to dream up a client api) that existing front-end code that is written for a WebSocket can immediately use the multiplexer with no changes necessary.
73  
74 Their proposal only includes a partially implemented reference implementation.
75 This module extends the protocol slightly in order to enough of the L<"WebSocket API"|https://developer.mozilla.org/en-US/docs/Web/API/WebSocket> to be useful.
76 More extensions may be necessary if the API is to be completely implemented, however those last few details are rarely used and will likely not be missed.
77  
78 On the server-side the logic is entirely up to the application author.
79 The module simply parses the multiplexed messages and emits events in accordance with them.
80 A typical use case may be to relay message to a bus, subscribing and unsubscribing from topics that it presents.
81 Another might be to stream updates to multiple types of data (perhaps in multiple parts of a single page application).
82 (Indeed those might not be distinct cases from each other).
83  
84 For reference, the distribution comes with an example which uses L<Mojo::Pg> as a message broker for a multi-channel chat application.
85 The example may also be seen on L<GitHub|https://github.com/jberger/Mojolicious-Plugin-Multiplex/blob/master/ex/vue_chat.pl>.
86  
87 =head1 CAVEAT
88  
89 While I'm declaring this module stable and production worthy, I still don't nearly have enough tests.
90 The biggest reason for this is that I don't have a great way to test Perl and Javascript together.
91 Unfortunately PhantomJS declared defeat right as L<Mojo::Phantom> was catching on.
92 A project to wrap its successor, headless Chrome, is stalled waiting for now, so we wait.
93 Contributions from people with experience in this area would be greatly appreciated.
94  
95 =head1 HELPERS
96  
97 =head2 multiplex
98  
99 my $multiplex = $c->multiplex;
100  
101 Establishes the WebSocket connection (if it hasn't been already) and returns an instance of L<Mojolicious::Plugin::Multiplex::Multiplexer>.
102 The multiplexer is attached to the websocket stream and begins listening for messages.
103 The multiplexer emits events for incoming messages and has methods to send outgoing messages; more details about those are contained in its own documentation.
104  
105 Note that for each websocket connection the same instance of the multiplexer will be returned on any subsequent call.
106 Though not prevented, the user is highly discouraged from sending other traffic over any websocket connection that is managed by a multiplexer.
107  
108 =head1 BUNDLED FILES
109  
110 =head2 websocket_multiplex.mjs
111  
112 <script type="module">
113 import WebSocketMultiplex from '/websocket_multiplex.mjs';
114 var ws = new WebSocket(url);
115 var multiplex = new WebSocketMultiplex(ws);
116 var channel = multiplex.channel(topic);
117 </script>
118  
119 Bundled with this plugin is a javascript module file called C<websocket_multiplex.mjs> which contains the front-end code to create a multiplexer.
120 It exports the C<WebSocketMultiplex> class, whose constructor takes as its only argument an existing WebSocket object or a url string to build one.
121 This then is used to open new channel objects via the C<channel> method which takes a topic string as an arugment.
122 Topics can be almost any string, however they must not contain a comma (a limitation of the protocol).
123 The resulting channel objects implement the same API as a WebSocket (though they do not inherit from it).
124  
125 The client-side multiplexer will also attempt to reconnect to closed sockets and when successful will automatically resubscribe to the channels that were subscribed.
126  
127 N.B. This library is the least stable of the entire project.
128 Use with caution.
129  
130 Also, this library will likely use very modern conventions, even going forward.
131 Older browsers are not the target for this file.
132 For those you want ...
133  
134 =head2 websocket_multiplex.js
135  
136 <script src="websocket_multiplex.js"></script>
137 <script>
138 var ws = new WebSocket(url);
139 var multiplex = new WebSocketMultiplex(ws);
140 var channel = multiplex.channel(topic);
141 </script>
142  
143 This is the above javascript module but transpiled back to work on older browsers (and minified).
144 It sets the global symbol C<WebSocketMultiplex> when loaded.
145 In all other ways it works just like the above file.
146  
147 =head2 websocket_multiplex.js.map
148  
149 A file used to get better diagnostics from the minified javascript file.
150  
151 =head1 SOURCE REPOSITORY
152  
153 L<http://github.com/jberger/Mojolicious-Plugin-Multiplex>
154  
155 =head1 AUTHOR
156  
157 Joel Berger, E<lt>joel.a.berger@gmail.comE<gt>
158  
159 =head1 ADDITIONAL THANKS
160  
161 John Susek
162  
163 =head1 COPYRIGHT AND LICENSE
164  
165 Copyright (C) 2016-2018 by Joel Berger
166  
167 This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
168  
169 The multiplexer protocol and javascript code (both extended by this project) are copyright their original authors and by their nature are assumed to be in the public domain.
170  
171 =cut
172  
173  
« Multiplex/Multiplexer.pm ↑ Summary