If you haven't done so yet, check out the Project Page 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 to give us your thoughts.
Find us on IRC #websocket-rails
Stop by #websocket-rails on freenode if you would like to chat or have any questions.
Check out the CHANGELOG to find out what's new.
As of version 0.2.0, non event machine based web servers such as Phusion Passenger are supported through the use of the Standalone Server Mode.
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.
- Installation Guide
- Event Router
- [WebsocketRails Controllers](https://github.com/websocket-rails/websocket-rails/wiki/WebsocketRails Controllers)
- Using the JavaScript Client
- Using Channels
- Using Private Channels
- The DataStore
- Reloading Controllers In Development
- Multiple Servers and Background Jobs
- Standalone Server Mode
Map events to controller actions using an Event Router.
WebsocketRails::EventMap.describe do
namespace :tasks do
# using a Hash to specify the target
subscribe :create, :to => TaskController, :with_method => :create
# using the same syntax as routes.rb
subscribe :update, 'task#update'
# if your controller is not a top-level object
subscribe :create_admin, :to => Admin::TaskController, :with_method => :create
subscribe :update_admin, 'admin/task#update'
end
endTrigger events using our JavaScript client.
var task = {
name: 'Start taking advantage of WebSockets',
completed: false
}
var dispatcher = new WebSocketRails('localhost:3000/websocket');
dispatcher.trigger('tasks.create', task);Handle events in your controller.
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
endReceive the response in the client.
dispatcher.bind('tasks.create_success', function(task) {
console.log('successfully created ' + task.name);
});Or just attach success and failure callbacks to your client events.
var success = function(task) { console.log("Created: " + task.name); }
var failure = function(task) {
console.log("Failed to create Product: " + product.name)
}
dispatcher.trigger('products.create', task, success, failure);Then trigger them in your controller:
def create
task = Task.create message
if task.save
trigger_success task
else
trigger_failure task
end
endIf you're feeling truly lazy, just trigger the failure callback with an exception.
def create
task = Task.create! message
trigger_success task # trigger success if the save went alright
endThat controller is starting to look pretty clean.
Now in the failure callback on the client we have access to the record and the errors.
var failureCallback = function(task) {
console.log( task.name );
console.log( task.errors );
console.log( "You have " + task.errors.length + " errors." );
}You can stop listening to an event now by using the unbind function.
dispatcher.unbind('tasks.create_success');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.
Tune in on the client side.
channel = dispatcher.subscribe('posts');
channel.bind('new', function(post) {
console.log('a new post about '+post.title+' arrived!');
});Broadcast to the channel from anywhere inside your Rails application. An existing controller, a model, a background job, or a new WebsocketRails controller.
latest_post = Post.latest
WebsocketRails[:posts].trigger 'new', latest_postNeed to restrict access to a particular channel? No problem. We've got that.
Private channels give you the ability to authorize a user's subscription using the authorization mechanism of your choice.
Just tell WebsocketRails which channels you would like to make private by using the private_channel method in the Event Router.
Then handle the channel authorization by subscribing to the websocket_rails.subscribe_private event.
WebsocketRails::EventMap.describe do
private_channel :secret_posts
namespace :websocket_rails
subscribe :subscribe_private, :to => AuthorizationController, :with_method => :authorize_channels
endOr you can always mark any channel as private later on.
WebsocketRails[:secret_posts].make_privateOn the client side, you can use the dispatcher.subscribe_private()
method to subscribe to a private channel.
Read the Private Channel Wiki for more information on subscribing to private channels from the JavaScript client and handling the authorization in your controller.
Big thanks to our contributors who have helped keep this project moving.
Special thanks to @nessche who provided the improved routing DSL and RSpec matcher suite.
The websocket-rails organization logo was kindly provided by Uken Games.
Please check out the Development Guide if you are interested in contributing. It should cover everything you need to get up and running.
The current websocket-rails core team consists of the following individuals:
New contributors and pull requests are always welcome.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent