pusher 0.7.0 → 0.7.1

data/.gitignore

@@ -17,6 +17,7 @@ tmtags
 coverage
 rdoc
 pkg
+.yardoc
 
 ## PROJECT::SPECIFIC
 .bundle

data/.travis.yml

@@ -0,0 +1 @@
+script: "rspec spec/*_spec.rb"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    pusher (0.6.0)
+    pusher (0.7.0)
       crack (~> 0.1.0)
       json (~> 1.4.0)
       ruby-hmac (~> 0.4.0)
@@ -10,28 +10,26 @@ PATH
 GEM
   remote: http://rubygems.org/
   specs:
-    addressable (2.2.2)
+    addressable (2.2.4)
     crack (0.1.8)
     diff-lcs (1.1.2)
-    em-http-request (0.2.14)
+    em-http-request (0.2.15)
       addressable (>= 2.0.0)
       eventmachine (>= 0.12.9)
     eventmachine (0.12.10)
     json (1.4.6)
-    rspec (2.0.1)
-      rspec-core (~> 2.0.1)
-      rspec-expectations (~> 2.0.1)
-      rspec-mocks (~> 2.0.1)
-    rspec-core (2.0.1)
-    rspec-expectations (2.0.1)
-      diff-lcs (>= 1.1.2)
-    rspec-mocks (2.0.1)
-      rspec-core (~> 2.0.1)
-      rspec-expectations (~> 2.0.1)
+    rspec (2.5.0)
+      rspec-core (~> 2.5.0)
+      rspec-expectations (~> 2.5.0)
+      rspec-mocks (~> 2.5.0)
+    rspec-core (2.5.1)
+    rspec-expectations (2.5.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.5.0)
     ruby-hmac (0.4.0)
     signature (0.1.2)
       ruby-hmac
-    webmock (1.4.0)
+    webmock (1.6.2)
       addressable (>= 2.2.2)
       crack (>= 0.1.7)
 
@@ -39,11 +37,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  crack (~> 0.1.0)
   em-http-request (~> 0.2.7)
-  json (~> 1.4.0)
   pusher!
   rspec (~> 2.0)
-  ruby-hmac (~> 0.4.0)
-  signature (~> 0.1.2)
   webmock

data/README.md

@@ -28,18 +28,25 @@ Errors are logged to `Pusher.logger`. It will by default use `Logger` from stdli
 Asynchronous triggering
 -----------------------
 
-To avoid blocking in a typical web application, if you are running inside eventmachine (for example if you use the thin server), you may wish to use the `trigger_async` method which uses the em-http-request gem to make api requests to pusher. It returns a deferrable which you can optionally bind to with success and failure callbacks. This is not a gem dependency, so you will need to install it manually.
+To avoid blocking in a typical web application, you may wish to use the `trigger_async` method which uses the makes asynchronous API requests to Pusher. `trigger_async` returns a deferrable which you can optionally bind to with success and failure callbacks.
 
