NAME
Mojolicious::Plugin::Mercury - Plugin for Mojolicious to add Mercury functionality
VERSION
version 0.016
SYNOPSIS
# myapp.pl
use Mojolicious::Lite;
plugin 'Mercury';DESCRIPTION
This plugin adds Mercury to your Mojolicious application, allowing you to build a websocket message broker customized to your needs.
After adding the plugin, you can add basic messaging patterns by using the Mercury controllers, or you can mix and match your patterns using the Mercury::Pattern classes.
Controllers handle establishing the websocket connections and giving them to the right Pattern object, and the Pattern object handles passing messages between the connected sockets. Controllers can create multiple instances of a single Pattern to isolate messages to a single topic.
NOTE: You should read the DESCRIPTION section of the main Mercury broker documentation before reading further.
Controllers
Controllers are Mojolicious::Controller subclasses with route handlers to establish websocket connections and add them to a Pattern. The built-in Controllers each handle one pattern, but you can add one socket to multiple Patterns to customize your message passing.
NOTE: Since Mercury does not yet have a way for brokers to share messages, you must run Mercury as a single process. You cannot run Mercury under Hypnotoad like other Mojolicious applications, nor prefork or other multi-processing schemes. See https://github.com/preaction/Mercury/issues/35 to track the clustering feature.
The built-in controllers are:
- Mercury::Controller::PubSub
-
Establish a Pub/Sub pattern on a topic. Pub/Sub allows publishers to publish messages that will be received by all subscribers, useful for event notifications.
- Mercury::Controller::PubSub::Cascade
-
Establish a Pub/Sub pattern on a topic in a heirarchy, with subscribers to parent topics receiving messages sent to child topics. More efficient when dealing with large numbers of topics.
- Mercury::Controller::PushPull
-
Establish a Push/Pull pattern on a topic. Push/Pull allows publishers to publish messages that will be received by one and only one subscriber in a round-robin fashion, useful for job workers
- Mercury::Controller::Bus
-
Establish a message bus pattern on a topic. The message bus shares all messages sent by connected clients with all other clients, useful for chat and games, and sharing state changes between peers.
Patterns
The Pattern objects handle transmission of messages on a single topic. Pattern objects take in Mojo::Transaction::WebSocket objects (gotten by the controller using $c->tx inside a websocket route).
The built-in patterns are:
- Mercury::Pattern::PubSub
-
A pub/sub pattern has each message sent by a publisher delivered to all connected subscribers. This pattern is useful for event notifications.
- Mercury::Pattern::PushPull
-
A push/pull pattern has each message sent by a pusher delivered to one and only one puller. This pattern is useful for job workers.
- Mercury::Pattern::Bus
-
A bus pattern has each message sent by a client received by all other connected clients. This pattern is useful for chat, and is similar to combining the publish and subscribe sides of PubSub into a single connection.
METHODS
pattern
my $pattern = $c->mercury->pattern( PushPull => $topic );
$c->mercury->pattern( PushPull => $topic => $pattern );Accessor for the pattern repository. Pattern objects track a single topic and are registered by a namespace (likely the pattern type).
register
Register the plugin with the Mojolicious app. Called automatically by Mojolicious when you use $app->plugin( 'Mercury' ).
SEE ALSO
AUTHOR
Doug Bell <preaction@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2018 by Doug Bell.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.