koala 1.2.1 → 1.3.0

data/lib/koala/http_service.rb

@@ -1,30 +1,37 @@
 require 'faraday'
+require 'koala/http_service/multipart_request'
+require 'koala/http_service/uploadable_io'
+require 'koala/http_service/response'
 
 module Koala
-  class Response
-    attr_reader :status, :body, :headers
-    def initialize(status, body, headers)
-      @status = status
-      @body = body
-      @headers = headers
-    end
-  end
-
-  module HTTPService
-    # common functionality for all HTTP services
-
+  module HTTPService    
     class << self
-      attr_accessor :faraday_middleware, :http_options
+      # A customized stack of Faraday middleware that will be used to make each request.
+      attr_accessor :faraday_middleware
+      # A default set of HTTP options (see https://github.com/arsduo/koala/wiki/HTTP-Services)
+      attr_accessor :http_options
     end
 
     @http_options ||= {}
     
+    # Koala's default middleware stack. 
+    # We encode requests in a Facebook-compatible multipart request, 
+    # and use whichever adapter has been configured for this application.
     DEFAULT_MIDDLEWARE = Proc.new do |builder|
-      builder.use Koala::MultipartRequest
+      builder.use Koala::HTTPService::MultipartRequest
       builder.request :url_encoded
       builder.adapter Faraday.default_adapter
     end
 
+    # The address of the appropriate Facebook server.
+    #
+    # @param options various flags to indicate which server to use.
+    # @option options :rest_api use the old REST API instead of the Graph API
+    # @option options :video use the server designated for video uploads
+    # @option options :beta use the beta tier
+    # @option options :use_ssl force https, even if not needed
+    # 
+    # @return a complete server address with protocol
     def self.server(options = {})
       server = "#{options[:rest_api] ? Facebook::REST_SERVER : Facebook::GRAPH_SERVER}"
       server.gsub!(/\.facebook/, "-video.facebook") if options[:video]
@@ -32,6 +39,23 @@ module Koala
       "#{options[:use_ssl] ? "https" : "http"}://#{server}"
     end
 
+    # Makes a request directly to Facebook.
+    # @note You'll rarely need to call this method directly.
+    #
+    # @see Koala::Facebook::API#api
+    # @see Koala::Facebook::GraphAPIMethods#graph_call
+    # @see Koala::Facebook::RestAPIMethods#rest_call
+    #
+    # @param path the server path for this request
+    # @param args (see Koala::Facebook::API#api)
+    # @param verb the HTTP method to use.  
+    #             If not get or post, this will be turned into a POST request with the appropriate :method
+    #             specified in the arguments.           
+    # @param options (see Koala::Facebook::API#api)
+    #
+    # @raise an appropriate connection error if unable to make the request to Facebook
+    #
+    # @return [Koala::HTTPService::Response] a response object representing the results from Facebook
     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"
@@ -48,13 +72,20 @@ module Koala
       conn = Faraday.new(server(request_options), request_options, &(faraday_middleware || DEFAULT_MIDDLEWARE))
 
       response = conn.send(verb, path, (verb == "post" ? params : {}))
-      Koala::Response.new(response.status.to_i, response.body, response.headers)
-    end
-
+      Koala::HTTPService::Response.new(response.status.to_i, response.body, response.headers)
+    end
+
+    # Encodes a given hash into a query string.  
+    # This is used mainly by the Batch API nowadays, since Faraday handles this for regular cases.
+    # 
+    # @param params_hash a hash of values to CGI-encode and appropriately join
+    # 
+    # @example
+    #   Koala.http_service.encode_params({:a => 2, :b => "My String"})
+    #   => "a=2&b=My+String"
+    #
+    # @return the appropriately-encoded string
     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
-      # this is used mainly by the Batch API nowadays
       ((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]}"
@@ -64,76 +95,92 @@ module Koala
     # deprecations
     # not elegant or compact code, but temporary
     
+    # @private
     def self.always_use_ssl
       Koala::Utils.deprecate("HTTPService.always_use_ssl is now HTTPService.http_options[:use_ssl]; always_use_ssl will be removed in a future version.")
       http_options[:use_ssl]
     end
 
+    # @private
     def self.always_use_ssl=(value)
       Koala::Utils.deprecate("HTTPService.always_use_ssl is now HTTPService.http_options[:use_ssl]; always_use_ssl will be removed in a future version.")
       http_options[:use_ssl] = value
     end
     
+    # @private
     def self.timeout
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout]
     end
 
+    # @private
     def self.timeout=(value)
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout] = value
     end
     
+    # @private
     def self.timeout
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout]
     end
 
+    # @private
     def self.timeout=(value)
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout] = value
     end
     
+    # @private
     def self.proxy
       Koala::Utils.deprecate("HTTPService.proxy is now HTTPService.http_options[:proxy]; .proxy will be removed in a future version.")
       http_options[:proxy]
     end
 
+    # @private
     def self.proxy=(value)
       Koala::Utils.deprecate("HTTPService.proxy is now HTTPService.http_options[:proxy]; .proxy will be removed in a future version.")
       http_options[:proxy] = value
     end
     
+    # @private
     def self.ca_path
       Koala::Utils.deprecate("HTTPService.ca_path is now (HTTPService.http_options[:ssl] ||= {})[:ca_path]; .ca_path will be removed in a future version.")
       (http_options[:ssl] || {})[:ca_path]
     end
 
