koala 1.5.0 → 1.6.0.rc1

data/lib/koala/api/graph_batch_api.rb

@@ -19,35 +19,23 @@ module Koala
       end
 
       def graph_call_in_batch(path, args = {}, verb = "get", options = {}, &post_processing)
-          # for batch APIs, we queue up the call details (incl. post-processing)
-          batch_calls << BatchOperation.new(
-            :url => path,
-            :args => args,
-            :method => verb,
-            :access_token => options['access_token'] || access_token,
-            :http_options => options,
-            :post_processing => post_processing
-          )
-          nil # batch operations return nothing immediately
+        # for batch APIs, we queue up the call details (incl. post-processing)
+        batch_calls << BatchOperation.new(
+          :url => path,
+          :args => args,
+          :method => verb,
+          :access_token => options['access_token'] || access_token,
+          :http_options => options,
+          :post_processing => post_processing
+        )
+        nil # batch operations return nothing immediately
       end
 
-      def check_graph_batch_api_response(response)
-        if response.is_a?(Hash) && response["error"] && !response["error"].is_a?(Hash)
-          # old error format -- see http://developers.facebook.com/blog/post/596/
-          APIError.new({"type" => "Error #{response["error"]}", "message" => response["error_description"]}.merge(response))
-        else
-          check_graph_api_response(response)
-        end
-      end
-
-      # redefine the graph_call and check_response methods
-      # so we can use this API inside the batch block just like any regular Graph API
+      # redefine the graph_call method so we can use this API inside the batch block
+      # just like any regular Graph API
       alias_method :graph_call_outside_batch, :graph_call
       alias_method :graph_call, :graph_call_in_batch
 
-      alias_method :check_graph_api_response, :check_response
-      alias_method :check_response, :check_graph_batch_api_response
-
       # execute the queued batch calls
       def execute(http_options = {})
         return [] unless batch_calls.length > 0
@@ -62,7 +50,7 @@ module Koala
           unless response
             # Facebook sometimes reportedly returns an empty body at times
             # see https://github.com/arsduo/koala/issues/184
-            raise APIError.new({"type" => "BadFacebookResponse", "message" => "Facebook returned invalid batch response: #{response.inspect}"})
+            raise BadFacebookResponse.new(200, '', "Facebook returned an empty body")
           end
 
           # map the results with post-processing included
@@ -72,13 +60,16 @@ module Koala
             batch_op = batch_calls[index]
             index += 1
 
+            raw_result = nil
             if call_result
-              # (see note in regular api method about JSON parsing)
-              body = MultiJson.load("[#{call_result['body'].to_s}]")[0]
+              if ( error = check_response(call_result['code'], call_result['body'].to_s) )
+                raw_result = error
+              else
+                # (see note in regular api method about JSON parsing)
+                body = MultiJson.load("[#{call_result['body'].to_s}]")[0]
 
-              unless call_result["code"].to_i >= 500 || error = check_response(body)
                 # Get the HTTP component they want
-                data = case batch_op.http_options[:http_component]
+                raw_result = case batch_op.http_options[:http_component]
                 when :status
                   call_result["code"].to_i
                 when :headers
@@ -87,20 +78,19 @@ module Koala
                 else
                   body
                 end
-
-                # process it if we are given a block to process with
-                batch_op.post_processing ? batch_op.post_processing.call(data) : data
-              else
-                error || APIError.new({"type" => "HTTP #{call_result["code"].to_s}", "message" => "Response body: #{body}"})
               end
+            end
+
+            # turn any results that are pageable into GraphCollections
+            # and pass to post-processing callback if given
+            result = GraphCollection.evaluate(raw_result, @original_api)
+            if batch_op.post_processing
+              batch_op.post_processing.call(result)
             else
-              nil
+              result
             end
           end
         end
-
-        # turn any results that are pageable into GraphCollections
-        batch_result.inject([]) {|processed_results, raw| processed_results << GraphCollection.evaluate(raw, @original_api)}
       end
 
     end

data/lib/koala/api/graph_collection.rb

@@ -1,3 +1,5 @@
+require 'addressable/uri'
+
 module Koala
   module Facebook
     class API
@@ -87,7 +89,7 @@ module Koala
         #
         # @return an array of parameters that can be provided via graph_call(*parsed_params)
         def self.parse_page_url(url)
