#!/usr/bin/env perl
# ABSTRACT: A message broker for WebSockets
# PODNAME: mercury

use strict;
use warnings;

require Mojolicious::Commands;
Mojolicious::Commands->start_app('Mercury');

__END__

=pod

=head1 NAME

mercury - A message broker for WebSockets

=head1 VERSION

version 0.002

=head1 SYNOPSIS

    mercury broker [-l <listen>]

=head1 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.

=head2 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.

=head2 Message Topics

Requesting a WebSocket from the URL C</sub/leela> creates a subscription to the
topic C<leela>. Requesting a WebSocket from the URL C</pub/leela> allows
sending messages to the C<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 C<wong> receives all messages published to
the topic C<wong> or any child topic like C<wong/amy> or C<wong/leo>.

=head2 Example App

In C<development> mode (the default), the broker provides an example
application to test the messaging patterns.

You can change the mode by using the C<-m> flag to the
L<C<mercury broker> command|Mercury::Command::broker> or the C<MOJO_MODE> environment
variable.

=head1 CONFIGURATION

The default for the C<listen> option can be set in a configuration file
C<mercury.conf> in the current working directory. The configuration file
should look like so:

    # mercury.conf
    {
        broker => {
            listen => "http://*:4000",
        },
    }

=head1 AUTHOR

Doug Bell <preaction@cpan.org>

=head1 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.

=cut
