juggernaut_rails 0.5.9

data/README.rdoc

@@ -0,0 +1,95 @@
+Juggernaut
+    by Alex MacCaw http://www.eribium.org
+    minor fixes and unit tests by Ripta Pasay
+    bundled by Karl Varga
+
+== ABOUT
+
+I've created this Gem to simplify the Juggernaut installation process and to improve its integration with Rails.  Previously you needed to install both the Juggernaut Gem and the Rails plugin, and things like log paths just weren't following Rails conventions.
+
+This Gem includes Rake tasks for starting and stopping the Jug server and allows Jug server configurations based on the Rails environment, as well as better support for jQuery.  For instance when we deploy to production we use Capistrano so we want our production PID to be in the <tt>shared/pids/</tt> directory, while in development we stick with the default: <tt>tmp/pids/</tt>.  Now your <tt>config/juggernaut.yml</tt> configuration can handle that.
+
+At the time of writing (Oct 29 2009) this Gem is based on (the latest) version 0.5.8 of Alex MacCaw's Gem and includes the latest <tt>juggernaut_plugin</tt>.
+
+== INSTALL
+
+Install the gem
+
+  # This requires GemCutter.  To get started with GemCutter:
+  #  gem install gemcutter
+  #  gem tumble
+  gem install juggernaut_rails
+
+Now add the gem to your application and include Juggernaut's Rake tasks in your app's Rakefile:
+
+  # config/environment.rb
+  config.gem 'juggernaut_rails'
+
+  # Rakefile
+  begin
+    require 'juggernaut/rails/tasks'
+  rescue Exception => e
+    puts "Warning, couldn't load gem tasks: #{e.message}! Skipping..."
+  end
+
+Copy the required media files into your application:
+
+  rake juggernaut:install
+
+If you are using jQuery, you will need the jQuery JS files as well:
+
+  rake juggernaut:install:jquery
+
+Include the Juggernaut scripts in your layout and create a simple Jug view:
+
+  # app/views/layout/application.html.erb
+  <%= javascript_include_tag :defaults, :juggernaut %>
+  
+  # If you're using jQuery (note: the jQuery library is not included in Juggernaut's install)
+  # <%= javascript_include_tag 'jquery', :juggernaut_jquery %>
+  
+  # app/views/your/view.html.erb
+  <%= juggernaut %>
+    
+Start your Juggernaut server.  To control the server use these Rake tasks:
+
+  rake juggernaut:start
+  rake juggernaut:stop
+
+Start your Rails application, open your browser and visit the view we created earlier.
+Now in your <tt>script/console</tt> execute the following:
+
+  Juggernaut.send_to_all("alert('hi from juggernaut')") 
+
+You should get the alert message in your browser, or in the console log if you are using FireFox's FireBug.
+  
+Take a look at the configuration options in <tt>config/juggernaut.yml</tt> and <tt>config/juggernaut_hosts.yml</tt>.  Look at your debugging log output in <tt>log/juggernaut.log</tt> and the PID of the running Jug server in <tt>tmp/pids/juggernaut.5001.pid</tt>.  By default debugging is turned on when running in <tt>development</tt> mode.
+  
+== DESCRIPTION:
+See Plugin README:
+    http://juggernaut.rubyforge.org/svn/trunk/juggernaut/README
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Alex MacCaw
+
+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,27 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "juggernaut_rails"
+    gemspec.summary = "A push server written in Ruby with Rails integration."
+    gemspec.email = "info@eribium.org"
+    gemspec.homepage = "http://juggernaut.rubyforge.org"
+    gemspec.rubyforge_project = 'juggernaut'
+    gemspec.description = <<-END
+      The Juggernaut Gem for Ruby on Rails aims to revolutionize your Rails app by letting the server initiate a connection and push data to the client. In other words your app can have a real time connection to the server with the advantage of instant updates. Although the obvious use of this is for chat, the most exciting prospect for me is collaborative cms and wikis.
+      
+      This Gem bundles Alex MacCaw's Juggernaut Gem and Rails plugin into one, and extends its Rails intergration for a simpler install and setup.
+      END
+    gemspec.authors = ["Alex MacCaw"]
+    gemspec.require_paths = ['lib', 'lib/juggernaut']
+    gemspec.files = FileList['[A-Z]*',
+                       '{bin,lib,media,rails,test,rails}/**/*']
+    gemspec.add_dependency 'eventmachine', '>= 0.10.0'
+    gemspec.add_dependency 'json', '>= 1.1.2'  
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end