-          uri = URI.parse(url)
+          uri = Addressable::URI.parse(url)
 
           base = uri.path.sub(/^\//, '')
           params = CGI.parse(uri.query)

data/lib/koala/api/rest_api.rb

@@ -21,7 +21,7 @@ module Koala
       #
       # @return true if successful, false if not.  (This call currently doesn't give useful feedback on failure.)
       def set_app_properties(properties, args = {}, options = {})
-        raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "setAppProperties requires an access token"}) unless @access_token
+        raise AuthenticationError.new(nil, nil, "setAppProperties requires an access token") unless @access_token
         rest_call("admin.setAppProperties", args.merge(:properties => MultiJson.dump(properties)), options, "post")
       end
 
@@ -44,8 +44,24 @@ module Koala
 
         api("method/#{fb_method}", args.merge('format' => 'json'), verb, options) do |response|
           # check for REST API-specific errors
-          if response.is_a?(Hash) && response["error_code"]
-            raise APIError.new("type" => response["error_code"], "message" => response["error_msg"])
+          if response.status >= 400
+            begin
+              response_hash = MultiJson.load(response.body)
+            rescue MultiJson::DecodeError
+              response_hash = {}
+            end
+
+            error_info = {
+              'code' => response_hash['error_code'],
+              'error_subcode' => response_hash['error_subcode'],
+              'message' => response_hash['error_msg']
+            }
+
+            if response.status >= 500
+              raise ServerError.new(response.status, response.body, error_info)
+            else
+              raise ClientError.new(response.status, response.body, error_info)
+            end
           end
         end
       end

data/lib/koala/errors.rb

@@ -0,0 +1,86 @@
+module Koala
+
+  class KoalaError < StandardError; end
+
+  module Facebook
+
+    # The OAuth signature is incomplete, invalid, or using an unsupported algorithm
+    class OAuthSignatureError < ::Koala::KoalaError; end
+
+    # Facebook responded with an error to an API request. If the exception contains a nil
+    # http_status, then the error was detected before making a call to Facebook. (e.g. missing access token)
+    class APIError < ::Koala::KoalaError
+      attr_accessor :fb_error_type, :fb_error_code, :fb_error_subcode, :fb_error_message,
+                    :http_status, :response_body
+
+      # Create a new API Error
+      #
+      # @param http_status [Integer] The HTTP status code of the response
+      # @param response_body [String] The response body
+      # @param error_info One of the following:
+      #                   [Hash] The error information extracted from the request 
+      #                          ("type", "code", "error_subcode", "message")
+      #                   [String] The error description
+      #                   If error_info is nil or not provided, the method will attempt to extract
+      #                   the error info from the response_body
+      #
+      # @return the newly created APIError
+      def initialize(http_status, response_body, error_info = nil)
+        if response_body
+          self.response_body = response_body.strip
+        else
+          self.response_body = ''
+        end
+        self.http_status = http_status
+
+        if error_info && error_info.is_a?(String)
+          message = error_info
+        else
+          unless error_info
+            begin
+              error_info = MultiJson.load(response_body)['error'] if response_body
+            rescue
+            end
+            error_info ||= {}
+          end
+
+          self.fb_error_type = error_info["type"]
+          self.fb_error_code = error_info["code"]
+          self.fb_error_subcode = error_info["error_subcode"]
+          self.fb_error_message = error_info["message"]
+
+          error_array = []
+          %w(type code error_subcode message).each do |key|
+            error_array << "#{key}: #{error_info[key]}" if error_info[key]
+          end
+
+          if error_array.empty?
+            message = self.response_body
+          else
+            message = error_array.join(', ')
+          end
+        end
+        message += " [HTTP #{http_status}]" if http_status
+
+        super(message)
+      end
+    end
+
+    # Facebook returned an invalid response body
+    class BadFacebookResponse < APIError; end
+
+    # Facebook responded with an error while attempting to request an access token
+    class OAuthTokenRequestError < APIError; end
+
+    # Any error with a 5xx HTTP status code
+    class ServerError < APIError; end
+
+    # Any error with a 4xx HTTP status code 
+    class ClientError < APIError; end
+
+    # All graph API authentication failures.
+    class AuthenticationError < ClientError; end
+
+  end
+
+end

data/lib/koala/oauth.rb

@@ -139,7 +139,7 @@ module Koala
       # @param code (see #url_for_access_token)
       # @param options any additional parameters to send to Facebook when redeeming the token
       #
-      # @raise Koala::Facebook::APIError if Facebook returns an error response
+      # @raise Koala::Facebook::OAuthTokenRequestError if Facebook returns an error response
       #
       # @return a hash of the access token info returned by Facebook (token, expiration, etc.)
       def get_access_token_info(code, options = {})
@@ -221,21 +221,21 @@ module Koala
       #
       # @param input the signed request from Facebook
       #
-      # @raise RuntimeError if the signature is incomplete, invalid, or using an unsupported algorithm
+      # @raise OAuthSignatureError if the signature is incomplete, invalid, or using an unsupported algorithm
       #
       # @return a hash of the validated request information
       def parse_signed_request(input)
         encoded_sig, encoded_envelope = input.split('.', 2)
