koala 2.4.0 → 3.5.0

data/lib/koala/api/graph_batch_api.rb

@@ -1,16 +1,18 @@
-require 'koala/api'
-require 'koala/api/batch_operation'
+require "koala/api"
+require "koala/api/batch_operation"
 
 module Koala
   module Facebook
     # @private
-    class GraphBatchAPI < API
+    class GraphBatchAPI
       # inside a batch call we can do anything a regular Graph API can do
       include GraphAPIMethods
 
+      # Limits from @see https://developers.facebook.com/docs/marketing-api/batch-requests/v2.8
+      MAX_CALLS = 50
+
       attr_reader :original_api
       def initialize(api)
-        super(api.access_token, api.app_secret)
         @original_api = api
       end
 
@@ -18,7 +20,9 @@ module Koala
         @batch_calls ||= []
       end
 
-      def graph_call_in_batch(path, args = {}, verb = "get", options = {}, &post_processing)
+      # Enqueue a call into the batch for later processing.
+      # See API#graph_call
+      def graph_call(path, args = {}, verb = "get", options = {}, &post_processing)
         # normalize options for consistency
         options = Koala::Utils.symbolize_hash(options)
 
@@ -34,74 +38,117 @@ module Koala
         nil # batch operations return nothing immediately
       end
 
-      # 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
-
-      # execute the queued batch calls
+      # execute the queued batch calls. limits it to 50 requests per call.
+      # NOTE: if you use `name` and JsonPath references, you should ensure to call `execute` for each
+      # co-reference group and that the group size is not greater than the above limits.
       def execute(http_options = {})
-        return [] unless batch_calls.length > 0
-        # Turn the call args collected into what facebook expects
-        args = {}
-        args["batch"] = MultiJson.dump(batch_calls.map { |batch_op|
-          args.merge!(batch_op.files) if batch_op.files
-          batch_op.to_batch_params(access_token, app_secret)
-        })
+        return [] if batch_calls.empty?
+
+        batch_results = []
+        batch_calls.each_slice(MAX_CALLS) do |batch|
+          # Turn the call args collected into what facebook expects
+          args = {"batch" => batch_args(batch)}
+          batch.each do |call|
+            args.merge!(call.files || {})
+          end
 
-        batch_result = graph_call_outside_batch('/', args, 'post', http_options) do |response|
-          unless response
-            # Facebook sometimes reportedly returns an empty body at times
-            # see https://github.com/arsduo/koala/issues/184
-            raise BadFacebookResponse.new(200, '', "Facebook returned an empty body")
+          original_api.graph_call("/", args, "post", http_options) do |response|
+            raise bad_response if response.nil?
+
+            batch_results += generate_results(response, batch)
           end
+        end
+
+        batch_results
+      end
+
+      def generate_results(response, batch)
+        index = 0
+        response.map do |call_result|
+          batch_op = batch[index]
+          index += 1
+          post_process = batch_op.post_processing
 
-          # map the results with post-processing included
-          index = 0 # keep compat with ruby 1.8 - no with_index for map
-          response.map do |call_result|
-            # Get the options hash
-            batch_op = batch_calls[index]
-            index += 1
-
-            raw_result = nil
-            if call_result
-              parsed_headers = if call_result.has_key?('headers')
-                call_result['headers'].inject({}) { |headers, h| headers[h['name']] = h['value']; headers}
-              else
-                {}
-              end
-
-              if (error = check_response(call_result['code'], call_result['body'].to_s, parsed_headers))
-                raw_result = error
-              else
-                # (see note in regular api method about JSON parsing)
-                body = MultiJson.load("[#{call_result['body'].to_s}]")[0]
-
-                # Get the HTTP component they want
-                raw_result = case batch_op.http_options[:http_component]
-                when :status
-                  call_result["code"].to_i
-                when :headers
-                  # facebook returns the headers as an array of k/v pairs, but we want a regular hash
-                  parsed_headers
-                else
-                  body
-                end
-              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
-              result
-            end
+          # turn any results that are pageable into GraphCollections
+          result = result_from_response(call_result, batch_op)
+
+          # and pass to post-processing callback if given
+          if post_process
+            post_process.call(result)
+          else
+            result
           end
         end
       end
 
