koala 1.0.0 → 1.1.0rc2

data/.autotest

@@ -0,0 +1,12 @@
+# Override autotest default magic to rerun all tests every time a
+# change is detected on the file system.
+class Autotest
+  
+  def get_to_green
+    begin
+      rerun_all_tests
+      wait_for_changes unless all_good
+    end until all_good
+  end
+                            
+end

data/.gitignore

@@ -1,3 +1,4 @@
 pkg
 .project
-Gemfile.lock
+Gemfile.lock
+.rvmrc

data/CHANGELOG

@@ -1,3 +1,21 @@
+v1.1
+New methods:
+-- Batch API support through Koala::Facebook::GraphAPI.batch (thanks, seejohnrun!)
+  -- includes file uploads, error handling, and FQL
+-- Added GraphAPI#get_comments_for_urls (thanks, amrnt!)
+-- Added RestAPI#fql_multiquery, which simplifies the results (thanks, amrnt!)   
+Updated methods:
+-- RealtimeUpdates now uses a GraphAPI object instead of its own API
+-- RestAPI#rest_call now has an optional last argument for method, for calls requiring POST, DELETE, etc. (thanks, sshilo!)
+-- Filename can now be specified when uploading (e.g. for Ads API) (thanks, sshilo!)
+-- get_objects([]) returns [] instead of a Facebook error in non-batch mode (thanks, aselder!)
+Internal improvements:
+-- HTTP services are more modular and can be changed on the fly (thanks, chadk!)
+  -- Includes support for uploading StringIOs and other non-files via Net::HTTP even when using TyphoeusService
+-- Support for global proxy and timeout settings (thanks, itchy!)
+-- Support for setting certificate path and file to address Net::HTTP errors under Ruby 1.9.2
+-- Koala now uses the modern Typhoeus API (thanks, aselder!)
+
 v1.0
 New methods:
 -- Photo and file upload now supported through #put_picture

data/autotest/discover.rb

@@ -0,0 +1 @@
+Autotest.add_discovery { "rspec2" }

data/koala.gemspec

@@ -2,8 +2,8 @@
 
 Gem::Specification.new do |s|
   s.name    = %q{koala}
-  s.version = "1.0.0"
-  s.date    = %q{2011-05-01}
+  s.version = "1.1.0rc2"
+  s.date    = %q{2011-06-06}
 
   s.summary     = %q{A lightweight, flexible library for Facebook with support for the Graph API, the REST API, realtime updates, and OAuth authentication.}
   s.description = %q{Koala is a lightweight, flexible Ruby SDK for Facebook.  It allows read/write access to the social graph via the Graph and REST APIs, as well as support for realtime updates and OAuth and Facebook Connect authentication.  Koala is fully tested and supports Net::HTTP and Typhoeus connections out of the box and can accept custom modules for other services.}
@@ -30,20 +30,20 @@ Gem::Specification.new do |s|
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<json>,          ["~> 1.0"])
       s.add_runtime_dependency(%q<multipart-post>,  ["~> 1.0"])
-      s.add_development_dependency(%q<rspec>,     ["~> 2.5.0"])
+      s.add_development_dependency(%q<rspec>,     ["~> 2.5"])
       s.add_development_dependency(%q<rake>,      ["~> 0.8.7"])
       s.add_development_dependency(%q<typhoeus>,  ["~> 0.2.4"])
     else
       s.add_dependency(%q<json>,      ["~> 1.0"])
       s.add_dependency(%q<multipart-post>,  ["~> 1.0"])
-      s.add_dependency(%q<rspec>,     ["~> 2.5.0"])
+      s.add_dependency(%q<rspec>,     ["~> 2.5"])
       s.add_dependency(%q<rake>,      ["~> 0.8.7"])
       s.add_dependency(%q<typhoeus>,  ["~> 0.2.4"])
     end
   else
     s.add_dependency(%q<json>,      ["~> 1.0"])
     s.add_dependency(%q<multipart-post>,  ["~> 1.0"])