+    # @private
     def self.ca_path=(value)
       Koala::Utils.deprecate("HTTPService.ca_path is now (HTTPService.http_options[:ssl] ||= {})[:ca_path]; .ca_path will be removed in a future version.")
       (http_options[:ssl] ||= {})[:ca_path] = value
     end
     
+    # @private
     def self.ca_file
       Koala::Utils.deprecate("HTTPService.ca_file is now (HTTPService.http_options[:ssl] ||= {})[:ca_file]; .ca_file will be removed in a future version.")
       (http_options[:ssl] || {})[:ca_file]
     end
 
+    # @private
     def self.ca_file=(value)
       Koala::Utils.deprecate("HTTPService.ca_file is now (HTTPService.http_options[:ssl] ||= {})[:ca_file]; .ca_file will be removed in a future version.")
       (http_options[:ssl] ||= {})[:ca_file] = value
     end
 
+    # @private
     def self.verify_mode
       Koala::Utils.deprecate("HTTPService.verify_mode is now (HTTPService.http_options[:ssl] ||= {})[:verify_mode]; .verify_mode will be removed in a future version.")
       (http_options[:ssl] || {})[:verify_mode]
     end
 
+    # @private
     def self.verify_mode=(value)
       Koala::Utils.deprecate("HTTPService.verify_mode is now (HTTPService.http_options[:ssl] ||= {})[:verify_mode]; .verify_mode will be removed in a future version.")
       (http_options[:ssl] ||= {})[:verify_mode] = value
     end
 
+    private 
+    
     def self.process_options(options)
       if typhoeus_options = options.delete(:typhoeus_options)
         Koala::Utils.deprecate("typhoeus_options should now be included directly in the http_options hash.  Support for this key will be removed in a future version.")
@@ -159,6 +206,7 @@ module Koala
     end   
   end
   
+  # @private
   module TyphoeusService
     def self.deprecated_interface
       # support old-style interface with a warning
@@ -167,6 +215,7 @@ module Koala
     end
   end
 
+  # @private
   module NetHTTPService
     def self.deprecated_interface
       # support old-style interface with a warning

data/lib/koala/oauth.rb

@@ -1,66 +1,165 @@
+# OpenSSL and Base64 are required to support signed_request
+require 'openssl'
+require 'base64'
+
 module Koala
   module Facebook
+    
+    DIALOG_HOST = "www.facebook.com"
+    
     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
-
-      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.
-
+      
+      # 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_cookies(cookie_hash)
         if signed_cookie = cookie_hash["fbsr_#{@app_id}"]
           parse_signed_cookie(signed_cookie)
         elsif unsigned_cookie = cookie_hash["fbs_#{@app_id}"]
           parse_unsigned_cookie(unsigned_cookie)
         end
       end
-      alias_method :get_user_info_from_cookies, :get_user_info_from_cookie
+      alias_method :get_user_info_from_cookie, :get_user_info_from_cookies
 
-      def get_user_from_cookie(cookies)
-        if info = get_user_info_from_cookies(cookies)
-          # signed cookie has user_id, unsigned cookie has uid
-          string = info["user_id"] || info["uid"]
+      # 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_cookies(cookies)
+        if signed_cookie = cookies["fbsr_#{@app_id}"]
+          if components = parse_signed_request(signed_cookie)
+            components["user_id"]
+          end
+        elsif info = get_user_info_from_cookies(cookies)
+          # Parsing unsigned cookie
+          info["uid"]
         end
       end
-      alias_method :get_user_from_cookies, :get_user_from_cookie
+      alias_method :get_user_from_cookie, :get_user_from_cookies
 
       # 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
-        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
-
+        if permissions = options.delete(:permissions)
+          options[:scope] = permissions.is_a?(Array) ? permissions.join(",") : permissions
+        end
+        url_options = {:client_id => @app_id}.merge(options)
+        
         # 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}"
+        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
-        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}"
+        url_options = {
+          :client_id => @app_id, 
+          :code => code,
+          :client_secret => @app_secret
+        }.merge(options)
+        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)        
+        build_url("http://#{DIALOG_HOST}/dialog/#{dialog_type}", true, url_options)
+      end
+      
+      # 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)
@@ -68,22 +167,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
@@ -100,8 +213,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',
@@ -119,6 +236,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)
@@ -126,6 +244,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
@@ -169,8 +288,15 @@ module Koala
       
       def parse_signed_cookie(fb_cookie)
         components = parse_signed_request(fb_cookie)
-        if (code = components["code"]) && token_info = get_access_token_info(code, :redirect_uri => '')
-          components.merge(token_info)
+        if code = components["code"]
+          begin
+            token_info = get_access_token_info(code, :redirect_uri => '')
+          rescue Koala::Facebook::APIError => err
+            return nil if err.message =~ /Code was invalid or expired/
+            raise
+          end
+
+          components.merge(token_info) if token_info
         else
           nil
         end
@@ -189,6 +315,14 @@ module Koala
         str += '=' * (4 - str.length.modulo(4))
         Base64.decode64(str.tr('-_', '+/'))
       end
+      
+      def build_url(base, require_redirect_uri = false, url_options = {})
+        if require_redirect_uri && !(url_options[:redirect_uri] ||= url_options.delete(:callback) || @oauth_callback_url)          
+          raise ArgumentError, "url_for_dialog must get a callback either from the OAuth object or in the parameters!"
+        end
+        
+        "#{base}?#{Koala::HTTPService.encode_params(url_options)}"
+      end
     end
   end
 end