Created Pubsubhubbub (markdown)

Pubsubhubbub.md

+PubSubHubBub (aka PuSH or PSHB) is a simple, open, server-to-server web-hook-based pubsub (publish/subscribe) protocol as an extension to Atom and RSS. Parties (servers) speaking the PubSubHubbub protocol can get near-instant notifications (via webhook callbacks) when a topic (feed URL) they're interested in is updated.
+
+**Spec:**<http://code.google.com/p/pubsubhubbub/>
+
+Note that **our goal is not to implement the full protocol**, we are not interested in providing a fully functional hub in the origianl PuSH sense. Instead, in an OStatus use case, your applications should be its own hub. It receives subscriptions requests from other OStatus nodes and is able to push them new content. It can also subscribe to remote node.
+
+## subscribe(url, parameters, callback)
+
+Submit a subscription request to a hub (url). The parameters attribute is an associative array whose keys are the parameters as described in the protocol [[section #6.1|http://pubsubhubbub.googlecode.com/svn/trunk/pubsubhubbub-core-0.3.html#anchor5]]. The result value in the callback will be a string with two possible values:
+
+*  **accepted**:  The requested was verified synchronously and accepted.
+*  **pending**: The request is pending async verification.
+
+Example:
+
+    var ostatus = require('ostatus');
+    var parameters = {
+       "hub.callback": "http://example.com/push/inbox/12345",
+       "hub.mode": "subscribe",
+       "hub.topic": "http://publisher.com/topics/sports.atom",
+       "hub.verify": "async",
+       "hub.verify": "sync",
+       "hub.secret": "A0F4D1C6B7DDF17645"
+    };
+    ostatus.push.subscribe("http://publisher.com/hub", parameters, function(error, status) {
+        console.log(status);
+    });
+
+## verify(request, callback)
+
+Verify a subscribe/unsubscribe request as per [[section #6.2 | http://pubsubhubbub.googlecode.com/svn/trunk/pubsubhubbub-core-0.3.html#verifysub]] of the protocol. The _request_ argument is an associative array containing the paramters of the received request. If the verification succeeds, the result contains the value of the subscribed topic. If it fails, an error is propagated to the callback.
+
+Example:
+
+    var ostatus = require('ostatus');
+    var request = require("querystring").parse(body); // body was submitted by http for example
+    ostatus.push.verify(request, function(error, topic) {
+      // if not an error, then the requets is verified. We can extract the topic,
+      // callback url, etc. from the original request.
+    });
+
+## distribute(content, url, secret, callback)
+
+Push new content to a subscriber callback url, signing it with your secret if provided. The content should be a string containing a properly formatted atom feed. On success, the callback returns the response status code.
+
+Example:
+
+    var ostatus = require('ostatus');
+    var data = ostatus.atom.render(..);
+    ostatus.push.distribute(data, "http://example.com/inbox/12345", "A0F4D1C6B7DDF17645", function(err, status, body) {
+         // err contains the error if any, false otherwise
+         // status is the HTTP status code returned by the subscriber
+         // body is the body returned by the subscribed (may be usefull for debugging).
+    });
\ No newline at end of file