Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
WebGlue ======== PubSubHubbub Ruby implementation Overview --------- PubSubHubbub (PSHB) is a simple, open, server-to-server web-hook-based pubsub (publish/subscribe) protocol as an extension to Atom. For more details see http://code.google.com/p/pubsubhubbub/ . Current project is as simple as possible implementation in Ruby of PSHB Core 0.2 Draft-compatible hub. Implemented features: - Publishing new topics (Atom Feeds) - Subscriptions to existing topics (including callbacks verification) - 'sync' and 'async' mode verifications - Fetching atom feeds, finding the new entries and sending them to all subscribers - Authenticated Content Distribution - 'hub.secret' Still missing (not implemented): - Publishers need to manually ping the hub (no automatic check for updated feeds) - Can only process Atom feeds, not RSS Required gems -------------- - sinatra - web framework - routing etc. - httpclient - POST requests, callbacks verification - crack - XML parsing - ratom - Atom feeds fetching/parsing - SystemTimer - for timeouts on unsuccessful requests - ruby-hmac - HMAC-SHA1 for content digests If you are using http://heroku.com/ for deployment, your '.gems' file will look like: httpclient SystemTimer crack ratom ruby-hmac Running ------ The whole system is implemented as a Sinatra [ http://www.sinatrarb.com/ ] application. To start it locally (on port 4567 for example): git clone git://github.com/zh/webglue.git cd webglue bundle install bundle exec rackup -p 4567 -s thin For production environment, maybe using 'unicorn' is better: bundle exec unicorn -c ./unicorn.conf -E production (optional) 'async' verification worker process: - from crontab: require 'worker' WebGlue::Worker.verify - independent daemon (checks every WebGlue::Config.CHECK minutes) require 'worker' WebGlue::Worker.run Or you can uncomment the proper lines in worker.rb ('if __FILE__ == $0' block) and do ruby worker.rb http://heroku.com/ will automatically recognize the startup file (config.ru) and will run your application after the deployment: git clone git://github.com/zh/webglue.git cd webglue heroku create mypubhub git push heroku master PubSub ------- Both publishing and subscriptions going to the same endpoint - '/'. So if your application is running on URL http://localhost:4567/ , that will be the endpoint for both publishers (atom:link[@rel="hub"] in the feed) and subscribers (POST requests for subscription). Only for debugging purposes, there are two web form on '/publish' and '/subscribe' URLs. Publishing new topics ---------------------- If your application is running on URL http://localhost:4567/ , go to http://localhost:4567/publish and insert your Atom feed in the 'Topic:' text box. Press "Publish". There will be no changes on the screen, because the hub is responding with HTTP code 204 "No Content". You can also POST directly to http://localhost:4567/ with parameters, described in the "PubSubHubbub Core 0.2" document - http://pubsubhubbub.googlecode.com/svn/trunk/pubsubhubbub-core-0.2.html Also in your feed, insert the line: <link rel="hub" href="http://localhost:4567/" /> (adjust for your install) For now, there is no automatic check for updated feeds implemented, so after changes in some feed, repeat the actions, described above (from the web form or via POST). Publishing is possible once every 5 min. Subscription to existing topics -------------------------------- If your application is running on URL http://localhost:4567/ , go to http://localhost:4567/subscribe and fill the web form: - Callback - URL to the webhook, which will receive Atom-formated notifications - Topic - Atom feed URL, ALREADY PUBLISHED to the system - see 'Publishing new topics' above - Verify mode - Both 'Synchronous' and 'Asynchronous' modes supported - Mode - 'Subscribe' for adding new subscribers and 'Unsubscribe' for removing the already inserted onces - Verify token - something that your callback need to approve - Secret - used to compute an HMAC digest of the content, send to the subscriber You can send also POST subscription requests with the required parameters directly to the hub endpoint (http://localhost:4567/ in our example). The hub is implementing callbacks verification, described in the "PubSubHubbub Core 0.2" document (sending back 'hub.challenge' parameter in the response body). In 'Synchronous' mode there will be no changes on the screen after subscription, because the hub is responding with HTTP code 204 "No Content". In 'Asynchronous' mode the hub will respond with HTTP code 202 "Scheduled for verification" Notifications format --------------------- Current implementation fetch the Atom feeds and just remove already known entries from them, without touching other parts of the feed ('title', 'id', 'author' etc.). After that, the feed, with only new entries in it is resend to all topic's subscribers. Because of that, the hub cannot process RSS feeds and may have some problems with non-well formated feeds. I'll try to fix this in the future releases. If the subscriber supplied a value for 'hub.secret' in their subscription request, the hub will generate an HMAC signature of the payload and include that signature in the response headers ('X-Hub-Signature') of the notification.