websocket-rails 0.1.5 → 0.1.6

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # WebsocketRails Change Log
 
+## Version 0.1.6
+
+July 17 2012
+
+* Added private channel support - Thanks to @MhdSyrwan
+* Added DSL method for marking channels as private.
+* Added support for attaching success and failure callbacks to triggered
+  events on the JavaScript client.
+* Fixed JSON parsing bug in HTTP streaming client when multiple events
+  were received together.
+* Added connection keepalive ping/pong timers to ensure clients do not
+  disconnect automatically. Ensures HTTP streaming works well on Heroku.
+* Removed the requirement of using the thin-socketrails executable. The
+  executable will be removed entirely in the next release.
+* Added Jasmine specs for CoffeeScript client.
+* Exceptions triggered in controller actions are now serialized and
+  passed to the failure callback on the client that triggered the
+  action.
+* Events triggered on the client before the connection is fully
+  established are now queued and sent in bulk once the connection is
+  ready.
+
 ## Version 0.1.5
 
 July 3 2012

data/Gemfile

@@ -3,6 +3,9 @@ source "http://rubygems.org"
 gemspec
 
 gem "rspec-rails"
+gem "jasmine"
+gem "headless"
+gem "coffee-script"
 gem "thin"
 gem "eventmachine", ">= 1.0.0.beta.3"
 gem "faye-websocket"
@@ -10,6 +13,7 @@ gem "simplecov"
 gem "ruby_gntp"
 gem "guard"
 gem "guard-rspec"
+gem "guard-coffeescript"
 
 platforms :jruby do
   gem 'activerecord-jdbcsqlite3-adapter', :require => 'jdbc-sqlite3', :require => 'arjdbc'

data/README.md

@@ -4,199 +4,106 @@
 
 If you haven't done so yet, check out the [Project Page](http://danknox.github.com/websocket-rails/) to get a feel for the project direction. Feedback is very much appreciated. Post an issue on the issue tracker or [shoot us an email](mailto://support@threedotloft.com) to give us your thoughts.
 
-## Overview
-
-Plug and play WebSocket support for ruby on rails with streaming HTTP fallback for improved cross browser compatibility. 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 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
-
-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/frames/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/frames/WebsocketRails/EventMap)
-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-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-rails'
-````
+## Update July 17 2012
 
