NAME AtomMQ - An atompub server that supports the message queue/bus model. VERSION version 1.0301 SYNOPSIS use Dancer; use AtomMQ; dance; DESCRIPTION AtomMQ is an atompub server that supports the message queue/bus model. Throughout this document, I will use the term message when referring to an atom feed entry, since the point of this module is to use atompub for messaging. The idea is that atom feeds correspond to conceptual queues (or buses) and atom entries correspond to messages. AtomMQ is built on top of the Dancer, XML::Atom and Atompub frameworks. Since AtomMQ is a PSGI application, deployment is very flexible. It can be run on any web server of your choice in any environment, such as PSGI, CGI or FastCGI. These examples assume that you have configured your web server to point http requests starting with /atommq to AtomMQ. To publish a message, make a HTTP POST request: $ curl -d ' allo
an important message
 ' http://localhost/atommq/feed=widgets That adds a new message to a feed titled widgets. If that feed didn't exist before, it will be created for you. To retrieve messages from the widgets feed, make a HTTP GET request: $ curl http://localhost/atommq/feed=widgets That will get all the messages since the feed was created. Lets say you are running a client that polls the feed and processes messages. If this client dies, you will not want it to process all the messages again when it comes back up. So clients are responsible for maintaining and persisting the id of the last message they processed. This allows a client to request only messages that came after the message with the given id. They can do this by providing the start_after parameter: $ curl -H http://localhost/atommq/feed=widgets?start_after=urn:uuid:4018425e-f747-11df-b990-b7043ee4d39e Alternatively, you can provide a start_at param. This will retrieve messages starting at the message with the given id: $ curl -H http://localhost/atommq/feed=widgets?start_at=urn:uuid:4018425e-f747-11df-b990-b7043ee4d39e 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. 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. Example config.yml: logger: file log: errors page_size: 100 plugins: DBIC: atommq: schema_class: "AtomMQ::Schema" 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 => { schema_class => 'AtomMQ::Schema', 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 for that to work, you will need create table privileges. All databases supported by DBIx::Class are supported, which are most major databases including postgresql, sqlite, mysql and oracle. 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 gone. 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 them to have issues with persistence. Actually, I have found ActiveMQ to be broken in general. An instance I manage has to be restarted every day. AtomMQ on the other hand will be extremely stable, because it is so simple. It is in essence just an interface to a database. As long as your database and web server are up, AtomMQ will be there for you. She will not let you down. And there are all sorts of ways to add redundancy to databases and web heads. Another advantage of using AtomMQ is that atompub is an RFC 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 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.