koala 1.0.0 → 1.1.0rc

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.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

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/oauth.rb

@@ -0,0 +1,181 @@
+module Koala
+  module Facebook
+    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
+  end
+end