private_pub 0.0.0 → 0.1.0

data/CHANGELOG.rdoc

@@ -0,0 +1,3 @@
+0.1.0 (April 4, 2011)
+
+* initial release

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/README.rdoc

@@ -1,71 +1,55 @@
 = Private Pub
 
-THIS PROJECT IS CURRENTLY VAPORWARE. I am writing the {readme first}[http://tom.preston-werner.com/2010/08/23/readme-driven-development.html].
-
-This is a Ruby gem for use in a Rails application to publish and subscribe to messages through a separate server such as {Faye}[http://faye.jcoglan.com/].
+This is a Ruby gem for use with Rails to publish and subscribe to messages through a separate server such as {Faye}[http://faye.jcoglan.com/]. All channels are automatically made private.
 
 
 == Setup
 
-Add the gem to your Gemfile.
+Add the gem to your Gemfile and run +bundle+.
 
   gem "private_pub"
 
-Run the generator to create the JavaScript file and initializer.
+Run the generator to create the initial files.
 
   rails g private_pub:install
 
-Add the JavaScript file to your layout file.
+Add the generated JavaScript to your layout file. Currently this uses jQuery, so you will need to customize it if you aren't using jQuery.
 
   <%= javascript_include_tag "private_pub" %>
 
-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.
-
-  PrivatePub.server = "http://localhost:9292/faye"
+Next, install and start up Faye using the rackup file that was generated.
 
-Finally add the PrivatePub 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).
+  gem install faye
+  rackup faye.ru -s thin -E production
 
-  require "private_pub"
-  require File.expand_path("../config/initializers/private_pub.rb", __FILE__)
-  faye_server.add_extension(PrivatePub.faye_extension)
+It's not necessary to add the faye.js since that will be handled automatically.
 
 
 == Usage
 
-This adds two helper methods to Rails: +subscribe_to+ and +publish_to+. Let's say you're building a chat application. On the page displaying a chat you can subscribe to anything incoming on the "/messages/new" channel.
+Use the +subscribe_to+ helper method on any page to subscribe to a channel.
 
   <%= subscribe_to "/messages/new" %>
 
-And then publish to that channel when a new message is added in the Rails app.
+Use the +publish_to+ helper method to publish messages to that channel. If a block of JavaScript is passed it will be evaluated automatically. This is usually done through a JavaScript AJAX response.
 
   <% publish_to "/messages/new" do %>
     $("#chat").append("<%= escape_javascript render(@messages) %>");
   <% end %>
 
-That bit of JavaScript will be published and executed to all subscribing clients.
-
-Alternatively you can pass anything you want to the +publish_to+ method (+to_json+ will be called on it).
-
-  publish_to "/messages/new", @message
-
-And then handle that in a callback in JavaScript.
-
-  var private_pub = new PrivatePub;
-  private_pub.subscribe("/messages/new", function(data) {
-    // data contains whatever json was passed in
-  });
+There will be alternative ways to publish/subscribe to messages in the future.
 
 
 == Security
 
-Security is handled automatically for you. Only the Rails app is able to publish. Users are only able to subscribe to messages on the channels they subscribe to. This means every channel is private.
+Security is handled automatically for you. Only the Rails app is able to publish. Users are only able to receive messages on the channels you subscribe them to. This means every channel is private.
 
-Here's how it works. The +subscribe+ helper will output an element containing data information about the channel.
+Here's how it works. The +subscribe_to+ helper will output an element containing data information about the channel.
 
-  <span class="private_pub_subscription" data-channel="/messages/new" data-key="2aae6c35c94fcfb415dbe95f408b9ce91ee846ed" timestamp="13019431281234"></span>
+  <span class="private_pub_subscription" data-channel="/messages/new" data-signature="2aae6c35c94fcfb415dbe95f408b9ce91ee846ed" data-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.
+The data-signature is a combination of the channel, timestamp, and secret token set in the Rails app. This is checked by the Faye extension when subscribing to a channel to ensure the signature is correct. The signature is automatically expired after 1 hour but this can be configured.
 
-  PrivatePub.key_expiration = 10.minutes
+  PrivatePub.signature_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.

data/Rakefile

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'rake'
+require 'rspec/core/rake_task'
+
+desc "Run RSpec"
+RSpec::Core::RakeTask.new do |t|
+  t.verbose = false
+end
+
+task :default => :spec

data/lib/generators/private_pub/install_generator.rb

@@ -0,0 +1,16 @@
+class PrivatePub
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      def self.source_root
+        File.dirname(__FILE__) + "/templates"
+      end
+
+      def copy_files
+        template "private_pub_initializer.rb", "config/initializers/private_pub.rb"
+        copy_file "private_pub_helper.rb", "app/helpers/private_pub_helper.rb"
+        copy_file "private_pub.js", "public/javascripts/private_pub.js"
+        copy_file "faye.ru", "faye.ru"
+      end
+    end
+  end
+end

data/lib/generators/private_pub/templates/faye.ru

@@ -0,0 +1,7 @@
+require "faye"
+require "private_pub"
+require File.expand_path("../config/initializers/private_pub.rb", __FILE__)
+
+faye_server = Faye::RackAdapter.new(:mount => '/faye', :timeout => 45)
+faye_server.add_extension(PrivatePub.faye_extension)
+run faye_server

data/lib/generators/private_pub/templates/private_pub.js

@@ -0,0 +1,27 @@
+PrivatePubExtension = {
+  outgoing: function(message, callback) {
+    if (message.channel == "/meta/subscribe") {
+      // Attach the signature and timestamp to subscription messages
+      var subscription = $(".private_pub_subscription[data-channel='" + message.subscription + "']");
+      if (!message.ext) message.ext = {};
+      message.ext.private_pub_signature = subscription.data("signature");
+      message.ext.private_pub_timestamp = subscription.data("timestamp");
+    }
+    callback(message);
+  }
+};
+
+jQuery(function() {
+  var faye;
+  if ($(".private_pub_subscription").length > 0) {
+    jQuery.getScript($(".private_pub_subscription").data("server") + ".js", function() {
+      faye = new Faye.Client($(".private_pub_subscription").data("server"));
+      faye.addExtension(PrivatePubExtension);
+      $(".private_pub_subscription").each(function(index) {
+        faye.subscribe($(this).data("channel"), function(data) {
+          if (data._eval) eval(data._eval);
+        });
+      });
+    });
+  }
+});

data/lib/generators/private_pub/templates/private_pub_helper.rb

@@ -0,0 +1,15 @@
+module PrivatePubHelper
+  def publish_to(channel, &block)
+    message = {:channel => channel, :data => {:_eval => capture(&block)}, :ext => {:private_pub_token => PrivatePub.secret_token}}
+    PrivatePub.publish(:message => message.to_json)
+  end
+
+  def subscribe_to(channel)
+    subscription = PrivatePub.subscription(:channel => channel)
+    content_tag :span, "", :class => "private_pub_subscription",
+      "data-server" => PrivatePub.server,
+      "data-channel" => subscription[:channel],
+      "data-signature" => subscription[:signature],
+      "data-timestamp" => subscription[:timestamp]
+  end
+end

data/lib/generators/private_pub/templates/private_pub_initializer.rb

@@ -0,0 +1,2 @@
+PrivatePub.server = "http://localhost:9292/faye"
+PrivatePub.secret_token = "<%= ActiveSupport::SecureRandom.hex(32) %>"

data/lib/private_pub/faye_extension.rb

@@ -0,0 +1,29 @@
+class PrivatePub
+  class FayeExtension
+    def incoming(message, callback)
+      if message["channel"] == "/meta/subscribe"
+        authenticate_subscribe(message)
+      elsif message["channel"] !~ %r{^/meta/}
+        authenticate_publish(message)
+      end
+      callback.call(message)
+    end
+
+    private
+
+    def authenticate_subscribe(message)
+      subscription = PrivatePub.subscription(:channel => message["subscription"], :timestamp => message["ext"]["private_pub_timestamp"])
+      if message["ext"]["private_pub_signature"] != subscription[:signature]
+        message["error"] = "Incorrect signature."
+      end
+    end
+
+    def authenticate_publish(message)
+      if PrivatePub.secret_token.nil?
+        raise Error, "No token set in PrivatePub.secret_token, set this to match the token used in the web app."
+      elsif message["ext"]["private_pub_token"] != PrivatePub.secret_token
+        message["error"] = "Incorrect token."
+      end
+    end
+  end
+end

data/lib/private_pub.rb

@@ -1 +1,57 @@
-# TODO
+require "digest/sha1"
+require "net/http"
+
+require "private_pub/faye_extension"
+
+class PrivatePub
+  class Error < StandardError; end
+
+  class << self
+    def server=(server)
+      @config[:server] = server
+    end
+
+    def server
+      @config[:server]
+    end
+
+    def signature_expiration=(signature_expiration)
+      @config[:signature_expiration] = signature_expiration
+    end
+
+    def signature_expiration
+      @config[:signature_expiration]
+    end
+
+    def secret_token=(secret_token)
+      @config[:secret_token] = secret_token
+    end
+
+    def secret_token
+      @config[:secret_token]
+    end
+
+    def reset_config
+      @config = {
+        :server => "http://localhost:9292/faye",
+        :signature_expiration => 60 * 60, # one hour
+      }
+    end
+
+    def subscription(options = {})
+      sub = {:timestamp => (Time.now.to_f * 1000).round}.merge(options)
+      sub[:signature] = Digest::SHA1.hexdigest([secret_token, sub[:channel], sub[:timestamp]].join)
+      sub
+    end
+
+    def publish(data)
+      Net::HTTP.post_form(URI.parse(PrivatePub.server), data)
+    end
+
+    def faye_extension
+      FayeExtension.new
+    end
+  end
+
+  reset_config
+end

data/spec/private_pub/faye_extension_spec.rb

@@ -0,0 +1,48 @@
+require "spec_helper"
+
+describe PrivatePub::FayeExtension do
+  before(:each) do
+    PrivatePub.reset_config
+    @faye = PrivatePub::FayeExtension.new
+    @message = {"channel" => "/meta/subscribe", "ext" => {}}
+  end
+
+  it "adds an error on an incoming subscription with a bad signature" do
+    @message["subscription"] = "hello"
+    @message["ext"]["private_pub_signature"] = "bad"
+    @message["ext"]["private_pub_timestamp"] = "123"
+    message = @faye.incoming(@message, lambda { |m| m })
+    message["error"].should == "Incorrect signature."
+  end
+
+  it "has no error when the signature matches the subscription" do
+    sub = PrivatePub.subscription(:timestamp => 123, :channel => "hello")
+    @message["subscription"] = sub[:channel]
+    @message["ext"]["private_pub_signature"] = sub[:signature]
+    @message["ext"]["private_pub_timestamp"] = sub[:timestamp]
+    message = @faye.incoming(@message, lambda { |m| m })
+    message["error"].should be_nil
+  end
+
+  it "has an error when trying to publish to a custom channel with a bad token" do
+    PrivatePub.secret_token = "good"
+    @message["channel"] = "/custom/channel"
+    @message["ext"]["private_pub_token"] = "bad"
+    message = @faye.incoming(@message, lambda { |m| m })
+    message["error"].should == "Incorrect token."
+  end
+
+  it "raises an exception when attempting to call a custom channel without a secret_token set" do
+    @message["channel"] = "/custom/channel"
+    @message["ext"]["private_pub_token"] = "bad"
+    lambda {
+      message = @faye.incoming(@message, lambda { |m| m })
+    }.should raise_error("No token set in PrivatePub.secret_token, set this to match the token used in the web app.")
+  end
+
+  it "has no error on other meta calls" do
+    @message["channel"] = "/meta/connect"
+    message = @faye.incoming(@message, lambda { |m| m })
+    message["error"].should be_nil
+  end
+end

data/spec/private_pub_spec.rb

@@ -0,0 +1,51 @@
+require "spec_helper"
+
+describe PrivatePub do
+  before(:each) do
+    PrivatePub.reset_config
+  end
+
+  it "has secret token, server, and signature expiration settings" do
+    PrivatePub.secret_token = "secret token"
+    PrivatePub.secret_token.should == "secret token"
+    PrivatePub.server = "http://localhost/"
+    PrivatePub.server.should == "http://localhost/"
+    PrivatePub.signature_expiration = 1000
+    PrivatePub.signature_expiration.should == 1000
+  end
+
+  it "defaults server to localhost:9292/faye" do
+    PrivatePub.server.should == "http://localhost:9292/faye"
+  end
+
+  it "defaults signature_expiration to 1 hour" do
+    PrivatePub.signature_expiration.should == 60 * 60
+  end
+
+  it "defaults subscription timestamp to current time in milliseconds" do
+    time = Time.now
+    Time.stub!(:now).and_return(time)
+    PrivatePub.subscription[:timestamp].should == (time.to_f * 1000).round
+  end
+
+  it "includes channel and custom time in subscription" do
+    subscription = PrivatePub.subscription(:timestamp => 123, :channel => "hello")
+    subscription[:timestamp].should == 123
+    subscription[:channel].should == "hello"
+  end
+
+  it "does a sha1 digest of channel, timestamp, and secret token" do
+    PrivatePub.secret_token = "token"
+    subscription = PrivatePub.subscription(:timestamp => 123, :channel => "channel")
+    subscription[:signature].should == Digest::SHA1.hexdigest("tokenchannel123")
+  end
+
+  it "publishes to server using Net::HTTP" do
+    Net::HTTP.should_receive(:post_form).with(URI.parse(PrivatePub.server), "hello world").and_return(:result)
+    PrivatePub.publish("hello world").should == :result
+  end
+
+  it "has a FayeExtension instance" do
+    PrivatePub.faye_extension.should be_kind_of(PrivatePub::FayeExtension)
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,6 @@
+require 'rubygems'
+require 'bundler/setup'
+Bundler.require(:default)
+
+RSpec.configure do |config|
+end

metadata

@@ -2,7 +2,7 @@
 name: private_pub
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors: 
 - Ryan Bates
@@ -12,8 +12,18 @@ cert_chain: []
 
 date: 2011-04-04 00:00:00 -07:00
 default_executable: 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 2.1.0
+  type: :development
+  version_requirements: *id001
 description: Private pub/sub messaging in Rails through Faye.
 email: ryan@railscasts.com
 executables: []
@@ -23,7 +33,19 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- lib/generators/private_pub/install_generator.rb
+- lib/generators/private_pub/templates/faye.ru
+- lib/generators/private_pub/templates/private_pub.js
+- lib/generators/private_pub/templates/private_pub_helper.rb
+- lib/generators/private_pub/templates/private_pub_initializer.rb
+- lib/private_pub/faye_extension.rb
 - lib/private_pub.rb
+- spec/private_pub/faye_extension_spec.rb
+- spec/private_pub_spec.rb
+- spec/spec_helper.rb
+- CHANGELOG.rdoc
+- Gemfile
+- Rakefile
 - README.rdoc
 has_rdoc: true
 homepage: http://github.com/ryanb/private_pub