-    s.add_dependency(%q<rspec>,     ["~> 2.5.0"])
+    s.add_dependency(%q<rspec>,     ["~> 2.5"])
     s.add_dependency(%q<rake>,      ["~> 0.8.7"])
     s.add_dependency(%q<typhoeus>,  ["~> 0.2.4"])
   end

data/lib/koala/graph_api.rb

@@ -28,7 +28,20 @@ module Koala
       # If you are using the JavaScript SDK, you can use the
       # Koala::Facebook::OAuth.get_user_from_cookie() method below to get the OAuth access token
       # for the active user from the cookie saved by the SDK.
-         
+
+      def self.included(base)
+        base.class_eval do
+          def self.check_response(response)
+            # check for Graph API-specific errors
+            # this returns an error, which is immediately raised (non-batch)
+            # or added to the list of batch results (batch)
+            if response.is_a?(Hash) && error_details = response["error"]
+              APIError.new(error_details) 
+            end
+          end
+        end
+      end
+
       # Objects
 
       def get_object(id, args = {}, options = {})
@@ -37,10 +50,10 @@ module Koala
       end
     
       def get_objects(ids, args = {}, options = {})
-        # Fetchs all of the given object from the graph.
-        # We return a map from ID to object. If any of the IDs are invalid,
-        # we raise an exception.
-        graph_call("", args.merge("ids" => ids.join(",")), "get", options)
+        # Fetchs all of the given objects from the graph.
+        # If any of the IDs are invalid, they'll raise an exception.
+        return [] if ids.empty?
+        graph_call("", args.merge("ids" => ids.respond_to?(:join) ? ids.join(",") : ids), "get", options)
       end
       
       def put_object(parent_object, connection_name, args = {}, options = {})
@@ -71,10 +84,19 @@ module Koala
           
       def get_connections(id, connection_name, args = {}, options = {})
         # Fetchs the connections for given object.
-        result = graph_call("#{id}/#{connection_name}", args, "get", options)
-        result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
+        graph_call("#{id}/#{connection_name}", args, "get", options) do |result|
+          result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
+        end
       end
 
+      def get_comments_for_urls(urls = [], args = {}, options = {})
+        # Fetchs the comments for given URLs (array or comma-separated string)
+        # see https://developers.facebook.com/blog/post/490
+        return [] if urls.empty?
+        args.merge!(:ids => urls.respond_to?(:join) ? urls.join(",") : urls)
+        get_object("comments", args, options)
+      end
+          
       def put_connections(id, connection_name, args = {}, options = {})
         # Posts a certain connection
         raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Write operations require an access token"}) unless @access_token
@@ -93,8 +115,9 @@ module Koala
     
       def get_picture(object, args = {}, options = {})
         # Gets a picture object, returning the URL (which Facebook sends as a header)
-        result = graph_call("#{object}/picture", args, "get", options.merge(:http_component => :headers))
-        result["Location"]
+        graph_call("#{object}/picture", args, "get", options.merge(:http_component => :headers)) do |result|
+          result["Location"]
+        end
       end    
       
       def put_picture(*picture_args)
@@ -123,7 +146,9 @@ module Koala
         options   = picture_args[3 + args_offset] || {} 
         
         args["source"] = Koala::UploadableIO.new(*picture_args.slice(0, 1 + args_offset))
-        
+
+        options[:http_service] = Koala.base_http_service if args["source"].requires_base_http_service
+
         self.put_object(target_id, "photos", args, options)
       end
     
@@ -172,47 +197,62 @@ module Koala
             
       def search(search_terms, args = {}, options = {})
         args.merge!({:q => search_terms}) unless search_terms.nil?
-        result = graph_call("search", args, "get", options)
-        result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
+        graph_call("search", args, "get", options) do |result|
+          result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
+        end
       end      
       
       # API access
