koala 2.4.0 → 3.5.0

data/lib/koala/http_service/request.rb

@@ -0,0 +1,133 @@
+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 by default (can be overriden by explicitly setting other SSL options)
+        {
+          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

@@ -1,4 +1,3 @@
-require "net/http/post/multipart"
 require "tempfile"
 
 module Koala
@@ -181,8 +180,4 @@ module Koala
       end
     end
   end
-
-  # @private
-  # legacy support for when UploadableIO lived directly under Koala
-  UploadableIO = HTTPService::UploadableIO
 end

data/lib/koala/http_service.rb

@@ -1,7 +1,8 @@
 require 'faraday'
-require 'koala/http_service/multipart_request'
+require 'faraday/multipart' unless defined? Faraday::FilePart # hack for faraday < 1.9 to avoid warnings
 require 'koala/http_service/uploadable_io'
 require 'koala/http_service/response'
+require 'koala/http_service/request'
 
 module Koala
   module HTTPService
@@ -18,103 +19,62 @@ module Koala
     # We encode requests in a Facebook-compatible multipart request,
     # and use whichever adapter has been configured for this application.
     DEFAULT_MIDDLEWARE = Proc.new do |builder|
-      builder.use Koala::HTTPService::MultipartRequest
+      builder.request :multipart
       builder.request :url_encoded
       builder.adapter Faraday.default_adapter
     end
 
-    # Default servers for Facebook. These are read into the config OpenStruct,
-    # and can be overridden via Koala.config.
+    # Default server information for Facebook. These can be overridden by setting config values.
+    # See Koala.config.
     DEFAULT_SERVERS = {
       :graph_server => 'graph.facebook.com',
       :dialog_host => 'www.facebook.com',
-      :rest_server => 'api.facebook.com',
-      # 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 and the replacement values.
-      # So for instance, 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'.
       :host_path_matcher => /\.facebook/,
       :video_replace => '-video.facebook',
       :beta_replace => '.beta.facebook'
     }
 
-    # The address of the appropriate Facebook server.
-    #
-    # @param options various flags to indicate which server to use.
-    # @option options :rest_api use the old REST API instead of the Graph API
-    # @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
-    #
-    # @return a complete server address with protocol
-    def self.server(options = {})
-      server = "#{options[:rest_api] ? Koala.config.rest_server : Koala.config.graph_server}"
-      server.gsub!(Koala.config.host_path_matcher, Koala.config.video_replace) if options[:video]
-      server.gsub!(Koala.config.host_path_matcher, Koala.config.beta_replace) if options[:beta]
-      "#{options[:use_ssl] ? "https" : "http"}://#{server}"
-    end
-
     # Makes a request directly to Facebook.
     # @note You'll rarely need to call this method directly.
     #
     # @see Koala::Facebook::API#api
     # @see Koala::Facebook::GraphAPIMethods#graph_call
-    # @see Koala::Facebook::RestAPIMethods#rest_call
     #
-    # @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 (see Koala::Facebook::API#api)
+    # @param request a Koala::HTTPService::Request object
     #
     # @raise an appropriate connection error if unable to make the request to Facebook
     #
     # @return [Koala::HTTPService::Response] a response object representing the results from Facebook
-    def self.make_request(path, args, verb, options = {})
-      # if the verb isn't get or post, send it as a post argument with a method param
-      args.merge!({:method => verb}) && verb = "post" if verb != "get" && verb != "post"
-
-      # turn all the keys to strings (Faraday has issues with symbols under 1.8.7) and resolve UploadableIOs
-      params = args.inject({}) {|hash, kv| hash[kv.first.to_s] = kv.last.is_a?(UploadableIO) ? kv.last.to_upload_io : kv.last; hash}
+    def self.make_request(request)
+      # set up our Faraday connection
+      conn = Faraday.new(request.server, faraday_options(request.options), &(faraday_middleware || DEFAULT_MIDDLEWARE))
 
-      # figure out our options for this request
-      request_options = {:params => (verb == "get" ? params : {})}.merge(http_options || {}).merge(options)
-      request_options[:use_ssl] = true if args["access_token"] # require https if there's a token
-      if request_options[:use_ssl]
-        ssl = (request_options[:ssl] ||= {})
-        ssl[:verify] = true unless ssl.has_key?(:verify)
-      end
+      filtered_args = request.raw_args.dup.transform_keys(&:to_s)
 
-      # if an api_version is specified and the path does not already contain
-      # one, prepend it to the path
-      api_version = request_options[:api_version] || Koala.config.api_version
-      if api_version && !path_contains_api_version?(path)
-        begins_with_slash = path[0] == "/"
-        divider = begins_with_slash ? "" : "/"
-        path = "/#{api_version}#{divider}#{path}"
+      if Koala.config.mask_tokens
+        %w(access_token input_token).each do |arg_token|
+          if (token = filtered_args[arg_token])
+            filtered_args[arg_token] = token[0, 10] + '*****' + token[-5, 5]
+          end
+        end
       end
 
-      # set up our Faraday connection
-      # we have to manually assign params to the URL or the
-      conn = Faraday.new(server(request_options), faraday_options(request_options), &(faraday_middleware || DEFAULT_MIDDLEWARE))
+      Koala::Utils.debug "STARTED => #{request.verb.upcase}: #{request.path} params: #{filtered_args.inspect}"
 
-      # remember, all non-GET requests are turned into POSTs -- see the the start of this method
-      if verb == "post" && options[:format] == :json
+      if request.verb == "post" && request.json?
+        # JSON requires a bit more handling
+        # remember, all non-GET requests are turned into POSTs, so this covers everything but GETs
         response = conn.post do |req|
-          req.path = path
+          req.path = request.path
           req.headers["Content-Type"] = "application/json"
-          req.body = params.to_json
+          req.body = request.post_args.to_json
           req
         end
       else
-        response = conn.send(verb, path, (verb == "post" ? params : {}))
+        response = conn.send(request.verb, request.path, request.post_args)
       end
 
-      # Log URL information
-      Koala::Utils.debug "#{verb.upcase}: #{path} params: #{params.inspect}"
+      Koala::Utils.debug "FINISHED => #{request.verb.upcase}: #{request.path} params: #{filtered_args.inspect}"
       Koala::HTTPService::Response.new(response.status.to_i, response.body, response.headers)
     end
 
@@ -130,21 +90,14 @@ module Koala
     # @return the appropriately-encoded string
     def self.encode_params(param_hash)
       ((param_hash || {}).sort_by{|k, v| k.to_s}.collect do |key_and_value|
-        key_and_value[1] = MultiJson.dump(key_and_value[1]) unless key_and_value[1].is_a? String
-        "#{key_and_value[0].to_s}=#{CGI.escape key_and_value[1]}"
+        value = key_and_value[1]
+        unless value.is_a? String
+          value = value.to_json
+        end
+        "#{key_and_value[0].to_s}=#{CGI.escape value}"
       end).join("&")
     end
 
-    # Determines whether a given path already contains an API version.
-    #
-    # @param path the URL path.
-    #
-    # @return true or false accordingly.
-    def self.path_contains_api_version?(path)
-      match = /^\/?(v\d+(?:\.\d+)?)\//.match(path)
-      !!(match && match[1])
-    end
-
     private
 
     def self.faraday_options(options)

data/lib/koala/oauth.rb

@@ -12,10 +12,10 @@ module Koala
       # @param app_id [String, Integer] a Facebook application ID
       # @param app_secret a Facebook application secret
       # @param oauth_callback_url the URL in your app to which users authenticating with OAuth will be sent
-      def initialize(app_id, app_secret, oauth_callback_url = nil)
-        @app_id = app_id
-        @app_secret = app_secret
-        @oauth_callback_url = oauth_callback_url
+      def initialize(app_id = nil, app_secret = nil, oauth_callback_url = nil)
+        @app_id = app_id || Koala.config.app_id
+        @app_secret = app_secret || Koala.config.app_secret
+        @oauth_callback_url = oauth_callback_url || Koala.config.oauth_callback_url
       end
 
       # Parses the cookie set Facebook's JavaScript SDK.
@@ -134,7 +134,7 @@ module Koala
         if response == ''
           raise BadFacebookResponse.new(200, '', 'generate_client_code received an error: empty response body')
         else
-          result = MultiJson.load(response)
+          result = JSON.parse(response)
         end
 
         result.has_key?('code') ? result['code'] : raise(Koala::KoalaError.new("Facebook returned a valid response without the expected 'code' in the body (response = #{response})"))
@@ -240,7 +240,7 @@ module Koala
         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))
