koala 1.2.0 → 1.3.0

data/lib/koala/{rest_api.rb → api/rest_api.rb}

@@ -2,22 +2,47 @@ module Koala
   module Facebook
     REST_SERVER = "api.facebook.com"
 
+    # Methods used to interact with Facebook's legacy REST API.  
+    # Where possible, you should use the newer, faster Graph API to interact with Facebook;
+    # in the future, the REST API will be deprecated.
+    # For now, though, there are a few methods that can't be done through the Graph API.
+    #
+    # When using the REST API, Koala will use Facebook's faster read-only servers 
+    # whenever the call allows.  
+    #
+    # See https://github.com/arsduo/koala/wiki/REST-API for a general introduction to Koala
+    # and the Rest API.
     module RestAPIMethods
-      def fql_query(fql, args = {}, options = {})
-        rest_call('fql.query', args.merge(:query => fql), options)
+      # Set a Facebook application's properties.
+      # 
+      # @param properties a hash of properties you want to update with their new values.
+      # @param (see #rest_call)
+      # @param options (see #rest_call)
+      #
+      # @return true if successful, false if not.  (This call currently doesn't give useful feedback on failure.)
+      def set_app_properties(properties, args = {}, options = {})
+        raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "setAppProperties requires an access token"}) unless @access_token
+        rest_call("admin.setAppProperties", args.merge(:properties => MultiJson.encode(properties)), options, "post")
       end
 
-      def fql_multiquery(queries = {}, args = {}, options = {})
-        if results = rest_call('fql.multiquery', args.merge(:queries => MultiJson.encode(queries)), options)
-          # simplify the multiquery result format
-          results.inject({}) {|outcome, data| outcome[data["name"]] = data["fql_result_set"]; outcome}
-        end
-      end
+      # Make a call to the REST API. 
+      #
+      # @note The order of the last two arguments is non-standard (for historical reasons).  Sorry.
+      # 
+      # @param fb_method the API call you want to make
+      # @param args (see Koala::Facebook::GraphAPIMethods#graph_call)
+      # @param options (see Koala::Facebook::GraphAPIMethods#graph_call)
+      # @param verb (see Koala::Facebook::GraphAPIMethods#graph_call)
+      # 
+      # @raise [Koala::Facebook::APIError] if Facebook returns an error
+      # 
+      # @return the result from Facebook
+      def rest_call(fb_method, args = {}, options = {}, verb = "get")
+        Koala::Utils.deprecate("The REST API is now deprecated; please use the equivalent Graph API methods instead.  See http://developers.facebook.com/blog/post/616/.")
 
-      def rest_call(fb_method, args = {}, options = {}, method = "get")
         options = options.merge!(:rest_api => true, :read_only => READ_ONLY_METHODS.include?(fb_method.to_s))
 
-        api("method/#{fb_method}", args.merge('format' => 'json'), method, options) do |response|
+        api("method/#{fb_method}", args.merge('format' => 'json'), verb, options) do |response|
           # check for REST API-specific errors
           if response.is_a?(Hash) && response["error_code"]
             raise APIError.new("type" => response["error_code"], "message" => response["error_msg"])
@@ -25,6 +50,7 @@ module Koala
         end
       end
 