-## Event Router
+We just released a new version containing significant new functionality. 
+We will be updating the documentation and wiki guides to cover it all over the next day
+or two but check out the
+[CHANGELOG](https://github.com/DanKnox/websocket-rails/blob/master/CHANGELOG.md) to get an early preview.
 
-Map WebSocket events to controller actions by creating an `events.rb` file in your app/config/initializers directory
+## Overview
 
-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.
+Start treating client side events as first class citizens inside your
+Rails application with a built in WebSocket server. Sure, WebSockets
+aren't quite universal yet. That's why we also support streaming HTTP.
+Oh, and if you don't mind running a separate process, you can support
+just about any browser with Flash sockets.
 
-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.
+## Respond Quicker with Socket Events
 
-The Event Map now supports namespacing events. Events triggered on the
-client as `namespace.event_name` will now be dispatched to 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.
+Map events to controller actions using an Event Router.
 
 ````ruby
-# app/config/initializers
-
 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
-	
-  # 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
-
-  namespace :product do
-    subscribe :new, to: ProductController, with_method: :new_product
+  namespace :tasks do
+    subscribe :create, :to => TaskController, :with_method => :create
   end
-
-  # 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.
-
-## WebSocketRails JavaScript Client
-
-There is an accompanying JavaScript client [located here](https://github.com/DanKnox/websocket-rails/tree/master/lib/assets/javascripts/websocket_rails). The client detects support for WebSockets in the browser and falls back to HTTP streaming if it is unavailable. The client currently works in every major browser except for internet explorer. If you are using the current master branch of this repository, you can require the client in your application.js manifest directly: `//= require websocket_rails/main`. The client will be released to rubygems soon. 
+Trigger events using our JavaScript client.
 
 ````javascript
-// Setting up the client and connecting to the server:
-// Do not pass the prefix of the URL, 'ws://' will be
-// added automatically when the client uses WebSockets
-var dispatcher = new WebSocketRails("localhost:port/websocket");
-
-dispatcher.on_open = function() {
-	// trigger a server event immediately after opening connection
-	dispatcher.trigger('new_user',{user_name: 'guest'});
+var task = {
+  name: 'Start taking advantage of WebSockets',
+  completed: false
 }
-
-//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) {
-	console.log(data.user_name);
-})
+dispatcher = new WebSocketRails('localhost:3000/websocket');
+dispatcher.trigger('tasks.create', task);
 ````
 
-Check out the [example application](https://github.com/DanKnox/websocket-rails-Example-Project) for a working implementation.  
-
-## Controllers
-
-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 WebsocketRails::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.
+Handle events in your controller.
 
 ````ruby
-new_message = {:message => 'this is a message'}
-broadcast_message :event_name, new_message
-send_message :event_name, new_message
-````
-
-Here is an example controller for handling the `:new_message` event for a basic chat application.
-
-````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  
+class TaskController < WebsocketRails::BaseController
+  def create
+    # The `message` method contains the data received
+    task = Task.new message
+    if task.save
+      send_message :create_success, task, :namespace => :tasks
+    else
+      send_message :create_fail, task, :namespace => :tasks
+    end
   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.
+Receive the response in the client.
 
-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
-
-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
+````javascript
+dispatcher.bind('tasks.create_successful', function(task) {
+  console.log('successfully created ' + task.name);
+});
 ````
 
-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:
-d
-````ruby
-data_store[:user] = 'User3'
-data_store.each_user
-=> ['User1','User2','User3']
-````
+## Channel Support
 
-A simple method for broadcasting the current user list to all clients would look like this:
+Keep your users up to date without waiting for them to refresh the page.
+Subscribe them to a channel and update it from wherever you please.
 
-````ruby
-def broadcast_user_list
-  users = data_store.each_user
-  broadcast_message :user_list, users
-end
-````
+Tune in on the client side.
 
-## 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. The example JavaScript dispatchers decode the JSON for you as well as provide a few conveniences for event subscribing and dispatching.
+````javascript
+channel = dispatcher.subscribe('posts');
+channel.bind('new', function(post) {
+  console.log('a new post about '+post.title+' arrived!');
+});
+````
 
-If you executed this code in your controller:
+Broadcast to the channel from anywhere inside your Rails application. An
+existing controller, a model, a background job, or a new WebsocketRails
+controller.
 
 ````ruby
-new_message = {:message => 'this is a message'}
-send_message :new_message, new_message
+latest_post = Post.latest
+WebsocketRails[:posts].trigger('new', latest_post)
 ````
 
-The message that arrives on the client would look like:
-
-````javascript
-['new_message',{message: 'this is a message'}]
-````
+## Installation and Usage Guides
+
+Check out the [Example Application](https://github.com/DanKnox/websocket-rails-Example-Project) for an example implementation.
+
+* [Installation
+  Guide](https://github.com/DanKnox/websocket-rails/wiki/Installation-and-Setup)
+* [Event
+  Router](https://github.com/DanKnox/websocket-rails/wiki/The-Event-Router)
+* [WebsocketRails Controllers](https://github.com/DanKnox/websocket-rails/wiki/WebsocketRails Controllers)
+* [Using the JavaScript
+  Client](https://github.com/DanKnox/websocket-rails/wiki/Using-the-JavaScript-Client)
+* [Using
+  Channels](https://github.com/DanKnox/websocket-rails/wiki/Working-with-Channels)
+* [The
+  DataStore](https://github.com/DanKnox/websocket-rails/wiki/Using-the-DataStore)
 
 ## Development
 

data/Rakefile

@@ -17,8 +17,6 @@ end
 
 Bundler::GemHelper.install_tasks
 
-task :default => :spec
-
 RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title    = 'websocket-rails'
@@ -29,17 +27,46 @@ end
 
 require 'rspec/core/rake_task'
 
-desc 'Default: run specs.'
-task :default => :spec
+desc 'Default: run RSpec and Jasmine specs.'
+task :default => :spec_and_jasmine
 
 desc "Run specs"
 RSpec::Core::RakeTask.new do |t|
   t.pattern = "./spec/**/*_spec.rb"
 end
 
+desc "Run rspec and jasmine:ci at the same time"
+task :spec_and_jasmine do
+  Rake::Task["spec"].execute
+  Rake::Task["jasmine:ci:headless"].execute
+end
+
 desc "Generate code coverage"
 task :coverage do
   ENV['COVERAGE'] = 'true'
   Rake::Task["spec"].execute
   `open coverage/index.html`
 end
+
+begin
+  require 'jasmine'
+  load 'jasmine/tasks/jasmine.rake'
+rescue LoadError
+  task :jasmine do
+    abort "Jasmine is not available. In order to run jasmine, you must: (sudo) gem install jasmine"
+  end
+end
+
+require 'headless'
+require 'selenium-webdriver'
+
+namespace :jasmine do
+  namespace :ci do
+    desc "Run Jasmine CI build headlessly"
+    task :headless do
+      ENV['DISPLAY'] = ':99.0'
+      puts "Running Jasmine Headlessly"
+      Rake::Task['jasmine:ci'].invoke
+    end
+  end
+end

data/bin/thin-socketrails

@@ -18,6 +18,21 @@
 require 'rubygems'
 require 'thin'
 
+puts <<END
+*** Deprecation Notice***
+
+The thin-socketrails executable is now deprecated and
+will be removed in the next release. 
+
+You may use the regular thin executable to launch the 
+server now. 
+
+Other EventMachine based web servers should now be
+supported but have not yet been tested.
+
+*************************
+END
+
 if EM::VERSION < "1.0.0"
   begin
     old_verbose, $VERBOSE = $VERBOSE, nil
@@ -27,4 +42,4 @@ if EM::VERSION < "1.0.0"
   end
 end
 
-Thin::Runner.new(ARGV).run!
+Thin::Runner.new(ARGV).run!

data/lib/assets/javascripts/websocket_rails/channel.js.coffee

@@ -9,18 +9,33 @@ For instance:
 ###
 class WebSocketRails.Channel
 
-  constructor: (@name,@dispatcher) ->
-    @dispatcher.trigger 'websocket_rails.subscribe', {channel: @name}
-    @callbacks = {}
+  constructor: (@name,@_dispatcher,@is_private) ->
+    if @is_private
+      event_name = 'websocket_rails.subscribe_private'
+    else
+      event_name = 'websocket_rails.subscribe'
+
+    event = new WebSocketRails.Event( [event_name, {data: {channel: @name}},@_dispatcher.connection_id], @_success_launcher, @_failure_launcher)
+    @_dispatcher.trigger_event event
+    @_callbacks = {}
 
   bind: (event_name, callback) =>
-    @callbacks[event_name] ?= []
-    @callbacks[event_name].push callback
+    @_callbacks[event_name] ?= []
+    @_callbacks[event_name].push callback
 
   trigger: (event_name, message) =>
-    @dispatcher.trigger_channel @name, event_name, message
+    event = new WebSocketRails.Event( [event_name, {channel: @name, data: message}, @_dispatcher.connection_id] )
+    @_dispatcher.trigger_event event
 
   dispatch: (event_name, message) =>
-    return unless @callbacks[event_name]?
-    for callback in @callbacks[event_name]
+    return unless @_callbacks[event_name]?
+    for callback in @_callbacks[event_name]
       callback message
+  
+  # using this method because @on_success will not be defined when the constructor is executed
+  _success_launcher: (data) =>
+    @on_success(data) if @on_success?
+    
+  # using this method because @on_failure will not be defined when the constructor is executed
+  _failure_launcher: (data) =>
+    @on_failure(data) if @on_failure?

data/lib/assets/javascripts/websocket_rails/event.js.coffee

@@ -0,0 +1,40 @@
+###
+The Event object stores all the relevant event information.
+###
+
+class WebSocketRails.Event
+
+  constructor: (data,@success_callback,@failure_callback) ->
+    @name    = data[0]
+    attr     = data[1]
+    if attr?
+      @id      = if attr['id']? then attr['id'] else (((1+Math.random())*0x10000)|0)
+      @channel = if attr.channel? then attr.channel
+      @data    = if attr.data? then attr.data else attr
+      @connection_id = data[2]
+      if attr.success?
+        @result  = true
+        @success = attr.success
+
+  is_channel: =>
+    @channel?
+
+  is_result: =>
+    @result == true
+
+  is_ping: =>
+    @name == 'websocket_rails.ping'
+
+  serialize: =>
+      JSON.stringify [@name, @attributes()]
+
+  attributes: =>
+    id: @id,
+    channel: @channel,
+    data: @data
+
+  run_callbacks: (success,data) =>
+    if success == true
+      @success_callback?(data)
+    else
+      @failure_callback?(data)

data/lib/assets/javascripts/websocket_rails/http_connection.js.coffee

@@ -21,8 +21,9 @@ class WebSocketRails.HttpConnection
     xmlhttp
 
   constructor: (@url, @dispatcher) ->
-    @_conn    = @createXMLHttpObject()
-    @last_pos = 0
+    @_conn         = @createXMLHttpObject()
+    @last_pos      = 0
+    @message_queue = []
     @_conn.onreadystatechange = @parse_stream
     @_conn.open "GET", "/websocket", true
     @_conn.send()
@@ -31,16 +32,15 @@ class WebSocketRails.HttpConnection
     if @_conn.readyState == 3
       data         = @_conn.responseText.substring @last_pos
       @last_pos    = @_conn.responseText.length
+      data = data.replace "]][[", "],["
       decoded_data = JSON.parse data
       @dispatcher.new_message decoded_data
 
-  trigger: (event_name, data, connection_id) =>
-    payload = JSON.stringify [event_name, data]
-    @post_data connection_id, payload
-
-  trigger_channel: (channel_name, event_name, data, connection_id) =>
-    payload = JSON.stringify [channel_name, event_name, data]
-    @post_data connection_id, payload
+  trigger: (event) =>
+    if @dispatcher.state != 'connected'
+      @message_queue.push event
+    else
+      @post_data @dispatcher.connection_id, event.serialize()
 
   post_data: (connection_id, payload) ->
     $.ajax "/websocket",
@@ -49,4 +49,12 @@ class WebSocketRails.HttpConnection
         client_id: connection_id
         data: payload
       success: ->
-        console.log "success"
+
+  flush_queue: (connection_id) =>
+    for event in @message_queue
+      # Events queued before connecting do not have the correct
+      # connection_id set yet. We need to update it before dispatching.
+      if connection_id?
+        event.connection_id = @dispatcher.connection_id
+      @trigger event
+    @message_queue = []

data/lib/assets/javascripts/websocket_rails/main.js

@@ -1,4 +1,5 @@
 //= require ./websocket_rails
+//= require ./event
 //= require ./http_connection
 //= require ./websocket_connection
 //= require ./channel

data/lib/assets/javascripts/websocket_rails/websocket_connection.js.coffee

@@ -4,22 +4,27 @@ WebSocket Interface for the WebSocketRails client.
 class WebSocketRails.WebSocketConnection
 
   constructor: (@url,@dispatcher) ->
-    @_conn           = new WebSocket("ws://#{@url}")
+    @url             = "ws://#{@url}" unless @url.match(/^wss?:\/\//)
+    @message_queue   = []
+    @_conn           = new WebSocket(@url)
     @_conn.onmessage = @on_message
     @_conn.onclose   = @on_close
 
-  trigger: (event_name, data, connection_id) =>
-    payload = JSON.stringify [event_name, data]
-    @_conn.send payload
-
-  trigger_channel: (channel_name, event_name, data, connection_id) =>
-    payload = JSON.stringify [channel_name, event_name, data]
-    @_conn.send payload
+  trigger: (event) =>
+    if @dispatcher.state != 'connected'
+      @message_queue.push event
+    else
+      @_conn.send event.serialize()
 
   on_message: (event) =>
     data = JSON.parse event.data
-    console.log data
     @dispatcher.new_message data
 
   on_close: (event) =>
-    @dispatcher.dispatch 'connection_close', {}
+    close_event = new WebSocketRails.Event(['connection_closed',{}])
+    @dispatcher.dispatch close_event
+
+  flush_queue: =>
+    for event in @message_queue
+      @_conn.send event.serialize()
+    @message_queue = []