-    d = Pusher['a_channel'].trigger_async('an_event', {:some => 'data'}, socket_id)
-    d.callback {
+You need to be running eventmachine to make use of this functionality. This is already the case if, for example, you're deploying to Heroku or using the Thin web server. You will also need to add `em-http-request` to your Gemfile.
+
+    $ gem install em-http-request
+
+    deferrable = Pusher['a_channel'].trigger_async('an_event', {
+      :some => 'data'
+    }, socket_id)
+    deferrable.callback {
       # Do something on success
     }
-    d.errback { |error|
-      # error is a pusher exception
+    deferrable.errback { |error|
+      # error is a instance of Pusher::Error
     }
 
 Private channels
------------------------
+----------------
+
 The Pusher Gem also deals with signing requests for authenticated private channels. A quick Rails controller example:
 
     reponse = Pusher['private-my_channel'].authenticate(params[:socket_id])

data/lib/pusher.rb

@@ -1,7 +1,18 @@
 autoload 'Logger', 'logger'
 require 'uri'
 
+# Used for configuring API credentials and creating Channel objects
+#
 module Pusher
+  # All Pusher errors descend from this class so you can easily rescue Pusher
+  # errors
+  #
+  # @example
+  #   begin
+  #     Pusher['a_channel'].trigger!('an_event', {:some => 'data'})
+  #   rescue Pusher::Error => e
+  #     # Do something on error
+  #   end
   class Error < RuntimeError; end
   class AuthenticationError < Error; end
   class ConfigurationError < Error; end
@@ -11,6 +22,7 @@ module Pusher
     attr_writer :logger
     attr_accessor :app_id, :key, :secret
 
+    # @private
     def logger
       @logger ||= begin
         log = Logger.new(STDOUT)
@@ -19,11 +31,12 @@ module Pusher
       end
     end
     
+    # @private
     def authentication_token
       Signature::Token.new(@key, @secret)
     end
 
-    # Builds a connection url for Pusherapp
+    # @private Builds a connection url for Pusherapp
     def url
       URI::Generic.build({
         :scheme => self.scheme,
@@ -33,7 +46,12 @@ module Pusher
       })
     end
 
-    # Allows configuration from a url
+    # Configure Pusher connection by providing a url rather than specifying
+    # scheme, key, secret, and app_id separately.
+    #
+    # @example
+    #   Pusher.url = http://KEY:SECRET@api.pusherapp.com/apps/APP_ID
+    #
     def url=(url)
       uri = URI.parse(url)
       self.app_id = uri.path.split('/').last
@@ -43,7 +61,12 @@ module Pusher
       self.port   = uri.port
     end
 
-    # Configure ssl by setting Pusher.encrypted = true
+    # Configure whether Pusher API calls should be made over SSL
+    # (default false)
+    #
+    # @example
+    #   Pusher.encrypted = true
+    #
     def encrypted=(boolean)
       Pusher.scheme = boolean ? 'https' : 'http'
       # Configure port if it hasn't already been configured
@@ -65,6 +88,13 @@ module Pusher
     self.url = ENV['PUSHER_URL']
   end
 
+  # Return a channel by name
+  #
+  # @example
+  #   Pusher['my-channel']
+  # @return [Channel]
+  # @raise [ConfigurationError] unless key, secret and app_id have been
+  #   configured
   def self.[](channel_name)
     raise ConfigurationError, 'Missing configuration: please check that Pusher.url is configured' unless configured?
     @channels ||= {}

data/lib/pusher/channel.rb

@@ -2,6 +2,7 @@ require 'crack/core_extensions' # Used for Hash#to_params
 require 'hmac-sha2'
 
 module Pusher
+  # Trigger events on Channels
   class Channel
     attr_reader :name
 
@@ -11,6 +12,17 @@ module Pusher
       @name = name
     end
 
+    # Trigger event asynchronously using EventMachine::HttpRequest
+    #
+    # @param (see #trigger!)
+    # @return [EM::DefaultDeferrable]
+    #   Attach a callback to be notified of success (with no parameters).
+    #   Attach an errback to be notified of failure (with an error parameter
+    #   which includes the HTTP status code returned)
+    # @raise [LoadError] unless em-http-request gem is available
+    # @raise [Pusher::Error] unless the eventmachine reactor is running. You
+    #   probably want to run your application inside a server such as thin
+    #
     def trigger_async(event_name, data, socket_id = nil, &block)
       unless defined?(EventMachine) && EventMachine.reactor_running?
         raise Error, "In order to use trigger_async you must be running inside an eventmachine loop"
@@ -24,7 +36,7 @@ module Pusher
       deferrable = EM::DefaultDeferrable.new
       
       http = @http_async.post({
-        :query => request.query, :timeout => 2, :body => request.body,
+        :query => request.query, :timeout => 5, :body => request.body,
         :head => {'Content-Type'=> 'application/json'}
       })
       http.callback {
@@ -43,6 +55,23 @@ module Pusher
       deferrable
     end
 
+    # Trigger event
+    #
+    # @example
+    #   begin
+    #     Pusher['my-channel'].trigger!('an_event', {:some => 'data'})
+    #   rescue Pusher::Error => e
+    #     # Do something on error
+    #   end
+    #
+    # @param data [Object] Event data to be triggered in javascript.
+    #   Objects other than strings will be converted to JSON
+    # @param socket_id Allows excluding a given socket_id from receiving the
+    #   event - see http://pusherapp.com/docs/duplicates for more info
+    #
+    # @raise [Pusher::Error] on invalid Pusher response
+    # @raise any Net::HTTP related errors
+    #
     def trigger!(event_name, data, socket_id = nil)
       require 'net/http' unless defined?(Net::HTTP)
       require 'net/https' if (ssl? && !defined?(Net::HTTPS))
@@ -62,18 +91,29 @@ module Pusher
       handle_response(response.code.to_i, response.body.chomp)
     end
 
+    # Trigger event, catching and logging any errors.
+    #
+    # @note CAUTION! No exceptions will be raised on failure
+    # @param (see #trigger!)
+    #
     def trigger(event_name, data, socket_id = nil)
       trigger!(event_name, data, socket_id)
     rescue StandardError => e
-      handle_error e
+      Pusher.logger.error("#{e.message} (#{e.class})")
+      Pusher.logger.debug(e.backtrace.join("\n"))
     end
     
-    # Auth string is:
-    # if custom data provided:
-    # socket_id:channel_name:[JSON-encoded custom data]
-    # if no custom data:
-    # socket_id:channel_name
-    def socket_auth(socket_id, custom_string = nil)
+    # Compute authentication string required to subscribe to this channel.
+    #
+    # See http://pusherapp.com/docs/auth_signatures for more details.
+    #
+    # @param socket_id [String] Each Pusher socket connection receives a
+    #   unique socket_id. This is sent from pusher.js to your server when
+    #   channel authentication is required.
+    # @param custom_string [String] Allows signing additional data
+    # @return [String]
+    #
+    def authentication_string(socket_id, custom_string = nil)
       raise "Invalid socket_id" if socket_id.nil? || socket_id.empty?
       raise 'Custom argument must be a string' unless custom_string.nil? || custom_string.kind_of?(String)
 
@@ -85,8 +125,18 @@ module Pusher
       return "#{token.key}:#{signature}"
     end
     
-    # Custom data is sent to server as JSON-encoded string in the :data key
-    # If :data present, server must include it in auth check
+    # Deprecated - for backward compatibility
+    alias :socket_auth :authentication_string
+
+    # Generate an authentication endpoint response
+    #
+    # @example
+    #   render :json => Pusher['private-my_channel'].authenticate(params[:socket_id])
+    #
+    # @return [Hash]
+    #
+    # @private Custom data is sent to server as JSON-encoded string
+    #
     def authenticate(socket_id, custom_data = nil)
       custom_data = Pusher::JSON.generate(custom_data) if custom_data
       auth = socket_auth(socket_id, custom_data)
@@ -97,11 +147,6 @@ module Pusher
 
     private
 
-    def handle_error(e)
-      Pusher.logger.error("#{e.message} (#{e.class})")
-      Pusher.logger.debug(e.backtrace.join("\n"))
-    end
-
     def handle_response(status_code, body)
       case status_code
       when 202
@@ -113,7 +158,7 @@ module Pusher
       when 404
         raise Error, "Resource not found: app_id is probably invalid"
       else
-        raise Error, "Unknown error in Pusher: #{body}"
+        raise Error, "Unknown error (status code #{status_code}): #{body}"
       end
     end
 

data/pusher.gemspec

@@ -3,7 +3,7 @@ $:.push File.expand_path("../lib", __FILE__)
 
 Gem::Specification.new do |s|
   s.name        = "pusher"
-  s.version     = "0.7.0"
+  s.version     = "0.7.1"
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["New Bamboo"]
   s.email       = ["support@pusherapp.com"]

data/spec/channel_spec.rb

@@ -105,7 +105,7 @@ describe Pusher::Channel do
       ).to_return(:status => 500, :body => "some error")
       lambda {
         Pusher['test_channel'].trigger!('new_event', 'Some data')
-      }.should raise_error(Pusher::Error, 'Unknown error in Pusher: some error')
+      }.should raise_error(Pusher::Error, 'Unknown error (status code 500): some error')
     end
   end
 
@@ -132,7 +132,7 @@ describe Pusher::Channel do
 
   describe "trigger_async" do
     before :each do
-      WebMock.reset_webmock
+      WebMock.reset!
       WebMock.disable_net_connect!
 
       @pusher_url_regexp = %r{/apps/20/channels/test_channel/events}

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 7
-  - 0
-  version: 0.7.0
+  - 1
+  version: 0.7.1
 platform: ruby
 authors: 
 - New Bamboo
@@ -14,13 +14,14 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-22 00:00:00 +00:00
+date: 2011-02-17 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: json
   prerelease: false
   requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
@@ -35,6 +36,7 @@ dependencies:
   name: crack
   prerelease: false
   requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
@@ -49,6 +51,7 @@ dependencies:
   name: ruby-hmac
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
@@ -63,6 +66,7 @@ dependencies:
   name: signature
   prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
@@ -77,6 +81,7 @@ dependencies:
   name: rspec
   prerelease: false
   requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
@@ -90,6 +95,7 @@ dependencies:
   name: webmock
   prerelease: false
   requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
@@ -102,6 +108,7 @@ dependencies:
   name: em-http-request
   prerelease: false
   requirement: &id007 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
@@ -124,6 +131,7 @@ extra_rdoc_files: []
 files: 
 - .document
 - .gitignore
+- .travis.yml
 - Gemfile
 - Gemfile.lock
 - LICENSE
@@ -147,6 +155,7 @@ rdoc_options: []
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
@@ -154,6 +163,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
@@ -163,7 +173,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.6
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: Pusherapp client