koala 3.0.0.beta1 → 3.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 04714e9f9ae4e70420567406530119f6560518d1
-  data.tar.gz: 92ec819da43149fc5de98f6ec931afc6736c8199
+  metadata.gz: 18d5d8c95bece65d5f4bab2640d75645dc5fb343
+  data.tar.gz: 6ec125b20dea63584e6dd69fc02ecd08f0800ce2
 SHA512:
-  metadata.gz: 51df761c7444da9dfb2c78b1fc30216b6fb3e5463c8e3bda322cae0f01e5e6fde5eecd62fc63f81527d25277972ff8ec00db71ca56aae9322bcfa626484e2470
-  data.tar.gz: f0545dd4651b30877186dd1f9bf3abe921a73a73f778980434536d4ad7923e17085fa64df53f7f449986d4fe5c460e08e6ceba605ddcc4a70de90c1ed21881c7
+  metadata.gz: 31a10322d86c4c49bd877ad5891cde67db496e506c6b8936d8cf3e67b6bc82e6faed1fe1e93f02dcd123ea8aee77026adc681a3b197006335e7d2f8aac40d968
+  data.tar.gz: f8d69365d42baf15acead1fcc5e38e334084dc49539358189aee046bf611d9c7761ec4ffeac690b07d3a647116ef81ac1e0fdfa2bc1d11010c5ae30dc239a189

data/.travis.yml

@@ -3,10 +3,10 @@ sudo: false
 cache: bundler
 rvm:
   # MRI
-  - 2.0
   - 2.1
   - 2.2
   - 2.3.1
+  - 2.4.0
   # Rubinius is failing due to segfaults on Travis (and takes significantly longer to run)
   # those builds will be restored later
   # jruby

data/changelog.md

@@ -1,28 +1,44 @@
 v3.0.0
 ======
 
-Key breaking changes:
+**Key breaking changes:**
 
+* Koala now requires Ruby 2.1+ (or equivalent for JRuby, etc.)
+* API#api now returns a Koala::HTTPService::Response object; graph_call handles further processing
+* GraphBatchAPI no longer inherits from API (the interface is otherwise unchanged)
+* Empty response bodies in batch API calls will raise a JSON::ParserError rather than returning nil
 * HTTPService.make_request now requires an HTTPService::Request object (Koala.make_request does
   not)
 * HTTPService behavior *should not* change, but in edge cases might. (If so, please let me know.)