+      def bad_response
+        # Facebook sometimes reportedly returns an empty body at times
+        BadFacebookResponse.new(200, "", "Facebook returned an empty body")
+      end
+
+      def result_from_response(response, options)
+        return nil if response.nil?
+
+        headers   = headers_from_response(response)
+        error     = error_from_response(response, headers)
+        component = options.http_options[:http_component]
+
+        error || desired_component(
+          component: component,
+          response: response,
+          headers: headers
+        )
+      end
+
+      def headers_from_response(response)
+        headers = response.fetch("headers", [])
+
+        headers.inject({}) do |compiled_headers, header|
+          compiled_headers.merge(header.fetch("name") => header.fetch("value"))
+        end
+      end
+
+      def error_from_response(response, headers)
+        code = response["code"]
+        body = response["body"].to_s
+
+        GraphErrorChecker.new(code, body, headers).error_if_appropriate
+      end
+
+      def batch_args(calls_for_batch)
+        calls = calls_for_batch.map do |batch_op|
+          batch_op.to_batch_params(access_token, app_secret)
+        end
+
+        JSON.dump calls
+      end
+
+      def json_body(response)
+        # quirks_mode is needed because Facebook sometimes returns a raw true or false value --
+        # in Ruby 2.4 we can drop that.
+        JSON.parse(response.fetch("body"), quirks_mode: true)
+      end
+
+      def desired_component(component:, response:, headers:)
+        result = Koala::HTTPService::Response.new(response['status'], response['body'], headers)
+
+        # Get the HTTP component they want
+        case component
+        when :status  then response["code"].to_i
+        # facebook returns the headers as an array of k/v pairs, but we want a regular hash
+        when :headers then headers
+        # (see note in regular api method about JSON parsing)
+        else GraphCollection.evaluate(result, original_api)
+        end
+      end
+
+      def access_token
+        original_api.access_token
+      end
+
+      def app_secret
+        original_api.app_secret
+      end
     end
   end
 end

data/lib/koala/api/graph_collection.rb

@@ -16,30 +16,41 @@ module Koala
         attr_reader :api
         # The entire raw response from Facebook.
         attr_reader :raw_response
+        # The headers from the Facebook response
+        attr_reader :headers
 
         # Initialize the array of results and store various additional paging-related information.
         #
-        # @param response the response from Facebook (a hash whose "data" key is an array)
+        # @param [Koala::HTTPService::Response] response object wrapping the raw Facebook response
         # @param api the Graph {Koala::Facebook::API API} instance to use to make calls
         #            (usually the API that made the original call).
         #
-        # @return [Koala::Facebook::GraphCollection] an initialized GraphCollection
+        # @return [Koala::Facebook::API::GraphCollection] an initialized GraphCollection
         #         whose paging, summary, raw_response, and api attributes are populated.
         def initialize(response, api)
-          super response["data"]
-          @paging = response["paging"]
-          @summary = response["summary"]
-          @raw_response = response
+          super response.data["data"]
+          @paging = response.data["paging"]
+          @summary = response.data["summary"]
+          @raw_response = response.data
           @api = api
+          @headers = response.headers
         end
 
         # @private
         # Turn the response into a GraphCollection if they're pageable;
-        # if not, return the original response.
+        # if not, return the data of the original response.
         # The Ads API (uniquely so far) returns a hash rather than an array when queried
         # with get_connections.
         def self.evaluate(response, api)
-          response.is_a?(Hash) && response["data"].is_a?(Array) ? self.new(response, api) : response
+          return nil if response.nil?
+
+          is_pageable?(response) ? self.new(response, api) : response.data
+        end
+
+        # response will always be an instance of Koala::HTTPService::Response
+        # since that is what we get from Koala::Facebook::API#api
+        def self.is_pageable?(response)
+          response.data.is_a?(Hash) && response.data["data"].is_a?(Array)
         end
 
         # Retrieve the next page of results.
