# NAME Mojolicious::Broker - A message broker for WebSockets # VERSION version 0.001 # STATUS Coverage Status # SYNOPSIS mojo broker [-l ] # DESCRIPTION This is a message broker that enables a simple publish/subscribe messaging pattern. A single socket is either a subscription to all messages on a topic, or a publishing socket allowed to send messages to that topic. WebSockets are a powerful tool, enabling many features previously impossible, difficult, or ugly for web developers to implement. Where once only an HTTP request could get data from a server, now a persistent socket can allow the server to send updates without the client needing to specifically request it. ## Server-side Communication WebSockets do not need to be a communication channel purely between browser and server. The Mojolicious web framework has excellent support for WebSockets. Using that support, we can communicate between different server processes. This solves the problem with client-to-client communication in a parallelized web server where all clients may not be connected to the same server process. The server processes can use a central message broker to coordinate and pass messages from one client to another. ## Message Topics Requesting a WebSocket from the URL `/sub/leela` creates a subscription to the topic `leela`. Requesting a WebSocket from the URL `/pub/leela` allows sending messages to the `leela` topic, which are then received by all the subscribers. Topics are heirarchical to allow for broad subscriptions without requring more sockets. A subscription to the topic `wong` receives all messages published to the topic `wong` or any child topic like `wong/amy` or `wong/leo`. ## Example App In `development` mode (the default), the broker provides an example application to test the messaging patterns. You can change the mode by using the `-m` flag to the [`broker` command](https://metacpan.org/pod/Mojolicious::Command::broker) or the `MOJO_MODE` environment variable. # ROUTES ## /sub/\*topic Establish a WebSocket to subscribe to the given `topic`. Messages published to the topic or any child topics will be sent to this subscriber. ## /pub/\*topic Establish a WebSocket to publish to the given `topic`. Messages published to the topic will be sent to all subscribers to the topic or any parent topics. # METHODS ## add\_topic\_subscriber $c->add_topic_subscriber( $topic ); Add the current connection as a subscriber to the given topic. Connections can be subscribed to only one topic, but they will receive all messages to child topics as well. ## remove\_topic\_subscriber $c->remote_topic_subscriber( $topic ); Remove the current connection from the given topic. Must be called to clean up the state. ## publish\_topic\_message $c->publish_topic_message( $topic, $message ); Publish a message on the given topic. The message will be sent once to any subscriber of this topic or any child topics. # AUTHOR Doug Bell # COPYRIGHT AND LICENSE This software is copyright (c) 2015 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.