websocket-rails 0.0.1 → 0.1.0

data/.gitignore

@@ -1,6 +1,10 @@
+.yardoc/
+coverage/
+.DS_Store
 .bundle/
 log/*.log
 pkg/
+doc/
 test/dummy/db/*.sqlite3
 test/dummy/log/*.log
 test/dummy/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 1.9.3

data/Gemfile

@@ -1,3 +1,8 @@
 source "http://rubygems.org"
 
-gemspec
+gemspec
+
+gem "rspec-rails"
+gem "eventmachine", ">= 1.0.0.beta.3"
+gem "faye-websocket"
+gem "simplecov"

data/Gemfile.lock

@@ -1,11 +1,10 @@
 PATH
   remote: .
   specs:
-    websocket-rails (0.0.1)
-      em-websocket (~> 0.3.6)
+    websocket-rails (0.1.0)
+      faye-websocket
       rack
       thin
-      websocket-rack
 
 GEM
   remote: http://rubygems.org/
@@ -37,16 +36,15 @@ GEM
       activemodel (= 3.0.12)
       activesupport (= 3.0.12)
     activesupport (3.0.12)
-    addressable (2.2.7)
     arel (2.0.10)
     builder (2.1.2)
     daemons (1.1.8)
-    em-websocket (0.3.6)
-      addressable (>= 2.1.1)
-      eventmachine (>= 0.12.9)
+    diff-lcs (1.1.3)
     erubis (2.6.6)
       abstract (>= 1.0.0)
-    eventmachine (0.12.10)
+    eventmachine (1.0.0.beta.4)
+    faye-websocket (0.4.5)
+      eventmachine (>= 0.12.0)
     i18n (0.5.0)
     json (1.6.5)
     mail (2.2.19)
@@ -55,6 +53,7 @@ GEM
       mime-types (~> 1.16)
       treetop (~> 1.4.8)
     mime-types (1.18)
+    multi_json (1.3.6)
     polyglot (0.3.3)
     rack (1.2.5)
     rack-mount (0.6.14)
@@ -78,6 +77,23 @@ GEM
     rake (0.9.2.2)
     rdoc (3.12)
       json (~> 1.4)
+    rspec (2.9.0)
+      rspec-core (~> 2.9.0)
+      rspec-expectations (~> 2.9.0)
+      rspec-mocks (~> 2.9.0)
+    rspec-core (2.9.0)
+    rspec-expectations (2.9.1)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.9.0)
+    rspec-rails (2.9.0)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      railties (>= 3.0)
+      rspec (~> 2.9.0)
+    simplecov (0.6.4)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.5.3)
+    simplecov-html (0.5.3)
     sqlite3 (1.3.5)
     thin (1.3.1)
       daemons (>= 1.0.9)
@@ -88,16 +104,16 @@ GEM
       polyglot
       polyglot (>= 0.3.1)
     tzinfo (0.3.32)
-    websocket-rack (0.3.3)
-      em-websocket (~> 0.3.6)
-      rack
-      thin
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  eventmachine (>= 1.0.0.beta.3)
+  faye-websocket
   rails
   rake
+  rspec-rails
+  simplecov
   sqlite3
   websocket-rails!

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2012 YOURNAME
+Copyright 2012 Dan Knox and Kyle Whalen
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,45 +1,71 @@
 # Websocket-Rails
 
-Plug and play WebSocket support for ruby on rails. Includes event router for mapping javascript events to controller actions. There is no need for a separate WebSocket server process. Requests to `/websocket` will be passed through to the embedded WebSocket server provided by the em-websocket gem.
+[![Build Status](https://secure.travis-ci.org/DanKnox/websocket-rails.png)](https://secure.travis-ci.org/DanKnox/websocket-rails)
+
+Plug and play WebSocket support for ruby on rails. Includes event router for mapping javascript events to controller actions. There is no need for a separate WebSocket server process. Requests to `/websocket` will be passed through to the `ConnectionManager` class which is a simple Rack based WebSocket server developed using the `Faye::WebSocket` library.
 
 *Important Note*
 
-This gem is not even close to production ready. This is mostly a proof of concept as of right now. Please try it out and let me know what you like or dislike. We will be adding much more soon including a development road map and full test coverage.
+This is mostly a proof of concept as of right now. Please try it out and let me know what you like or dislike. We will be adding much more soon including a development road map.
+
+*Update*
+
+We are finally very close to the first production release. Any comments or suggestions would be appreciated. The test coverage is now solid and the `ConnectionManager` class has been completely rewritten. There were a few bugs in the connection management on the first release that have been eliminated. Please upgrade to the latest version if you have not yet done so.
 
 ## Installation
 
-Add the gem to your Gemfile
+Check out the [Example Application](https://github.com/DanKnox/websocket-rails-Example-Project) for additional information.
+
+1. Add the gem to your Gemfile
+3. Create a WebsocketRails controller - [See Documentation](http://rdoc.info/github/DanKnox/websocket-rails/master/WebsocketRails/BaseController)
+4. Create an `events.rb` initializer file to map events to your controller - [See Documentation](http://rdoc.info/github/DanKnox/websocket-rails/master/WebsocketRails/Events)
+5. Launch the web server and connect a WebSocket client to `ws://yourserver:port/websocket`
 
 *Important Note About Web Servers*
 
-Thin is the only web server currently supported. Use the `thin-websocket` executable provided by the websocket-rack gem to override the Thin connection timeout setting. The full command to start the server in development is `thin-websocket -p 3000 start`. Be sure to enable config.threadsafe! in your rails application and use the Rack::Fiberpool middleware to take advantage of Thin's asynchronous request processing.
+Thin is the only web server currently supported. Use the `thin-socketrails` executable to override the Thin connection timeout setting. The full command to start the server in development is `thin-socketrails -p 3000 start`. Be sure to enable config.threadsafe! in your rails application and use the Rack::Fiberpool middleware to take advantage of Thin's asynchronous request processing.
 
 ````ruby
-gem 'websocket-ruby'
+gem 'websocket-rails'
 ````
 
+## Event Router
+
 Map WebSocket events to controller actions by creating an `events.rb` file in your app/config/initializers directory
 
+There are two built in events that are fired automatically by the dispatcher. The built in events are `:client_connected` and `:client_disconnected`. They are triggered when a new WebSocket client connects or disconnects to the server. You can handle them however you like by subscribing to the appropriate event in your `events.rb` file.
+
+You can subscribe multiple controllers and actions to the same event to provide very clean event handling logic. The new message will be available in each controller using the `message` method discussed in the *Controllers* section below. The example event router below demonstrates subscribing to the `:new_message` event with one controller action to rebroadcast the message out to all connected clients and another controller action to log the message to a database.
+
 ````ruby
 # app/config/initializers
 
-WebsocketRails::Dispatcher.describe_events do
+WebsocketRails::Events.describe_events do
+  # The :client_connected method is fired automatically when a new client connects
   subscribe :client_connected, to: ChatController, with_method: :client_connected
+	
+  # You can subscribe any number of controller actions to a single event
   subscribe :new_message, to: ChatController, with_method: :new_message
+  subscribe :new_message, to: ChatLogController, with_method: :log_message
+	
   subscribe :new_user, to: ChatController, with_method: :new_user
   subscribe :change_username, to: ChatController, with_method: :change_username
+
+  # The :client_disconnected method is fired automatically when a client disconnects
   subscribe :client_disconnected, to: ChatController, with_method: :delete_user
 end
 ````
 
 The `subscribe` method takes the event name as the first argument, then a hash where `:to` is the Controller class and `:with_method` is the action to execute.
 
+## Javascript Client
+
 The websocket client must connect to `/websocket`. You can connect using the following javascript. Replace the port with the port that your web server is running on.
 
 ````javascript
 var conn = new WebSocket("ws://localhost:3000/websocket")
 conn.onopen = function(evt) {
-	dispatcher.trigger('new_user',current_user)
+	dispatcher.trigger('new_user',current_user) // Dispatcher not included
 }
 
 conn.onmessage = function(evt) {
@@ -54,21 +80,103 @@ We will be posting a basic javascript event dispatcher soon.
 
 ## Controllers
 
-The Websocket::BaseController class provides methods for working with the WebSocket connection. Make sure you extend this class for controllers that you are using. The two most important methods are `send_data` and `broadcast_data`. The `send_data` method sends a message to the client that initiated this event, the `broadcast_data` method broadcasts messages to all connected clients. Both methods take two arguments, the event name to trigger on the client, and the message that accompanies it.
+There are a few differences between WebSocket controllers and standard Rails controllers. The biggest of which, is that each event will be handled by the same, continually running instance of your controller class. This means that if you set any instance variables in your methods, they will still be available when the next event is processed. On top of that, every single client that is connected will share these same instance variables. This can be an advantage if used properly, but it can also lead to bugs if not expected. We provide our own `DataStore` object accessible in a WebsocketRails controller to make it easier to store data isolated from each connected client. This is explained further below.
+
+Do not override the `initialize` method in your class to set up. Instead, define an `initialize_session` method and perform your set up there. The `initialize_session` method will be called the first time a controller is subscribed to an event in the event router. Instance variables defined in the `initialize_session` method will be available throughout the course of the server lifetime.
+
+````
+class ChatController < WebsocketRails::BaseController
+  def initialize_session
+    # perform application setup here
+    @message_count = 0
+  end
+end
+````
+
+The Websocket::BaseController class provides methods for working with the WebSocket connection. Make sure you extend this class for controllers that you are using. The two most important methods are `send_message` and `broadcast_message`. The `send_message` method sends a message to the client that initiated this event, the `broadcast_message` method broadcasts messages to all connected clients. Both methods take two arguments, the event name to trigger on the client, and the message that accompanies it.
 
 ````ruby
-message = {:message => 'this is a message'}
-broadcast_message :event_name, message
-send_message :event_name, message
+new_message = {:message => 'this is a message'}
+broadcast_message :event_name, new_message
+send_message :event_name, new_message
 ````
 
-The message can be a string, hash, or array. The message is serialized as JSON before being sent to the client.
+Here is an example controller for handling the `:new_message` event for a basic chat application.
 
-TODO: Show examples of using these methods.
+````ruby
+class ChatController < WebsocketRails::BaseController
+  def new_message
+    # Print the new message and client id to the console
+    puts "Message from client #{client_id} received: #{message.inspect}"
+    
+    # Broadcast the new message to all connected clients
+    broadcast_message :new_message, message  
+  end
+end
+````
+
+We are using several of the methods provided by `WebsocketRails::BaseController` here, two of which are in the `puts` statement. 
+
+The first method used is the `client_id` method. This method contains the ID of the current WebSocket client that initiated this event. Each connected client is randomly assigned an ID upon connecting to the server. You can keep track of who is who by storing the `client_id` associated with each user somewhere. You can also use the provided `DataStore` (explained later) to make keeping track of users easier.
+
+The next method used is the `message` method. This method will always return the message, if any, that was received along with the event initiated by the client. These messages are JSON decoded by the dispatcher automatically so you can serialize objects in your javascript client and send them along with events.
+
+Lastly, the `broadcast_message` method is called, triggering the `:new_message` event on every connected client and sending the `message` received from the client along with it.
 
 ## Data Store
 
-TODO: write documentation for the data store
+The `DataStore` object is a private Hash. When you access it in a controller, you will be accessing a Hash that is private to the client that initiated the event currently executing. You can use it exactly as you would a regular Hash, except you do not have to worry about it being overridden by the next client that triggers an event. This means that unlike instance variables in WebsocketRails controllers which are shared amongst all connected clients, the data store is an easy place to temporarily persist data for each user between events.
+
+You can access the `DataStore` object by using the `data_store` controller method.
+
+````ruby
+class ChatController < WebsocketRails::BaseController
+  def new_user
+    # The instance variable would be overwritten when the next user joins
+    @user = User.new(name: message[:user_name])  # No Good!
+    
+    # This will be private for each user
+    data_store[:user] = User.new(name: message[:user_name])  # Good!
+    broadcast_user_list
+  end
+end
+````
+
+If you wish to output an Array of the assigned values in the data store for every connected client, you can use the `each_<key>` method, replacing `<key>` with the hash key that you wish to collect. 
+  
+Given our ongoing chat server example, we could collect all of the current `User` objects like so:
+
+````ruby
+data_store[:user] = 'User3'
+data_store.each_user
+=> ['User1','User2','User3']
+````
+
+A simple method for broadcasting the current user list to all clients would look like this:
+
+````ruby
+def broadcast_user_list
+  users = data_store.each_user
+  broadcast_message :user_list, users
+end
+````
+
+## Message Format
+
+The message can be a string, hash, or array. The message is serialized as JSON before being sent to the client. The message arrives at the client as a two element serialized array with the `event_name` string as the first element and the message object you passed to the `message` parameter of the `send_message` method as the second element.
+
+If you executed this code in your controller:
+
+````ruby
+new_message = {:message => 'this is a message'}
+send_message :new_message, new_message
+````
+
+The message that arrives on the client would look like:
+
+````javascript
+['new_message',{message: 'this is a message'}]
+````
 
 ## Development
 

data/Rakefile

@@ -17,16 +17,7 @@ end
 
 Bundler::GemHelper.install_tasks
 
-require 'rake/testtask'
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib'
-  t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = false
-end
-
-task :default => :test
+task :default => :spec
 
 RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
@@ -35,3 +26,20 @@ RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_files.include('README.md')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
+
+require 'rspec/core/rake_task'
+
+desc 'Default: run specs.'
+task :default => :spec
+
+desc "Run specs"
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = "./spec/**/*_spec.rb"
+end
+
+desc "Generate code coverage"
+task :coverage do
+  ENV['COVERAGE'] = 'true'
+  Rake::Task["spec"].execute
+  `open coverage/index.html`
+end