@@ -113,9 +124,5 @@ module Koala
         end
       end
     end
-
-    # @private
-    # legacy support for when GraphCollection lived directly under Koala::Facebook
-    GraphCollection = API::GraphCollection
   end
 end

data/lib/koala/api/graph_error_checker.rb

@@ -17,7 +17,7 @@ module Koala
 
       # Facebook can return debug information in the response headers -- see
       # https://developers.facebook.com/docs/graph-api/using-graph-api#bugdebug
-      DEBUG_HEADERS = ["x-fb-debug", "x-fb-rev", "x-fb-trace-id"]
+      DEBUG_HEADERS = %w[x-fb-debug x-fb-rev x-fb-trace-id x-business-use-case-usage x-ad-account-usage x-app-usage]
 
       def error_if_appropriate
         if http_status >= 400
@@ -61,8 +61,9 @@ module Koala
         # Normally, we start with the response body. If it isn't valid JSON, we start with an empty
         # hash and fill it with error data.
         @response_hash ||= begin
-          MultiJson.load(body)
-        rescue MultiJson::DecodeError
+          parsed_body = JSON.parse(body)
+          parsed_body.is_a?(Hash) ? parsed_body : {}
+        rescue JSON::ParserError
           {}
         end
       end

data/lib/koala/api.rb

@@ -1,6 +1,6 @@
 # graph_batch_api and legacy are required at the bottom, since they depend on API being defined
-require 'koala/api/graph_api'
-require 'koala/api/rest_api'
+require 'koala/api/graph_api_methods'
+require 'koala/api/graph_collection'
 require 'openssl'
 
 module Koala
@@ -13,23 +13,74 @@ module Koala
       #                 signed by default, unless you pass appsecret_proof:
       #                 false as an option to the API call. (See
       #                 https://developers.facebook.com/docs/graph-api/securing-requests/)
+      # @param [Block]  rate_limit_hook block called with limits received in facebook response headers
       # @note If no access token is provided, you can only access some public information.
       # @return [Koala::Facebook::API] the API client
-      def initialize(access_token = nil, app_secret = nil)
+      def initialize(access_token = Koala.config.access_token, app_secret = Koala.config.app_secret, rate_limit_hook = Koala.config.rate_limit_hook)
         @access_token = access_token
         @app_secret = app_secret
+        @rate_limit_hook = rate_limit_hook
       end
 
-      attr_reader :access_token, :app_secret
+      attr_reader :access_token, :app_secret, :rate_limit_hook
 
       include GraphAPIMethods
-      include RestAPIMethods
+
+      # Make a call directly to the Graph API.
+      # (See any of the other methods for example invocations.)
+      #
+      # @param path the Graph API path to query (no leading / needed)
+      # @param args (see #get_object)
+      # @param verb the type of HTTP request to make (get, post, delete, etc.)
+      # @options (see #get_object)
+      #
+      # @yield response when making a batch API call, you can pass in a block
+      #        that parses the results, allowing for cleaner code.
+      #        The block's return value is returned in the batch results.
+      #        See the code for {#get_picture} for examples.
+      #        (Not needed in regular calls; you'll probably rarely use this.)
+      #
+      # @raise [Koala::Facebook::APIError] if Facebook returns an error
+      #
+      # @return the result from Facebook
+      def graph_call(path, args = {}, verb = "get", options = {}, &post_processing)
+        # enable appsecret_proof by default
+        options = {:appsecret_proof => true}.merge(options) if @app_secret
+        response = api(path, args, verb, options)
+
+        error = GraphErrorChecker.new(response.status, response.body, response.headers).error_if_appropriate
+        raise error if error
+
+        # if we want a component other than the body (e.g. redirect header for images), provide that
+        http_component = options[:http_component]
+        desired_data = if options[:http_component]
+          http_component == :response ? response : response.send(http_component)
+        else
+          # turn this into a GraphCollection if it's pageable
+          API::GraphCollection.evaluate(response, self)
+        end
+
+        if rate_limit_hook
+          limits = %w(x-business-use-case-usage x-ad-account-usage x-app-usage).each_with_object({}) do |key, hash|
+            value = response.headers.fetch(key, nil)
+            next unless value
+            hash[key] = JSON.parse(response.headers[key])
+          rescue JSON::ParserError => e
+            Koala::Utils.logger.error("#{e.class}: #{e.message} while parsing #{key} = #{value}")
+          end
+
+          rate_limit_hook.call(limits) if limits.keys.any?
+        end
+
+        # now process as appropriate for the given call (get picture header, etc.)
+        post_processing ? post_processing.call(desired_data) : desired_data
+      end
+
 
       # Makes a request to the appropriate Facebook API.
       # @note You'll rarely need to call this method directly.
       #
       # @see GraphAPIMethods#graph_call
