Provided by: libatombus-perl_1.0405-6_all bug

NAME

       AtomBus - An AtomPub server for messaging.

VERSION

       version 1.0405

SYNOPSIS

           use Dancer;
           use AtomBus;
           dance;

DESCRIPTION

       AtomBus is an AtomPub server that can be used for messaging.  The idea is that atom feeds
       can correspond to conceptual queues or buses.  AtomBus is built on top of the Dancer
       framework.  It is also pubsubhubbub friendly.

       These examples assume that you have configured your web server to point HTTP requests
       starting with /atombus to your AtomBus server (see "DEPLOYMENT").  To publish an entry,
       make a HTTP POST request:

           $ curl -d '<entry> <title>allo</title> <content type="xhtml">
             <div xmlns="http://www.w3.org/1999/xhtml" >an important message</div>
             </content> </entry>' http://localhost/atombus/feeds/widgets

       That adds a new entry to a feed titled widgets.  If that feed didn't exist before, it will
       be created for you.  To retrieve the widgets feed, make a HTTP GET request:

           $ curl http://localhost/atombus/feeds/widgets

       Clients can request only entries that came after the last entry they processed.  They can
       do this by providing the id of the last message as the start_after parameter:

           $ curl http://localhost/atombus/feeds/widgets?start_after=42

       Alternatively, you can provide a start_at param.  This will retrieve entries starting with
       the given id:

           $ curl http://localhost/atombus/feeds/widgets?start_at=42

       HTTP ETags are also supported.  The server responds with an ETag header for each request.
       The client can provide that ETag as the If-None-Match header.  The following example will
       work the same as if the client provided a start_after parameter.  Except that it will
       return an empty body and a 304 status if there are no new entries.  This is the behavior
       that pubsubhubbub recommends
       <http://code.google.com/p/pubsubhubbub/wiki/PublisherEfficiency>.

           $ curl -H 'If-None-Match: "42"' http://localhost/atombus/feeds/widgets

       Note that the most messages you will get per request is determined by the page_size
       setting.  If you do not specify a page_size setting, it defaults to 1000.  This default
       may change in the future, so don't count on it.

       AtomBus is mostly a proper implementation of the AtomPub protocol and will validate 100%
       against <http://validator.w3.org/feed>.  One point where it diverges from the AtomPub spec
       is that feed entries are returned in fifo order.  This is because a message consumer will
       most likely want to consume messages in the order that they were published.  In the
       future, a config setting may be available to reverse the order.

CONFIGURATION

       Configuration can be achieved via a config.yml file or via the set keyword.  To use the
       config.yml approach, you will need to install YAML.  See the Dancer documentation for more
       information.  The only required config setting is the dsn.

       Example config.yml:

           # Dancer specific config settings
           logger: file
           log: errors

           atombus:
               page_size: 100
               db:
                   dsn:  dbi:mysql:database=atombus
                   user: joe
                   pass: momma

       You can alternatively configure the server via the 'set' keyword in the source code. This
       approach does not require a config file.

           use Dancer;
           use AtomBus;

           # Dancer specific config settings
           set logger      => 'file';
           set log         => 'debug';
           set show_errors => 1;

           set atombus => {
               page_size => 100,
               db => {
                   dsn => 'dbi:SQLite:dbname=/var/local/atombus/atombus.db',
               }
           };

           dance;

DATABASE

       AtomBus is backed by a database.  The dsn in the config must point to a database which you
       have write privileges to.  The tables will be created automagically for you if they don't
       already exist.  Of course that requires create table privileges.  All databases supported
       by DBIx::Class are supported, which are most major databases including postgresql, sqlite,
       mysql and oracle.

DEPLOYMENT

       Deployment is very flexible.  It can be run on a web server via CGI or FastCGI.  It can
       also be run on any Plack web server.  See Dancer::Deployment for more details.

   FastCGI
       AtomBus can be run via FastCGI.  This requires that you have the FCGI and Plack modules
       installed.  Here is an example FastCGI script.  It assumes your AtomBus server is in the
       file atombus.pl.

           #!/usr/bin/env perl
           use Dancer ':syntax';
           use Plack::Handler::FCGI;

           my $app = do "/path/to/atombus.pl";
           my $server = Plack::Handler::FCGI->new(nproc => 5, detach => 1);
           $server->run($app);

       Here is an example lighttpd config.  It assumes you named the above file atombus.fcgi.

           fastcgi.server += (
               "/atombus" => ((
                   "socket" => "/tmp/fcgi.sock",
                   "check-local" => "disable",
                   "bin-path" => "/path/to/atombus.fcgi",
               )),
           )

       Now AtomBus will be running via FastCGI under /atombus.

   Plack
       AtomBus can be run with any Plack web server.  Just run:

           plackup atombus.pl

       You can change the Plack web server via the -s option to plackup.

MOTIVATION

       I like messaging systems because they make it so easy to create scalable applications.
       Existing message brokers are great for creating message queues.  But once a consumer reads
       a message off of a queue, it is not available for other consumers.  I needed a system to
       publish events such that multiple heterogeneous services could subscribe to them.  So I
       really needed a message bus, not a message queue.  I could for example have used something
       called topics in ActiveMQ, but I have found ActiveMQ to be broken in general.  An instance
       I manage has to be restarted daily.  AtomBus on the other hand will be extremely stable,
       because it is so simple.  It is in essence just a simple interface to a database.  As long
       as your database and web server are up, AtomBus will be there for you.  And there are many
       ways to add redundancy to databases and web heads.  Another advantage of using AtomBus is
       that Atom is a well known standard.  Everyone already has a client for it, their browser.
       Aren't standards great!  By the way, if you just need message queues, try
       POE::Component::MessageQueue.  It rocks. If you need a message bus, give AtomBus a shot.

AUTHOR

       Naveed Massjouni <naveedm9@gmail.com>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2010 by Naveed Massjouni.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.