-        raise 'SignedRequest: Invalid (incomplete) signature data' unless encoded_sig && encoded_envelope
+        raise OAuthSignatureError, 'Invalid (incomplete) signature data' unless encoded_sig && encoded_envelope
 
         signature = base64_url_decode(encoded_sig).unpack("H*").first
         envelope = MultiJson.load(base64_url_decode(encoded_envelope))
 
-        raise "SignedRequest: Unsupported algorithm #{envelope['algorithm']}" if envelope['algorithm'] != 'HMAC-SHA256'
+        raise OAuthSignatureError, "Unsupported algorithm #{envelope['algorithm']}" if envelope['algorithm'] != 'HMAC-SHA256'
 
         # now see if the signature is valid (digest, key, data)
         hmac = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, @app_secret, encoded_envelope)
-        raise 'SignedRequest: Invalid signature' if (signature != hmac)
+        raise OAuthSignatureError, 'Invalid signature' if (signature != hmac)
 
         envelope
       end
@@ -254,10 +254,7 @@ module Koala
 
         # Facebook returns an empty body in certain error conditions
         if response == ""
-          raise APIError.new({
-            "type" => "ArgumentError",
-            "message" => "get_token_from_session_key received an error (empty response body) for sessions #{sessions.inspect}!"
-          })
+          raise BadFacebookResponse.new(200, '', "get_token_from_session_key received an error (empty response body) for sessions #{sessions.inspect}!")
         end
 
         MultiJson.load(response)
@@ -282,13 +279,8 @@ module Koala
 
       def get_token_from_server(args, post = false, options = {})
         # fetch the result from Facebook's servers
-        result = fetch_token_string(args, post, "access_token", options)
-
-        # if we have an error, parse the error JSON and raise an error
-        raise APIError.new((MultiJson.load(result)["error"] rescue nil) || {}) if result =~ /error/
-
-        # otherwise, parse the access token
-        parse_access_token(result)
+        response = fetch_token_string(args, post, "access_token", options)
+        parse_access_token(response)
       end
 
       def parse_access_token(response_text)
@@ -318,9 +310,12 @@ module Koala
         if code = components["code"]
           begin
             token_info = get_access_token_info(code, :redirect_uri => '')
-          rescue Koala::Facebook::APIError => err
-            return nil if err.message =~ /Code was invalid or expired/
-            raise
+          rescue Koala::Facebook::OAuthTokenRequestError => err
+            if err.fb_error_type == 'OAuthException' && err.fb_error_message =~ /Code was invalid or expired/
+              return nil
+            else
+              raise
+            end
           end
 
           components.merge(token_info) if token_info
@@ -331,10 +326,15 @@ module Koala
       end
 
       def fetch_token_string(args, post = false, endpoint = "access_token", options = {})
-        Koala.make_request("/oauth/#{endpoint}", {
+        response = Koala.make_request("/oauth/#{endpoint}", {
           :client_id => @app_id,
           :client_secret => @app_secret
-        }.merge!(args), post ? "post" : "get", {:use_ssl => true}.merge!(options)).body
+        }.merge!(args), post ? "post" : "get", {:use_ssl => true}.merge!(options))
+
+        raise ServerError.new(response.status, response.body) if response.status >= 500
+        raise OAuthTokenRequestError.new(response.status, response.body) if response.status >= 400
+
+        response.body
       end
 
       # base 64

data/lib/koala/realtime_updates.rb

@@ -7,19 +7,19 @@ module Koala
       # @note: to subscribe to real-time updates, you must have an application access token
       #        or provide the app secret when initializing your RealtimeUpdates object.
 
-      # The application API interface used to communicate with Facebook. 
-      # @return [Koala::Facebook::API] 
+      # The application API interface used to communicate with Facebook.
+      # @return [Koala::Facebook::API]
       attr_reader :api
       attr_reader :app_id, :app_access_token, :secret
 
-      # Create a new RealtimeUpdates instance.  
-      # If you don't have your app's access token, provide the app's secret and 
+      # Create a new RealtimeUpdates instance.
+      # If you don't have your app's access token, provide the app's secret and
       # Koala will make a request to Facebook for the appropriate token.
-      # 
+      #
       # @param options initialization options.
       # @option options :app_id the application's ID.
       # @option options :app_access_token an application access token, if known.
-      # @option options :secret the application's secret.  
+      # @option options :secret the application's secret.
       #
       # @raise ArgumentError if the application ID and one of the app access token or the secret are not provided.
       def initialize(options = {})
