koala 1.0.0 → 1.1.0rc

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/updated 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.0rc"
+  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.rb

@@ -9,10 +9,14 @@ require 'base64'
 
 # include koala modules
 require 'koala/http_services'
+require 'koala/http_services/net_http_service'
+require 'koala/oauth'
 require 'koala/graph_api'
+require 'koala/graph_api_batch'
 require 'koala/rest_api'
 require 'koala/realtime_updates'
 require 'koala/test_users'
+require 'koala/http_services'
 
 # add KoalaIO class
 require 'koala/uploadable_io'
@@ -47,27 +51,24 @@ module Koala
         # 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 check for errors if provided a mechanism to do so
+        # 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 JSON.parse to fail -- so we account for that by wrapping the result in []
-        body = response = JSON.parse("[#{result.body.to_s}]")[0]
-        if error_checking_block
-          yield(body)
-        end
+        body = JSON.parse("[#{result.body.to_s}]")[0]
+        yield body if error_checking_block
 
-        # now return the desired information
-        if options[:http_component]
-          result.send(options[:http_component])
-        else
-          body
-        end
+        # if we want a component other than the body (e.g. redirect header for images), return that
+        options[:http_component] ? result.send(options[:http_component]) : body
       end
     end
 
+    # APIs
+    
     class GraphAPI < API
       include GraphAPIMethods
+      include GraphAPIBatchMethods
     end
-
+    
     class RestAPI < API
       include RestAPIMethods
     end
@@ -87,6 +88,8 @@ module Koala
       attr_reader :graph_api
     end
 
+    # Errors
+
     class APIError < StandardError
       attr_accessor :fb_error_type
       def initialize(details = {})
@@ -94,201 +97,33 @@ module Koala
         super("#{fb_error_type}: #{details["message"]}")
       end
     end
+  end
 
+  class KoalaError < StandardError; end
 