-    
-      def graph_call(*args)
+
+      # Make a call which may or may not be batched
+      def graph_call(path, args = {}, verb = "get", options = {}, &post_processing)
         # Direct access to the Facebook API
         # see any of the above methods for example invocations
-        response = api(*args) do |response|
-          # check for Graph API-specific errors
-          if response.is_a?(Hash) && error_details = response["error"]
-            raise APIError.new(error_details)
+        unless GraphAPI.batch_mode?
+          result = api(path, args, verb, options) do |response|
+            if error = GraphAPI.check_response(response)
+              raise error
+            end
           end
+          
+          # now process as appropriate (get picture header, make GraphCollection, etc.)
+          post_processing ? post_processing.call(result) : result
+        else
+          # for batch APIs, we queue up the call details (incl. post-processing)
+          GraphAPI.batch_calls << BatchOperation.new(
+            :url => path,
+            :args => args,
+            :method => verb,
+            :access_token => @access_token,
+            :http_options => options,
+            :post_processing => post_processing
+          )
+          nil # batch operations return nothing immediately 
         end
-      
-        response
-      end 
+      end
       
       # GraphCollection support
-      
       def get_page(params)
         # Pages through a set of results stored in a GraphCollection
         # Used for connections and search results
-        result = graph_call(*params)
-        result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
+        graph_call(*params) do |result|
+          result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
+        end
       end
       
     end
     
     
     class GraphCollection < Array
-      #This class is a light wrapper for collections returned
-      #from the Graph API.
+      # This class is a light wrapper for collections returned
+      # from the Graph API.
       #
-      #It extends Array to allow direct access to the data colleciton
-      #which should allow it to drop in seamlessly.
+      # It extends Array to allow direct access to the data colleciton
+      # which should allow it to drop in seamlessly.
       #
-      #It also allows access to paging information and the
-      #ability to get the next/previous page in the collection
-      #by calling next_page or previous_page.
+      # It also allows access to paging information and the
+      # ability to get the next/previous page in the collection
+      # by calling next_page or previous_page.
       attr_reader :paging
       attr_reader :api
       

data/lib/koala/graph_api_batch.rb

