koala 1.3.0rc1 → 1.3.0rc2

data/lib/koala/http_service/multipart_request.rb

@@ -0,0 +1,41 @@
+require 'faraday'
+
+module Koala  
+  module HTTPService
+    class MultipartRequest < Faraday::Request::Multipart
+      # Facebook expects nested parameters to be passed in a certain way
+      # Based on our testing (https://github.com/arsduo/koala/issues/125),
+      # Faraday needs two changes to make that work:
+      # 1) [] need to be escaped (e.g. params[foo]=bar ==> params%5Bfoo%5D=bar)
+      # 2) such messages need to be multipart-encoded
+    
+      self.mime_type = 'multipart/form-data'.freeze
+    
+      def process_request?(env)
+        # if the request values contain any hashes or arrays, multipart it
+        super || !!(env[:body].respond_to?(:values) && env[:body].values.find {|v| v.is_a?(Hash) || v.is_a?(Array)})
+      end   
+    
+    
+      def process_params(params, prefix = nil, pieces = nil, &block)
+        params.inject(pieces || []) do |all, (key, value)|
+          key = "#{prefix}%5B#{key}%5D" if prefix
+
+          case value
+          when Array
+            values = value.inject([]) { |a,v| a << [nil, v] }
+            process_params(values, key, all, &block)
+          when Hash
+            process_params(value, key, all, &block)
+          else
+            all << block.call(key, value)
+          end
+        end
+      end
+    end
+  end
+  
+  # @private
+  # legacy support for when MultipartRequest lived directly under Koala
+  MultipartRequest = HTTPService::MultipartRequest  
+end

data/lib/koala/http_service/response.rb

@@ -0,0 +1,18 @@
+module Koala
+  module HTTPService
+    class Response
+      attr_reader :status, :body, :headers
+
+      # Creates a new Response object, which standardizes the response received by Facebook for use within Koala.
+      def initialize(status, body, headers)
+        @status = status
+        @body = body
+        @headers = headers
+      end
+    end
+  end
+  
+  # @private
+  # legacy support for when Response lived directly under Koala
+  Response = HTTPService::Response
+end

data/lib/koala/http_service/uploadable_io.rb

@@ -0,0 +1,187 @@
+require "net/http/post/multipart"
+
+module Koala
+  module HTTPService
+    class UploadableIO
+      attr_reader :io_or_path, :content_type, :filename
+
+      def initialize(io_or_path_or_mixed, content_type = nil, filename = nil)
+        # see if we got the right inputs
+        parse_init_mixed_param io_or_path_or_mixed, content_type
+
+        # filename is used in the Ads API
+        # if it's provided, take precedence over the detected filename
+        # otherwise, fall back to a dummy name
+        @filename = 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
+      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,
+        :parse_io
+      ]
+
+      def parse_init_mixed_param(mixed, content_type = nil)
+        PARSE_STRATEGIES.each do |method|
+          send(method, mixed, content_type)
+          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, content_type = nil)
+        if UploadableIO.rails_3_param?(uploaded_file)
+          @io_or_path = uploaded_file.tempfile.path
+          @content_type = content_type || uploaded_file.content_type
+          @filename = uploaded_file.original_filename
+        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, content_type = nil)
+        if UploadableIO.sinatra_param?(file_hash)
+          @io_or_path = file_hash[:tempfile]
+          @content_type = content_type || file_hash[:type] || detect_mime_type(tempfile)
+          @filename = file_hash[:filename]
+        end
+      end
+
+      # takes a file object
+      def self.file_param?(file)
+        file.kind_of?(File)
+      end
+
+      def parse_file_object(file, content_type = nil)
+        if UploadableIO.file_param?(file)
+          @io_or_path = file
+          @content_type = content_type || detect_mime_type(file.path)
+          @filename = File.basename(file.path)
+        end
+      end
+
+      def parse_string_path(path, content_type = nil)
+        if path.kind_of?(String)
+          @io_or_path = path
+          @content_type = content_type || detect_mime_type(path)
+          @filename = File.basename(path)
+        end
+      end
+
+      def parse_io(io, content_type = nil)
+        if io.respond_to?(:read)
+          @io_or_path = io
+          @content_type = content_type
+        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
+  
+  # @private
+  # legacy support for when UploadableIO lived directly under Koala
+  UploadableIO = HTTPService::UploadableIO
+end