+        envelope = JSON.parse(base64_url_decode(encoded_envelope))
 
         raise OAuthSignatureError, "Unsupported algorithm #{envelope['algorithm']}" if envelope['algorithm'] != 'HMAC-SHA256'
 
@@ -260,8 +260,8 @@ module Koala
       end
 
       def parse_access_token(response_text)
-        MultiJson.load(response_text)
-      rescue MultiJson::LoadError
+        JSON.parse(response_text)
+      rescue JSON::ParserError
         response_text.split("&").inject({}) do |hash, bit|
           key, value = bit.split("=")
           hash.merge!(key => value)

data/lib/koala/realtime_updates.rb

@@ -7,9 +7,6 @@ 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]
-      attr_reader :api
       attr_reader :app_id, :app_access_token, :secret
 
       # Create a new RealtimeUpdates instance.
@@ -23,20 +20,27 @@ module Koala
       #
       # @raise ArgumentError if the application ID and one of the app access token or the secret are not provided.
       def initialize(options = {})
-        @app_id = options[:app_id]
-        @app_access_token = options[:app_access_token]
-        @secret = options[:secret]
+        @app_id = options[:app_id] || Koala.config.app_id
+        @app_access_token = options[:app_access_token] || Koala.config.app_access_token
+        @secret = options[:secret] || Koala.config.app_secret
         unless @app_id && (@app_access_token || @secret) # make sure we have what we need
           raise ArgumentError, "Initialize must receive a hash with :app_id and either :app_access_token or :secret! (received #{options.inspect})"
         end
