koala 2.5.0 → 3.0.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"] = JSON.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 = JSON.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

@@ -61,7 +61,7 @@ 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
-          JSON.load(body)
+          JSON.parse(body)
         rescue JSON::ParserError
           {}
         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
@@ -15,7 +15,7 @@ module Koala
       #                 https://developers.facebook.com/docs/graph-api/securing-requests/)
       # @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)
         @access_token = access_token
         @app_secret = app_secret
       end
@@ -23,13 +23,50 @@ module Koala
       attr_reader :access_token, :app_secret
 
       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
+
+        # 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 +81,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 +93,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
@@ -77,18 +111,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 are valid[RFC7159]
-          # but unsupported by Ruby's stdlib[RFC4627] and cause JSON.load to fail -- so we account for
-          # that by wrapping the result in []
-          JSON.load("[#{result.body.to_s}]")[0]
-        end
+        result
       end
 
       private
@@ -114,8 +137,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,49 @@
+# 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
+
+  # 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
+  end
+end

data/lib/koala/errors.rb

@@ -50,7 +50,7 @@ module Koala
         else
           unless error_info
             begin
-              error_info = JSON.load(response_body)['error'] if response_body
+              error_info = JSON.parse(response_body)['error'] if response_body
             rescue
             end
             error_info ||= {}

data/lib/koala/http_service/multipart_request.rb

@@ -1,6 +1,6 @@
 require 'faraday'
 
-module Koala  
+module Koala
   module HTTPService
     class MultipartRequest < Faraday::Request::Multipart
       # Facebook expects nested parameters to be passed in a certain way
@@ -8,15 +8,15 @@ module Koala
       # Faraday needs two changes to make that work:
       # 1) [] need to be escaped (e.g. params[foo]=bar ==> params%5Bfoo%5D=bar)
       # 2) such messages need to be multipart-encoded
-    
+
       self.mime_type = 'multipart/form-data'.freeze
-    
+
       def process_request?(env)
         # if the request values contain any hashes or arrays, multipart it
         super || !!(env[:body].respond_to?(:values) && env[:body].values.find {|v| v.is_a?(Hash) || v.is_a?(Array)})
-      end   
-    
-    
+      end
+
+
       def process_params(params, prefix = nil, pieces = nil, &block)
         params.inject(pieces || []) do |all, (key, value)|
           key = "#{prefix}%5B#{key}%5D" if prefix
@@ -34,8 +34,4 @@ module Koala
       end
     end
   end
-  
-  # @private
-  # legacy support for when MultipartRequest lived directly under Koala
-  MultipartRequest = HTTPService::MultipartRequest  
 end

data/lib/koala/http_service/request.rb

