koala 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3209d60dbf8ab51fac40f7b990f221076bb453329641194dce55b800d0611856
-  data.tar.gz: 9dfb75f13c1b1e187c325453793b6dfcdc085a0f42e119d40df7a30d7b492250
+  metadata.gz: 9f879bff1a0797804e8a89a2d8d34366ba21fafedd5317b4649326169dc9b7ed
+  data.tar.gz: 8f77e5f1d2f3eebcf5e08983ba4f2af69b64566d7d2d4dac6185a8b5c3222ba6
 SHA512:
-  metadata.gz: 2aa7c4c61594d111e5654788712a56eea9005e4e3f6ce133536de6d2089f6014a6a0f5a059012b3bccf2204862b6c28212b517a4a264ea4b2cc272530d11cb4f
-  data.tar.gz: 318d505d832d0d2e70cd9df39040254c1eea64bdf3c743cf29c6311e8fe2cd68159f3237a27a6a066136b5d3306029771fae2935fc4c768860a2c12525f29137
+  metadata.gz: 704dee302c62d906fd9f065abc86ea0e9268a4b160460ccfb455f8a7dbd3d41631bacf75e155953e5fd9d54e01fa81abc39f7730db4ea1023893b80dd378aa22
+  data.tar.gz: 38c9e731f1a76e3d441c3e783032a8f306168723e1552e00167dcd0bd5ad696833afffd2797ff4f4e0ed97e986578f08533b58f5064fa0610819fb409d10ddd3

data/Gemfile

@@ -13,7 +13,7 @@ group :development, :test do
 end
 
 group :test do
-  gem "rspec", '~> 3.4'
+  gem "rspec", "~> 3.0", "< 3.10" # resrict rspec version until https://github.com/rspec/rspec-support/pull/537 gets merged
   gem "vcr", github: 'vcr/vcr', ref: '8ced6c96e01737a418cd270e0382a8c2c6d85f7f' # needs https://github.com/vcr/vcr/pull/907 for ruby 3.1
   gem "webmock"
   gem "simplecov"

data/changelog.md

@@ -15,7 +15,19 @@ Testing improvements:
 
 Others:
 
