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

Mercury
Mojolicious::Plugins

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.