private_pub 0.3.0 → 1.0.0

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 1.0.0 (January 15, 2012)
+
+* setting config defaults to nil so everything must be set in `private_pub.yml`
+
+* Documentation improvements
+
+
 ## 0.3.0 (January 14, 2012)
 
 * adding `PrivatePub.publish_to` method for publishing from anywhere - issue #15

data/LICENSE

@@ -1,5 +1,5 @@
 Copyright (c) 2012 Ryan Bates
- 
+
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
 "Software"), to deal in the Software without restriction, including
@@ -7,10 +7,10 @@ without limitation the rights to use, copy, modify, merge, publish,
 distribute, sublicense, and/or sell copies of the Software, and to
 permit persons to whom the Software is furnished to do so, subject to
 the following conditions:
- 
+
 The above copyright notice and this permission notice shall be
 included in all copies or substantial portions of the Software.
- 
+
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND

data/README.md

@@ -61,7 +61,7 @@ This JavaScript will be immediately evaluated on all clients who have subscribed
 
 ## Alternative Usage
 
-If you prefer to work through JSON instead of JavaScript templates to handle AJAX responses, you can pass an argument to `publish_to` instead of a block and it will be converted `to_json` behind the scenes. This can also be done anywhere (such as the controller).
+If you prefer to work through JSON instead of `.js.erb` templates, you can pass a hash to `publish_to` instead of a block and it will be converted `to_json` behind the scenes. This can be done anywhere (such as the controller).
 
 ```ruby
 PrivatePub.publish_to "/messages/new", :chat_message => "Hello, world!"
@@ -75,14 +75,21 @@ PrivatePub.subscribe("/messages/new", function(data, channel) {
 });
 ```
 
-The Ruby `subscribe_to` call is still necessary with this approach to grant the user access to the channel. The JavaScript is just a callback for any custom behavior.
+The Ruby `subscribe_to` helper call is still necessary with this approach to grant the user access to the channel. The JavaScript is just a callback for any custom behavior.
 
 
-## Security
+## Configuration
 
-Security is handled automatically for you. Only the Rails app is able to publish messages. Users are only able to receive messages on the channels you subscribe them to so every channel is private.
+The configuration is set separately for each environment in the generated `config/private_pub.yml` file. Here are the options.
 
-Here's how it works. The `subscribe_to` helper will output a script element containing data information about the channel.
+* `server`: The URL to use for the Faye server such as `http://localhost:9292/faye`.
+* `secret_token`: A secret hash to secure the server. Can be any string.
+* `signature_expiration`: The length of time in seconds before a subscription signature expires. If this is not set there is no expiration. Note: if Faye is on a separate server from the Rails app, the system clocks must be in sync for the expiration to work properly.
+
+
+## How It Works
+
+The `subscribe_to` helper will output the following script which subscribes the user to a specific channel and server.
 
 ```html
 <script type="text/javascript">
@@ -95,21 +102,11 @@ Here's how it works. The `subscribe_to` helper will output a script element cont
 </script>
 ```
 
-The 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 automatically expires after 1 hour but this can be configured in the generated YAML config file.
-
-```yaml
-signature_expiration: 600 # 10 minutes, expressed in seconds
-```
-
-Or use a blank value for no expiration.
-
-```yaml
-signature_expiration:
-```
+The signature and timestamp checked on the Faye server to ensure users are only able to access channels you subscribe them to. The signature will automatically expire after the time specified in the configuration.
 
-Note: if Faye is on a separate server from the Rails app it's important that the system clocks be in sync so the expiration works properly.
+The `publish_to` method will send a post request to the Faye server (using `Net::HTTP`) instructing it to send the given data back to the browser.
 
 
 ## Development & Feedback
 