-v3.1.0 (2022-18-01)
+v3.2.0 (2022-05-27)
+======
+
+New features:
+
+  * Exposes limiting headers(`x-business-use-case-usage, x-ad-account-usage, x-app-usage`) to APIError ([#668](https://github.com/arsduo/koala/pull/668))
+  * Add `rate_limit_hook` configuration to get rate limiting headers (`x-business-use-case-usage, x-ad-account-usage, x-app-usage`) ([#670](https://github.com/arsduo/koala/pull/670))
+
+Testing improvements:
+
+* Fix builds for ruby 3.x
+
+v3.1.0 (2022-01-18)
 ======
 
 New features:

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

data/lib/koala/api.rb

@@ -13,14 +13,16 @@ 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 = Koala.config.access_token, app_secret = Koala.config.app_secret)
+      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
 
@@ -58,6 +60,18 @@ module Koala
           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

data/lib/koala/configuration.rb

@@ -31,6 +31,9 @@ class Koala::Configuration
   # 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

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
       #
@@ -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

data/lib/koala/version.rb

@@ -1,3 +1,3 @@
 module Koala
-  VERSION = "3.1.0"
+  VERSION = "3.2.0"
 end

data/readme.md

@@ -177,6 +177,37 @@ Koala::Facebook::RealtimeUpdates.meet_challenge(params, your_verify_token)
 ```
 For more information about meet_challenge and the RealtimeUpdates class, check out the Real-Time Updates page on the wiki.
 
+Rate limits
+-----------
+
+We support Facebook rate limit informations as defined here: [https://developers.facebook.com/docs/graph-api/overview/rate-limiting/](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/)
+
+The information is available either via the `Facebook::APIError`:
+
+```ruby
+error.fb_buc_usage
+error.fb_ada_usage
+error.fb_app_usage
+```
+
+Or with the rate_limit_hook:
+
+```ruby
+# App level configuration
+
+Koala.configure do |config|
+  config.rate_limit_hook = ->(limits) { 
+    limits["x-app-usage"] # {"call_count"=>0, "total_cputime"=>0, "total_time"=>0}
+    limits["x-ad-account-usage"] # {"acc_id_util_pct"=>9.67}
+    limits["x-business-use-case-usage"] # {"123456789012345"=>[{"type"=>"messenger", "call_count"=>1, "total_cputime"=>1, "total_time"=>1, "estimated_time_to_regain_access"=>0}]}
+  }
+end
+
+# Per API configuration
+
+Koala::Facebook::API.new('', '', ->(limits) {})
+```
+
 Test Users
 ----------
 

data/spec/cases/api_spec.rb

@@ -282,4 +282,81 @@ describe "Koala::Facebook::API" do
       expect(@service.graph_call('anything')).to be_falsey
     end
   end
+
+  describe "Rate limit hook" do
+    it "is called when x-business-use-case-usage header is present" do
+      api = Koala::Facebook::API.new('', '', ->(limits) {
+        expect(limits["x-business-use-case-usage"]).to eq({"123456789012345"=>[{"type"=>"messenger", "call_count"=>1, "total_cputime"=>1, "total_time"=>1, "estimated_time_to_regain_access"=>0}]})
+      })
+
+      result = {"a" => 2}
+      response = Koala::HTTPService::Response.new(200, result.to_json, { "x-business-use-case-usage" => "{\"123456789012345\":[{\"type\":\"messenger\",\"call_count\":1,\"total_cputime\":1,\"total_time\":1,\"estimated_time_to_regain_access\":0}]}" })
+      allow(Koala).to receive(:make_request).and_return(response)
+
+      api.graph_call('anything')
+    end
+
+    it "is called when x-ad-account-usage header is present" do
+      api = Koala::Facebook::API.new('', '', ->(limits) {
+        expect(limits["x-ad-account-usage"]).to eq({"acc_id_util_pct"=>9.67})
+      })
+
+      result = {"a" => 2}
+      response = Koala::HTTPService::Response.new(200, result.to_json, { "x-ad-account-usage" => "{\"acc_id_util_pct\":9.67}" })
+      allow(Koala).to receive(:make_request).and_return(response)
+
+      api.graph_call('anything')
+    end
+
+    it "is called when x-app-usage header is present" do
+      api = Koala::Facebook::API.new('', '', ->(limits) {
+        expect(limits["x-app-usage"]).to eq({"call_count"=>0, "total_cputime"=>0, "total_time"=>0})
+      })
+
+      result = {"a" => 2}
+      response = Koala::HTTPService::Response.new(200, result.to_json, { "x-app-usage" => "{\"call_count\":0,\"total_cputime\":0,\"total_time\":0}" })
+      allow(Koala).to receive(:make_request).and_return(response)
+
+      api.graph_call('anything')
+    end
+
+    it "isn't called if none of the rate limit header is present" do
+      rate_limit_hook_called = false
+
+      api = Koala::Facebook::API.new('', '', ->(limits) {
+        rate_limit_hook_called = true
+      })
+
+      result = {"a" => 2}
+      response = Koala::HTTPService::Response.new(200, result.to_json, {})
+      allow(Koala).to receive(:make_request).and_return(response)
+
+      api.graph_call('anything')
+
+      expect(rate_limit_hook_called).to be(false)
+    end
+
+    it "isn't called if no rate limit hook is defined" do
+      api = Koala::Facebook::API.new('', '', ->(limits) {
+        #noop
+      })
+
+      result = {"a" => 2}
+      response = Koala::HTTPService::Response.new(200, result.to_json, { "x-ad-account-usage" => "{\"acc_id_util_pct\"9.67}"})
+      allow(Koala).to receive(:make_request).and_return(response)
+
+      expect(Koala::Utils.logger).to receive(:error).with("JSON::ParserError: 859: unexpected token at '{\"acc_id_util_pct\"9.67}' while parsing x-ad-account-usage = {\"acc_id_util_pct\"9.67}")
+      api.graph_call('anything')
+    end
+
+    it "logs an error if the rate limit header can't be properly parsed" do
+      api = Koala::Facebook::API.new('', '', nil)
+
+      result = {"a" => 2}
+      response = Koala::HTTPService::Response.new(200, result.to_json, {})
+      allow(Koala).to receive(:make_request).and_return(response)
+
+      api.graph_call('anything')
+    end
+  end
 end

data/spec/cases/error_spec.rb

@@ -1,5 +1,9 @@
 require 'spec_helper'
 
+BUC_USAGE_JSON = "{\"123456789012345\":[{\"type\":\"messenger\",\"call_count\":1,\"total_cputime\":1,\"total_time\":1,\"estimated_time_to_regain_access\":0}]}"
+ADA_USAGE_JSON = "{\"acc_id_util_pct\":9.67}"
+APP_USAGE_JSON = "{\"call_count\":0,\"total_cputime\":0,\"total_time\":0}"
+
 describe Koala::Facebook::APIError do
   it "is a Koala::KoalaError" do
     expect(Koala::Facebook::APIError.new(nil, nil)).to be_a(Koala::KoalaError)
@@ -32,7 +36,10 @@ describe Koala::Facebook::APIError do
         'error_user_title' => 'error user title',
         'x-fb-trace-id' => 'fb trace id',
         'x-fb-debug' => 'fb debug token',
-        'x-fb-rev' => 'fb revision'
+        'x-fb-rev' => 'fb revision',
+        'x-business-use-case-usage' => BUC_USAGE_JSON,
+        'x-ad-account-usage' => ADA_USAGE_JSON,
+        'x-app-usage' => APP_USAGE_JSON
       }
       Koala::Facebook::APIError.new(400, '', error_info)
     }
@@ -46,7 +53,10 @@ describe Koala::Facebook::APIError do
       :fb_error_user_title => 'error user title',
       :fb_error_trace_id => 'fb trace id',
       :fb_error_debug => 'fb debug token',
-      :fb_error_rev => 'fb revision'
+      :fb_error_rev => 'fb revision',
+      :fb_buc_usage => JSON.parse(BUC_USAGE_JSON),
+      :fb_ada_usage => JSON.parse(ADA_USAGE_JSON),
+      :fb_app_usage => JSON.parse(APP_USAGE_JSON)
     }.each_pair do |accessor, value|
       it "sets #{accessor} to #{value}" do
         expect(error.send(accessor)).to eq(value)
@@ -76,7 +86,10 @@ describe Koala::Facebook::APIError do
         :fb_error_code => 1,
         :fb_error_subcode => 'subcode',
         :fb_error_user_msg => 'error user message',
-        :fb_error_user_title => 'error user title'
+        :fb_error_user_title => 'error user title',
+        :fb_buc_usage => nil,
+        :fb_ada_usage => nil,
+        :fb_app_usage => nil
       }.each_pair do |accessor, value|
         expect(error.send(accessor)).to eq(value)
       end

data/spec/cases/graph_api_batch_spec.rb

@@ -593,7 +593,7 @@ describe "Koala::Facebook::GraphAPI in batch mode" do
           hash_including(@other_access_token_args.dup),
           anything,
           anything
-      ).and_return(Koala::HTTPService::Response.new(200, "", ""))
+      ).and_return(Koala::HTTPService::Response.new(200, "", {}))
 
       # Page the collection
       app_event_types.next_page

data/spec/cases/graph_error_checker_spec.rb

@@ -11,7 +11,10 @@ module Koala
         expect(GraphErrorChecker::DEBUG_HEADERS).to match_array([
           "x-fb-rev",
           "x-fb-debug",
-          "x-fb-trace-id"
+          "x-fb-trace-id",
+          "x-business-use-case-usage",
+          "x-ad-account-usage",
+          "x-app-usage"
         ])
       end
 
@@ -84,10 +87,25 @@ module Koala
               "x-fb-debug" => double("fb debug"),
               "x-fb-rev" => double("fb rev"),
               "x-fb-trace-id" => double("fb trace id"),
+              "x-business-use-case-usage" => { 'a' => 1, 'b' => 2 }.to_json,
+              "x-ad-account-usage" => { 'c' => 3, 'd' => 4 }.to_json,
+              "x-app-usage" => { 'e' => 5, 'f' => 6 }.to_json
             )
             expect(error.fb_error_trace_id).to eq(headers["x-fb-trace-id"])
             expect(error.fb_error_debug).to eq(headers["x-fb-debug"])
             expect(error.fb_error_rev).to eq(headers["x-fb-rev"])
+            expect(error.fb_buc_usage).to eq({ 'a' => 1, 'b' => 2 })
+            expect(error.fb_ada_usage).to eq({ 'c' => 3, 'd' => 4 })
+            expect(error.fb_app_usage).to eq({ 'e' => 5, 'f' => 6 })
+          end
+
+          it "logs if one of the FB debug headers can't be parsed" do
+            headers.merge!(
+              "x-app-usage" => '{invalid:json}'
+            )
+
+            expect(Koala::Utils.logger).to receive(:error).with("JSON::ParserError: 859: unexpected token at '{invalid:json}' while parsing x-app-usage = {invalid:json}")
+            expect(error.fb_app_usage).to eq(nil)
           end
 
           context "it returns an AuthenticationError" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: koala
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.2.0
 platform: ruby
 authors:
 - Alex Koppel
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-18 00:00:00.000000000 Z
+date: 2022-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday