# NAME
Mojolicious::Broker - A message broker for WebSockets
# VERSION
version 0.001
# 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.