data/bin/thin-socketrails

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# * Borrowed from the <tt>websocket-rack</tt>
+#   Gem as a temporary workaround for the
+#   timeout problem.
+#
+# Modified Thin command line interface script.
+# This is fallback for WebSocket-Rack.
+# Use it when you have EventMachine version < 1.0.0
+# Rationale:
+#   Older versions of EM have bug that prevent to
+#   clearing connection inactivity once it's set.
+#   This one will set connection timeout to 0 at
+#   default, so there will be no need to overwrite it.
+#   Be aware that this will also change inactivity
+#   timeout for "normal" connection, so it will be
+#   easy to make DoS attack.
+
+require 'rubygems'
+require 'thin'
+
+if EM::VERSION < "1.0.0"
+  begin
+    old_verbose, $VERBOSE = $VERBOSE, nil
+    ::Thin::Server.const_set 'DEFAULT_TIMEOUT', 0
+  ensure
+    $VERBOSE = old_verbose
+  end
+end
+
+Thin::Runner.new(ARGV).run!

data/lib/websocket-rails.rb

@@ -1,4 +1,5 @@
 require "active_support/dependencies"
+require 'thin'
 
 module WebsocketRails
   mattr_accessor :app_root
@@ -7,12 +8,20 @@ module WebsocketRails
     yield self
   end
   