@@ -0,0 +1,151 @@
+module Koala
+  module Facebook
+    class BatchOperation
+      attr_reader :access_token, :http_options, :post_processing, :files
+       
+      def initialize(options = {})
+        @args = (options[:args] || {}).dup # because we modify it below
+        @access_token = options[:access_token]
+        @http_options = (options[:http_options] || {}).dup # dup because we modify it below
+        @batch_args = @http_options.delete(:batch_args) || {}
+        @url = options[:url]
+        @method = options[:method].to_sym
+        @post_processing = options[:post_processing]
+        
+        process_binary_args
+        
+        raise Koala::KoalaError, "Batch operations require an access token, none provided." unless @access_token
+      end
+      
+      def to_batch_params(main_access_token)
+        # set up the arguments
+        args_string = Koala.http_service.encode_params(@access_token == main_access_token ? @args : @args.merge(:access_token => @access_token))
+        
+        response = {
+          :method => @method, 
+          :relative_url => @url,
+        }
+         
+        # handle batch-level arguments, such as name, depends_on, and attached_files
+        @batch_args[:attached_files] = @files.keys.join(",") if @files
+        response.merge!(@batch_args) if @batch_args
+        
+        # for get and delete, we append args to the URL string
+        # otherwise, they go in the body
+        if args_string.length > 0
+          if args_in_url?
+            response[:relative_url] += (@url =~ /\?/ ? "&" : "?") + args_string if args_string.length > 0
+          else
+            response[:body] = args_string if args_string.length > 0
+          end
+        end
+        
+        response
+      end
+  
+      protected
+      
+      def process_binary_args
+        # collect binary files
+        @args.each_pair do |key, value| 
+          if UploadableIO.binary_content?(value)
+            @files ||= {}
+            # we use object_id to ensure unique file identifiers across multiple batch operations
+            # remove it from the original hash and add it to the file store
+            id = "file#{GraphAPI.batch_calls.length}_#{@files.keys.length}"
+            @files[id] = @args.delete(key).is_a?(UploadableIO) ? value : UploadableIO.new(value)
+          end
+        end          
+      end
+      
+      def args_in_url?
+        @method == :get || @method == :delete 
+      end   
+    end
+    
+    module GraphAPIBatchMethods
+      def self.included(base)
+        base.class_eval do
+          # batch mode flags
+          def self.batch_mode?
+            !!@batch_mode
+          end
+
+          def self.batch_calls
+            raise KoalaError, "GraphAPI.batch_calls accessed when not in batch block!" unless batch_mode?
+            @batch_calls
+          end
+
+          def self.batch(http_options = {}, &block)
+            @batch_mode = true
+            @batch_http_options = http_options
+            @batch_calls = []
+            yield
+            begin
+              results = batch_api(@batch_calls)
+            ensure
+              @batch_mode = false
+            end
+            results
+          end
+
+          def self.batch_api(batch_calls)
+            return [] unless batch_calls.length > 0
+            # Facebook requires a top-level access token
+
+            # Get the access token for the user and start building a hash to store params
+            # Turn the call args collected into what facebook expects
+            args = {}
+            access_token = args["access_token"] = batch_calls.first.access_token
+            args['batch'] = batch_calls.map { |batch_op| 
+              args.merge!(batch_op.files) if batch_op.files
+              batch_op.to_batch_params(access_token)
+            }.to_json
+            
+            # Make the POST request for the batch call
+            # batch operations have to go over SSL, but since there's an access token, that secures that
+            result = Koala.make_request('/', args, 'post', @batch_http_options) 
+            # Raise an error if we get a 500
+            raise APIError.new("type" => "HTTP #{result.status.to_s}", "message" => "Response body: #{result.body}") if result.status >= 500
+
+            response = JSON.parse(result.body.to_s)
+            # raise an error if we get a Batch API error message
+            raise APIError.new("type" => "Error #{response["error"]}", "message" => response["error_description"]) if response.is_a?(Hash) && response["error"]
+
+            # otherwise, 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
+
+              if call_result
+                # (see note in regular api method about JSON parsing)
+                body = JSON.parse("[#{call_result['body'].to_s}]")[0]
+                unless call_result["code"].to_i >= 500 || error = GraphAPI.check_response(body)
+                  # Get the HTTP component they want
+                  data = 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
+                    call_result['headers'].inject({}) { |headers, h| headers[h['name']] = h['value']; headers}
+                  else
+                    body
+                  end
+                
+                  # process it if we are given a block to process with
+                  batch_op.post_processing ? batch_op.post_processing.call(data) : data
+                else
+                  error || APIError.new({"type" => "HTTP #{call_result["code"].to_s}", "message" => "Response body: #{body}"})
+                end
+              else
+                nil
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/koala/http_services/net_http_service.rb

