websocket-rails 0.1.2 → 0.1.3

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# WebsocketRails Change Log
+
+## Version 0.1.3
+
+June 22 2012
+
+* Added support for namespaced events.
+* Improved event machine scheduling for action processing.
+* Made a client's connection ID private.
+* Bugfixes in the JavaScript event dispatchers.
+
+## Version 0.1.2
+
+June 10 2012
+
+* Added streaming HTTP support as a fallback from WebSockets.
+* Added example JavaScript event dispatchers.
+
+## Version 0.1.1
+
+June 2 2012
+
+* Created project home page.
+* Improved test coverage and cleaned up the internals.
+
+## Version 0.1.0
+
+April 14 2012
+
+* Complete project rewrite.
+* Removed websocket-rack dependency.
+* Enhanced documentation.
+* Added event observers in WebsocketRail Controllers.
+* First stable release!

data/Gemfile

@@ -6,5 +6,6 @@ gem "rspec-rails"
 gem "eventmachine", ">= 1.0.0.beta.3"
 gem "faye-websocket"
 gem "simplecov"
+gem "ruby_gntp"
 gem "guard"
 gem "guard-rspec"

data/README.md

@@ -41,10 +41,16 @@ There are two built in events that are fired automatically by the dispatcher. Th
 
 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.
 