+      # @private
       # read-only methods for which we can use API-read
       # taken directly from the FB PHP library (https://github.com/facebook/php-sdk/blob/master/src/facebook.php)
       READ_ONLY_METHODS = [

data/lib/koala/api.rb

@@ -0,0 +1,93 @@
+# 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'
+
+module Koala
+  module Facebook
+    class API
+      # Creates a new API client.
+      # @param [String] access_token access token
+      # @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)
+        @access_token = access_token
+      end
+      
+      attr_reader :access_token
+
+      include GraphAPIMethods
+      include RestAPIMethods
+      
+      # 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
+      # @param verb the HTTP method to use
+      # @param options request-related options for Koala and Faraday. 
+      #                See https://github.com/arsduo/koala/wiki/HTTP-Services for additional options.
+      # @option options [Symbol] :http_component which part of the response (headers, body, or status) to return
+      # @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 body for evaluation
+      #
+      # @raise [Koala::Facebook::APIError] 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)
+        # Fetches the given path in the Graph API.
+        args["access_token"] = @access_token || @app_access_token if @access_token || @app_access_token
+
+        # add a leading /
+        path = "/#{path}" unless path =~ /^\//
+
+        # make the request via the provided service
+        result = Koala.make_request(path, args, verb, options)
+
+        # Check for any 500 errors before parsing the body
+        # since we're not guaranteed that the body is valid JSON
+        # in the case of a server error
+        raise APIError.new({"type" => "HTTP #{result.status.to_s}", "message" => "Response body: #{result.body}"}) if result.status >= 500
+
+        # 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.decode to fail -- so we account for that by wrapping the result in []
+        body = MultiJson.decode("[#{result.body.to_s}]")[0]
+        yield body 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
+          body
+        end
+      end
+    end
+    
+    class APIError < StandardError
+      attr_accessor :fb_error_type, :raw_response
+
+      # Creates a new APIError. 
+      #
+      # Assigns the error type (as reported by Facebook) to #fb_error_type
+      # and the raw error response available to #raw_response.
+      #
+      # @param details error details containing "type" and "message" keys.
+      def initialize(details = {})
+        self.raw_response = details
+        self.fb_error_type = details["type"]
+        super("#{fb_error_type}: #{details["message"]}")
+      end
+    end
+  end
+end
+
+require 'koala/api/graph_batch_api'
+# legacy support for old pre-1.2 API interfaces
+require 'koala/api/legacy'

data/lib/koala/http_service/multipart_request.rb

@@ -0,0 +1,41 @@
+require 'faraday'
+
+module Koala  
+  module HTTPService
+    class MultipartRequest < Faraday::Request::Multipart
+      # Facebook expects nested parameters to be passed in a certain way
+      # Based on our testing (https://github.com/arsduo/koala/issues/125),
+      # 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   
+    
+    
+      def process_params(params, prefix = nil, pieces = nil, &block)
+        params.inject(pieces || []) do |all, (key, value)|
+          key = "#{prefix}%5B#{key}%5D" if prefix
+
+          case value
+          when Array
+            values = value.inject([]) { |a,v| a << [nil, v] }
+            process_params(values, key, all, &block)
+          when Hash
+            process_params(value, key, all, &block)
+          else
+            all << block.call(key, value)
+          end
+        end
+      end
+    end
+  end
+  
+  # @private
+  # legacy support for when MultipartRequest lived directly under Koala
+  MultipartRequest = HTTPService::MultipartRequest  
+end

data/lib/koala/http_service/response.rb

@@ -0,0 +1,18 @@
+module Koala
+  module HTTPService
+    class Response
+      attr_reader :status, :body, :headers
+
+      # Creates a new Response object, which standardizes the response received by Facebook for use within Koala.
+      def initialize(status, body, headers)
+        @status = status
+        @body = body
+        @headers = headers
+      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

@@ -0,0 +1,187 @@
+require "net/http/post/multipart"
+
+module Koala
+  module HTTPService
+    class UploadableIO
+      attr_reader :io_or_path, :content_type, :filename
+
+      def initialize(io_or_path_or_mixed, content_type = nil, filename = nil)
+        # see if we got the right inputs
+        parse_init_mixed_param io_or_path_or_mixed, content_type
+
+        # filename is used in the Ads API
+        # if it's provided, take precedence over the detected filename
+        # otherwise, fall back to a dummy name
+        @filename = filename || @filename || "koala-io-file.dum"
+
+        raise KoalaError.new("Invalid arguments to initialize an UploadableIO") unless @io_or_path
+        raise KoalaError.new("Unable to determine MIME type for UploadableIO") if !@content_type
+      end
+
+      def to_upload_io
+        UploadIO.new(@io_or_path, @content_type, @filename)
+      end
+
+      def to_file
+        @io_or_path.is_a?(String) ? File.open(@io_or_path) : @io_or_path
+      end
+
+      def self.binary_content?(content)
+        content.is_a?(UploadableIO) || DETECTION_STRATEGIES.detect {|method| send(method, content)}
+      end
+
+      private
+      DETECTION_STRATEGIES = [
+        :sinatra_param?,
+        :rails_3_param?,
+        :file_param?
+      ]
+
+      PARSE_STRATEGIES = [
+        :parse_rails_3_param,
+        :parse_sinatra_param,
+        :parse_file_object,
+        :parse_string_path,
+        :parse_io
+      ]
+
+      def parse_init_mixed_param(mixed, content_type = nil)
+        PARSE_STRATEGIES.each do |method|
+          send(method, mixed, content_type)
+          return if @io_or_path && @content_type
+        end
+      end
+
+      # Expects a parameter of type ActionDispatch::Http::UploadedFile
+      def self.rails_3_param?(uploaded_file)
+        uploaded_file.respond_to?(:content_type) and uploaded_file.respond_to?(:tempfile) and uploaded_file.tempfile.respond_to?(:path)
+      end
+
+      def parse_rails_3_param(uploaded_file, content_type = nil)
+        if UploadableIO.rails_3_param?(uploaded_file)
+          @io_or_path = uploaded_file.tempfile.path
+          @content_type = content_type || uploaded_file.content_type
+          @filename = uploaded_file.original_filename
+        end
+      end
+
+      # Expects a Sinatra hash of file info
+      def self.sinatra_param?(file_hash)
+        file_hash.kind_of?(Hash) and file_hash.has_key?(:type) and file_hash.has_key?(:tempfile)
+      end
+
+      def parse_sinatra_param(file_hash, content_type = nil)
+        if UploadableIO.sinatra_param?(file_hash)
+          @io_or_path = file_hash[:tempfile]
+          @content_type = content_type || file_hash[:type] || detect_mime_type(tempfile)
+          @filename = file_hash[:filename]
+        end
+      end
+
+      # takes a file object
+      def self.file_param?(file)
+        file.kind_of?(File)
+      end
+
+      def parse_file_object(file, content_type = nil)
+        if UploadableIO.file_param?(file)
+          @io_or_path = file
+          @content_type = content_type || detect_mime_type(file.path)
+          @filename = File.basename(file.path)
+        end
+      end
+
+      def parse_string_path(path, content_type = nil)
+        if path.kind_of?(String)
+          @io_or_path = path
+          @content_type = content_type || detect_mime_type(path)
+          @filename = File.basename(path)
+        end
+      end
+
+      def parse_io(io, content_type = nil)
+        if io.respond_to?(:read)
+          @io_or_path = io
+          @content_type = content_type
+        end
+      end
+
+      MIME_TYPE_STRATEGIES = [
+        :use_mime_module,
+        :use_simple_detection
+      ]
+
+      def detect_mime_type(filename)
+        if filename
+          MIME_TYPE_STRATEGIES.each do |method|
+            result = send(method, filename)
+            return result if result
+          end
+        end
+        nil # if we can't find anything
+      end
+
+      def use_mime_module(filename)
+        # if the user has installed mime/types, we can use that
+        # if not, rescue and return nil
+        begin
+          type = MIME::Types.type_for(filename).first
+          type ? type.to_s : nil
+        rescue
+          nil
+        end
+      end
+
+      def use_simple_detection(filename)
+        # very rudimentary extension analysis for images
+        # first, get the downcased extension, or an empty string if it doesn't exist
+        extension = ((filename.match(/\.([a-zA-Z0-9]+)$/) || [])[1] || "").downcase
+        case extension
+          when ""
+            nil
+          # images
+          when "jpg", "jpeg"
+            "image/jpeg"
+          when "png"
+            "image/png"
+          when "gif"
+            "image/gif"
+
+          # video
+          when "3g2"
+          	"video/3gpp2"
+          when "3gp", "3gpp"
+          	"video/3gpp"
+          when "asf"
+          	"video/x-ms-asf"
+          when "avi"
+          	"video/x-msvideo"
+          when "flv"
+          	"video/x-flv"
+          when "m4v"
+          	"video/x-m4v"
+          when "mkv"
+          	"video/x-matroska"
+          when "mod"
+          	"video/mod"
+          when "mov", "qt"
+          	"video/quicktime"
+          when "mp4", "mpeg4"
+          	"video/mp4"
+          when "mpe", "mpeg", "mpg", "tod", "vob"
+          	"video/mpeg"
+          when "nsv"
+          	"application/x-winamp"
+          when "ogm", "ogv"
+          	"video/ogg"
+          when "wmv"
+          	"video/x-ms-wmv"
+        end
+      end
+    end
+  end
+  
+  # @private
+  # legacy support for when UploadableIO lived directly under Koala
+  UploadableIO = HTTPService::UploadableIO
+end

data/lib/koala/http_service.rb

@@ -1,36 +1,61 @@
 require 'faraday'
+require 'koala/http_service/multipart_request'
+require 'koala/http_service/uploadable_io'
+require 'koala/http_service/response'
 
 module Koala
-  class Response
-    attr_reader :status, :body, :headers
-    def initialize(status, body, headers)
-      @status = status
-      @body = body
-      @headers = headers
-    end
-  end
-
-  module HTTPService
-    # common functionality for all HTTP services
-
+  module HTTPService    
     class << self
-      attr_accessor :faraday_middleware, :http_options
+      # A customized stack of Faraday middleware that will be used to make each request.
+      attr_accessor :faraday_middleware
+      # A default set of HTTP options (see https://github.com/arsduo/koala/wiki/HTTP-Services)
+      attr_accessor :http_options
     end
 
     @http_options ||= {}
     
+    # Koala's default middleware stack. 
+    # 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.request :multipart
+      builder.use Koala::HTTPService::MultipartRequest
       builder.request :url_encoded
       builder.adapter Faraday.default_adapter
     end
 
+    # 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] ? Facebook::REST_SERVER : Facebook::GRAPH_SERVER}"
       server.gsub!(/\.facebook/, "-video.facebook") if options[:video]
-      "#{options[:use_ssl] ? "https" : "http"}://#{options[:beta] ? "beta." : ""}#{server}"
-    end
-
+      server.gsub!(/\.facebook/, ".beta.facebook") 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)
+    #
+    # @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
       args.merge!({:method => verb}) && verb = "post" if verb != "get" && verb != "post"
