koala 0.9.0 → 1.1.0

data/lib/koala/http_services.rb

@@ -8,64 +8,39 @@ module Koala
     end
   end
 
-  module NetHTTPService
-    # this service uses Net::HTTP to send requests to the graph
+  module HTTPService
+    # common functionality for all HTTP services
     def self.included(base)
       base.class_eval do
-        require 'net/http' unless defined?(Net::HTTP)
-        require 'net/https'
-
-        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.
-
-          # 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)}"))
-            Koala::Response.new(response.code.to_i, body, response)
-          }
+        class << self
+          attr_accessor :always_use_ssl, :proxy, :timeout
         end
 
-        protected
+        def self.server(options = {})
+          server = "#{options[:rest_api] ? Facebook::REST_SERVER : Facebook::GRAPH_SERVER}"
+          server.gsub!(/\.facebook/, "-video.facebook") if options[:video]
+          "#{options[:beta] ? "beta." : ""}#{server}"
+        end
+        
         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
+          ((param_hash || {}).collect do |key_and_value|
+            key_and_value[1] = MultiJson.encode(key_and_value[1]) unless key_and_value[1].is_a? String
             "#{key_and_value[0].to_s}=#{CGI.escape key_and_value[1]}"
           end).join("&")
         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
-
-        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
-          typhoeus_options = {:params => args}.merge(options[:typhoeus_options] || {})
-          response = self.send(verb, "https://#{server}#{path}", typhoeus_options)
-          Koala::Response.new(response.code, response.body, response.headers_hash)
+                                      
+        protected
+        
+        def self.params_require_multipart?(param_hash)
+          param_hash.any? { |key, value| value.kind_of?(Koala::UploadableIO) }
         end
-      end # class_eval
+    
+        def self.multipart_requires_content_type?
+          true
+        end
+      end
     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 = MultiJson.decode(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
+
+        MultiJson.decode(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((MultiJson.decode(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

data/lib/koala/realtime_updates.rb

@@ -46,6 +46,8 @@ module Koala
           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
       
       # subscribes for realtime updates
@@ -59,7 +61,7 @@ module Koala
           :verify_token => verify_token
         }
         # a subscription is a success if Facebook returns a 200 (after hitting your server for verification)
-        api(subscription_path, args, 'post', :http_component => :status) == 200
+        @graph_api.graph_call(subscription_path, args, 'post', :http_component => :status) == 200
       end
           
       # removes subscription for object
@@ -67,24 +69,13 @@ module Koala
       def unsubscribe(object = nil)
         args = {}
         args[:object] = object if object
-        api(subscription_path, args, 'delete', :http_component => :status) == 200
+        @graph_api.graph_call(subscription_path, args, 'delete', :http_component => :status) == 200
       end
   
       def list_subscriptions
-        api(subscription_path)["data"]
+        @graph_api.graph_call(subscription_path)["data"]
       end
       
-      def api(*args) # same as GraphAPI
-        response = super(*args) do |response|
-          # check for subscription errors
-          if response.is_a?(Hash) && error_details = response["error"]
-            raise APIError.new(error_details)
-          end
-        end
-      
-        response
-      end    
-      
       protected
       
       def subscription_path

data/lib/koala/rest_api.rb

@@ -1,23 +1,95 @@
 module Koala
   module Facebook
     REST_SERVER = "api.facebook.com"
-    
+
     module RestAPIMethods
-      def fql_query(fql)
-        rest_call('fql.query', 'query' => fql)
+      def fql_query(fql, args = {}, options = {})
+        rest_call('fql.query', args.merge(:query => fql), options) 
       end
-      
-      def rest_call(method, args = {})
-        response = api("method/#{method}", args.merge('format' => 'json'), 'get', :rest_api => true) do |response|
+
+      def fql_multiquery(queries = {}, args = {}, options = {})
+        if results = rest_call('fql.multiquery', args.merge(:queries => MultiJson.encode(queries)), options)
+          # simplify the multiquery result format
+          results.inject({}) {|outcome, data| outcome[data["name"]] = data["fql_result_set"]; outcome}
+        end
+      end
+
+      def rest_call(fb_method, args = {}, options = {}, method = "get")
+        options = options.merge!(:rest_api => true, :read_only => READ_ONLY_METHODS.include?(fb_method.to_s))
+
+        api("method/#{fb_method}", args.merge('format' => 'json'), method, 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
+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,175 @@
+require 'koala'
+
+module Koala
+  class UploadableIO
+    attr_reader :io_or_path, :content_type, :requires_base_http_service
+
+    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
+      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
+      
+      # 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, @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
+    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
+    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
+    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
+    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
+    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
+      case extension 
+        when ""
+          nil
+        # images
+        when "jpg", "jpeg"
+          "image/jpeg"
+        when "png"
+          "image/png"
+        when "gif"
+          "image/gif"
+
+        # 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