NAME
    AtomMQ - An AtomPub server for messaging.

VERSION
    version 1.0401

SYNOPSIS
        use Dancer;
        use AtomMQ;
        dance;

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

    These examples assume that you have configured your web server to point
    HTTP requests starting with /atommq to your AtomMQ 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/atommq/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/atommq/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 -H http://localhost/atommq/feeds/widgets?start_after=42

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

        $ curl -H http://localhost/atommq/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/atommq/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.

    AtomMQ 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:

        logger: file
        log: errors
        page_size: 100
        plugins:
            DBIC:
                atommq:
                    dsn: 'dbi:mysql:database=atommq'
                    user: joe
                    password: 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 AtomMQ;

        set logger      => 'file';
        set log         => 'debug';
        set show_errors => 1;
        set page_size   => 100;

        set plugins => {
            DBIC => {
                atommq => {
                    dsn => 'dbi:SQLite:dbname=/var/local/atommq/atommq.db',
                }
            }
        };

        dance;

DATABASE
    AtomMQ 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
    AtomMQ 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 AtomMQ server is in the file atommq.pl.

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

        my $app = do "/path/to/atommq.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
    atommq.fcgi.

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

    Now AtomMQ will be running via FastCGI under /atommq.

  PSGI
    AtomMQ can be run in a PSGI environment via Plack. You will need to have
    Plack installed. To deploy AtomMQ, just run:

        plackup atommq.pl

    Now AtomMQ is running via the HTTP::Server::PSGI web server. Of course
    you can use any PSGI/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.
    AtomMQ 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, AtomMQ will be there for you.
    And there are many ways to add redundancy to databases and web heads.
    Another advantage of using AtomMQ 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
    AtomMQ a shot.

AUTHOR
    Naveed Massjouni <naveed.massjouni@rackspace.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.