@@ -47,13 +72,20 @@ module Koala
       conn = Faraday.new(server(request_options), request_options, &(faraday_middleware || DEFAULT_MIDDLEWARE))
 
       response = conn.send(verb, path, (verb == "post" ? params : {}))
-      Koala::Response.new(response.status.to_i, response.body, response.headers)
-    end
-
+      Koala::HTTPService::Response.new(response.status.to_i, response.body, response.headers)
+    end
+
+    # Encodes a given hash into a query string.  
+    # This is used mainly by the Batch API nowadays, since Faraday handles this for regular cases.
+    # 
+    # @param params_hash a hash of values to CGI-encode and appropriately join
+    # 
+    # @example
+    #   Koala.http_service.encode_params({:a => 2, :b => "My String"})
+    #   => "a=2&b=My+String"
+    #
+    # @return the appropriately-encoded string
     def self.encode_params(param_hash)
-      # unfortunately, we can't use to_query because that's Rails, not Ruby
-      # if no hash (e.g. no auth token) return empty string
-      # this is used mainly by the Batch API nowadays
       ((param_hash || {}).collect do |key_and_value|
         key_and_value[1] = MultiJson.encode(key_and_value[1]) unless key_and_value[1].is_a? String
         "#{key_and_value[0].to_s}=#{CGI.escape key_and_value[1]}"
@@ -63,76 +95,92 @@ module Koala
     # deprecations
     # not elegant or compact code, but temporary
     
+    # @private
     def self.always_use_ssl
       Koala::Utils.deprecate("HTTPService.always_use_ssl is now HTTPService.http_options[:use_ssl]; always_use_ssl will be removed in a future version.")
       http_options[:use_ssl]
     end
 
+    # @private
     def self.always_use_ssl=(value)
       Koala::Utils.deprecate("HTTPService.always_use_ssl is now HTTPService.http_options[:use_ssl]; always_use_ssl will be removed in a future version.")
       http_options[:use_ssl] = value
     end
     
+    # @private
     def self.timeout
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout]
     end
 