-      # @see RestAPIMethods#rest_call
       #
       # @param path the server path for this request (leading / is prepended if not present)
       # @param args arguments to be sent to Facebook
@@ -44,14 +95,10 @@ module Koala
       # @option options [Boolean] :beta use Facebook's beta tier
       # @option options [Boolean] :use_ssl force SSL for this request, even if it's tokenless.
       #                                    (All API requests with access tokens use SSL.)
-      # @param error_checking_block a block to evaluate the response status for additional JSON-encoded errors
-      #
-      # @yield The response for evaluation
-      #
       # @raise [Koala::Facebook::ServerError] if Facebook returns an error (response status >= 500)
       #
-      # @return the body of the response from Facebook (unless another http_component is requested)
-      def api(path, args = {}, verb = "get", options = {}, &error_checking_block)
+      # @return a Koala::HTTPService::Response object representing the returned Facebook data
+      def api(path, args = {}, verb = "get", options = {})
         # we make a copy of args so the modifications (added access_token & appsecret_proof)
         # do not affect the received argument
         args = args.dup
@@ -60,6 +107,7 @@ module Koala
         # This is explicitly needed in batch requests so GraphCollection
         # results preserve any specific access tokens provided
         args["access_token"] ||= @access_token || @app_access_token if @access_token || @app_access_token
+
         if options.delete(:appsecret_proof) && args["access_token"] && @app_secret
           args["appsecret_proof"] = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), @app_secret, args["access_token"])
         end
@@ -68,7 +116,7 @@ module Koala
         args = sanitize_request_parameters(args) unless preserve_form_arguments?(options)
 
         # add a leading / if needed...
-        path = "/#{path}" unless path =~ /^\//
+        path = "/#{path}" unless path.to_s =~ /^\//
 
         # make the request via the provided service
         result = Koala.make_request(path, args, verb, options)
@@ -77,17 +125,7 @@ module Koala
           raise Koala::Facebook::ServerError.new(result.status.to_i, result.body)
         end
 
-        yield result if error_checking_block
-
-        # if we want a component other than the body (e.g. redirect header for images), return that
-        if component = options[:http_component]
-          component == :response ? result : result.send(options[:http_component])
-        else
-          # parse the body as JSON and run it through the error checker (if provided)
-          # Note: Facebook sometimes sends results like "true" and "false", which aren't strictly objects
-          # and cause MultiJson.load to fail -- so we account for that by wrapping the result in []
-          MultiJson.load("[#{result.body.to_s}]")[0]
-        end
+        result
       end
 
       private
@@ -113,8 +151,9 @@ module Koala
       def preserve_form_arguments?(options)
         options[:format] == :json || options[:preserve_form_arguments] || Koala.config.preserve_form_arguments
       end
+
+      def check_response(http_status, body, headers)
+      end
     end
   end
 end
-
-require 'koala/api/graph_batch_api'

data/lib/koala/configuration.rb