data/lib/koala/oauth.rb

@@ -1,3 +1,7 @@
+# OpenSSL and Base64 are required to support signed_request
+require 'openssl'
+require 'base64'
+
 module Koala
   module Facebook
     
@@ -5,21 +9,29 @@ module Koala
     
     class OAuth
       attr_reader :app_id, :app_secret, :oauth_callback_url
+      
+      # Creates a new OAuth client.
+      #
+      # @param app_id [String, Integer] a Facebook application ID
+      # @param app_secret a Facebook application secret
+      # @param oauth_callback_url the URL in your app to which users authenticating with OAuth will be sent
       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
       
+      # Parses the cookie set Facebook's JavaScript SDK.
+      #
+      # @note in parsing Facebook's new signed cookie format this method has to make a request to Facebook.
+      #       We recommend storing authenticated user info in your Rails session (or equivalent) and only
+      #       calling this when needed.
+      #
+      # @param cookie_hash a set of cookies that includes the Facebook cookie.  
+      #                     You can pass Rack/Rails/Sinatra's cookie hash directly to this method.
+      #
+      # @return the authenticated user's information as a hash, or nil.
       def get_user_info_from_cookie(cookie_hash)
-        # Parses the cookie set Facebook's JavaScript SDK.
-        # You can pass Rack/Rails/Sinatra's cookie hash directly to this method.
-        #
-        # 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.
-
         if signed_cookie = cookie_hash["fbsr_#{@app_id}"]
           parse_signed_cookie(signed_cookie)
         elsif unsigned_cookie = cookie_hash["fbs_#{@app_id}"]
@@ -28,6 +40,13 @@ module Koala
       end
       alias_method :get_user_info_from_cookies, :get_user_info_from_cookie
 
+      # Parses the cookie set Facebook's JavaScript SDK and returns only the user ID.
+      #
+      # @note (see #get_user_info_from_cookie)
+      #
+      # @param (see #get_user_info_from_cookie)
+      #
+      # @return the authenticated user's Facebook ID, or nil.
       def get_user_from_cookie(cookies)
         if info = get_user_info_from_cookies(cookies)
           # signed cookie has user_id, unsigned cookie has uid
@@ -38,6 +57,23 @@ module Koala
 
       # URLs
       
+      # Builds an OAuth URL, where users will be prompted to log in and for any desired permissions.
+      # When the users log in, you receive a callback with their   
+      # See http://developers.facebook.com/docs/authentication/.
+      #
+      # @see #url_for_access_token
+      #
+      # @note The server-side authentication and dialog methods should only be used 
+      #       if your application can't use the Facebook Javascript SDK,
+      #       which provides a much better user experience.
+      #       See http://developers.facebook.com/docs/reference/javascript/.
+      #
+      # @param options any query values to add to the URL, as well as any special/required values listed below.
+      # @option options permissions an array or comma-separated string of desired permissions
+      # 
+      # @raise ArgumentError if no OAuth callback was specified in OAuth#new or in options as :redirect_uri
+      #
+      # @return an OAuth URL you can send your users to
       def url_for_oauth_code(options = {})
         # for permissions, see http://developers.facebook.com/docs/authentication/permissions
         if permissions = options.delete(:permissions)
@@ -49,6 +85,20 @@ module Koala
         build_url("https://#{GRAPH_SERVER}/oauth/authorize", true, url_options)
       end
 