+The Event Map now supports namespacing events. Events triggered on the
+client as `namespace.event_name` will now be dispatched the the action
+subscribed to the `event_name` event under the `namespace` namespace.
+See the [EventMap
+Documentation](http://rdoc.info/github/DanKnox/websocket-rails/master/frames/WebsocketRails/EventMap) for more details.
+
 ````ruby
 # app/config/initializers
 
-WebsocketRails::Events.describe_events do
+WebsocketRails::EventMap.describe do
   # The :client_connected method is fired automatically when a new client connects
   subscribe :client_connected, to: ChatController, with_method: :client_connected
 	
@@ -55,6 +61,10 @@ WebsocketRails::Events.describe_events do
   subscribe :new_user, to: ChatController, with_method: :new_user
   subscribe :change_username, to: ChatController, with_method: :change_username
 
+  namespace :product do
+    subscribe :new, to: ProductController, with_method: :new_product
+  end
+
   # The :client_disconnected method is fired automatically when a client disconnects
   subscribe :client_disconnected, to: ChatController, with_method: :delete_user
 end
@@ -62,42 +72,32 @@ 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
+## JavaScript Dispatcher
+
+There are two example dispatchers located in the [assets/javascripts](https://github.com/DanKnox/websocket-rails/tree/master/assets/javascripts) directory. One connects to the server using
+WebSockets and the other connects using streaming HTTP. These will eventually be merged into one dispatcher that selects the best transport at runtime based on what's available in the
+browser. A pull request providing this functionality will definitely be accepted.
 
-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.
+The current dispatchers are limited in functionality and meant mostly as a reference implementation. The two dispatchers are functionally equivalent and can be swapped out at will.
 
 ````javascript
-var conn = new WebSocket("ws://localhost:3000/websocket")
-conn.onopen = function(evt) {
-  // Example dispatcher located in the assets/ directory
-	dispatcher.trigger('new_user',current_user)
-}
-
-conn.onmessage = function(evt) {
-	var data = JSON.parse(evt.data),
-		event_name = data[0],
-		message = data[1];
-	console.log(data)
-}
+//Setting up the dispatcher and connecting to the server:
+var dispatcher = new ServerEventsDispatcher()
+dispatcher.onopen(function() {
+	// trigger a server event immediately after opening connection
+	dispatcher.trigger('new_user',{user_name: 'guest'})
+})
+
+//Triggering a new event on the server
+dispatcher.trigger('event_name',object_to_be_serialized_to_json)
+
+//Listening for new events from the server
+dispatcher.bind('event_name', function(data) {
+	alert(data.user_name)
+})
 ````
 
-There are two example dispatchers located in the
-[assets/javascripts](https://github.com/DanKnox/websocket-rails/tree/master/assets/javascripts) directory.
-One for connecting to the server using WebSockets and the other for
-using streaming HTTP. The HTTP dispatcher was built to mimick the
-WebSocket interface so they are completely interchangable. These will
-eventually be merged into one dispatcher which detects which protocol to
-use based on what's available in the browser. Please feel free to submit
-a pull request that accomplishes this.
-
-View the source for the dispatchers for example usage or check out the
-[example application](https://github.com/DanKnox/websocket-rails-Example-Project) for a working implementation.
-
-*Note on the dispatchers*
-
-The example dispatchers are currently meant to be used for reference and
-are not yet included into the Rails asset pipleline. If you want to use
-one, copy it into your local project.
+Check out the [example application](https://github.com/DanKnox/websocket-rails-Example-Project) for a working implementation.  
 
 ## Controllers
 
@@ -184,7 +184,7 @@ 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 three element serialized array with the `client_id` as the first element,`event_name` string as the second element, and the message object you passed to the `message` parameter of the `send_message` method as the third element.
+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. The example JavaScript dispatchers decode the JSON for you as well as provide a few conveniences for event subscribing and dispatching.
 
 If you executed this code in your controller:
 
@@ -196,7 +196,7 @@ send_message :new_message, new_message
 The message that arrives on the client would look like:
 
 ````javascript
-['70291412510420','new_message',{message: 'this is a message'}]
+['new_message',{message: 'this is a message'}]
 ````
 
 ## Development

data/assets/javascripts/http_dispatcher.js

@@ -21,18 +21,19 @@ var ServerEventsDispatcher = function(){
       open_handler = function(){},
       loaded = false,
       lastPos = 0,
-      client_id = '';
+      client_id = 0;
 
   conn.onreadystatechange = function() {
     if (conn.readyState == 3) {
       var data = conn.responseText.substring(lastPos);
       lastPos = conn.responseText.length;
       var json_data = JSON.parse(data),
-          id = json_data[0],
-          event_name = json_data[1],
-          message = json_data[2];
+          event_name = json_data[0],
+          message = json_data[1];
 
-      client_id = id
+      if (client_id == 0 && event_name == 'client_connected') {
+        client_id = message.connection_id
+      }
       
       if (loaded == false) {
         open_handler();

data/assets/javascripts/websocket_dispatcher.js

@@ -42,11 +42,12 @@ var ServerEventsDispatcher = function(){
 
 	conn.onmessage = function(evt) {
 		var data = JSON.parse(evt.data),
-      id = data[0],
-			event_name = data[1],
-			message = data[2];
-			
-    client_id = id
+			event_name = data[0],
+			message = data[1];
+    
+    if (client_id === '' && event_name === 'client_connected') {
+      client_id = message.connection_id
+    }
 		console.log(data)
 		dispatch(event_name, message)
 	}
@@ -62,4 +63,4 @@ var ServerEventsDispatcher = function(){
 			chain[i]( message )
 		}
 	}	
-}
+}

data/lib/websocket-rails.rb

@@ -20,7 +20,8 @@ end
 require "websocket_rails/engine"
 require 'websocket_rails/connection_manager'
 require 'websocket_rails/dispatcher'
-require 'websocket_rails/events'
+require 'websocket_rails/event'
+require 'websocket_rails/event_map'
 require 'websocket_rails/base_controller'
 
 require 'websocket_rails/connection_adapters'
@@ -28,4 +29,23 @@ require 'websocket_rails/connection_adapters/http'
 require 'websocket_rails/connection_adapters/web_socket'
 
 ::Thin::Server.send( :remove_const, 'DEFAULT_TIMEOUT' )
-::Thin::Server.const_set( 'DEFAULT_TIMEOUT', 0 )
+::Thin::Server.const_set( 'DEFAULT_TIMEOUT', 0 )
+
+# Exceptions
+class InvalidConnectionError < StandardError
+  def rack_response
+    [400,{'Content-Type' => 'text/plain'},['invalid connection']]
+  end
+end
+
+# Deprecation Notices
+class WebsocketRails::Dispatcher
+  def self.describe_events(&block)
+    raise "This method has been deprecated. Please use WebsocketRails::EventMap.describe instead."
+  end
+end
+class WebsocketRails::Events
+  def self.describe_events(&block)
+    raise "This method has been deprecated. Please use WebsocketRails::EventMap.describe instead."
+  end
+end

data/lib/websocket_rails/base_controller.rb

@@ -53,7 +53,7 @@ module WebsocketRails
     # Provides direct access to the Faye::WebSocket connection object for the client that
     # initiated the event that is currently being executed.
     def connection
-      @_connection
+      @_event.connection
     end
     
     # The numerical ID for the client connection that initiated the event. The ID is unique
@@ -66,23 +66,39 @@ module WebsocketRails
     # 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
+      @_event.data
     end
+    alias_method :data, :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.
+    # 
+    #   # Will arrive on the client as JSON string like the following:
+    #   # ['new_message',{'message': 'new message for the client'}]
     #   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 client_id, event.to_s, message, connection if @_dispatcher.respond_to?(:send_message)
+    #
+    # To send an event under a namespace, add the `:namespace => :target_namespace` option.
+    #
+    #   # Will arrive as: ['product.new_message',{'message': 'new message'}]
+    #   send_message :new_message, message_hash, :namespace => :product
+    #
+    # Nested namespaces can be passed as an array like the following:
+    #
+    #   # Will arrive as: ['products.glasses.new',{'message': 'new message'}]
+    #   send_message :new, message_hash, :namespace => [:products,:glasses]
+    #
+    # See the {EventMap} documentation for more on mapping namespaced actions.
+    def send_message(event_name, message, options={})
+      event = Event.new( event_name, message, connection, options )
+      @_dispatcher.send_message event if @_dispatcher.respond_to?(:send_message)
     end
     
     # Broadcasts a message to all connected clients. See {#send_message} for message passing details.
-    def broadcast_message(event, message)
-      @_dispatcher.broadcast_message client_id, event.to_s, message if @_dispatcher.respond_to?(:broadcast_message)
+    def broadcast_message(event_name, message, options={})
+      event = Event.new( event_name, message, connection, options )
+      @_dispatcher.broadcast_message event if @_dispatcher.respond_to?(:broadcast_message)
     end
     
     # Provides access to the {DataStore} for the current controller. The {DataStore} provides convenience

data/lib/websocket_rails/connection_adapters.rb

@@ -4,35 +4,52 @@ module WebsocketRails
     attr_reader :adapters
     module_function :adapters
     
-    def self.register_adapter(adapter)
+    def self.register(adapter)
       @adapters ||= []
       @adapters.unshift adapter
     end
     
-    def self.establish_connection(env)
-      adapter = adapters.detect { |a| a.accepts?( env ) } || return
-      adapter.new( env )
+    def self.establish_connection(env,dispatcher)
+      adapter = adapters.detect { |a| a.accepts?( env ) } || (raise InvalidConnectionError)
+      adapter.new env, dispatcher
     end
     
     class Base
-      
-      ADAPTER_EVENTS = [:onmessage, :onerror, :onclose]
+
+      def self.accepts?(env)
+        false
+      end
       
       def self.inherited(adapter)
-        ConnectionAdapters.register_adapter( adapter )
+        ConnectionAdapters.register adapter
       end
       
-      def initialize(env)
+      attr_accessor :dispatcher
+
+      def initialize(env,dispatcher)
         @env = env
+        @dispatcher = dispatcher
       end
-      
-      ADAPTER_EVENTS.each do |adapter_event|
-        define_method "#{adapter_event}" do |event=nil|
-          instance_variable_get( "@#{adapter_event}" ).call( event )
-        end
-        define_method "#{adapter_event}=" do |block=nil|
-          instance_variable_set( "@#{adapter_event}", block )
-        end
+
+      def on_open(data=nil)
+        event = Event.new_on_open( self, data )
+        dispatch event
+        send event.serialize
+      end
+
+      def on_message(encoded_data)
+        dispatch Event.new_from_json( encoded_data, self )
+      end
+
+      def on_close(data=nil)
+        dispatch Event.new_on_close( self, data )
+        close_connection
+      end
+
+      def on_error(data=nil)
+        event = Event.new_on_error( self, data )
+        dispatch event
+        on_close event.data
       end
       
       def send(message)
@@ -46,6 +63,16 @@ module WebsocketRails
       def id
         object_id.to_i
       end
+
+      private
+
+      def dispatch(event)
+        dispatcher.dispatch( event )
+      end
+
+      def close_connection
+        dispatcher.connection_manager.close_connection self
+      end
     end
     
   end

data/lib/websocket_rails/connection_adapters/http.rb

@@ -3,6 +3,10 @@ module WebsocketRails
     class Http < Base
       TERM = "\r\n".freeze
       TAIL = "0#{TERM}#{TERM}".freeze
+      HttpHeaders = {
+        'Content-Type'      => 'text/json',
+        'Transfer-Encoding' => 'chunked'
+      }
       
       def self.accepts?(env)
         true
@@ -10,15 +14,17 @@ module WebsocketRails
       
       attr_accessor :headers
 
-      def initialize(env)
+      def initialize(env,dispatcher)
         super
         @body = DeferrableBody.new
-        @headers = Hash.new
-        @headers['Content-Type'] = 'text/json'
-        @headers['Transfer-Encoding'] = 'chunked'
-
+        @headers = HttpHeaders
+        
         define_deferrable_callbacks
-        EM.next_tick { @env['async.callback'].call [200, @headers, @body] }
+
+        EM.next_tick do
+          @env['async.callback'].call [200, @headers, @body]
+          on_open
+        end
       end
 
       def send(message)
@@ -29,10 +35,10 @@ module WebsocketRails
       
       def define_deferrable_callbacks
         @body.callback do |event|
-          onclose(event)
+          on_close(event)
         end
         @body.errback do |event|
-          onclose(event)
+          on_close(event)
         end
       end
       
@@ -45,8 +51,6 @@ module WebsocketRails
         size = Rack::Utils.bytesize(c)
         return nil if size == 0
         c.dup.force_encoding(Encoding::BINARY) if c.respond_to?(:force_encoding)
-        puts "Chunking:: #{c}"
-        puts "Chunking:: #{size.to_s(16)}#{TERM}#{c}#{TERM}"
         [size.to_s(16), TERM, c, TERM].join
       end
             

data/lib/websocket_rails/connection_adapters/web_socket.rb

@@ -2,27 +2,28 @@ module WebsocketRails
   module ConnectionAdapters
     class WebSocket < Base
       
-      extend Forwardable
-      
       def self.accepts?(env)
-        ::Faye::WebSocket.websocket?( env )
-      end
-      
-      def self.delegated_methods
-        setter_methods = ADAPTER_EVENTS.map {|e| "#{e}=".to_sym }
-        setter_methods + ADAPTER_EVENTS
+        Faye::WebSocket.websocket?( env )
       end
-      def_delegators :@connection, *delegated_methods
       
-      def initialize(env)
+      def initialize(env,dispatcher)
         super
-        @connection = ::Faye::WebSocket.new( env )
+        @connection = Faye::WebSocket.new( env )
+        @connection.onmessage = method(:on_message)
+        @connection.onerror   = method(:on_error)
+        @connection.onclose   = method(:on_close)
+        on_open
       end
       
       def send(message)
         @connection.send message
       end
+
+      def on_message(event)
+        data = event.respond_to?(:data) ? event.data : event
+        super data
+      end
       
     end
   end
-end
+end