File Coverage

blib/lib/Mojolicious/Plugin/Mercury.pm
Criterion Covered Total %
statement 14 14 100.0
branch 2 2 100.0
condition n/a
subroutine 4 4 100.0
pod 2 2 100.0
total 22 22 100.0


line stmt bran cond sub pod time code
1             package Mojolicious::Plugin::Mercury;
2             our $VERSION = '0.014';
3             # ABSTRACT: Plugin for Mojolicious to add Mercury functionality
4              
5             #pod =head1 SYNOPSIS
6             #pod
7             #pod # myapp.pl
8             #pod use Mojolicious::Lite;
9             #pod plugin 'Mercury';
10             #pod
11             #pod =head1 DESCRIPTION
12             #pod
13             #pod This plugin adds L to your L application, allowing you
14             #pod to build a websocket message broker customized to your needs.
15             #pod
16             #pod After adding the plugin, you can add basic messaging patterns by using the Mercury
17             #pod controllers, or you can mix and match your patterns using the Mercury::Pattern
18             #pod classes.
19             #pod
20             #pod Controllers handle establishing the websocket connections and giving
21             #pod them to the right Pattern object, and the Pattern object handles passing
22             #pod messages between the connected sockets. Controllers can create multiple
23             #pod instances of a single Pattern to isolate messages to a single topic.
24             #pod
25             #pod B: You should read L
26             #pod documentation|mercury/DESCRIPTION> before reading further.
27             #pod
28             #pod =head2 Controllers
29             #pod
30             #pod Controllers are L subclasses with route handlers
31             #pod to establish websocket connections and add them to a Pattern. The built-in
32             #pod Controllers each handle one pattern, but you can add one socket to multiple
33             #pod Patterns to customize your message passing.
34             #pod
35             #pod B: Since Mercury does not yet have a way for brokers to share messages,
36             #pod you must run Mercury as a single process. You cannot run Mercury under
37             #pod L like other Mojolicious applications, nor C or other
38             #pod multi-processing schemes. See L
39             #pod to track the clustering feature.
40             #pod
41             #pod The built-in controllers are:
42             #pod
43             #pod =over
44             #pod
45             #pod =item L
46             #pod
47             #pod Establish a LSub pattern|Mercury::Pattern::PubSub> on a topic.
48             #pod Pub/Sub allows publishers to publish messages that will be received by
49             #pod all subscribers, useful for event notifications.
50             #pod
51             #pod =item L
52             #pod
53             #pod Establish a LSub pattern|Mercury::Pattern::PubSub> on a topic in
54             #pod a heirarchy, with subscribers to parent topics receiving messages sent
55             #pod to child topics. More efficient when dealing with large numbers of
56             #pod topics.
57             #pod
58             #pod =item L
59             #pod
60             #pod Establish a LPull pattern|Mercury::Pattern::PushPull> on a topic.
61             #pod Push/Pull allows publishers to publish messages that will be received by
62             #pod one and only one subscriber in a round-robin fashion, useful for job
63             #pod workers
64             #pod
65             #pod =item L
66             #pod
67             #pod Establish a L on a topic.
68             #pod The message bus shares all messages sent by connected clients with all
69             #pod other clients, useful for chat and games, and sharing state changes
70             #pod between peers.
71             #pod
72             #pod =back
73             #pod
74             #pod =head2 Patterns
75             #pod
76             #pod The Pattern objects handle transmission of messages on a single topic.
77             #pod Pattern objects take in L objects (gotten
78             #pod by the controller using C<< $c->tx >> inside a C route).
79             #pod
80             #pod The built-in patterns are:
81             #pod
82             #pod =over
83             #pod
84             #pod =item L
85             #pod
86             #pod A pub/sub pattern has each message sent by a publisher delivered to all
87             #pod connected subscribers. This pattern is useful for event notifications.
88             #pod
89             #pod =item L
90             #pod
91             #pod A push/pull pattern has each message sent by a pusher delivered to one
92             #pod and only one puller. This pattern is useful for job workers.
93             #pod
94             #pod =item L
95             #pod
96             #pod A bus pattern has each message sent by a client received by all other
97             #pod connected clients. This pattern is useful for chat, and is similar to
98             #pod combining the publish and subscribe sides of PubSub into a single
99             #pod connection.
100             #pod
101             #pod =back
102             #pod
103             #pod =head1 SEE ALSO
104             #pod
105             #pod =over
106             #pod
107             #pod =item L
108             #pod
109             #pod =item L
110             #pod
111             #pod =back
112             #pod
113             #pod =cut
114              
115 5     5   12296 use Mojo::Base 'Mojolicious::Plugin';
  5         11  
  5         25  
116              
117             #=attr _patterns
118             #
119             # A repository for pattern objects to share between controller
120             # instances.
121             #
122             #=cut
123              
124             has _patterns => sub { {} };
125              
126             #pod =method pattern
127             #pod
128             #pod my $pattern = $c->mercury->pattern( PushPull => $topic );
129             #pod $c->mercury->pattern( PushPull => $topic => $pattern );
130             #pod
131             #pod Accessor for the pattern repository. Pattern objects track a single topic
132             #pod and are registered by a namespace (likely the pattern type).
133             #pod
134             #pod =cut
135              
136             sub pattern {
137 42     42 1 133 my ( $self, $namespace, $topic, $pattern ) = @_;
138 42 100       143 if ( $pattern ) {
139 10         34 $self->_patterns->{ $namespace }{ $topic } = $pattern;
140 10         68 return;
141             }
142 32         126 return $self->_patterns->{ $namespace }{ $topic };
143             }
144              
145             #pod =method register
146             #pod
147             #pod Register the plugin with the Mojolicious app. Called automatically by Mojolicious
148             #pod when you use C<< $app->plugin( 'Mercury' ) >>.
149             #pod
150             #pod =cut
151              
152             sub register {
153 5     5 1 140 my ( $self, $app, $conf ) = @_;
154 5     42   34 $app->helper( 'mercury.pattern' => sub { shift; $self->pattern( @_ ) } );
  42         3735  
  42         172  
155 5         99 push @{$app->routes->namespaces}, 'Mercury::Controller';
  5         19  
156             }
157              
158             1;
159              
160             __END__