+  def self.route_block=(routes)
+    @event_routes = routes
+  end
+  
+  def self.route_block
+    @event_routes
+  end
 end
 
 require "websocket_rails/engine"
 require 'websocket_rails/connection_manager'
 require 'websocket_rails/dispatcher'
+require 'websocket_rails/events'
 require 'websocket_rails/base_controller'
-require 'websocket_rails/extensions/common'
 
-WebsocketRails::Extensions::Common.apply!
+::Thin::Server.send( :remove_const, 'DEFAULT_TIMEOUT' )
+::Thin::Server.const_set( 'DEFAULT_TIMEOUT', 0 )

data/lib/websocket_rails/base_controller.rb

@@ -1,29 +1,110 @@
 require 'websocket_rails/data_store'
 
 module WebsocketRails
+  # Provides controller helper methods for developing a WebsocketRails controller. Action methods
+  # defined on a WebsocketRails controller can be mapped to events using the {Events} class.
+  # This class should be sub classed in a user's application, similar to the ApplicationController
+  # in a Rails application. You can create your WebsocketRails controllers in your standard Rails
+  # controllers directory.
+  #
+  # == Example WebsocketRails controller
+  #   class ChatController < WebsocketRails::BaseController
+  #     # Can be mapped to the :client_connected event in the events.rb file.
+  #     def new_user
+  #       send_message :new_message, {:message => 'Welcome to the Chat Room!'}
+  #     end
+  #   end
+  #
+  # It is best to use the provided {DataStore} to temporarily persist data for each client between
+  # events. Read more about it in the {DataStore} documentation.
   class BaseController