data/VERSION

@@ -0,0 +1 @@
+0.5.9

data/bin/juggernaut

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require File.join(File.dirname(__FILE__), '..', 'lib', 'juggernaut')
+Juggernaut::Runner.run

data/lib/juggernaut.rb

@@ -0,0 +1,158 @@
+require 'rubygems'
+require 'logger'
+require 'eventmachine'
+require 'json'
+$:.unshift(File.dirname(__FILE__))
+
+module Juggernaut
+  VERSION   = '0.5.8'
+  
+  class JuggernautError < StandardError #:nodoc:
+  end
+
+  @@options = {}
+  
+  DEFAULT_CONFIG_FILE = <<-EOF
+     # ======================
+     # Juggernaut Options
+     # ======================
+
+     # === Subscription authentication ===
+     # Leave all subscription options uncommented to allow anyone to subscribe.
+
+     # If specified, subscription_url is called everytime a client subscribes.
+     # Parameters passed are: session_id, client_id and an array of channels.
+     # 
+     # The server should check that the session_id matches up to the client_id
+     # and that the client is allowed to access the specified channels.
+     # 
+     # If a status code other than 200 is encountered, the subscription_request fails
+     # and the client is disconnected.
+     # 
+     # :subscription_url:  http://localhost:3000/sessions/juggernaut_subscription
+
+     # === Broadcast and query authentication ===
+     # Leave all broadcast/query options uncommented to allow anyone to broadcast/query.
+     # 
+     # Broadcast authentication in a production environment is very importantant since broadcasters
+     # can execute JavaScript on subscribed clients, leaving you vulnerable to cross site scripting
+     # attacks if broadcasters aren't authenticated. 
+
+     # 1) Via IP address
+     # 
+     # If specified, if a client has an ip that is specified in allowed_ips, than it is automatically
+     # authenticated, even if a secret_key isn't provided. 
+     # 
+     # This is the recommended method for broadcast authentication.
+     #
+     :allowed_ips: 
+                  - 127.0.0.1
+                  # - 192.168.0.1
+
+     # 2) Via HTTP request
+     # 
+     # If specified, if a client attempts a broadcast/query, without a secret_key or using an IP
+     # no included in allowed_ips, then broadcast_query_login_url will be called.
+     # Parameters passed, if given, are: session_id, client_id, channels and type.
+     # 
+     # The server should check that the session_id matches up to the client id, and the client
+     # is allowed to perform that particular type of broadcast/query.
+     # 
+     # If a status code other than 200 is encountered, the broadcast_query_login_url fails
+     # and the client is disconnected.
+     # 
+     # :broadcast_query_login_url: http://localhost:3000/sessions/juggernaut_broadcast
+
+     # 3) Via shared secret key
+     # 
+     # This secret key must be sent with any query/broadcast commands. 
+     # It must be the same as the one in the Rails config file.
+     # 
+     # You shouldn't authenticate broadcasts from subscribed clients using this method
+     # since the secret_key will be easily visible in the page (and not so secret any more)!
+     # 
+     # :secret_key: your_secret_key_here
+
+     # == Subscription Logout ==
+
+     # If specified, logout_connection_url is called everytime a specific connection from a subscribed client disconnects. 
+     # Parameters passed are session_id, client_id and an array of channels specific to that connection.
+     # 
+     # :logout_connection_url: http://localhost:3000/sessions/juggernaut_connection_logout
+
+     # Logout url is called when all connections from a subscribed client are closed.
+     # Parameters passed are session_id and client_id.
+     # 
+     # :logout_url: http://localhost:3000/sessions/juggernaut_logout
+
+     # === Miscellaneous ===
+
+     # timeout defaults to 10. A timeout is the time between when a client closes a connection
+     # and a logout_request or logout_connection_request is made. The reason for this is that a client
+     # may only temporarily be disconnected, and may attempt a reconnect very soon.
+     # 
+     # :timeout: 10
+
+     # store_messages defaults to false. If this option is true, messages send to connections will be stored. 
+     # This is useful since a client can then receive broadcasted message that it has missed (perhaps it was disconnected).
+     #
+     # :store_messages: false
+
+     # === Server ===
+
+     # Host defaults to "0.0.0.0". You shouldn't need to change this.
+     # :host: 0.0.0.0
+
+     # Port is mandatory
+     :port: 5001
+     
+     # Defaults to value of :port. If you are doing port forwarding you'll need to configure this to the same 
+     # value as :public_port in the juggernaut_hosts.yml file
+     # :public_port: 5001
+
+  EOF
+
+  class << self
+    def options
+      @@options
+    end
+    
+    def options=(val)
+      @@options = val
+    end
+    
+    def logger
+      return @@logger if defined?(@@logger) && !@@logger.nil?
+      FileUtils.mkdir_p(File.dirname(log_path))
+      @@logger = Logger.new(log_path)
+      @@logger.level = Logger::INFO if options[:debug] == false
+      @@logger
+    rescue
+      @@logger = Logger.new(STDOUT)
+    end
+    
+    def logger=(logger)
+      @@logger = logger
+    end
+    
+    def log_path
+      options[:log_path] || File.join(%w( / var run juggernaut.log ))
+    end
+    
+    def pid_path
+      options[:pid_path] || File.join(%w( / var run ), "juggernaut.#{options[:port]}.pid" )
+    end
+      
+    def config_path
+      options[:config_path] || File.join(%w( / var run juggernaut.yml ))
+    end
+    
+  end
+end
+
+require 'juggernaut/utils'
+require 'juggernaut/miscel'
+require 'juggernaut/message'
+require 'juggernaut/client'
+require 'juggernaut/server'
+require 'juggernaut/runner'