@@ -0,0 +1,56 @@
+# Global configuration for Koala.
+class Koala::Configuration
+  # The default access token to be used if none is otherwise supplied.
+  attr_accessor :access_token
+
+  # The default app secret value to be used if none is otherwise supplied.
+  attr_accessor :app_secret
+
+  # The default application ID to use if none is otherwise supplied.
+  attr_accessor :app_id
+
+  # The default app access token to be used if none is otherwise supplied.
+  attr_accessor :app_access_token
+
+  # The default API version to use if none is otherwise specified.
+  attr_accessor :api_version
+
+  # The default value to use for the oauth_callback_url if no other is provided.
+  attr_accessor :oauth_callback_url
+
+  # Whether to preserve arrays in arguments, which are expected by certain FB APIs (see the ads API
+  # in particular, https://developers.facebook.com/docs/marketing-api/adgroup/v2.4)
+  attr_accessor :preserve_form_arguments
+
+  # The server to use for Graph API requests
+  attr_accessor :graph_server
+
+  # The server to use when constructing dialog URLs.
+  attr_accessor :dialog_host
+
+  # Whether or not to mask tokens
+  attr_accessor :mask_tokens
+
+  # Called with the info for the rate limits in the response header
+  attr_accessor :rate_limit_hook
+
+  # Certain Facebook services (beta, video) require you to access different
+  # servers. If you're using your own servers, for instance, for a proxy,
+  # you can change both the matcher (what value to change when updating the URL) and the
+  # replacement values (what to add).
+  #
+  # So, for instance, to use the beta stack, we match on .facebook and change it to .beta.facebook.
+  # If you're talking to fbproxy.mycompany.com, you could set up beta.fbproxy.mycompany.com for
+  # FB's beta tier, and set the matcher to /\.fbproxy/ and the beta_replace to '.beta.fbproxy'.
+  attr_accessor :host_path_matcher
+  attr_accessor :video_replace
+  attr_accessor :beta_replace
+
+  def initialize
+    # Default to our default values.
+    Koala::HTTPService::DEFAULT_SERVERS.each_pair do |key, value|
+      self.public_send("#{key}=", value)
+    end
+    self.mask_tokens = true
+  end
+end

data/lib/koala/errors.rb

@@ -23,7 +23,10 @@ module Koala
                     :fb_error_user_title,
                     :fb_error_trace_id,
                     :fb_error_debug,
-                    :fb_error_rev
+                    :fb_error_rev,
+                    :fb_buc_usage,
+                    :fb_ada_usage,
+                    :fb_app_usage
 
       # Create a new API Error
       #
@@ -50,7 +53,7 @@ module Koala
         else
           unless error_info
             begin
-              error_info = MultiJson.load(response_body)['error'] if response_body
+              error_info = JSON.parse(response_body)['error'] if response_body
             rescue
             end
             error_info ||= {}
@@ -66,6 +69,9 @@ module Koala
           self.fb_error_trace_id = error_info["x-fb-trace-id"]
           self.fb_error_debug = error_info["x-fb-debug"]
           self.fb_error_rev = error_info["x-fb-rev"]
+          self.fb_buc_usage = json_parse_for(error_info, "x-business-use-case-usage")
+          self.fb_ada_usage = json_parse_for(error_info, "x-ad-account-usage")
+          self.fb_app_usage = json_parse_for(error_info, "x-app-usage")
 
           error_array = []
           %w(type code error_subcode message error_user_title error_user_msg x-fb-trace-id).each do |key|
@@ -82,6 +88,20 @@ module Koala
 
         super(message)
       end
+
+      private
+
+      # refs: https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#headers
+      # NOTE: The header will contain a JSON-formatted string that describes current application rate limit usage.
+      def json_parse_for(error_info, key)
+        string = error_info[key]
+        return if string.nil?
+
+        JSON.parse(string)
+      rescue JSON::ParserError => e
+        Koala::Utils.logger.error("#{e.class}: #{e.message} while parsing #{key} = #{string}")
+        nil
+      end
     end
 
     # Facebook returned an invalid response body