+    
+    # Add observers to specific events or the controller in general. This functionality is similar
+    # to the Rails before_filter methods. Observers are stored as Proc objects and have access
+    # to the current controller environment.
+    #
+    # Observing all events sent to a controller:
+    #   class ChatController < WebsocketRails::BaseController
+    #     observe {
+    #       if data_store.each_user.count > 0
+    #         puts 'a user has joined'
+    #       end
+    #     }
+    #   end
+    # Observing a single event that occurrs:
+    #   observe(:new_message) {
+    #     puts 'new_message has fired!'
+    #   }
+    def self.observe(event = nil, &block)
+      if event
+        @@observers[event] << block
+      else
+        @@observers[:general] << block
+      end
+    end
+    
+    # Stores the observer Procs for the current controller. See {observe} for details.
+    @@observers = Hash.new {|h,k| h[k] = Array.new}
+    
     def initialize
       @data_store = DataStore.new(self)
     end
     
+    # Provides direct access to the Faye::WebSocket connection object for the client that
+    # initiated the event that is currently being executed.
+    def connection
+      @_connection
+    end
+    
+    # The numerical ID for the client connection that initiated the event. The ID is unique
+    # for each currently active connection but can not be used to associate a client between
+    # multiple connection attempts. 
     def client_id
-      @_message.first
+      connection.object_id
     end
