meerkat 0.2.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+*.swp

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in meerkat.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,43 @@
+PATH
+  remote: .
+  specs:
+    meerkat (0.2.0)
+      em-hiredis
+      eventmachine
+      pg
+      yajl-ruby
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    daemons (1.1.4)
+    em-hiredis (0.1.0)
+      hiredis (~> 0.3.0)
+    em-minitest-spec (1.1.1)
+      eventmachine
+    eventmachine (0.12.10)
+    hiredis (0.3.2)
+    minitest (2.6.2)
+    pg (0.11.0)
+    rack (1.3.5)
+    rack-test (0.6.1)
+      rack (>= 1.0)
+    thin (1.2.11)
+      daemons (>= 1.0.9)
+      eventmachine (>= 0.12.6)
+      rack (>= 1.0.0)
+    thin-async-test (1.0.0)
+    thin_async (0.1.1)
+      thin (>= 1.2.1)
+    yajl-ruby (1.0.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  em-minitest-spec
+  meerkat!
+  minitest
+  rack-test
+  thin-async-test
+  thin_async

data/README.md

@@ -0,0 +1,81 @@
+Meerkat
+=======
+
+Rack middleware for [Server-Sent Events (HTML5 SSE)](http://www.html5rocks.com/en/tutorials/eventsource/basics/).
+
+Requires an evented server, like [Thin](http://code.macournoyer.com/thin/).
+
+Supported backends: 
+
+ * In memory, using [EventMachine Channels](http://eventmachine.rubyforge.org/EventMachine/Channel.html), good for single server usage.
+ * Redis, using [em-hiredis](https://github.com/mloughran/em-hiredis#readme) and the [Pub/Sub API](http://redis.io/topics/pubsub). 
+ * Postgres, using the [Notify/Listen API](http://www.postgresql.org/docs/9.1/static/sql-notify.html). Note, this is totally async, no polling.
+
+Usage
+-----
+
+config.ru: 
+
+```ruby
+require 'bundler/setup'
+require 'meerkat' 
+require './app'
+
+#Meerkat.backend = Meerkat::Backend::InMemory.new 
+#Meerkat.backend = Meerkat::Backend::Redis.new 'redis://localhost/0'
+Meerkat.backend = Meerkat::Backend::PG.new :dbname => 'postgres'
+map '/' do
+  run App
+end
+map '/stream' do
+  run Meerkat::RackAdapter.new
+end
+```
+
+On the client:
+
+```javascript
+var source = new EventSource('/stream/mychannel');
+var streamList = document.getElementById('stream');
+source.addEventListener('message', function(e) {
+  var li = document.createElement('li');
+  li.innerHTML = JSON.parse(e.data);
+  streamList.appendChild(li);
+}, false);
+```
+
+To push things:
+
+```ruby
+Meerkat.publish "/mychannel", {:any => hash}
+Meerkat.publish "/mychannel/2", 'any string'
+Meerkat.publish "/mychannel/3", any_object
+```
+
+The published objects will be JSON serialized (with [Yajl](https://github.com/brianmario/yajl-ruby)) before sent to the backend. Deserialize it in the client. 
+
+Read more about Server-Sent Events and the EventSource API on [HTML5Rocks](http://www.html5rocks.com/en/tutorials/eventsource/basics/).
+
+License
+-------
+(MIT license)
+
+Copyright (C) 2011 by Carl Hörberg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:spec) do |t|
+  t.pattern = "spec/**/*_spec.rb"
+end

data/examples/Gemfile

@@ -0,0 +1,6 @@
+source :rubygems
+
+gem 'thin'
+gem 'sinatra'
+gem 'haml'
+gem 'meerkat', :path => '..'

data/examples/app.rb

@@ -0,0 +1,14 @@
+require 'sinatra/base'
+require 'haml'
+
+class App < Sinatra::Base
+  get '*' do
+    @route = params[:splat].join
+    haml :index
+  end
+  post '*' do
+    Meerkat.publish params[:splat].join, params[:message]
+    204
+  end
+end
+

data/examples/config.ru

@@ -0,0 +1,13 @@
+require 'bundler/setup'
+require 'meerkat' 
+require './app'
+
+#Meerkat.backend = Meerkat::Backend::InMemory.new
+#Meerkat.backend = Meerkat::Backend::Redis.new 
+Meerkat.backend = Meerkat::Backend::PG.new :dbname => 'postgres'
+map '/' do
+  run App
+end
+map '/stream' do
+  run Meerkat::RackAdapter.new
+end

data/examples/views/index.haml

@@ -0,0 +1,32 @@
+!!!
+%head
+  %title Meerkat test
+  %script{:src=>'https://ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.min.js', :type => 'text/javascript'}
+%body
+  %fieldset
+    %legend Publish
+    %form#pub{:method => :post}
+      %input{:name => 'message'}
+      %input{:type=>'submit', :value => 'Send'}
+
+  %fieldset
+    %legend Subscribe
+    %p 
+      Subscribing to 
+      %strong= @route
+    %ul#stream
+  :javascript
+    var source = new EventSource('/stream#{@route}');
+    var stream = document.getElementById('stream');
+    source.addEventListener('message', function(e) {
+      var li = document.createElement('li');
+      li.innerHTML = JSON.parse(e.data);
+      stream.appendChild(li);
+    }, false);
+
+    $(function() {
+      $("#pub").submit(function() {
+        $.post(this.action, $(this).serialize())
+        return false
+      });
+    })

data/lib/meerkat/backend/inmemory.rb

@@ -0,0 +1,26 @@
+require 'eventmachine'
+
+module Meerkat
+  module Backend
+    class InMemory
+      def initialize
+        @channel = EventMachine::Channel.new
+      end
+
+      def publish(route, json)
+        @channel.push({:route => route, :json => json})
+      end
+
+      def subscribe(route, &callback)
+        @channel.subscribe do |msg|
+          callback.call(msg[:json]) if msg[:route] == route
+        end
+      end
+
+      def unsubscribe(sid)
+        @channel.unsubscribe(sid)
+      end
+    end
+  end
+end
+

data/lib/meerkat/backend/pg.rb

@@ -0,0 +1,43 @@
+require 'pg'
+
+module Meerkat
+  module Backend
+    class PG
+      def initialize(pg_uri = nil)
+        @pg_uri = pg_uri
+        @pg = PGconn.connect pg_uri
+      end
+
+      def publish(route, json)
+        @pg.exec "SELECT pg_notify($1, $2)", [route, json]
+      end
+
+      def subscribe(route, &callback)
+        pg = PGconn.connect @pg_uri
+        pg.exec "LISTEN #{PGconn.quote_ident route}"
+        EM.watch(pg.socket, SubscribeClient, pg, callback) { |c| c.notify_readable = true }
+      end
+
+      def unsubscribe(pg)
+        pg.detach
+      end
+
+      module SubscribeClient
+        def initialize(pg, cb)
+          @pg = pg
+          @cb = cb
+        end
+        def notify_readable
+          @pg.consume_input
+          msg = @pg.notifies
+          @cb.call(msg[:extra]) if msg
+        end
+        
+        def unbind
+          @pg.close
+        end
+      end
+    end
+  end
+end
+

data/lib/meerkat/backend/redis.rb

@@ -0,0 +1,31 @@
+require 'em-hiredis'
+
+module Meerkat
+  module Backend
+    class Redis
+      def initialize(redis_uri = nil)
+        @redis_uri = redis_uri
+        EM.next_tick {
+          @pub = EM::Hiredis.connect redis_uri
+        }
+      end
+
+      def publish(route, json)
+        @pub.publish route, json
+      end
+
+      def subscribe(route, &callback)
+        sub = EM::Hiredis.connect @redis_uri
+        sub.subscribe route 
+        sub.on :message do |channel, message|
+          callback.call(message) 
+        end
+        sub
+      end
+
+      def unsubscribe(sub)
+        sub.close_connection
+      end
+    end
+  end
+end

data/lib/meerkat/rackadapter.rb

@@ -0,0 +1,57 @@
+module Meerkat
+  class RackAdapter
+    attr_accessor :keep_alive
+    attr_accessor :retry
+    attr_accessor :timeout
+
+    def initialize(app = nil, &blk)
+      blk.call(self) if blk
+    end
+
+    def call(env)
+      body = DeferrableBody.new
+
+      EM.next_tick { 
+        env['async.callback'].call [200, {'Content-Type' => 'text/event-stream'}, body] 
+      }
+
+      EM.next_tick {
+        body << "retry: #{@retry || 3000}\n"
+      }
+
+      path_info = Rack::Utils.unescape env["PATH_INFO"]
+      sub = Meerkat.subscribe(path_info) do |message|
+        body << "data: #{message}\n\n"
+      end
+      body.errback {
+        Meerkat.unsubscribe sub
+      }
+
+      EM.add_periodic_timer(@keep_alive || 20) do
+        body << ":\n"
+      end
+
+      EM.add_timer(@timeout) { body.succeed } if @timeout
+
+      [-1, {}, []]
+    end
+
+    class DeferrableBody
+      include EventMachine::Deferrable
+
+      def call(body)
+        body.each do |chunk|
+          @body_callback.call(chunk)
+        end
+      end
+
+      def <<(str)
+        call([str])
+      end
+
+      def each(&blk)
+        @body_callback = blk
+      end
+    end
+  end
+end

data/lib/meerkat/version.rb

@@ -0,0 +1,3 @@
+module Meerkat
+  VERSION = "0.2.0"
+end

data/lib/meerkat.rb

@@ -0,0 +1,29 @@
+require_relative 'meerkat/version'
+require_relative 'meerkat/rackadapter'
+require_relative 'meerkat/backend/inmemory'
+require_relative 'meerkat/backend/redis'
+require_relative 'meerkat/backend/pg'
+
+require 'yajl'
+
+module Meerkat
+  extend self
+
+  def backend=(backend)
+    @backend = backend
+  end
+
+  def publish(route, message)
+    json = Yajl::Encoder.encode message
+    @backend.publish(route, json)
+  end
+
+  def subscribe(route, &callback)
+    @backend.subscribe(route, &callback)
+  end
+
+  def unsubscribe(sid)
+    @backend.unsubscribe(sid)
+  end
+end
+

data/meerkat.gemspec

@@ -0,0 +1,31 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "meerkat/version"
+
+Gem::Specification.new do |s|
+  s.name        = "meerkat"
+  s.version     = Meerkat::VERSION
+  s.authors     = ["Carl Hörberg"]
+  s.email       = ["carl.hoerberg@gmail.com"]
+  s.homepage    = "https://github.com/carlhoerberg/meerkat"
+  s.summary     = %q{Rack middleware for HTML5 Server-Sent Events, with swappable backends}
+  s.description = %q{Requires an evented Ruby dispatcher, like Thin}
+
+  s.rubyforge_project = "meerkat"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "minitest"
+  s.add_development_dependency "rack-test"
+  s.add_development_dependency "thin_async"
+  s.add_development_dependency "thin-async-test"
+  s.add_development_dependency "em-minitest-spec"
+
+  s.add_runtime_dependency "yajl-ruby"
+  s.add_runtime_dependency "eventmachine"
+  s.add_runtime_dependency "em-hiredis"
+  s.add_runtime_dependency "pg"
+end

data/spec/backend/inmemory_spec.rb

@@ -0,0 +1,30 @@
+require 'minitest/autorun'
+require 'em/minitest/spec'
+require './lib/meerkat/backend/inmemory'
+
+describe 'The in memory backend' do
+  include EM::MiniTest::Spec
+
+  it 'can publish and subscribe' do
+    im = Meerkat::Backend::InMemory.new
+    im.subscribe 'route' do |msg| 
+      @recivied = msg
+    end
+    im.publish 'route', 'messsage'
+    assert_equal 'messsage', @recivied 
+  end
+  it 'can does only subscribe to specific routes' do
+    im = Meerkat::Backend::InMemory.new
+    im.subscribe 'route' do |msg| 
+      @recivied = msg
+    end
+    im.publish 'route2', 'messsage'
+    assert_equal nil, @recivied
+  end
+  it 'can unbsubscribe' do
+    im = Meerkat::Backend::InMemory.new
+    sid = im.subscribe 'route' do |msg| 
+    end
+    im.unsubscribe sid
+  end
+end

data/spec/backend/pg_spec.rb

@@ -0,0 +1,25 @@
+require 'minitest/autorun'
+require 'em/minitest/spec'
+require './lib/meerkat/backend/pg'
+
+describe 'Postgres backend' do
+  include EM::MiniTest::Spec
+
+  it 'can publish and subscribe' do
+    b = Meerkat::Backend::PG.new :dbname => 'postgres'
+    b.subscribe '/' do |msg| 
+      assert_equal 'messsage', msg
+      done!
+    end
+    b.publish '/', 'messsage'
+    wait!
+  end
+
+  it 'can unsubscribe' do
+    b = Meerkat::Backend::PG.new :dbname => 'postgres'
+    sid = b.subscribe 'route' do |msg| 
+    end
+    b.unsubscribe sid
+  end
+end
+

data/spec/backend/redis_spec.rb

@@ -0,0 +1,28 @@
+require 'minitest/autorun'
+require 'em/minitest/spec'
+require './lib/meerkat/backend/redis'
+
+describe 'Redis backend' do
+  include EM::MiniTest::Spec
+
+  it 'can publish and subscribe' do
+    b = Meerkat::Backend::Redis.new
+    b.subscribe '/' do |msg| 
+      assert_equal 'messsage', msg
+      done!
+    end
+    EM.next_tick {
+      b.publish '/', 'messsage'
+    }
+    wait!
+  end
+
+  it 'can unsubscribe' do
+    b = Meerkat::Backend::Redis.new
+    sid = b.subscribe 'route' do |msg| 
+      @recivied = msg
+    end
+    b.unsubscribe sid
+  end
+end
+

data/spec/meerkat_spec.rb

@@ -0,0 +1,36 @@
+require 'bundler/setup'
+require 'minitest/autorun'
+require 'rack/test'
+require 'thin/async/test'
+require './lib/meerkat'
+
+describe 'Meerkat' do
+  include Rack::Test::Methods
+
+  def app
+    Meerkat.backend = Meerkat::Backend::InMemory.new
+    Rack::Builder.new {
+      meerkat = Meerkat::RackAdapter.new do |m|
+        m.keep_alive = 0.1
+        m.timeout = 0.2
+      end
+      run Thin::Async::Test.new(meerkat)
+    }.to_app
+  end
+
+  it 'should return status 200 and content-type text/event-stream' do
+    get '/'
+    assert_equal 200, last_response.status
+    assert_equal 'text/event-stream', last_response.headers['Content-Type']
+  end
+
+  it 'first return a retry value' do
+    get '/'
+    assert_equal "retry: 3000\n", last_response.body.lines.first
+  end
+
+  it 'should periodically emit a comment to keep alive the connection' do
+    get '/'
+    assert_equal ":", last_response.body.split("\n")[1]
+  end
+end

metadata

@@ -0,0 +1,174 @@
+--- !ruby/object:Gem::Specification
+name: meerkat
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+  prerelease: 
+platform: ruby
+authors:
+- Carl Hörberg
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-10-25 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: &70275010936200 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70275010936200
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: &70275010935740 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70275010935740
+- !ruby/object:Gem::Dependency
+  name: thin_async
+  requirement: &70275010935300 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70275010935300
+- !ruby/object:Gem::Dependency
+  name: thin-async-test
+  requirement: &70275010934840 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70275010934840
+- !ruby/object:Gem::Dependency
+  name: em-minitest-spec
+  requirement: &70275010934400 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70275010934400
+- !ruby/object:Gem::Dependency
+  name: yajl-ruby
+  requirement: &70275010933940 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70275010933940
+- !ruby/object:Gem::Dependency
+  name: eventmachine
+  requirement: &70275010933500 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70275010933500
+- !ruby/object:Gem::Dependency
+  name: em-hiredis
+  requirement: &70275010933040 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70275010933040
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: &70275010932600 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70275010932600
+description: Requires an evented Ruby dispatcher, like Thin
+email:
+- carl.hoerberg@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- examples/Gemfile
+- examples/app.rb
+- examples/config.ru
+- examples/views/index.haml
+- lib/meerkat.rb
+- lib/meerkat/backend/inmemory.rb
+- lib/meerkat/backend/pg.rb
+- lib/meerkat/backend/redis.rb
+- lib/meerkat/rackadapter.rb
+- lib/meerkat/version.rb
+- meerkat.gemspec
+- spec/backend/inmemory_spec.rb
+- spec/backend/pg_spec.rb
+- spec/backend/redis_spec.rb
+- spec/meerkat_spec.rb
+homepage: https://github.com/carlhoerberg/meerkat
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 4297295389839479768
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 4297295389839479768
+requirements: []
+rubyforge_project: meerkat
+rubygems_version: 1.8.6
+signing_key: 
+specification_version: 3
+summary: Rack middleware for HTML5 Server-Sent Events, with swappable backends
+test_files:
+- spec/backend/inmemory_spec.rb
+- spec/backend/pg_spec.rb
+- spec/backend/redis_spec.rb
+- spec/meerkat_spec.rb