-Questions or comments? Please use the [issue tracker](https://github.com/ryanb/private_pub/issues). If you would like to contribue to this project, clone this repository and run `bundle` and `rake` to run the tests.
+Questions or comments? Please use the [issue tracker](https://github.com/ryanb/private_pub/issues). Tests can be run with `bundle` and `rake` commands.

data/lib/generators/private_pub/templates/private_pub.yml

@@ -7,3 +7,4 @@ test:
 production:
   server: "http://example.com/faye"
   secret_token: "<%= ActiveSupport::SecureRandom.hex(32) %>"
+  signature_expiration: 3600 # one hour

data/lib/private_pub.rb

@@ -10,29 +10,31 @@ module PrivatePub
   class << self
     attr_reader :config
 
+    # Resets the configuration to the default (empty hash)
     def reset_config
-      @config = {
-        :server => "http://localhost:9292/faye",
-        :signature_expiration => 60 * 60, # one hour
-      }
+      @config = {}
     end
 
+    # Loads the  configuration from a given YAML file and environment (such as production)
     def load_config(filename, environment)
       yaml = YAML.load_file(filename)[environment.to_s]
       raise ArgumentError, "The #{environment} environment does not exist in #{filename}" if yaml.nil?
       yaml.each { |k, v| config[k.to_sym] = v }
     end
 
-    def subscription(options = {})
-      sub = {:timestamp => (Time.now.to_f * 1000).round}.merge(options)
-      sub[:signature] = Digest::SHA1.hexdigest([config[:secret_token], sub[:channel], sub[:timestamp]].join)
-      sub
-    end
-
+    # Publish the given data to a specific channel. This ends up sending
+    # a Net::HTTP POST request to the Faye server.
     def publish_to(channel, data)
       publish_message(message(channel, data))
     end
 
+    # Sends the given message hash to the Faye server using Net::HTTP.
+    def publish_message(message)
+      raise Error, "No server specified, ensure private_pub.yml was loaded properly." unless config[:server]
+      Net::HTTP.post_form(URI.parse(config[:server]), :message => message.to_json)
+    end
+
+    # Returns a message hash for sending to Faye
     def message(channel, data)
       message = {:channel => channel, :data => {:channel => channel}, :ext => {:private_pub_token => config[:secret_token]}}
       if data.kind_of? String
@@ -43,14 +45,21 @@ module PrivatePub
       message
     end
 
-    def publish_message(message)
-      Net::HTTP.post_form(URI.parse(config[:server]), :message => message.to_json)
+    # Returns a subscription hash to pass to the PrivatePub.sign call in JavaScript.
+    # Any options passed are merged to the hash.
+    def subscription(options = {})
+      sub = {:server => config[:server], :timestamp => (Time.now.to_f * 1000).round}.merge(options)
+      sub[:signature] = Digest::SHA1.hexdigest([config[:secret_token], sub[:channel], sub[:timestamp]].join)
+      sub
     end
 
+    # Determine if the signature has expired given a timestamp.
     def signature_expired?(timestamp)
       timestamp < ((Time.now.to_f - config[:signature_expiration])*1000).round if config[:signature_expiration]
     end
 
+    # Returns the Faye Rack application.
+    # Any options given are passed to the Faye::RackAdapter.
     def faye_app(options = {})
       options = {:mount => "/faye", :timeout => 45, :extensions => [FayeExtension.new]}.merge(options)
       Faye::RackAdapter.new(options)

data/lib/private_pub/engine.rb

@@ -2,11 +2,13 @@ require "private_pub/view_helpers"
 
 module PrivatePub
   class Engine < Rails::Engine
+    # Loads the private_pub.yml file if it exists.
     initializer "private_pub.config" do
       path = Rails.root.join("config/private_pub.yml")
       PrivatePub.load_config(path, Rails.env) if path.exist?
     end
 
+    # Adds the ViewHelpers into ActionView::Base
     initializer "private_pub.view_helpers" do
       ActionView::Base.send :include, ViewHelpers
     end

data/lib/private_pub/faye_extension.rb

@@ -1,5 +1,9 @@
 module PrivatePub
+  # This class is an extension for the Faye::RackAdapter.
+  # It is used inside of PrivatePub.faye_app.
   class FayeExtension
+    # Callback to handle incoming Faye messages. This authenticates both
+    # subscribe and publish calls.
     def incoming(message, callback)
       if message["channel"] == "/meta/subscribe"
         authenticate_subscribe(message)
@@ -11,6 +15,7 @@ module PrivatePub
 
   private
 
+    # Ensure the subscription signature is correct and that it has not expired.
     def authenticate_subscribe(message)
       subscription = PrivatePub.subscription(:channel => message["subscription"], :timestamp => message["ext"]["private_pub_timestamp"])
       if message["ext"]["private_pub_signature"] != subscription[:signature]
@@ -20,6 +25,7 @@ module PrivatePub
       end
     end
 
+    # Ensures the secret token is correct before publishing.
     def authenticate_publish(message)
       if PrivatePub.config[:secret_token].nil?
         raise Error, "No secret_token config set, ensure private_pub.yml is loaded properly."

data/lib/private_pub/view_helpers.rb

@@ -1,12 +1,19 @@
 module PrivatePub
   module ViewHelpers
+    # Publish the given data or block to the client by sending
+    # a Net::HTTP POST request to the Faye server. If a block
+    # or string is passed in, it is evaluated as JavaScript
+    # on the client. Otherwise it will be converted to JSON
+    # for use in a JavaScript callback.
     def publish_to(channel, data = nil, &block)
       PrivatePub.publish_to(channel, data || capture(&block))
     end
 
+    # Subscribe the client to the given channel. This generates
+    # some JavaScript calling PrivatePub.sign with the subscription
+    # options.
     def subscribe_to(channel)
       subscription = PrivatePub.subscription(:channel => channel)
-      subscription[:server] = PrivatePub.config[:server]
       content_tag "script", :type => "text/javascript" do
         raw("PrivatePub.sign(#{subscription.to_json});")
       end

data/spec/fixtures/private_pub.yml

@@ -6,5 +6,3 @@ production:
   server: http://example.com/faye
   secret_token: PRODUCTION_SECRET_TOKEN
   signature_expiration: 600
-no_signature_expiration:
-  signature_expiration:

data/spec/private_pub/faye_extension_spec.rb

@@ -12,7 +12,7 @@ describe PrivatePub::FayeExtension do
     @message["ext"]["private_pub_signature"] = "bad"
     @message["ext"]["private_pub_timestamp"] = "123"
     message = @faye.incoming(@message, lambda { |m| m })
-    message["error"].should == "Incorrect signature."
+    message["error"].should eq("Incorrect signature.")
   end
 
   it "has no error when the signature matches the subscription" do
@@ -24,13 +24,14 @@ describe PrivatePub::FayeExtension do
     message["error"].should be_nil
   end
 
-  it "has an error when signature is just expired" do
+  it "has an error when signature just expired" do
+    PrivatePub.config[:signature_expiration] = 1
     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 == "Signature has expired."
+    message["error"].should eq("Signature has expired.")
   end
 
   it "has an error when trying to publish to a custom channel with a bad token" do
@@ -38,7 +39,7 @@ describe PrivatePub::FayeExtension do
     @message["channel"] = "/custom/channel"
     @message["ext"]["private_pub_token"] = "bad"
     message = @faye.incoming(@message, lambda { |m| m })
-    message["error"].should == "Incorrect token."
+    message["error"].should eq("Incorrect token.")
   end
 
   it "raises an exception when attempting to call a custom channel without a secret_token set" do
@@ -54,13 +55,13 @@ describe PrivatePub::FayeExtension do
     message = @faye.incoming(@message, lambda { |m| m })
     message["error"].should be_nil
   end
-  
+
   it "should not let message carry the private pub token after server's validation" do
     PrivatePub.config[:secret_token] = "good"
     @message["channel"] = "/custom/channel"
     @message["ext"]["private_pub_token"] = PrivatePub.config[:secret_token]
     message = @faye.incoming(@message, lambda { |m| m })
-    message['ext']["private_pub_token"].should be_nil    
+    message['ext']["private_pub_token"].should be_nil
   end
-    
+
 end

data/spec/private_pub_spec.rb

@@ -5,30 +5,25 @@ describe PrivatePub do
     PrivatePub.reset_config
   end
 
-  it "defaults server to localhost:9292/faye" do
-    PrivatePub.config[:server].should == "http://localhost:9292/faye"
+  it "defaults server to nil" do
+    PrivatePub.config[:server].should be_nil
   end
 
-  it "defaults signature_expiration to 1 hour" do
-    PrivatePub.config[:signature_expiration].should == 60 * 60
+  it "defaults signature_expiration to nil" do
+    PrivatePub.config[:signature_expiration].should be_nil
   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
+    PrivatePub.subscription[:timestamp].should eq((time.to_f * 1000).round)
   end
 
   it "loads a simple configuration file via load_config" do
     PrivatePub.load_config("spec/fixtures/private_pub.yml", "production")
-    PrivatePub.config[:server].should == "http://example.com/faye"
-    PrivatePub.config[:secret_token].should == "PRODUCTION_SECRET_TOKEN"
-    PrivatePub.config[:signature_expiration].should == 600
-  end
-
-  it "supports a nil signature_expiration via a blank value in the configuration file" do
-    PrivatePub.load_config("spec/fixtures/private_pub.yml", :no_signature_expiration)
-    PrivatePub.config[:signature_expiration].should be_nil
+    PrivatePub.config[:server].should eq("http://example.com/faye")
+    PrivatePub.config[:secret_token].should eq("PRODUCTION_SECRET_TOKEN")
+    PrivatePub.config[:signature_expiration].should eq(600)
   end
 
   it "raises an exception if an invalid environment is passed to load_config" do
@@ -37,16 +32,18 @@ describe PrivatePub do
     }.should raise_error ArgumentError
   end
 
-  it "includes channel and custom time in subscription" do
+  it "includes channel, server, and custom time in subscription" do
+    PrivatePub.config[:server] = "server"
     subscription = PrivatePub.subscription(:timestamp => 123, :channel => "hello")
-    subscription[:timestamp].should == 123
-    subscription[:channel].should == "hello"
+    subscription[:timestamp].should eq(123)
+    subscription[:channel].should eq("hello")
+    subscription[:server].should eq("server")
   end
 
   it "does a sha1 digest of channel, timestamp, and secret token" do
     PrivatePub.config[:secret_token] = "token"
     subscription = PrivatePub.subscription(:timestamp => 123, :channel => "channel")
-    subscription[:signature].should == Digest::SHA1.hexdigest("tokenchannel123")
+    subscription[:signature].should eq(Digest::SHA1.hexdigest("tokenchannel123"))
   end
 
   it "formats a message hash given a channel and a string for eval" do
@@ -74,15 +71,22 @@ describe PrivatePub do
   end
 
   it "publish message as json to server using Net::HTTP" do
+    PrivatePub.config[:server] = "http://localhost"
     message = stub(:to_json => "message_json")
-    Net::HTTP.should_receive(:post_form).with(URI.parse(PrivatePub.config[:server]), :message => "message_json").and_return(:result)
-    PrivatePub.publish_message(message).should == :result
+    Net::HTTP.should_receive(:post_form).with(URI.parse("http://localhost"), :message => "message_json").and_return(:result)
+    PrivatePub.publish_message(message).should eq(:result)
+  end
+
+  it "raises an exception if no server is specified when calling publish_message" do
+    lambda {
+      PrivatePub.publish_message("foo")
+    }.should raise_error(PrivatePub::Error)
   end
 
   it "publish_to passes message to publish_message call" do
     PrivatePub.should_receive(:message).with("chan", "foo").and_return("message")
     PrivatePub.should_receive(:publish_message).with("message").and_return(:result)
-    PrivatePub.publish_to("chan", "foo").should == :result
+    PrivatePub.publish_to("chan", "foo").should eq(:result)
   end
 
   it "has a Faye rack app instance" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: private_pub
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2012-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faye
-  requirement: &70172946940680 !ruby/object:Gem::Requirement
+  requirement: &70255009397180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70172946940680
+  version_requirements: *70255009397180
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70172946940000 !ruby/object:Gem::Requirement
+  requirement: &70255009396460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70172946940000
+  version_requirements: *70255009396460
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70172946939000 !ruby/object:Gem::Requirement
+  requirement: &70255009395280 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: 2.8.0
   type: :development
   prerelease: false
-  version_requirements: *70172946939000
+  version_requirements: *70255009395280
 - !ruby/object:Gem::Dependency
   name: jasmine
-  requirement: &70172946936820 !ruby/object:Gem::Requirement
+  requirement: &70255009393320 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,7 +54,7 @@ dependencies:
         version: 1.1.1
   type: :development
   prerelease: false
-  version_requirements: *70172946936820
+  version_requirements: *70255009393320
 description: Private pub/sub messaging in Rails through Faye.
 email: ryan@railscasts.com
 executables: []