-    class OAuth
-      attr_reader :app_id, :app_secret, :oauth_callback_url
-      def initialize(app_id, app_secret, oauth_callback_url = nil)
-        @app_id = app_id
-        @app_secret = app_secret
-        @oauth_callback_url = oauth_callback_url
-      end
-
-      def get_user_info_from_cookie(cookie_hash)
-        # Parses the cookie set by the official Facebook JavaScript SDK.
-        #
-        # cookies should be a Hash, like the one Rails provides
-        #
-        # If the user is logged in via Facebook, we return a dictionary with the
-        # keys "uid" and "access_token". The former is the user's Facebook ID,
-        # and the latter can be used to make authenticated requests to the Graph API.
-        # If the user is not logged in, we return None.
-        #
-        # Download the official Facebook JavaScript SDK at
-        # http://github.com/facebook/connect-js/. Read more about Facebook
-        # authentication at http://developers.facebook.com/docs/authentication/.
-
-        if fb_cookie = cookie_hash["fbs_" + @app_id.to_s]
-          # remove the opening/closing quote
-          fb_cookie = fb_cookie.gsub(/\"/, "")
-
-          # since we no longer get individual cookies, we have to separate out the components ourselves
-          components = {}
-          fb_cookie.split("&").map {|param| param = param.split("="); components[param[0]] = param[1]}
-
-          # generate the signature and make sure it matches what we expect
-          auth_string = components.keys.sort.collect {|a| a == "sig" ? nil : "#{a}=#{components[a]}"}.reject {|a| a.nil?}.join("")
-          sig = Digest::MD5.hexdigest(auth_string + @app_secret)
-          sig == components["sig"] && (components["expires"] == "0" || Time.now.to_i < components["expires"].to_i) ? components : nil
-        end
-      end
-      alias_method :get_user_info_from_cookies, :get_user_info_from_cookie
-
-      def get_user_from_cookie(cookies)
-        if info = get_user_info_from_cookies(cookies)
-          string = info["uid"]
-        end
-      end
-      alias_method :get_user_from_cookies, :get_user_from_cookie
-
-      # URLs
-
-      def url_for_oauth_code(options = {})
-        # for permissions, see http://developers.facebook.com/docs/authentication/permissions
-        permissions = options[:permissions]
-        scope = permissions ? "&scope=#{permissions.is_a?(Array) ? permissions.join(",") : permissions}" : ""
-        display = options.has_key?(:display) ? "&display=#{options[:display]}" : ""
-        
-        callback = options[:callback] || @oauth_callback_url
-        raise ArgumentError, "url_for_oauth_code must get a callback either from the OAuth object or in the options!" unless callback
-
-        # Creates the URL for oauth authorization for a given callback and optional set of permissions
-        "https://#{GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{callback}#{scope}#{display}"
-      end
-
-      def url_for_access_token(code, options = {})
-        # Creates the URL for the token corresponding to a given code generated by Facebook
-        callback = options[:callback] || @oauth_callback_url
-        raise ArgumentError, "url_for_access_token must get a callback either from the OAuth object or in the parameters!" unless callback
-        "https://#{GRAPH_SERVER}/oauth/access_token?client_id=#{@app_id}&redirect_uri=#{callback}&client_secret=#{@app_secret}&code=#{code}"
-      end
-
-      def get_access_token_info(code, options = {})
-        # convenience method to get a parsed token from Facebook for a given code
-        # should this require an OAuth callback URL?
-        get_token_from_server({:code => code, :redirect_uri => @oauth_callback_url}, false, options)
-      end
-
-      def get_access_token(code, options = {})
-        # upstream methods will throw errors if needed
-        if info = get_access_token_info(code, options)
-          string = info["access_token"]
-        end
-      end
-
-      def get_app_access_token_info(options = {})
-        # convenience method to get a the application's sessionless access token
-        get_token_from_server({:type => 'client_cred'}, true, options)
-      end
-
-      def get_app_access_token(options = {})
-        if info = get_app_access_token_info(options)
-          string = info["access_token"]
-        end
-      end
-
-      # Originally provided directly by Facebook, however this has changed
-      # as their concept of crypto changed. For historic purposes, this is their proposal:
-      # https://developers.facebook.com/docs/authentication/canvas/encryption_proposal/
-      # Currently see https://github.com/facebook/php-sdk/blob/master/src/facebook.php#L758
-      # for a more accurate reference implementation strategy.
-      def parse_signed_request(input)
-        encoded_sig, encoded_envelope = input.split('.', 2)
-        signature = base64_url_decode(encoded_sig).unpack("H*").first
-        envelope = JSON.parse(base64_url_decode(encoded_envelope))
-
-        raise "SignedRequest: Unsupported algorithm #{envelope['algorithm']}" if envelope['algorithm'] != 'HMAC-SHA256'
-
-        # now see if the signature is valid (digest, key, data)
-        hmac = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, @app_secret, encoded_envelope.tr("-_", "+/"))
-        raise 'SignedRequest: Invalid signature' if (signature != hmac)
-
-        return envelope
-      end
-
-      # from session keys
-      def get_token_info_from_session_keys(sessions, options = {})
-        # fetch the OAuth tokens from Facebook
-        response = fetch_token_string({
-          :type => 'client_cred',
-          :sessions => sessions.join(",")
-        }, true, "exchange_sessions", options)
-
-        # Facebook returns an empty body in certain error conditions
-        if response == ""
-          raise APIError.new({
-            "type" => "ArgumentError",
-            "message" => "get_token_from_session_key received an error (empty response body) for sessions #{sessions.inspect}!"
-          })
-        end
-
-        JSON.parse(response)
-      end
-
-      def get_tokens_from_session_keys(sessions, options = {})
-        # get the original hash results
-        results = get_token_info_from_session_keys(sessions, options)
-        # now recollect them as just the access tokens
-        results.collect { |r| r ? r["access_token"] : nil }
-      end
-
-      def get_token_from_session_key(session, options = {})
-        # convenience method for a single key
-        # gets the overlaoded strings automatically
-        get_tokens_from_session_keys([session], options)[0]
-      end
-
-      protected
-
-      def get_token_from_server(args, post = false, options = {})
-        # fetch the result from Facebook's servers
-        result = fetch_token_string(args, post, "access_token", options)
-
-        # if we have an error, parse the error JSON and raise an error
-        raise APIError.new((JSON.parse(result)["error"] rescue nil) || {}) if result =~ /error/
-
-        # otherwise, parse the access token
-        parse_access_token(result)
-      end
-
-      def parse_access_token(response_text)
-        components = response_text.split("&").inject({}) do |hash, bit|
-          key, value = bit.split("=")
-          hash.merge!(key => value)
-        end
-        components
-      end
-
-      def fetch_token_string(args, post = false, endpoint = "access_token", options = {})
-        Koala.make_request("/oauth/#{endpoint}", {
-          :client_id => @app_id,
-          :client_secret => @app_secret
-        }.merge!(args), post ? "post" : "get", {:use_ssl => true}.merge!(options)).body
-      end
-
-      # base 64
-      # directly from https://github.com/facebook/crypto-request-examples/raw/master/sample.rb
-      def base64_url_decode(str)
-        str += '=' * (4 - str.length.modulo(4))
-        Base64.decode64(str.tr('-_', '+/'))
-      end
-    end
+  # Make an api request using the provided api service or one passed by the caller
+  def self.make_request(path, args, verb, options = {})
+    http_service = options.delete(:http_service) || Koala.http_service
+    options = options.merge(:use_ssl => true) if @always_use_ssl
+    http_service.make_request(path, args, verb, options)
   end
 
-  class KoalaError< StandardError; end
-
   # finally, set up the http service Koala methods used to make requests
   # you can use your own (for HTTParty, etc.) by calling Koala.http_service = YourModule
-  def self.http_service=(service)
-    self.send(:include, service)
+  class << self
+    attr_accessor :http_service
+    attr_accessor :always_use_ssl
+    attr_accessor :base_http_service
   end
+  Koala.base_http_service = NetHTTPService
 
   # by default, try requiring Typhoeus -- if that works, use it
   # if you have Typheous and don't want to use it (or want another service),
   # you can run Koala.http_service = NetHTTPService (or MyHTTPService)
   begin
+    require 'koala/http_services/typhoeus_service'
     Koala.http_service = TyphoeusService
   rescue LoadError
-    Koala.http_service = NetHTTPService
+    Koala.http_service = Koala.base_http_service
   end
 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