-
+    
+    # The current message that was passed from the client when the event was initiated. The
+    # message is typically a standard ruby Hash object. See the README for more information.
     def message
-      @_message.last
+      @_message
     end
-
-    def send_message(event,message)
-      @_dispatcher.send_message event.to_s, [client_id,message]
+    
+    # Sends a message to the client that initiated the current event being executed. Messages
+    # are serialized as JSON into a two element Array where the first element is the event
+    # and the second element is the message that was passed, typically a Hash.
+    #   message_hash = {:message => 'new message for the client'}
+    #   send_message :new_message, message_hash
+    #   # Will arrive on the client as JSON string like the following:
+    #   # ['new_message',{message: 'new message for the client'}]
+    def send_message(event, message)
+      @_dispatcher.send_message event.to_s, message, connection if @_dispatcher.respond_to?(:send_message)
     end
-
-    def broadcast_message(event,message)
-      @_dispatcher.broadcast_message event.to_s, message
+    
+    # Broadcasts a message to all connected clients. See {#send_message} for message passing details.
+    def broadcast_message(event, message)
+      @_dispatcher.broadcast_message event.to_s, message if @_dispatcher.respond_to?(:broadcast_message)
     end
     
+    # Provides access to the {DataStore} for the current controller. The {DataStore} provides convenience
+    # methods for keeping track of data associated with active connections. See it's documentation for
+    # more information.
     def data_store
       @data_store
-    end  
+    end
+    
+    private
+    
+    # Executes the observers that have been defined for this controller. General observers are executed
+    # first and event specific observers are executed last. Each will be executed in the order that
+    # they have been defined. This method is executed by the {Dispatcher}.
+    def execute_observers(event)
+      @@observers[:general].each do |observer|
+        instance_eval( &observer )
+      end
+      @@observers[event].each do |observer|
+        instance_eval( &observer )
+      end
+    end
+    
   end
 end