Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Handle pub/sub messaging through private channels in Rails using Faye.
Ruby CoffeeScript
tree: 2b89484ddf

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
README.rdoc

README.rdoc

Broadcast Center

This is a Ruby gem for use in a Rails application to broadcast and receive messages through a separate messaging server such as Faye.

This project is still in very early development so what is described here does not yet work. I am writing the readme first.

Setup

Add the gem to your Gemfile.

gem "broadcast_center"

Run the generator to create the JavaScript file and initializer.

rails g broadcast_center:install

Add the JavaScript file to your layout file.

<%= javascript_include_tag "broadcast_center" %>

Next setup Faye and configure the generated initializer file to point to the faye server if it's not already. DON'T add the faye.js file to your layout because this will be done automatically.

BroadcastCenter.server = "http://localhost:9292/faye"

Finally add the BroadcastCenter extension to Faye through the rackup file. You'll need to load the initializer file there too so it sets the secret token (or set it some other way).

require "broadcast_center"
require File.expand_path("../config/initializers/broadcast_center.rb", __FILE__)
faye_server.add_extension(BroadcastCenter.faye_extension)

Usage

This adds two helper methods to Rails: listen and broadcast. Let's say you're building a chat application. On the page displaying a chat you can listen to anything incoming on the “/messages/new” channel.

<%= listen "/messages/new" %>

And then broadcast to that channel when a new message is added in the Rails app.

<% broadcast "/messages/new" do %>
  $("#chat").append("<%= escape_javascript render(@messages) %>");
<% end %>

That bit of JavaScript will be broadcast and executed to all listening clients.

Alternatively you can pass anything you want to the broadcast method (to_json will be called on it).

broadcast "/messages/new", @message

And then handle that in a callback in JavaScript.

var broadcast_center = new BroadcastCenter;
broadcast_center.listen("/messages/new", function(data) {
  // data contains whatever json was passed in
});

Security

Security is handled automatically for you. Only the Rails app is able to broadcast messages. Users are only able to listen to messages on the channels they subscribe to. This means every channel is private.

Here's how it works. The listen helper will output an element containing data information about the channel.

<span class="broadcast_center_listen" data-channel="/messages/new" data-key="2aae6c35c94fcfb415dbe95f408b9ce91ee846ed" timestamp="13019431281234"></span>

The key is a combination of the message name, timestamp, and secret token set in the Rails app. This is checked by the Faye extension when subscribing to a channel to ensure the key is correct. The key is automatically expired after 1 hour but this can be configured.

BroadcastCenter.key_expiration = 10.minutes

Or nil for no expiration. Note: if Faye is on a separate server from the Rails app it's important that the time is in sync.

Something went wrong with that request. Please try again.