bayeux-rack 0.6.0

data/README.rdoc

@@ -0,0 +1,37 @@
+= bayeux.rack
+
+Bayeux (COMET or long-polling) protocol server as a Sinatra application.
+Light weight and high scalability are achieved by using the
+asynchronous Rack extensions added to Thin by async_sinatra.
+
+Because it uses async_sinatra, which uses EventMachine, it won't work in Passenger.
+Sorry about that, but Apache doesn't really like long-polling anyhow. Use Thin.
+
+== Usage
+
+See http://github.com/cjheath/jquery.comet
+for an example of usage and for a COMET client in Javascript.
+
+== Installing
+
+  gem install bayeux-rack
+
+== License
+
+The jquery.comet.js and chat_server are subject to the MIT license.
+
+== Developing
+
+Fork on github https://github.com/cjheath/bayeux-rack or just clone to play:
+
+  git clone git://github.com/cjheath/bayeux-rack.git
+
+Patches welcome! Fork and send a pull request. Please follow coding conventions already in use.
+Please use jslint if you can. There are currently no warnings, please keep it that way.
+
+== Status
+
+Current release has a happy path (working ok). Significant drawbacks to be fixed are:
+
+* Server-side timeout of long-polls to avoid possible loss of sent messages
+* Detecting multiple connections (tabs?) from the same browser, to fall back to callback polling.

data/Rakefile