data/lib/juggernaut/client.rb

@@ -0,0 +1,263 @@
+require 'timeout'
+require 'net/http'
+require 'net/https'
+require 'uri'
+
+module Juggernaut
+  class Client
+    include Juggernaut::Miscel
+
+    @@clients = [ ]
+
+    attr_reader   :id
+    attr_accessor :session_id
+    attr_reader   :connections
+
+    class << self
+      # Actually does a find_or_create_by_id
+      def find_or_create(subscriber, request)
+        if client = find_by_id(request[:client_id])
+          client.session_id = request[:session_id]
+          client.add_new_connection(subscriber)
+          client
+        else
+          self.new(subscriber, request)
+        end
+      end
+
+      # Client find methods
+      def find_all
+        @@clients
+      end
+
+      def find(&block)
+        @@clients.select(&block).uniq
+      end
+
+      def find_by_id(id)
+        find { |client| client.id == id }.first
+      end
+
+      def find_by_signature(signature)
+        # signature should be unique
+        find do |client| 
+          client.connections.select { |connection| connection.signature == signature }.any?
+        end.first
+      end
+
+      def find_by_channels(channels)
+        find do |client| 
+          client.has_channels?(channels)
+        end
+      end
+
+      def find_by_id_and_channels(id, channels)
+        find do |client| 
+          client.has_channels?(channels) && client.id == id
+        end.first
+      end
+
+      def send_logouts_after_timeout
+        @@clients.each do |client|
+          if client.give_up?
+            client.logout_request
+          end
+        end
+      end
+
+      # Called when the server is shutting down
+      def send_logouts_to_all_clients
+        @@clients.each do |client|
+          client.logout_request
+        end
+      end
+
+      def reset!
+        @@clients.clear
+      end
+
+      def register_client(client)
+        @@clients << client unless @@clients.include?(client)
+      end
+
+      def client_registered?(client)
+        @@clients.include?(client)
+      end
+
+      def unregister_client(client)
+        @@clients.delete(client)
+      end
+    end
+
+    def initialize(subscriber, request)
+      @connections = []
+      @id         = request[:client_id]
+      @session_id = request[:session_id]
+      @messages   = []
+      @logout_timeout = 0
+      self.register
+      add_new_connection(subscriber)
+    end
+
+    def to_json
+      {
+        :client_id  => @id, 
+        :num_connections => @connections.size,
+        :session_id => @session_id
+      }.to_json
+    end
+
+    def add_new_connection(subscriber)
+      @connections << subscriber
+    end
+
+    def friendly_id
+      if self.id
+        "with ID #{self.id}"
+      else
+        "session #{self.session_id}"
+      end
+    end
+
+    def subscription_request(channels)
+      return true unless options[:subscription_url]
+      post_request(options[:subscription_url], channels, :timeout => options[:post_request_timeout] || 5)
+    end
+
+    def logout_connection_request(channels)
+      return true unless options[:logout_connection_url]
+      post_request(options[:logout_connection_url], channels, :timeout => options[:post_request_timeout] || 5)
+    end
+
+    def logout_request
+      self.unregister
+      logger.debug("Timed out client #{friendly_id}")
+      return true unless options[:logout_url]
+      post_request(options[:logout_url], [ ], :timeout => options[:post_request_timeout] || 5)
+    end
+    
+    def remove_connection(connection)
+      @connections.delete(connection)
+      self.reset_logout_timeout!
+      self.logout_request if self.give_up?
+    end
+
+    def send_message(msg, channels = nil)
+      store_message(msg, channels) if options[:store_messages]
+      send_message_to_connections(msg, channels)
+    end
+
+    # Send messages that are queued up for this particular client.
+    # Messages are only queued for previously-connected clients.
+    def send_queued_messages(connection)
+      self.expire_queued_messages!
+
+      # Weird looping because we don't want to send messages that get
+      # added to the array after we start iterating (since those will
+      # get sent to the client anyway).
+      @length = @messages.length
+
+      logger.debug("Sending #{@length} queued message(s) to client #{friendly_id}")
+
+      @length.times do |id|
+        message = @messages[id]
+        send_message_to_connection(connection, message[:message], message[:channels])
+      end
+    end
+
+    def channels
+      @connections.collect { |em| em.channels }.flatten.uniq
+    end
+
+    def has_channels?(channels)
+      @connections.each do |em|
+        return true if em.has_channels?(channels)
+      end
+      false
+    end
+
+    def remove_channels!(channels)
+      @connections.each do |em|
+        em.remove_channels!(channels)
+      end
+    end
+
+    def alive?
+      @connections.select { |em| em.alive? }.any?
+    end
+
+    # This client is only dead if there are no connections and we are
+    # past the timeout (if we are within the timeout, the user could
+    # just be doing a page reload or going to a new page)
+    def give_up?
+      !alive? and (Time.now > @logout_timeout)
+    end
+
+    protected
+
+    def register
+      self.class.register_client(self)
+    end
+
+    def registered?
+      self.class.client_registered?(self)
+    end
+
+    def unregister
+      self.class.unregister_client(self)
+    end
+
+    def post_request(url, channels = [ ], options = { })
+      uri = URI.parse(url)
+      uri.path = '/' if uri.path == ''
+      params = []
+      params << "client_id=#{id}" if id
+      params << "session_id=#{session_id}" if session_id
+      channels.each {|chan| params << "channels[]=#{chan}" }
+      headers = {"User-Agent" => "Ruby/#{RUBY_VERSION}"}
+      begin
+        http = Net::HTTP.new(uri.host, uri.port)
+        if uri.scheme == 'https'
+          http.use_ssl = true
+          http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        end
+        http.read_timeout = options[:timeout] || 5
+        resp, data = http.post(uri.path, params.join('&'), headers)
+        return resp.is_a?(Net::HTTPOK)
+      rescue => e
+        logger.error("Bad request #{url.to_s} (#{e.class}: #{e.message})")
+        return false
+      rescue Timeout::Error
+        logger.error("#{url.to_s} timeout")
+        return false
+      end
+    end  
+
+    def send_message_to_connections(msg, channels)
+      @connections.each do |connection|
+        send_message_to_connection(connection, msg, channels)
+      end
+    end
+
+    def send_message_to_connection(connection, msg, channels)
+      connection.broadcast(msg) if !channels or channels.empty? or connection.has_channels?(channels)
+    end
+
+    # Queued messages are stored until a timeout is reached which is the
+    # same as the connection timeout. This takes care of messages that
+    # come in between page loads or ones that come in right when you are
+    # clicking off one page and loading the next one.
+    def store_message(msg, channels)
+      self.expire_queued_messages!
+      @messages << { :channels => channels, :message => msg, :timeout => Time.now + options[:timeout] }
+    end
+
+    def expire_queued_messages!
+      @messages.reject! { |message| Time.now > message[:timeout] }
+    end
+
+    def reset_logout_timeout!
+      @logout_timeout = Time.now + options[:timeout]
+    end
+  end
+end