+      end
 
-        # fetch the access token if we're provided a secret
-        if @secret && !@app_access_token
-          oauth = Koala::Facebook::OAuth.new(@app_id, @secret)
-          @app_access_token = oauth.get_app_access_token
-        end
+      # The app access token, either provided on initialization or fetched from Facebook using the
+      # app_id and secret.
+      def app_access_token
+        # If a token isn't provided but we need it, fetch it
+        @app_access_token ||= Koala::Facebook::OAuth.new(@app_id, @secret).get_app_access_token
+      end
 
-        @api = API.new(@app_access_token)
+      # The application API interface used to communicate with Facebook.
+      # @return [Koala::Facebook::API]
+      def api
+        # Only instantiate the API if needed. validate_update doesn't require it, so we shouldn't
+        # make an unnecessary request to get the app_access_token.
+        @api ||= API.new(app_access_token)
       end
 
       # Subscribe to realtime updates for certain fields on a given object (user, page, etc.).
@@ -60,7 +64,7 @@ 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)
+        api.graph_call(subscription_path, args, 'post', options)
       end
 
       # Unsubscribe from updates for a particular object or from updates.
@@ -71,7 +75,7 @@ module Koala
       #
       # @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)
+        api.graph_call(subscription_path, object ? {:object => object} : {}, "delete", options)
       end
 
       # List all active subscriptions for this application.
@@ -80,7 +84,7 @@ module Koala
       #
       # @return [Array] a list of active subscriptions
       def list_subscriptions(options = {})
-        @api.graph_call(subscription_path, {}, "get", options)
+        api.graph_call(subscription_path, {}, "get", options)
       end
 
       # As a security measure (to prevent DDoS attacks), Facebook sends a verification request to your server
@@ -129,12 +133,13 @@ module Koala
           raise AppSecretNotDefinedError, "You must init RealtimeUpdates with your app secret in order to validate updates"
         end
 