@@ -0,0 +1,87 @@
+require "net/http" unless defined?(Net::HTTP)
+require "net/https"
+require "net/http/post/multipart"
+
+module Koala
+  module NetHTTPService
+    # this service uses Net::HTTP to send requests to the graph
+    include Koala::HTTPService
+
+    def self.make_request(path, args, verb, options = {})
+      # We translate args to a valid query string. If post is specified,
+      # we send a POST request to the given path with the given arguments.
+
+      # by default, we use SSL only for private requests
+      # this makes public requests faster
+      private_request = args["access_token"] || @always_use_ssl || options[:use_ssl]
+
+      # if proxy/timeout options aren't passed, check if defaults are set
+      options[:proxy] ||= proxy
+      options[:timeout] ||= timeout
+
+      # 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"
+
+      http = create_http(server(options), private_request, options)
+
+      result = http.start do |http|
+        response, body = if verb == "post"
+          if params_require_multipart? args
+            http.request Net::HTTP::Post::Multipart.new path, encode_multipart_params(args)
+          else
+            http.post(path, encode_params(args))
+          end
+        else
+          http.get("#{path}?#{encode_params(args)}")
+        end
+      
+        Koala::Response.new(response.code.to_i, body, response)
+      end
+    end
+
+    protected
+    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
+      ((param_hash || {}).collect do |key_and_value|
+        key_and_value[1] = key_and_value[1].to_json if key_and_value[1].class != String
+        "#{key_and_value[0].to_s}=#{CGI.escape key_and_value[1]}"
+      end).join("&")
+    end
+  
+    def self.encode_multipart_params(param_hash)
+      Hash[*param_hash.collect do |key, value| 
+        [key, value.kind_of?(Koala::UploadableIO) ? value.to_upload_io : value]
+      end.flatten]
+    end
+
+    def self.create_http(server, private_request, options)
+      if options[:proxy]
+        proxy = URI.parse(options[:proxy])
+        http  = Net::HTTP.new(server, private_request ? 443 : nil,
+                              proxy.host, proxy.port, proxy.user, proxy.password)
+      else
+        http = Net::HTTP.new(server, private_request ? 443 : nil)
+      end
+      
+      if options[:timeout]
+        http.open_timeout = options[:timeout]
+        http.read_timeout = options[:timeout]
+      end
+      
+      # For HTTPS requests, set the proper CA certificates
+      if private_request
+        http.use_ssl = true  
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        
+        options[:ca_file] ||= ca_file
+        http.ca_file = options[:ca_file] if options[:ca_file] && File.exists?(options[:ca_file])
+        
+        options[:ca_path] ||= ca_path
+        http.ca_path = options[:ca_path] if options[:ca_path] && Dir.exists?(options[:ca_path])
+      end
+            
+      http
+    end
+  end
+end

data/lib/koala/http_services/typhoeus_service.rb

@@ -0,0 +1,37 @@
+require "typhoeus" unless defined?(Typhoeus)
+
+module Koala
+  module TyphoeusService
+    # this service uses Typhoeus to send requests to the graph
+    include Typhoeus  
+    include Koala::HTTPService
+
+    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"
+
+      # switch any UploadableIOs to the files Typhoeus expects 
+      args.each_pair {|key, value| args[key] = value.to_file if value.is_a?(UploadableIO)}
+
+      # you can pass arguments directly to Typhoeus using the :typhoeus_options key
+      typhoeus_options = {:params => args}.merge(options[:typhoeus_options] || {})
+
+      # if proxy/timeout options aren't passed, check if defaults are set
+      typhoeus_options[:proxy] ||= proxy
+      typhoeus_options[:timeout] ||= timeout
+
+      # by default, we use SSL only for private requests (e.g. with access token)
+      # this makes public requests faster
+      prefix = (args["access_token"] || @always_use_ssl || options[:use_ssl]) ? "https" : "http"
+
+      response = Typhoeus::Request.send(verb, "#{prefix}://#{server(options)}#{path}", typhoeus_options)
+      Koala::Response.new(response.code, response.body, response.headers_hash)
+    end
+  
+    protected
+      
+    def self.multipart_requires_content_type?
+      false # Typhoeus handles multipart file types, we don't have to require it
+    end
+  end
+end

data/lib/koala/http_services.rb

@@ -13,134 +13,32 @@ module Koala
     def self.included(base)
       base.class_eval do
         class << self
-          attr_accessor :always_use_ssl
+          attr_accessor :always_use_ssl, :proxy, :timeout, :ca_path, :ca_file
         end
-               
+
         def self.server(options = {})
           "#{options[:beta] ? "beta." : ""}#{options[:rest_api] ? Facebook::REST_SERVER : Facebook::GRAPH_SERVER}"          
         end
-                                      
-        protected
         
