koala 0.9.0 → 1.0.0

data/lib/koala/http_services.rb

@@ -8,63 +8,138 @@ module Koala
     end
   end
 
+  module HTTPService
+    # common functionality for all HTTP services
+    def self.included(base)
+      base.class_eval do
+        class << self
+          attr_accessor :always_use_ssl
+        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" 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"
 
-          server = options[:rest_api] ? Facebook::REST_SERVER : Facebook::GRAPH_SERVER
-          http = Net::HTTP.new(server, 443)
-          http.use_ssl = true
-          # we turn off certificate validation to avoid the 
-          # "warning: peer certificate won't be verified in this SSL session" warning
-          # not sure if this is the right way to handle it
-          # see http://redcorundum.blogspot.com/2008/03/ssl-certificates-and-nethttps.html
-          http.verify_mode = OpenSSL::SSL::VERIFY_NONE
-
-          result = http.start { |http|
-            response, body = (verb == "post" ? http.post(path, encode_params(args)) : http.get("#{path}?#{encode_params(args)}"))
+          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| 
+          ((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
+          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)
+        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"
-          server = options[:rest_api] ? Facebook::REST_SERVER : Facebook::GRAPH_SERVER
+
+          # 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] || {})
-          response = self.send(verb, "https://#{server}#{path}", 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)
         end
+        
+        private
+        
+        def self.multipart_requires_content_type?
+          false # Typhoeus handles multipart file types, we don't have to require it
+        end
       end # class_eval
     end
   end

data/lib/koala/rest_api.rb

@@ -1,23 +1,90 @@
 module Koala
   module Facebook
     REST_SERVER = "api.facebook.com"
-    
+
     module RestAPIMethods
       def fql_query(fql)
         rest_call('fql.query', 'query' => fql)
       end
-      
-      def rest_call(method, args = {})
-        response = api("method/#{method}", args.merge('format' => 'json'), 'get', :rest_api => true) do |response|
+
+      def rest_call(method, args = {}, options = {})
+        options = options.merge!(:rest_api => true, :read_only => READ_ONLY_METHODS.include?(method))
+
+        response = api("method/#{method}", args.merge('format' => 'json'), 'get', options) do |response|
           # check for REST API-specific errors
           if response.is_a?(Hash) && response["error_code"]
             raise APIError.new("type" => response["error_code"], "message" => response["error_msg"])
           end
         end
-        
+
         response
       end
+
+      # read-only methods for which we can use API-read
+      # taken directly from the FB PHP library (https://github.com/facebook/php-sdk/blob/master/src/facebook.php)
+      READ_ONLY_METHODS = [
+        'admin.getallocation',
+        'admin.getappproperties',
+        'admin.getbannedusers',
+        'admin.getlivestreamvialink',
+        'admin.getmetrics',
+        'admin.getrestrictioninfo',
+        'application.getpublicinfo',
+        'auth.getapppublickey',
+        'auth.getsession',
+        'auth.getsignedpublicsessiondata',
+        'comments.get',
+        'connect.getunconnectedfriendscount',
+        'dashboard.getactivity',
+        'dashboard.getcount',
+        'dashboard.getglobalnews',
+        'dashboard.getnews',
+        'dashboard.multigetcount',
+        'dashboard.multigetnews',
+        'data.getcookies',
+        'events.get',
+        'events.getmembers',
+        'fbml.getcustomtags',
+        'feed.getappfriendstories',
+        'feed.getregisteredtemplatebundlebyid',
+        'feed.getregisteredtemplatebundles',
+        'fql.multiquery',
+        'fql.query',
+        'friends.arefriends',
+        'friends.get',
+        'friends.getappusers',
+        'friends.getlists',
+        'friends.getmutualfriends',
+        'gifts.get',
+        'groups.get',
+        'groups.getmembers',
+        'intl.gettranslations',
+        'links.get',
+        'notes.get',
+        'notifications.get',
+        'pages.getinfo',
+        'pages.isadmin',
+        'pages.isappadded',
+        'pages.isfan',
+        'permissions.checkavailableapiaccess',
+        'permissions.checkgrantedapiaccess',
+        'photos.get',
+        'photos.getalbums',
+        'photos.gettags',
+        'profile.getinfo',
+        'profile.getinfooptions',
+        'stream.get',
+        'stream.getcomments',
+        'stream.getfilters',
+        'users.getinfo',
+        'users.getloggedinuser',
+        'users.getstandardinfo',
+        'users.hasapppermission',
+        'users.isappuser',
+        'users.isverified',
+        'video.getuploadlimits'
+      ]
     end
-    
+
   end # module Facebook
 end # module Koala

data/lib/koala/test_users.rb

@@ -0,0 +1,85 @@
+require 'koala'
+
+module Koala
+  module Facebook
+    module TestUserMethods
+      
+      def initialize(options = {})
+        @app_id = options[:app_id]
+        @app_access_token = options[:app_access_token]
+        @secret = options[:secret]
+        unless @app_id && (@app_access_token || @secret) # make sure we have what we need
+          raise ArgumentError, "Initialize must receive a hash with :app_id and either :app_access_token or :secret! (received #{options.inspect})"
+        end
+
+        # fetch the access token if we're provided a secret
+        if @secret && !@app_access_token
+          oauth = Koala::Facebook::OAuth.new(@app_id, @secret)
+          @app_access_token = oauth.get_app_access_token
+        end
+        @graph_api = GraphAPI.new(@app_access_token)
+      end
+
+      def create(installed, permissions = nil, args = {}, options = {})
+        # Creates and returns a test user
+        args['installed'] = installed
+        args['permissions'] = (permissions.is_a?(Array) ? permissions.join(",") : permissions) if installed
+        result = @graph_api.graph_call(accounts_path, args, "post", options)
+      end
+      
+      def list
+        @graph_api.graph_call(accounts_path)["data"]
+      end
+      
+      def delete(test_user)
+        test_user = test_user["id"] if test_user.is_a?(Hash)
+        @graph_api.delete_object(test_user)
+      end
+      
+      def delete_all
+        list.each {|u| delete u }
+      end
+      
+      def befriend(user1_hash, user2_hash)
+        user1_id = user1_hash["id"] || user1_hash[:id]
+        user2_id = user2_hash["id"] || user2_hash[:id]
+        user1_token = user1_hash["access_token"] || user1_hash[:access_token]
+        user2_token = user2_hash["access_token"] || user2_hash[:access_token]
+        unless user1_id && user2_id && user1_token && user2_token
+          # we explicitly raise an error here to minimize the risk of confusing output
+          # if you pass in a string (as was previously supported) no local exception would be raised
+          # but the Facebook call would fail
+          raise ArgumentError, "TestUsers#befriend requires hash arguments for both users with id and access_token"
+        end
+        
+        u1_graph_api = GraphAPI.new(user1_token)
+        u2_graph_api = GraphAPI.new(user2_token)
+
+        u1_graph_api.graph_call("#{user1_id}/friends/#{user2_id}", {}, "post") && 
+          u2_graph_api.graph_call("#{user2_id}/friends/#{user1_id}", {}, "post")
+      end
+
+      def create_network(network_size, installed = true, permissions = '')
+        network_size = 50 if network_size > 50 # FB's max is 50
+        users = (0...network_size).collect { create(installed, permissions) }
+        friends = users.clone
+        users.each do |user|
+          # Remove this user from list of friends
+          friends.delete_at(0)
+          # befriend all the others
+          friends.each do |friend|
+            befriend(user, friend)
+          end
+        end
+        return users
+      end
+      
+      protected
+      
+      def accounts_path
+        @accounts_path ||= "/#{@app_id}/accounts/test-users"
+      end
+
+    end # TestUserMethods
+  end # Facebook
+end # Koala

data/lib/koala/uploadable_io.rb

@@ -0,0 +1,115 @@
+require 'koala'
+
+module Koala
+  class UploadableIO
+    attr_reader :io_or_path, :content_type
+
+    def initialize(io_or_path_or_mixed, content_type = nil)
+      # see if we got the right inputs
+      if content_type.nil?
+        parse_init_mixed_param io_or_path_or_mixed
+      elsif !content_type.nil? && (io_or_path_or_mixed.respond_to?(:read) or io_or_path_or_mixed.kind_of?(String))
+        @io_or_path = io_or_path_or_mixed
+        @content_type = content_type
+      end
+      
+      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")
+    end
+    
+    def to_file
+      @io_or_path.is_a?(String) ? File.open(@io_or_path) : @io_or_path
+    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
+      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 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
+      
+      # 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
+      
+      def parse_string_path(path)
+        if path.kind_of?(String)
+          @io_or_path = path
+          @content_type = detect_mime_type(path)
+        end
+      end
+      
+      MIME_TYPE_STRATEGIES = [
+        :use_mime_module,
+        :use_simple_detection
+      ]
+      
+      def detect_mime_type(filename)
+        if filename
+          MIME_TYPE_STRATEGIES.each do |method|
+            result = send(method, filename)
+            return result if result
+          end
+        end
+        nil # if we can't find anything
+      end
+      
+      def use_mime_module(filename)
+        # if the user has installed mime/types, we can use that
+        # if not, rescue and return nil
+        begin
+          type = MIME::Types.type_for(filename).first
+          type ? type.to_s : nil
+        rescue
+          nil
+        end
+      end
+      
+      def use_simple_detection(filename)
+        # very rudimentary extension analysis for images
+        # first, get the downcased extension, or an empty string if it doesn't exist
+        extension = ((filename.match(/\.([a-zA-Z0-9]+)$/) || [])[1] || "").downcase
+        if extension == ""
+          nil
+        elsif extension == "jpg" || extension == "jpeg"
+          "image/jpeg"
+        elsif extension == "png"
+          "image/png"
+        elsif extension == "gif"
+          "image/gif"
+        end
+      end
+  end
+end