koala 1.0.0 → 1.1.0rc3

data/lib/koala/uploadable_io.rb

@@ -2,9 +2,9 @@ require 'koala'
 
 module Koala
   class UploadableIO
-    attr_reader :io_or_path, :content_type
+    attr_reader :io_or_path, :content_type, :requires_base_http_service
 
-    def initialize(io_or_path_or_mixed, content_type = nil)
+    def initialize(io_or_path_or_mixed, content_type = nil, filename = nil)
       # see if we got the right inputs
       if content_type.nil?
         parse_init_mixed_param io_or_path_or_mixed
@@ -13,103 +13,163 @@ module Koala
         @content_type = content_type
       end
       
+      # Probably a StringIO or similar object, which won't work with Typhoeus
+      @requires_base_http_service = @io_or_path.respond_to?(:read) && !@io_or_path.kind_of?(File)
+
+      # filename is used in the Ads API
+      @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 && Koala.multipart_requires_content_type?
     end
     
     def to_upload_io
-      UploadIO.new(@io_or_path, @content_type, "koala-io-file.dum")
+      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
-      PARSE_STRATEGIES = [
-        :parse_rails_3_param,
-        :parse_sinatra_param,
-        :parse_file_object,
-        :parse_string_path
-      ]
-      
-      def parse_init_mixed_param(mixed)
-        PARSE_STRATEGIES.each do |method|
-          send(method, mixed)
-          return if @io_or_path && @content_type
-        end
+    DETECTION_STRATEGIES = [
+      :sinatra_param?,
+      :rails_3_param?,
+      :file_param?
+    ]
+  
+    PARSE_STRATEGIES = [
+      :parse_rails_3_param,
+      :parse_sinatra_param,
+      :parse_file_object,
+      :parse_string_path
+    ]
+    
+    def parse_init_mixed_param(mixed)
+      PARSE_STRATEGIES.each do |method|
+        send(method, mixed)
+        return if @io_or_path && @content_type
       end
-      
-      # Expects a parameter of type ActionDispatch::Http::UploadedFile
-      def parse_rails_3_param(uploaded_file)
-        if uploaded_file.respond_to?(:content_type) and uploaded_file.respond_to?(:tempfile) and uploaded_file.tempfile.respond_to?(:path)
-          @io_or_path = uploaded_file.tempfile.path
-          @content_type = uploaded_file.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)
+      if UploadableIO.rails_3_param?(uploaded_file) 
+        @io_or_path = uploaded_file.tempfile.path
+        @content_type = uploaded_file.content_type
       end
-      
-      # Expects a Sinatra hash of file info
-      def parse_sinatra_param(file_hash)
-        if file_hash.kind_of?(Hash) and file_hash.has_key?(:type) and file_hash.has_key?(:tempfile)
-          @io_or_path = file_hash[:tempfile]
-          @content_type = file_hash[:type] || detect_mime_type(tempfile)
-        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)
+      if UploadableIO.sinatra_param?(file_hash)
+        @io_or_path = file_hash[:tempfile]
+        @content_type = file_hash[:type] || detect_mime_type(tempfile)
       end
-      
-      # takes a file object
-      def parse_file_object(file)
-        if file.kind_of?(File)
-          @io_or_path = file
-          @content_type = detect_mime_type(file.path)
-        end
+    end
+    
+    # takes a file object
+    def self.file_param?(file)
+      file.kind_of?(File)
+    end
+    
+    def parse_file_object(file)
+      if UploadableIO.file_param?(file)
+        @io_or_path = file
+        @content_type = detect_mime_type(file.path)
       end
-      
-      def parse_string_path(path)
-        if path.kind_of?(String)
-          @io_or_path = path
-          @content_type = detect_mime_type(path)
-        end
+    end
+    
+    def parse_string_path(path)
+      if path.kind_of?(String)
+        @io_or_path = path
+        @content_type = detect_mime_type(path)
       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
+    
+    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
-        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
+      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
-      
-      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
-        if extension == ""
+    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
-        elsif extension == "jpg" || extension == "jpeg"
+        # images
+        when "jpg", "jpeg"
           "image/jpeg"
-        elsif extension == "png"
+        when "png"
           "image/png"
-        elsif extension == "gif"
+        when "gif"
           "image/gif"
-        end
-      end
+
+        # 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
+end

data/lib/koala.rb

@@ -1,7 +1,7 @@
 require 'cgi'
 require 'digest/md5'
 
-require 'json'
+require 'multi_json'
 
 # OpenSSL and Base64 are required to support signed_request
 require 'openssl'
@@ -9,10 +9,16 @@ 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_batch_api'
+require 'koala/batch_operation'
+require 'koala/graph_collection'
 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 +53,27 @@ 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
+        # 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
 
-        # 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
     end
-
+    
+    class GraphBatchAPI < GraphAPI
+      include GraphBatchAPIMethods      
+    end
+        
     class RestAPI < API
       include RestAPIMethods
     end
@@ -87,6 +93,8 @@ module Koala
       attr_reader :graph_api
     end
 
+    # Errors
+
     class APIError < StandardError
       attr_accessor :fb_error_type
       def initialize(details = {})