+    # @private
     def self.timeout=(value)
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout] = value
     end
     
+    # @private
     def self.timeout
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout]
     end
 
+    # @private
     def self.timeout=(value)
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout] = value
     end
     
+    # @private
     def self.proxy
       Koala::Utils.deprecate("HTTPService.proxy is now HTTPService.http_options[:proxy]; .proxy will be removed in a future version.")
       http_options[:proxy]
     end
 
+    # @private
     def self.proxy=(value)
       Koala::Utils.deprecate("HTTPService.proxy is now HTTPService.http_options[:proxy]; .proxy will be removed in a future version.")
       http_options[:proxy] = value
     end
     
+    # @private
     def self.ca_path
       Koala::Utils.deprecate("HTTPService.ca_path is now (HTTPService.http_options[:ssl] ||= {})[:ca_path]; .ca_path will be removed in a future version.")
       (http_options[:ssl] || {})[:ca_path]
     end
 
+    # @private
     def self.ca_path=(value)
       Koala::Utils.deprecate("HTTPService.ca_path is now (HTTPService.http_options[:ssl] ||= {})[:ca_path]; .ca_path will be removed in a future version.")
       (http_options[:ssl] ||= {})[:ca_path] = value
     end
     
+    # @private
     def self.ca_file
       Koala::Utils.deprecate("HTTPService.ca_file is now (HTTPService.http_options[:ssl] ||= {})[:ca_file]; .ca_file will be removed in a future version.")
       (http_options[:ssl] || {})[:ca_file]
     end
 