@@ -0,0 +1,135 @@
+module Koala
+  module HTTPService
+    class Request
+      attr_reader :raw_path, :raw_args, :raw_verb, :raw_options
+
+      # @param path the server path for this request
+      # @param args (see Koala::Facebook::API#api)
+      # @param verb the HTTP method to use.
+      #             If not get or post, this will be turned into a POST request with the appropriate :method
+      #             specified in the arguments.
+      # @param options various flags to indicate which server to use. (see Koala::Facebook::API#api)
+      # @param options
+      # @option options :video use the server designated for video uploads
+      # @option options :beta use the beta tier
+      # @option options :use_ssl force https, even if not needed
+      # @option options :json whether or not to send JSON to Facebook
+      def initialize(path:, verb:, args: {}, options: {})
+        @raw_path = path
+        @raw_args = args
+        @raw_verb = verb
+        @raw_options = options
+      end
+
+      # Determines which type of request to send to Facebook. Facebook natively accepts GETs and POSTs, for others we have to include the method in the post body.
+      #
+      # @return one of get or post
+      def verb
+        ["get", "post"].include?(raw_verb) ? raw_verb : "post"
+      end
+
+      # Determines the path to be requested on Facebook, incorporating an API version if specified.
+      #
+      # @return the original path, with API version if appropriate.
+      def path
+        # if an api_version is specified and the path does not already contain
+        # one, prepend it to the path
+        api_version = raw_options[:api_version] || Koala.config.api_version
+        if api_version && !path_contains_api_version?
+          begins_with_slash = raw_path[0] == "/"
+          divider = begins_with_slash ? "" : "/"
+          "/#{api_version}#{divider}#{raw_path}"
+        else
+          raw_path
+        end
+      end
+
+      # Determines any arguments to be sent in a POST body.
+      #
+      # @return {} for GET; the provided args for POST; those args with the method parameter for
+      # other values
+      def post_args
+        if raw_verb == "get"
+          {}
+        elsif raw_verb == "post"
+          args
+        else
+          args.merge(method: raw_verb)
+        end
+      end
+
+      def get_args
+        raw_verb == "get" ? args : {}
+      end
+
+      # Calculates a set of request options to pass to Faraday.
+      #
+      # @return a hash combining GET parameters (if appropriate), default options, and
+      # any specified for the request.
+      def options
+        # figure out our options for this request
+        add_ssl_options(
+          # for GETs, we pass the params to Faraday to encode
+          {params: get_args}.merge(HTTPService.http_options).merge(raw_options)
+        )
+      end
+
+      # Whether or not this request should use JSON.
+      #
+      # @return true or false
+      def json?
+        raw_options[:format] == :json
+      end
+
+      # The address of the appropriate Facebook server.
+      #
+      # @return a complete server address with protocol
+      def server
+        uri = "#{options[:use_ssl] ? "https" : "http"}://#{Koala.config.graph_server}"
+        # if we want to use the beta tier or the video server, make those substitutions as
+        # appropriate
+        replace_server_component(
+          replace_server_component(uri, options[:video], Koala.config.video_replace),
+          options[:beta],
+          Koala.config.beta_replace
+        )
+      end
+
+      protected
+
+      # The arguments to include in the request.
+      def args
+        raw_args.inject({}) do |hash, (key, value)|
+          # Resolve UploadableIOs into data Facebook can work with
+          hash.merge(key => value.is_a?(UploadableIO) ? value.to_upload_io : value)
+        end
+      end
+
+      def add_ssl_options(opts)
+        # require https if there's a token
+        return opts unless raw_args["access_token"]
+
+        {
+          use_ssl: true,
+          ssl: {verify: true}.merge(opts[:ssl] || {})
+        }.merge(opts)
+      end
+
+      # Determines whether a given path already contains an API version.
+      #
+      # @param path the URL path.
+      #
+      # @return true or false accordingly.
+      def path_contains_api_version?
+        # looks for "/$MAJOR[.$MINOR]/" in the path
+        match = /^\/?(v\d+(?:\.\d+)?)\//.match(raw_path)
+        !!(match && match[1])
+      end
+
+      def replace_server_component(host, condition_met, replacement)
+        return host unless condition_met
+        host.gsub(Koala.config.host_path_matcher, replacement)
+      end
+    end
+  end
+end

data/lib/koala/http_service/response.rb

@@ -9,10 +9,12 @@ module Koala
         @body = body
         @headers = headers
       end
+
+      def data
+        # quirks_mode is needed because Facebook sometimes returns a raw true or false value --
+        # in Ruby 2.4 we can drop that.
+        @data ||= JSON.parse(body, quirks_mode: true) unless body.empty?
+      end
     end
   end
-  
-  # @private
-  # legacy support for when Response lived directly under Koala
-  Response = HTTPService::Response
 end

data/lib/koala/http_service/uploadable_io.rb

@@ -181,8 +181,4 @@ module Koala
       end
     end
   end
-
-  # @private
-  # legacy support for when UploadableIO lived directly under Koala
-  UploadableIO = HTTPService::UploadableIO
 end