+      # Once you receive an OAuth code, you need to redeem it from Facebook using an appropriate URL.
+      # (This is done by your server behind the scenes.)
+      # See http://developers.facebook.com/docs/authentication/.
+      # 
+      # @see #url_for_oauth_code
+      # 
+      # @note (see #url_for_oauth_code)
+      #
+      # @param code an OAuth code received from Facebook
+      # @param options any additional query parameters to add to the URL
+      #
+      # @raise (see #url_for_oauth_code)
+      #
+      # @return an URL your server can query for the user's access token
       def url_for_access_token(code, options = {})
         # Creates the URL for the token corresponding to a given code generated by Facebook
         url_options = {
@@ -59,6 +109,15 @@ module Koala
         build_url("https://#{GRAPH_SERVER}/oauth/access_token", true, url_options)
       end
 
+      # Builds a URL for a given dialog (feed, friends, OAuth, pay, send, etc.)
+      # See http://developers.facebook.com/docs/reference/dialogs/.
+      # 
+      # @note (see #url_for_oauth_code)
+      #
+      # @param dialog_type the kind of Facebook dialog you want to show
+      # @param options any additional query parameters to add to the URL
+      #
+      # @return an URL your server can query for the user's access token
       def url_for_dialog(dialog_type, options = {})
         # some endpoints require app_id, some client_id, supply both doesn't seem to hurt
         url_options = {:app_id => @app_id, :client_id => @app_id}.merge(options)        
@@ -67,12 +126,36 @@ module Koala
       
       # access tokens
       
+      # Fetches an access token, token expiration, and other info from Facebook.
+      # Useful when you've received an OAuth code using the server-side authentication process.
+      # @see url_for_oauth_code
+      #
+      # @note (see #url_for_oauth_code)
+      # 
+      # @param code (see #url_for_access_token)
+      # @param options any additional parameters to send to Facebook when redeeming the token
+      # 
+      # @raise Koala::Facebook::APIError if Facebook returns an error response 
+      # 
+      # @return a hash of the access token info returned by Facebook (token, expiration, etc.) 
       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 => options[:redirect_uri] || @oauth_callback_url}, false, options)
       end
 
+      
+      # Fetches the access token (ignoring expiration and other info) from Facebook.
+      # Useful when you've received an OAuth code using the server-side authentication process.
+      # @see get_access_token_info
+      # 
+      # @note (see #url_for_oauth_code)
+      # 
+      # @param (see #get_access_token_info)
+      #
+      # @raise (see #get_access_token_info)
+      #
+      # @return the access token
       def get_access_token(code, options = {})
         # upstream methods will throw errors if needed
         if info = get_access_token_info(code, options)
@@ -80,22 +163,36 @@ module Koala
         end
       end
 
+      # Fetches the application's access token, along with any other information provided by Facebook.
+      # See http://developers.facebook.com/docs/authentication/ (search for App Login).
+      # 
+      # @param options any additional parameters to send to Facebook when redeeming the token
+      #
+      # @return the application access token and other information (expiration, etc.)
       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
 
+      # Fetches the application's access token (ignoring expiration and other info).
+      # @see get_app_access_token_info
+      # 
+      # @param (see #get_app_access_token_info)
+      #
+      # @return the application access token
       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.
+      # Parses a signed request string provided by Facebook to canvas apps or in a secure cookie.
+      #
+      # @param input the signed request from Facebook
+      # 
+      # @raise RuntimeError if the signature is incomplete, invalid, or using an unsupported algorithm
+      # 
+      # @return a hash of the validated request information 
       def parse_signed_request(input)
         encoded_sig, encoded_envelope = input.split('.', 2)
         raise 'SignedRequest: Invalid (incomplete) signature data' unless encoded_sig && encoded_envelope
@@ -112,8 +209,12 @@ module Koala
         envelope
       end
 
-      # from session keys
+      # Old session key code
+      
+      # @deprecated Facebook no longer provides session keys.
       def get_token_info_from_session_keys(sessions, options = {})
+        Koala::Utils.deprecate("Facebook no longer provides session keys. The relevant OAuth methods will be removed in the next release.")
+
         # fetch the OAuth tokens from Facebook
         response = fetch_token_string({
           :type => 'client_cred',
@@ -131,6 +232,7 @@ module Koala
         MultiJson.decode(response)
       end
 
+      # @deprecated (see #get_token_info_from_session_keys)
       def get_tokens_from_session_keys(sessions, options = {})
         # get the original hash results
         results = get_token_info_from_session_keys(sessions, options)
@@ -138,6 +240,7 @@ module Koala
         results.collect { |r| r ? r["access_token"] : nil }
       end
 
+      # @deprecated (see #get_token_info_from_session_keys)
       def get_token_from_session_key(session, options = {})
         # convenience method for a single key
         # gets the overlaoded strings automatically