+    # @private
     def self.ca_file=(value)
       Koala::Utils.deprecate("HTTPService.ca_file is now (HTTPService.http_options[:ssl] ||= {})[:ca_file]; .ca_file will be removed in a future version.")
       (http_options[:ssl] ||= {})[:ca_file] = value
     end
 
+    # @private
     def self.verify_mode
       Koala::Utils.deprecate("HTTPService.verify_mode is now (HTTPService.http_options[:ssl] ||= {})[:verify_mode]; .verify_mode will be removed in a future version.")
       (http_options[:ssl] || {})[:verify_mode]
     end
 
+    # @private
     def self.verify_mode=(value)
       Koala::Utils.deprecate("HTTPService.verify_mode is now (HTTPService.http_options[:ssl] ||= {})[:verify_mode]; .verify_mode will be removed in a future version.")
       (http_options[:ssl] ||= {})[:verify_mode] = value
     end
 
+    private 
+    
     def self.process_options(options)
       if typhoeus_options = options.delete(:typhoeus_options)
         Koala::Utils.deprecate("typhoeus_options should now be included directly in the http_options hash.  Support for this key will be removed in a future version.")
@@ -158,6 +206,7 @@ module Koala
     end   
   end
   
+  # @private
   module TyphoeusService
     def self.deprecated_interface
       # support old-style interface with a warning
@@ -166,6 +215,7 @@ module Koala
     end
   end
 
+  # @private
   module NetHTTPService
     def self.deprecated_interface
       # support old-style interface with a warning