Add README file.

README.md

@@ -0,0 +1,82 @@
+# PubSub-over-Webhooks with RabbitHub
+
+[RabbitHub][gitrepo] is an implementation of
+[PubSubHubBub][pshb_project], a straightforward pubsub layer on top of
+plain old HTTP POST - pubsub over Webhooks. RabbitHub provides an
+HTTP-based interface to [RabbitMQ][].
+
+It gives every AMQP exchange and queue hosted by a RabbitMQ broker a
+couple of URLs: one to use for delivering messages to the exchange or
+queue, and one to use to subscribe to messages forwarded on by the
+exchange or queue. You subscribe with a callback URL, so when messages
+arrive, RabbitHub POSTs them on to your callback. For example,
+
+ - <http://dev.rabbitmq.com/rabbithub/endpoint/x/amq.direct> is the
+   URL for delivering messages to the "amq.direct" exchange on the
+   public test instance of RabbitMQ, and
+
+ - <http://dev.rabbitmq.com/rabbithub/subscribe/q/some_queue_name> is
+   the URL for subscribing to messages from the (hypothetical) queue
+   "some_queue_name" on the broker.
+
+The symmetrical .../subscribe/x/... and .../endpoint/q/... also exist.
+
+The [PubSubHubBub protocol][spec] specifies some RESTful(ish)
+operations for establishing subscriptions between message sources
+(a.k.a "topics") and message sinks. RabbitHub implements these
+operations as well as a few more for RESTfully creating and deleting
+exchanges and queues.
+
+While PubSubHubBub is written assuming Atom content, RabbitHub is
+content-agnostic (just like RabbitMQ): any content at all can be sent
+using RabbitHub's implementation of the PubSubHubBub protocol. Because
+RabbitHub is content-agnostic, it doesn't implement any of the
+Atom-specific parts of the PubSubHubBub protocol, including the "ping"
+operation that tells a PSHB hub to re-fetch content feeds.
+
+## Example: combining HTTP messaging with AMQP and XMPP
+
+Combining RabbitHub with the AMQP protocol implemented by RabbitMQ
+itself and with the other adapters and gateways that form part of the
+RabbitMQ universe lets you send messages across different kinds of
+message networks - for example, our public RabbitMQ instance,
+`dev.rabbitmq.com`, has RabbitHub running as well as the standard AMQP
+adapter, the [rabbitmq-xmpp][] plugin, and a bunch of our other
+experimental stuff, so you can do things like this:
+
+<img src="http://github.com/tonyg/rabbithub/raw/master/doc/rabbithub-example.png" alt="RabbitHub example configuration"/>
+
+ - become XMPP friends with `pshb@dev.rabbitmq.com` (the XMPP adapter
+   gives each exchange a JID of its own)
+
+ - use PubSubHubBub to subscribe the sink
+   <http://dev.rabbitmq.com/rabbithub/endpoint/x/pshb> to some
+   PubSubHubBub source - perhaps one on the public Google PSHB
+   instance. (Note how the given URL ends in "x/pshb", meaning the
+   "pshb" exchange - which lines up with the JID we just became XMPP
+   friends with.)
+
+ - wait for changes to be signalled by Google's PSHB hub to RabbitHub
+
+ - when they are, you get an XMPP IM from `pshb@dev.rabbitmq.com` with
+   the Atom XML that the hub sent out as the body
+
+Again, RabbitHub is content-agnostic, so the fact that Atom appears is
+an artifact of what Google's public PSHB instance is mailing out,
+rather than anything intrinsic in pubsub-over-webhooks.
+
+## HTTP messaging in the Browser
+
+In order to push AMQP messages out to a webpage running in a browser,
+try using <http://www.reversehttp.net/> to run a PubSubHubBub endpoint
+in a webpage - see for instance
+<http://www.reversehttp.net/demos/endpoint.html> and its [associated
+Javascript](http://www.reversehttp.net/demos/endpoint.js) for a simple
+prototype of the idea. It's also possible to build simple PSHB hubs in
+Javascript using the same tools.
+
+  [gitrepo]: http://github.com/tonyg/rabbithub
+  [pshb_project]: http://code.google.com/p/pubsubhubbub/
+  [spec]: http://pubsubhubbub.googlecode.com/svn/trunk/pubsubhubbub-core-0.1.html
+  [RabbitMQ]: http://www.rabbitmq.com/
+  [rabbitmq-xmpp]: http://hg.rabbitmq.com/rabbitmq-xmpp/raw-file/default/doc/overview-summary.html