@@ -39,7 +39,7 @@ module Koala
         @api = API.new(@app_access_token)
       end
 
-      # Subscribe to realtime updates for certain fields on a given object (user, page, etc.).  
+      # Subscribe to realtime updates for certain fields on a given object (user, page, etc.).
       # See {http://developers.facebook.com/docs/reference/api/realtime the realtime updates documentation}
       # for more information on what objects and fields you can register for.
       #
@@ -48,11 +48,11 @@ module Koala
       # @param object a Facebook ID (name or number)
       # @param fields the fields you want your app to be updated about
       # @param callback_url the URL Facebook should ping when an update is available
-      # @param verify_token a token included in the verification request, allowing you to ensure the call is genuine 
+      # @param verify_token a token included in the verification request, allowing you to ensure the call is genuine
       #                     (see the docs for more information)
       # @param options (see Koala::HTTPService.make_request)
       #
-      # @return true if successful, false (or an APIError) otherwise.
+      # @raise A subclass of Koala::Facebook::APIError if the subscription request failed.
       def subscribe(object, fields, callback_url, verify_token, options = {})
         args = {
           :object => object,
@@ -60,23 +60,23 @@ module Koala
           :callback_url => callback_url,
         }.merge(verify_token ? {:verify_token => verify_token} : {})
         # a subscription is a success if Facebook returns a 200 (after hitting your server for verification)
-        @api.graph_call(subscription_path, args, 'post', options.merge(:http_component => :status)) == 200
+        @api.graph_call(subscription_path, args, 'post', options)
       end
 
-      # Unsubscribe from updates for a particular object or from updates. 
+      # Unsubscribe from updates for a particular object or from updates.
       #
-      # @param object the object whose subscriptions to delete. 
+      # @param object the object whose subscriptions to delete.
       #               If no object is provided, all subscriptions will be removed.
       # @param options (see Koala::HTTPService.make_request)
       #
-      # @return true if the unsubscription is successful, false (or an APIError) otherwise.
+      # @raise A subclass of Koala::Facebook::APIError if the subscription request failed.
       def unsubscribe(object = nil, options = {})
-        @api.graph_call(subscription_path, object ? {:object => object} : {}, "delete", options.merge(:http_component => :status)) == 200
+        @api.graph_call(subscription_path, object ? {:object => object} : {}, "delete", options)
       end
 
       # List all active subscriptions for this application.
-      # 
-      # @param options (see Koala::HTTPService.make_request) 
+      #
+      # @param options (see Koala::HTTPService.make_request)
       #
       # @return [Array] a list of active subscriptions
       def list_subscriptions(options = {})
@@ -89,12 +89,12 @@ module Koala
       #
       # @param params the request parameters sent by Facebook.  (You can pass in a Rails params hash.)
       # @param verify_token the verify token sent in the {#subscribe subscription request}, if you provided one
-      # 
+      #
       # @yield verify_token if you need to compute the verification token
       #                     (for instance, if your callback URL includes a record ID, which you look up
-      #                     and use to calculate a hash), you can pass meet_challenge a block, which 
+      #                     and use to calculate a hash), you can pass meet_challenge a block, which
       #                     will receive the verify_token received back from Facebook.
-      # 
+      #
       # @return the challenge string to be sent back to Facebook, or false if the request is invalid.
       def self.meet_challenge(params, verify_token = nil, &verification_block)
         if params["hub.mode"] == "subscribe" &&
@@ -111,12 +111,33 @@ module Koala
           false
         end
       end
-      
+
+      # Public: As a security measure, all updates from facebook are signed using
+      # X-Hub-Signature: sha1=XXXX where XXX is the sha1 of the json payload
+      # using your application secret as the key.
+      #
+      # Example:
+      #   # in Rails controller
+      #   # @oauth being a previously defined Koala::Facebook::OAuth instance
+      #   def receive_update
+      #     if @oauth.validate_update(request.body, headers)
+      #       ...
+      #     end
+      #   end
+      def validate_update(body, headers)
+        if request_signature = headers['X-Hub-Signature'] || headers['HTTP_X_HUB_SIGNATURE'] and
+           signature_parts = request_signature.split("sha1=")
+          request_signature = signature_parts[1]
+          calculated_signature = OpenSSL::HMAC.hexdigest('sha1', @secret, body)
+          calculated_signature == request_signature
+        end
+      end
+
       # The Facebook subscription management URL for your application.
       def subscription_path
         @subscription_path ||= "#{@app_id}/subscriptions"
       end
-      
+
       # @private
       def graph_api
         Koala::Utils.deprecate("the TestUsers.graph_api accessor is deprecated and will be removed in a future version; please use .api instead.")