-        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
+        request_signature = headers['X-Hub-Signature'] || headers['HTTP_X_HUB_SIGNATURE']
+        return unless request_signature
+
+        signature_parts = request_signature.split("sha1=")
+        request_signature = signature_parts[1]
+        calculated_signature = OpenSSL::HMAC.hexdigest('sha1', @secret, body)
+        calculated_signature == request_signature
       end
 
       # The Facebook subscription management URL for your application.

data/lib/koala/test_users.rb

@@ -14,7 +14,6 @@ module Koala
     #
     # See http://developers.facebook.com/docs/test_users/.
     class TestUsers
-
       # The application API interface used to communicate with Facebook.
       # @return [Koala::Facebook::API]
       attr_reader :api
@@ -31,9 +30,10 @@ module Koala
       #
       # @raise ArgumentError if the application ID and one of the app access token or the secret are not provided.
       def initialize(options = {})
-        @app_id = options[:app_id]
-        @app_access_token = options[:app_access_token]
-        @secret = options[:secret]
+        @app_id = options[:app_id] || Koala.config.app_id
+        @app_access_token = options[:app_access_token] || Koala.config.app_access_token
+        @secret = options[:secret] || Koala.config.app_secret
+
         unless @app_id && (@app_access_token || @secret) # make sure we have what we need
           raise ArgumentError, "Initialize must receive a hash with :app_id and either :app_access_token or :secret! (received #{options.inspect})"
         end
@@ -146,11 +146,12 @@ module Koala
           raise ArgumentError, "TestUsers#befriend requires hash arguments for both users with id and access_token"
         end
 
-        u1_graph_api = API.new(user1_token)
-        u2_graph_api = API.new(user2_token)
+        u1_graph_api = API.new(user1_token, secret)
+        u2_graph_api = API.new(user2_token, secret)
 
-        u1_graph_api.graph_call("#{user1_id}/friends/#{user2_id}", {}, "post", options) &&
-          u2_graph_api.graph_call("#{user2_id}/friends/#{user1_id}", {}, "post", options)
+        # if we have a secret token, flag that we want the appsecret_proof to be generated
+        u1_graph_api.graph_call("#{user1_id}/friends/#{user2_id}", {}, "post", options.merge(appsecret_proof: !!secret)) &&
+          u2_graph_api.graph_call("#{user2_id}/friends/#{user1_id}", {}, "post", options.merge(appsecret_proof: !!secret))
       end
 
       # Create a network of test users, all of whom are friends and have the same permissions.

data/lib/koala/version.rb

@@ -1,3 +1,3 @@
 module Koala
-  VERSION = "2.4.0"
+  VERSION = "3.5.0"
 end

data/lib/koala.rb

@@ -1,10 +1,11 @@
 # useful tools
 require 'digest/md5'
-require 'multi_json'
+require 'json'
 
 # include koala modules
 require 'koala/errors'
 require 'koala/api'
+require 'koala/api/graph_batch_api'
 require 'koala/oauth'
 require 'koala/realtime_updates'
 require 'koala/test_users'
@@ -13,6 +14,7 @@ require 'koala/test_users'
 require 'koala/http_service'
 
 # miscellaneous
+require 'koala/configuration'
 require 'koala/utils'
 require 'koala/version'
 require 'ostruct'
@@ -36,14 +38,10 @@ module Koala
     end
 
     # Allows you to control various Koala configuration options.
-    # Notable options:
-    #   * server endpoints: you can override any or all the server endpoints
-    #   (see HTTPService::DEFAULT_SERVERS) if you want to run requests through
-    #   other servers.
-    #   * api_version: controls which Facebook API version to use (v1.0, v2.0,
-    #   etc)
+    # NOTE: this is not currently threadsafe.
+    # See Koala::Configuration.
     def config
-      @config ||= OpenStruct.new(HTTPService::DEFAULT_SERVERS)
+      @config ||= Configuration.new
     end
 
     # Used for testing.
@@ -61,7 +59,7 @@ module Koala
 
   # An convenenient alias to Koala.http_service.make_request.
   def self.make_request(path, args, verb, options = {})
-    http_service.make_request(path, args, verb, options)
+    http_service.make_request(HTTPService::Request.new(path: path, args: args, verb: verb, options: options))
   end
 
   # we use Faraday as our main service, with mock as the other main one