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

package Mojolicious::Plugin::Mercury;
our $VERSION = '0.015';
# ABSTRACT: Plugin for Mojolicious to add Mercury functionality

#pod =head1 SYNOPSIS
#pod
#pod     # myapp.pl
#pod     use Mojolicious::Lite;
#pod     plugin 'Mercury';
#pod
#pod =head1 DESCRIPTION
#pod
#pod This plugin adds L to your L application, allowing you
#pod to build a websocket message broker customized to your needs.
#pod
#pod After adding the plugin, you can add basic messaging patterns by using the Mercury
#pod controllers, or you can mix and match your patterns using the Mercury::Pattern
#pod classes.
#pod
#pod Controllers handle establishing the websocket connections and giving
#pod them to the right Pattern object, and the Pattern object handles passing
#pod messages between the connected sockets. Controllers can create multiple
#pod instances of a single Pattern to isolate messages to a single topic.
#pod
#pod B: You should read L
#pod documentation|mercury/DESCRIPTION> before reading further.
#pod
#pod =head2 Controllers
#pod
#pod Controllers are L subclasses with route handlers
#pod to establish websocket connections and add them to a Pattern. The built-in
#pod Controllers each handle one pattern, but you can add one socket to multiple
#pod Patterns to customize your message passing.
#pod
#pod B: Since Mercury does not yet have a way for brokers to share messages,
#pod you must run Mercury as a single process. You cannot run Mercury under
#pod L like other Mojolicious applications, nor C or other
#pod multi-processing schemes. See L
#pod to track the clustering feature.
#pod
#pod The built-in controllers are:
#pod
#pod =over
#pod
#pod =item L
#pod
#pod Establish a LSub pattern|Mercury::Pattern::PubSub> on a topic.
#pod Pub/Sub allows publishers to publish messages that will be received by
#pod all subscribers, useful for event notifications.
#pod
#pod =item L
#pod
#pod Establish a LSub pattern|Mercury::Pattern::PubSub> on a topic in
#pod a heirarchy, with subscribers to parent topics receiving messages sent
#pod to child topics. More efficient when dealing with large numbers of
#pod topics.
#pod
#pod =item L
#pod
#pod Establish a LPull pattern|Mercury::Pattern::PushPull> on a topic.
#pod Push/Pull allows publishers to publish messages that will be received by
#pod one and only one subscriber in a round-robin fashion, useful for job
#pod workers
#pod
#pod =item L
#pod
#pod Establish a L on a topic.
#pod The message bus shares all messages sent by connected clients with all
#pod other clients, useful for chat and games, and sharing state changes
#pod between peers.
#pod
#pod =back
#pod
#pod =head2 Patterns
#pod
#pod The Pattern objects handle transmission of messages on a single topic.
#pod Pattern objects take in L objects (gotten
#pod by the controller using C<< $c->tx >> inside a C route).
#pod
#pod The built-in patterns are:
#pod
#pod =over
#pod
#pod =item L
#pod
#pod A pub/sub pattern has each message sent by a publisher delivered to all
#pod connected subscribers. This pattern is useful for event notifications.
#pod
#pod =item L
#pod
#pod A push/pull pattern has each message sent by a pusher delivered to one
#pod and only one puller. This pattern is useful for job workers.
#pod
#pod =item L
#pod
#pod A bus pattern has each message sent by a client received by all other
#pod connected clients. This pattern is useful for chat, and is similar to
#pod combining the publish and subscribe sides of PubSub into a single
#pod connection.
#pod
#pod =back
#pod
#pod =head1 SEE ALSO
#pod
#pod =over
#pod
#pod =item L
#pod
#pod =item L
#pod
#pod =back
#pod
#pod =cut

use Mojo::Base 'Mojolicious::Plugin';

#=attr _patterns
#
# A repository for pattern objects to share between controller
# instances.
#
#=cut

has _patterns => sub { {} };

#pod =method pattern
#pod
#pod     my $pattern = $c->mercury->pattern( PushPull => $topic );
#pod     $c->mercury->pattern( PushPull => $topic => $pattern );
#pod
#pod Accessor for the pattern repository. Pattern objects track a single topic
#pod and are registered by a namespace (likely the pattern type).
#pod
#pod =cut

sub pattern {
    my ( $self, $namespace, $topic, $pattern ) = @_;
    if ( $pattern ) {
        $self->_patterns->{ $namespace }{ $topic } = $pattern;
        return;
    }
    return $self->_patterns->{ $namespace }{ $topic };
}

#pod =method register
#pod
#pod Register the plugin with the Mojolicious app. Called automatically by Mojolicious
#pod when you use C<< $app->plugin( 'Mercury' ) >>.
#pod
#pod =cut

sub register {
    my ( $self, $app, $conf ) = @_;
    $app->helper( 'mercury.pattern' => sub { shift; $self->pattern( @_ ) } );
    push @{$app->routes->namespaces}, 'Mercury::Controller';
}

1;

__END__