@@ -0,0 +1,58 @@
+require 'rubygems'
+require 'rake'
+
+require 'jeweler'
+require './lib/bayeux'
+
+Jeweler::Tasks.new do |gem|
+  gem.name = "bayeux-rack"
+  gem.version = Bayeux::VERSION
+  gem.homepage = "http://github.com/cjheath/bayeux-rack"
+  gem.license = "MIT"
+  gem.summary = %Q{Bayeux (COMET or long-polling) protocol server as a Sinatra application}
+  gem.description = %Q{
+Bayeux (COMET or long-polling) protocol server as a Sinatra application.
+Light weight and high scalability are achieved by using the
+asynchronous Rack extensions added to Thin by async_sinatra.}
+  gem.email = %w[clifford.heath@gmail.com]
+  gem.authors = ["Clifford Heath"]
+  gem.add_runtime_dependency 'json', '>= 1.5.1'
+  gem.add_runtime_dependency 'async_sinatra', '> 0.1'
+  gem.add_runtime_dependency 'eventmachine', '>= 0.12'
+  gem.add_runtime_dependency 'thin', '>= 1.2'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+task :default => :test
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "bayeux-rack #{Bayeux::VERSION}"
+  rdoc.rdoc_files.include('README.rdoc')
+  # rdoc.rdoc_files.include('History.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+desc 'Generate website files'
+task :website_generate do
+  sh %q{ruby script/txt2html website/index.txt > website/index.html}
+end
+
+desc 'Upload website files via rsync'
+task :website_upload do
+  local_dir  = 'website'
+  website_config = YAML.load(File.read("config/website.yml"))
+  host       = website_config["host"]
+  host       = host ? "#{host}:" : ""
+  remote_dir = website_config["remote_dir"]
+  sh %{rsync -aCv #{local_dir}/ #{host}#{remote_dir}}
+end
+

data/lib/bayeux.rb

@@ -0,0 +1,343 @@
+#
+# A Bayeux (COMET) server using Async Sinatra.
+# This requires a web server built on EventMachine, such as Thin.
+#
+# Copyright: Clifford Heath http://dataconstellation.com 2011
+# License: MIT
+#
+require 'sinatra'
+require 'sinatra/async'
+require 'json'
+require 'eventmachine'
+
+# A Sinatra application that handles PUTs and POSTs on the /cometd URL,
+# implementing the COMET protocol.
+class Bayeux < Sinatra::Base
+  # The Gem version of this implementation
+  VERSION = "0.6.0"
+  register Sinatra::Async
+
+  # A connected client
+  class Client
+    # The clientId we assigned
+    attr_accessor :clientId
+
+    # Timestamp when we last had activity from this client
+    #attr_accessor :lastSeen
+
+    # The EM::Channel on which this client subscribes
+    attr_accessor :channel
+
+    # The EM::Subscription a long-poll is currently active
+    attr_accessor :subscription
+
+    # Messages queued for this client (an Array)
+    attr_accessor :queue
+
+    # Array of channels this client is subscribed to
+    attr_accessor :channels
+
+    def initialize clientId     #:nodoc:
+      @clientId = clientId
+      @channel = EM::Channel.new
+      @queue = []
+      @channels = []
+    end
+
+    def flush sinatra           #:nodoc:
+      queued = @queue
+      sinatra.trace "Sending to #{@clientId}: #{queued.inspect}"
+      @queue = []
+
+      sinatra.respond(queued)
+    end
+  end
+
+  enable :show_exceptions
+
+  # Perhaps some initialisation here in future?
+  #def initialize *a, &b
+  #  super
+  #end
+
+  configure do
+    set :tracing, false         # Enable to get Bayeux tracing
+    set :poll_interval, 5       # 5 seconds for polling
+    set :long_poll_interval, 30 # maximum duration for a long-poll
+  end
+
+  # Trace to stdout if the :tracing setting is enabled
+  def trace s
+    if settings.tracing
+      puts s
+    end
+  end
+
+  # A Hash of channels by channel name. Each channel is an Array of subscribed clients
+  def channels
+    # Sinatra dup's this object, so we have to use class variables
+    @@channels ||= Hash.new {|h, k| h[k] = [] }
+  end
+
+  # A Hash of all clients by clientId
+  def clients
+    @@clients ||= {}
+  end
+
+  # ClientIds should be strong random numbers containing at least 128 bits of entropy. These aren't!
+  def next_client_id
+    @@next_client_id ||= 0
+    (@@next_client_id += 1).to_s
+  end
+
+  # Send a message (a Hash) to a channel.
+  # The message must have the channel name under the key :channel or "channel"
+  def publish message
+    channel = message['channel'] || message[:channel]
+    clients = channels[channel]
+    trace "publishing to #{channel} with #{clients.size} subscribers: #{message.inspect}"
+    clients.each do | client|
+      client.queue << message
+      client.channel.push true    # Wake up the subscribed client
+    end
+  end
+
+  # Handle a request from a client. Normally over-ridden in the subclass to add server behaviour.
+  def deliver(message)
+    id = message['id']
+    clientId = message['clientId']
+    channel_name = message['channel']
+
+    response =
+      case channel_name
+      when '/meta/handshake'      # Client says hello, greet them
+        clientId = next_client_id
+        clients[clientId] = Client.new(clientId)
+        trace "Client #{clientId} offers a handshake from #{request.ip}"
+        handshake message
+
+      when '/meta/subscribe'      # Client wants to subscribe to a channel:
+        subscribe message
+
+      when '/meta/unsubscribe'    # Client wants to unsubscribe from a channel:
+        unsubscribe message
+
+      # This is the long-polling request.
+      when '/meta/connect'
+        connect message
+
+      when '/meta/disconnect'
+        disconnect message
+
+      # Other meta channels are disallowed
+      when %r{/meta/(.*)}
+        trace "Client #{clientId} tried to send a message to #{channel_name}"
+        { :successful => false }
+
+      # Service channels default to no-op. Service messages are never broadcast.
+      when %r{/service/(.*)}
+        trace "Client #{clientId} sent a private message to #{channel_name}"
+        { :successful => true }
+
+      else
+        puts "Unknown channel in request: "+message.inspect
+        pass  # 404
+      end
+
+    # Set the standard parameters for all response messages
+    if response
+      response[:channel] = channel_name
+      response[:clientId] = clientId
+      response[:id] = id
+      [response]
+    else
+      []
+    end
+  end
+
+  # Send an asynchronous JSON or JSONP response to an async_sinatra GET or POST
+  def respond messages
+    if jsonp = params['jsonp']
+      trace "responding jsonp=#{messages.to_json}"
+      headers({'Content-Type' => 'text/javascript'})
+      body "#{jsonp}(#{messages.to_json});\n"
+    else
+      trace "responding #{messages.to_json}"
+      headers({'Content-Type' => 'application/json'})
+      body messages.to_json
+    end
+  end
+
+  protected
+
+  # Handle a handshake request from a client
+  def handshake message
+    publish :channel => '/cometd/meta', :data => {}, :action => "handshake", :reestablish => false, :successful => true
+    publish :channel => '/cometd/meta', :data => {}, :action => "connect", :successful => true
+    interval = params['jsonp'] ? settings.poll_interval : settings.long_poll_interval
+    trace "Setting interval to #{interval}"
+    {
+      :version => '1.0',
+      :supportedConnectionTypes => ['long-polling','callback-polling'],
+      :successful => true,
+      :advice => { :reconnect => 'retry', :interval => interval*1000 },
+      :minimumVersion => message['minimumVersion'],
+    }
+  end
+
+  # Handle a request by a client to subscribe to a channel
+  def subscribe message
+    clientId = message['clientId']
+    subscription = message['subscription']
+    if subscription =~ %r{^/meta/}
+      # No-one may subscribe to meta channels.
+      # The Bayeux protocol allows server-side clients to (e.g. monitoring apps) but we don't.
+      trace "Client #{clientId} may not subscribe to #{subscription}"
+      { :successful => false, :error => "500" }
+    else
+      subscribed_channel = subscription
+      trace "Client #{clientId} wants messages from #{subscribed_channel}"
+      client_array = channels[subscribed_channel]
+      client = clients[clientId]
+      if client and !client_array.include?(client)
+        client_array << client
+        client.channels << subscribed_channel
+      end
+      publish message
+      {
+        :successful => true,
+        :subscription => subscribed_channel
+      }
+    end
+  end
+
+  # Handle a request by a client to unsubscribe from a channel
+  def unsubscribe message
+    clientId = message['clientId']
+    subscribed_channel = message['subscription']
+    trace "Client #{clientId} no longer wants messages from #{subscribed_channel}"
+    client_array = channels[subscribed_channel]
+    client = clients[clientId]
+    client.channels.delete(subscribed_channel)
+    client_array.delete(client)
+    publish message
+    {
+      :successful => true,
+      :subscription => subscribed_channel
+    }
+  end
+
+  # Handle a long-poll request by a client
+  def connect message
+    @is_connect = true
+    clientId = message['clientId']
+    # trace "Client #{clientId} is long-polling"
+    client = clients[clientId]
+    pass unless client        # Or "not authorised", or "handshake"?
+
+    connect_response = {
+      :channel => '/meta/connect', :clientId => clientId, :id => message['id'], :successful => true
+    }
+
+    queued = client.queue
+    if !queued.empty? || client.subscription
+      if client.subscription
+        # If the client opened a second long-poll, finish that one and this:
+        client.channel.push true    # Complete the outstanding poll
+      end
+      client.queue << connect_response
+      client.flush(self)
+      return
+    end
+
+    client.subscription =
+      client.channel.subscribe do |msg|
+        queued = client.queue
+        trace "Client #{clientId} awoke but found an empty queue" if queued.empty?
+        client.queue << connect_response
+        client.flush(self)
+      end
+
+    if client.subscription
+      # trace "Client #{clientId} is waiting on #{client.subscription}"
+      on_close {
+        client.channel.unsubscribe(client.subscription)
+        client.subscription = nil
+      }
+    else
+      trace "Client #{clientId} failed to wait"
+    end
+    nil
+  end
+
+  # Handle a disconnect request from a client
+  def disconnect message
+    clientId = message['clientId']
+    if client = clients[clientId]
+      # Unsubscribe all subscribed channels:
+      while !client.channels.empty?
+        unsubscribe({'clientId' => clientId, 'channel' => '/meta/unsubscribe', 'subscription' => client.channels[0]})
+      end
+      client.queue += [{:channel => '/cometd/meta', :data => {}, :action => "connect", :successful => false}]
+      # Finish an outstanding poll:
+      client.channel.push true if client.subscription
+      clients.delete(clientId)
+      { :successful => true }
+    else
+      { :successful => false }
+    end
+  end
+
+  # Deliver a Bayeux message or array of messages
+  def deliver_all(message)
+    begin
+      if message.is_a?(Array)
+        response = []
+        message.map do |m|
+          response += [deliver(m)].flatten
+        end
+        response
+      else
+        Array(deliver(message))
+      end
+    rescue NameError    # Usually an "Uncaught throw" from calling pass
+      raise
+    rescue => e
+      puts "#{e.class.name}: #{e.to_s}\n#{e.backtrace*"\n\t"}"
+    end
+  end
+
+  # Parse a message (or array of messages) from an HTTP request and deliver the messages
+  def receive message_json
+    message = JSON.parse(message_json)
+
+    # The message here should either be a connect message (long-poll) or messages being sent.
+    # For a long-poll we return a reponse immediately only if messages are queued for this client.
+    # For a send-message, we always return a response immediately, even if it's just an acknowledgement.
+    @is_connect = false
+    response = deliver_all(message)
+    return if @is_connect
+
+    if clientId = params['clientId'] and client = clients[clientId]
+      client.queue += response
+      client.flush if params['jsonp'] || !client.queue.empty?
+    else
+      # No client so no queue. Respond immediately if we can, else long-poll
+      respond(response) unless response.empty?
+    end
+  rescue => e
+    respond([])
+  end
+
+  # Normal JSON operation uses a POST
+  apost '/cometd' do
+    receive params['message']
+  end
+
+  # JSONP always uses a GET, since it fulfils a script tag.
+  # GETs can only send data which fit into a single URL.
+  aget '/cometd' do
+    receive params['message']
+  end
+
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification 
+name: bayeux-rack
+version: !ruby/object:Gem::Version 
+  hash: 7
+  prerelease: 
+  segments: 
+  - 0
+  - 6
+  - 0
+  version: 0.6.0
+platform: ruby
+authors: 
+- Clifford Heath
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-06-17 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 1
+        segments: 
+        - 1
+        - 5
+        - 1
+        version: 1.5.1
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: async_sinatra
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        hash: 9
+        segments: 
+        - 0
+        - 1
+        version: "0.1"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: eventmachine
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 19
+        segments: 
+        - 0
+        - 12
+        version: "0.12"
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: thin
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 11
+        segments: 
+        - 1
+        - 2
+        version: "1.2"
+  type: :runtime
+  version_requirements: *id004
+description: |-
+  
+  Bayeux (COMET or long-polling) protocol server as a Sinatra application.
+  Light weight and high scalability are achieved by using the
+  asynchronous Rack extensions added to Thin by async_sinatra.
+email: 
+- clifford.heath@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- Rakefile
+- lib/bayeux.rb
+homepage: http://github.com/cjheath/bayeux-rack
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.5
+signing_key: 
+specification_version: 3
+summary: Bayeux (COMET or long-polling) protocol server as a Sinatra application
+test_files: []
+