@@ -94,201 +102,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/readme.md

@@ -1,21 +1,24 @@
 Koala
 ====
-Koala (<a href="http://github.com/arsduo/koala" target="_blank">http://github.com/arsduo/koala</a>) is a new Facebook library for Ruby, supporting the Graph API (including photo uploads), the old REST API, realtime updates, and OAuth validation.  We wrote Koala with four goals:
+[Koala](http://github.com/arsduo/koala) is a new Facebook library for Ruby, supporting the Graph API (including the batch requests and photo uploads), the REST API, realtime updates, test users, and OAuth validation.  We wrote Koala with four goals:
 
-* Lightweight: Koala should be as light and simple as Facebook’s own new libraries, providing API accessors and returning simple JSON.  (We clock in, with comments, just over 750 lines of code.)
-* Fast: Koala should, out of the box, be quick. In addition to supporting the vanilla Ruby networking libraries, it natively supports Typhoeus, our preferred gem for making fast HTTP requests. Of course, That brings us to our next topic:
+* Lightweight: Koala should be as light and simple as Facebook’s own new libraries, providing API accessors and returning simple JSON.  (We clock in, with comments, at just over 750 lines of code.)
+* Fast: Koala should, out of the box, be quick. In addition to supporting the vanilla Ruby networking libraries, it natively supports Typhoeus, our preferred gem for making fast HTTP requests. Of course, that brings us to our next topic:
 * Flexible: Koala should be useful to everyone, regardless of their current configuration.  (We have no dependencies beyond the JSON gem.  Koala also has a built-in mechanism for using whichever HTTP library you prefer to make requests against the graph.)
 * Tested: Koala should have complete test coverage, so you can rely on it.  (Our complete test coverage can be run against either mocked responses or the live Facebook servers.)
 
-1.0 
+Installation
 ---
-Version 1.0 is due out on May 1st, 2011 with a ton of great features.  
+
+Easy:
+    
+    [sudo|rvm] gem install koala
+    # for 1.1rc add --pre
     
-    sudo gem install koala
 
-Until then, you can install the release candidate like so:
+Or in Bundler:
   
-    sudo gem install koala --pre
+    gem "koala" # add ', "~> 1.1rc"' for the release candidate
   
 Graph API
 ----
@@ -44,9 +47,18 @@ When retrieving data that returns an array of results (for example, when calling
     # This is useful for paging across multiple requests
     next_path, next_args = feed.next_page_params
 
-    # You can use those params to easily get the next (or prevous) page
+    # You can use those params to easily get the next (or previous) page
     page = graph.get_page(feed.next_page_params)
 
+You can make multiple calls at once using Facebook's batch API:
+
+    # Returns an array of results as if they were called non-batch
+    graph.batch do
+      graph.get_connections('me', 'friends')
+      graph.get_object('me')
+      graph.get_picture('me')
+    end
+
 Check out the wiki for more examples.
 
 The old-school REST API
@@ -132,12 +144,12 @@ Testing
 Unit tests are provided for all of Koala's methods.  By default, these tests run against mock responses and hence are ready out of the box:
     
     # From anywhere in the project directory:
-    rake spec
+    bundle exec rake spec
     
 
 You can also run live tests against Facebook's servers:
     
     # Again from anywhere in the project directory:
-    LIVE=true rake spec
+    LIVE=true bundle exec rake spec
 
-Important Note: to run the live tests, you have to provide some of your own data in spec/fixtures/facebook_data.yml: a valid OAuth access token with publish\_stream, read\_stream, and user\_photos permissions and an OAuth code that can be used to generate an access token.  You can get thisdata at the OAuth Playground; if you want to use your own app, remember to swap out the app ID, secret, and other values.  (The file also provides valid values for other tests, which you're welcome to swap out for data specific to your own application.)
+Important Note: to run the live tests, you have to provide some of your own data in spec/fixtures/facebook_data.yml: a valid OAuth access token with publish\_stream, read\_stream, and user\_photos permissions and an OAuth code that can be used to generate an access token.  You can get this data at the OAuth Playground; if you want to use your own app, remember to swap out the app ID, secret, and other values.  (The file also provides valid values for other tests, which you're welcome to swap out for data specific to your own application.)

data/spec/cases/api_base_spec.rb

@@ -52,21 +52,21 @@ describe "Koala::Facebook::API" do
     Koala.stub(:make_request).and_return(response)
 
     json_body = mock('JSON body')
-    JSON.stub(:parse).and_return([json_body])
+    MultiJson.stub(:decode).and_return([json_body])
 
     @service.api('anything').should == json_body
   end
 
-  it "should execute a block with the response body if passed one" do
+  it "should execute an error checking block if provided" do
     body = '{}'
     Koala.stub(:make_request).and_return(Koala::Response.new(200, body, {}))
 
     yield_test = mock('Yield Tester')
     yield_test.should_receive(:pass)
 
-    @service.api('anything') do |arg|
+    @service.api('anything', {}, "get") do |arg|
       yield_test.pass
-      arg.should == JSON.parse(body)
+      arg.should == MultiJson.decode(body)
     end
   end