-        def self.params_require_multipart?(param_hash)
-          param_hash.any? { |key, value| value.kind_of?(Koala::UploadableIO) }
-        end
-    
-        def self.multipart_requires_content_type?
-          true
-        end
-      end
-    end
-  end
-
-  module NetHTTPService
-    # this service uses Net::HTTP to send requests to the graph
-    def self.included(base)
-      base.class_eval do
-        require "net/http" unless defined?(Net::HTTP)
-        require "net/https"
-        require "net/http/post/multipart"
-
-        include Koala::HTTPService
-
-        def self.make_request(path, args, verb, options = {})
-          # We translate args to a valid query string. If post is specified,
-          # we send a POST request to the given path with the given arguments.
-
-          # by default, we use SSL only for private requests
-          # this makes public requests faster
-          private_request = args["access_token"] || @always_use_ssl || options[:use_ssl]
-
-          # 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"
-
-          http = create_http(server(options), private_request, options)
-          http.use_ssl = true if private_request
-
-          result = http.start do |http|
-            response, body = if verb == "post"
-              if params_require_multipart? args
-                http.request Net::HTTP::Post::Multipart.new path, encode_multipart_params(args)
-              else
-                http.post(path, encode_params(args))
-              end
-            else
-              http.get("#{path}?#{encode_params(args)}")
-            end
-            
-            Koala::Response.new(response.code.to_i, body, response)
-          end
-        end
-
-        protected
         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
           ((param_hash || {}).collect do |key_and_value|
-            key_and_value[1] = key_and_value[1].to_json if key_and_value[1].class != String
+            key_and_value[1] = key_and_value[1].to_json unless key_and_value[1].is_a? String
             "#{key_and_value[0].to_s}=#{CGI.escape key_and_value[1]}"
           end).join("&")
         end
+                                      
+        protected
         
-        def self.encode_multipart_params(param_hash)
-          Hash[*param_hash.collect do |key, value| 
-            [key, value.kind_of?(Koala::UploadableIO) ? value.to_upload_io : value]
-          end.flatten]
-        end
-
-        def self.create_http(server, private_request, options)
-          if options[:proxy]
-            proxy = URI.parse(options[:proxy])
-            http  = Net::HTTP.new(server, private_request ? 443 : nil,
-                                  proxy.host, proxy.port, proxy.user, proxy.password)
-          else
-            http = Net::HTTP.new(server, private_request ? 443 : nil)
-          end
-          if options[:timeout]
-            http.open_timeout = options[:timeout]
-            http.read_timeout = options[:timeout]
-          end
-          http
-        end
-
-      end
-    end
-  end
-
-  module TyphoeusService
-    # this service uses Typhoeus to send requests to the graph
-
-    def self.included(base)
-      base.class_eval do
-        require "typhoeus" unless defined?(Typhoeus)
-        include Typhoeus
-        
-        include Koala::HTTPService
-
-        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"
-
-          # switch any UploadableIOs to the files Typhoeus expects 
-          args.each_pair {|key, value| args[key] = value.to_file if value.is_a?(UploadableIO)}
-
-          # you can pass arguments directly to Typhoeus using the :typhoeus_options key
-          typhoeus_options = {:params => args}.merge(options[:typhoeus_options] || {})
-
-          # by default, we use SSL only for private requests (e.g. with access token)
-          # this makes public requests faster
-          prefix = (args["access_token"] || @always_use_ssl || options[:use_ssl]) ? "https" : "http"
-
-          response = self.send(verb, "#{prefix}://#{server(options)}#{path}", typhoeus_options)
-          Koala::Response.new(response.code, response.body, response.headers_hash)
+        def self.params_require_multipart?(param_hash)
+          param_hash.any? { |key, value| value.kind_of?(Koala::UploadableIO) }
         end
-        
-        private
-        
+    
         def self.multipart_requires_content_type?
-          false # Typhoeus handles multipart file types, we don't have to require it
+          true
         end
-      end # class_eval
+      end
     end
   end
 end