-* Empty response bodies in batch API calls will raise a JSON parse error rather than returning nil
+* API#search now requires a "type"/:type argument, matching Facebook's behavior (improving their
+  cryptic error message)
+
+Updated features:
+
+* TestUser#befriend will provide the appsecret_proof if a secret is set (thanks, kwasimensah!)
+* API#search now requires an object type parameter to be included, matching Facebook's API (#575)
 
 Removed features:
 
 * Removed support for the Rest API, since Facebook removed support for it (#568)
 * Removed support for FQL, which Facebook removed on August 8, 2016 (#569)
 * Removed legacy duplication of serveral constants in the Koala module (#569)
+* Removed API#get_comments_for_urls, which pointed to a no-longer-extant endpoint(#570)
 
 Internal improvements:
 
 * Completely rewrote HTTPService.make_request and several others, extracting most logic into
   HTTPService::Request (#566)
+* API#api now returns a Koala::HTTPService::Response object (#584)
+* GraphBatchAPI no longer inherits from API (#580)
+* GraphBatchAPI has been refactored to be simpler and more readable (thanks, acuppy!) (#551)
 * Use the more secure JSON.parse instead of JSON.load (thanks, lautis!) (#567)
+* Use JSON's quirks_mode option to remove hacky JSON hack (#573 -- thanks sakuro for the
+  suggestion!)
 
 Testing improvements:
 
-* Fixed a bunch of failing specs
+* Fixed a bunch of failing mocked specs
 
 v2.5.0
 ======

data/koala.gemspec

@@ -21,6 +21,9 @@ Gem::Specification.new do |gem|
   gem.extra_rdoc_files = ["readme.md", "changelog.md"]
   gem.rdoc_options     = ["--line-numbers", "--inline-source", "--title", "Koala"]
 
+  gem.required_ruby_version = '>= 2.1'
+
   gem.add_runtime_dependency("faraday")
   gem.add_runtime_dependency("addressable")
+  gem.add_runtime_dependency("json", ">= 2.0")
 end

data/lib/koala/api.rb

@@ -1,5 +1,5 @@
 # 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/graph_api_methods'
 require 'koala/api/graph_collection'
 require 'openssl'
 
@@ -24,6 +24,45 @@ module Koala
 
       include GraphAPIMethods
 
+      # 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.data, 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.
       #
@@ -42,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
@@ -58,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
@@ -75,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.parse to fail -- so we account for
-          # that by wrapping the result in []
-          JSON.parse("[#{result.body.to_s}]")[0]
-        end
+        result
       end
 
       private
@@ -112,6 +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

data/lib/koala/api/{graph_api.rb → graph_api_methods.rb}

@@ -32,7 +32,6 @@ module Koala
     # for the active user from the cookie provided by Facebook.
     # See the Koala and Facebook documentation for more information.
     module GraphAPIMethods
-
       # Objects
 
       # Get information about a Facebook object.
@@ -107,7 +106,7 @@ module Koala
       # @return true if successful, false (or an APIError) if not
       def delete_object(id, options = {}, &block)
         # Deletes the object with the given ID from the graph.
-        raise AuthenticationError.new(nil, nil, "Delete requires an access token") unless @access_token
+        raise AuthenticationError.new(nil, nil, "Delete requires an access token") unless access_token
         graph_call(id, {}, "delete", options, &block)
       end
 
@@ -157,7 +156,7 @@ module Koala
       # @return a hash containing the new object's id
       def put_connections(id, connection_name, args = {}, options = {}, &block)
         # Posts a certain connection
-        raise AuthenticationError.new(nil, nil, "Write operations require an access token") unless @access_token
+        raise AuthenticationError.new(nil, nil, "Write operations require an access token") unless access_token
 
         graph_call("#{id}/#{connection_name}", args, "post", options, &block)
       end
@@ -175,7 +174,7 @@ module Koala
       # @return (see #delete_object)
       def delete_connections(id, connection_name, args = {}, options = {}, &block)
         # Deletes a given connection
-        raise AuthenticationError.new(nil, nil, "Delete requires an access token") unless @access_token
+        raise AuthenticationError.new(nil, nil, "Delete requires an access token") unless access_token
         graph_call("#{id}/#{connection_name}", args, "delete", options, &block)
       end
 
@@ -336,7 +335,7 @@ module Koala
       # @return (see #delete_object)
       def delete_like(id, options = {}, &block)
         # Unlikes a given object for the logged-in user
-        raise AuthenticationError.new(nil, nil, "Unliking requires an access token") unless @access_token
+        raise AuthenticationError.new(nil, nil, "Unliking requires an access token") unless access_token
         graph_call("#{id}/likes", {}, "delete", options, &block)
       end
 
@@ -344,14 +343,16 @@ module Koala
       # See {http://developers.facebook.com/docs/reference/api/#searching Facebook documentation} for more information.
       #
       # @param search_terms the query to search for
-      # @param args additional arguments, such as type, fields, etc.
+      # @param args object type and any additional arguments, such as fields, etc.
       # @param options (see #get_object)
       # @param block (see Koala::Facebook::API#api)
       #
       # @return [Koala::Facebook::API::GraphCollection] an array of search results
       def search(search_terms, args = {}, options = {}, &block)
-        args.merge!({:q => search_terms}) unless search_terms.nil?
-        graph_call("search", args, "get", options, &block)
+        # Normally we wouldn't enforce Facebook API behavior, but the API fails with cryptic error
+        # messages if you fail to include a type term. For a convenience method, that is valuable.
+        raise ArgumentError, "type must be includedin args when searching" unless args[:type] || args["type"]
+        graph_call("search", args.merge("q" => search_terms), "get", options, &block)
       end
 
       # Convenience Methods
@@ -391,21 +392,6 @@ module Koala
         block ? block.call(access_token_info) : access_token_info
       end
 
-      # Fetches the comments from fb:comments widgets for a given set of URLs (array or comma-separated string).
-      # See https://developers.facebook.com/blog/post/490.
-      #
-      # @param urls the URLs for which you want comments
-      # @param args (see #get_object)
-      # @param options (see #get_object)
-      # @param block (see Koala::Facebook::API#api)
-      #
-      # @returns a hash of urls => comment arrays
-      def get_comments_for_urls(urls = [], args = {}, options = {}, &block)
-        return [] if urls.empty?
-        args.merge!(:ids => urls.respond_to?(:join) ? urls.join(",") : urls)
-        get_object("comments", args, options, &block)
-      end
-
       # App restrictions require you to JSON-encode the restriction value. This
       # is neither obvious nor intuitive, so this convenience method is
       # provided.
@@ -479,44 +465,8 @@ module Koala
         end
       end
 
-      # 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
-        result = api(path, args, verb, options) do |response|
-          error = check_response(response.status, response.body, response.headers)
-          raise error if error
-        end
-
-        # turn this into a GraphCollection if it's pageable
-        result = API::GraphCollection.evaluate(result, self)
-
-        # now process as appropriate for the given call (get picture header, etc.)
-        post_processing ? post_processing.call(result) : result
-      end
-
       private
 
-      def check_response(http_status, body, headers)
-        GraphErrorChecker.new(http_status, body, headers).error_if_appropriate
-      end
-
       def parse_media_args(media_args, method)
         # photo and video uploads can accept different types of arguments (see above)
         # so here, we parse the arguments into a form directly usable in put_connections

data/lib/koala/api/graph_batch_api.rb

@@ -4,13 +4,12 @@ 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
 
       attr_reader :original_api
       def initialize(api)
-        super(api.access_token, api.app_secret)
         @original_api = api
       end
 
@@ -18,7 +17,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,73 +35,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
       def execute(http_options = {})
-        return [] unless batch_calls.length > 0
+        return [] if batch_calls.empty?
+
         # 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)
-        })
+        args = { 'batch' => batch_args }
+        batch_calls.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")
-          end
+        original_api.graph_call('/', args, 'post', http_options, &handle_response)
+      end
+
+      def handle_response
+        lambda do |response|
+          raise bad_response if response.nil?
+          response.map(&generate_results)
+        end
+      end
+
+      def generate_results
+        index = 0
+        lambda do |call_result|
+          batch_op     = batch_calls[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.parse("[#{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 = GraphCollection.evaluate(
+            result_from_response(call_result, batch_op),
+            original_api
+          )
+
+          # 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   = coerced_headers_from_response(response)
+        error     = error_from_response(response, headers)
+        component = options.http_options[:http_component]
+
+        error || result_from_component({
+          :component => component,
+          :response  => response,
+          :headers   => headers
+        })
+      end
+
+      def coerced_headers_from_response(response)
+        headers = response.fetch('headers', [])
+
+        headers.each_with_object({}) do |h, memo|
+          memo.merge! h.fetch('name') => h.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 = batch_calls.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 result_from_component(options)
+        component = options.fetch(:component)
+        response  = options.fetch(:response)
+        headers   = options.fetch(: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 json_body(response)
+        end
+      end
+
+      def access_token
+        original_api.access_token
+      end
+
+      def app_secret
+        original_api.app_secret
+      end
     end
   end
 end