koala 0.4 → 3.7.0

data/lib/koala/http_service/response.rb

@@ -0,0 +1,20 @@
+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
+
+      def data
+        # quirks_mode is needed because Facebook sometimes returns a raw true or false value --
+        # in Ruby 2.4 we can drop that.
+        @data ||= JSON.parse(body, quirks_mode: true) unless body.empty?
+      end
+    end
+  end
+end

data/lib/koala/http_service/uploadable_io.rb

@@ -0,0 +1,183 @@
+require "tempfile"
+
+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) || file.kind_of?(Tempfile)
+      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
+end

data/lib/koala/http_service.rb

@@ -0,0 +1,108 @@
+require 'faraday'
+require 'faraday/multipart' unless defined? Faraday::FilePart # hack for faraday < 1.9 to avoid warnings
+require 'koala/http_service/uploadable_io'
+require 'koala/http_service/response'
+require 'koala/http_service/request'
+
+module Koala
+  module HTTPService
+    class << self
+      # 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.request :multipart
+      builder.request :url_encoded
+      builder.adapter Faraday.default_adapter
+    end
+
+    # Default server information for Facebook. These can be overridden by setting config values.
+    # See Koala.config.
+    DEFAULT_SERVERS = {
+      :graph_server => 'graph.facebook.com',
+      :dialog_host => 'www.facebook.com',
+      :host_path_matcher => /\.facebook/,
+      :video_replace => '-video.facebook',
+      :beta_replace => '.beta.facebook'
+    }
+
+    # 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
+    #
+    # @param request a Koala::HTTPService::Request object
+    #
+    # @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(request)
+      # set up our Faraday connection
+      conn = Faraday.new(request.server, faraday_options(request.options), &(faraday_middleware || DEFAULT_MIDDLEWARE))
+
+      filtered_args = request.raw_args.dup.transform_keys(&:to_s)
+
+      if Koala.config.mask_tokens
+        %w(access_token input_token).each do |arg_token|
+          if (token = filtered_args[arg_token])
+            filtered_args[arg_token] = token[0, 10] + '*****' + token[-5, 5]
+          end
+        end
+      end
+
+      Koala::Utils.debug "STARTED => #{request.verb.upcase}: #{request.path} params: #{filtered_args.inspect}"
+
+      if request.verb == "post" && request.json?
+        # JSON requires a bit more handling
+        # remember, all non-GET requests are turned into POSTs, so this covers everything but GETs
+        response = conn.post do |req|
+          req.path = request.path
+          req.headers["Content-Type"] = "application/json"
+          req.body = request.post_args.to_json
+          req
+        end
+      else
+        response = conn.send(request.verb, request.path, request.post_args)
+      end
+
+      Koala::Utils.debug "FINISHED => #{request.verb.upcase}: #{request.path} params: #{filtered_args.inspect}"
+      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)
+      ((param_hash || {}).sort_by{|k, v| k.to_s}.collect do |key_and_value|
+        value = key_and_value[1]
+        unless value.is_a? String
+          value = value.to_json
+        end
+        "#{key_and_value[0].to_s}=#{CGI.escape value}"
+      end).join("&")
+    end
+
+    private
+
+    def self.faraday_options(options)
+      valid_options = [:request, :proxy, :ssl, :builder, :url, :parallel_manager, :params, :headers, :builder_class]
+      Hash[ options.select { |key,value| valid_options.include?(key) } ]
+    end
+  end
+end

data/lib/koala/oauth.rb

@@ -0,0 +1,342 @@
+# OpenSSL and Base64 are required to support signed_request
+require 'openssl'
+require 'base64'
+
+module Koala
+  module Facebook
+    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 = nil, app_secret = nil, oauth_callback_url = nil)
+        @app_id = app_id || Koala.config.app_id
+        @app_secret = app_secret || Koala.config.app_secret
+        @oauth_callback_url = oauth_callback_url || Koala.config.oauth_callback_url
+      end
+
+      # Parses the cookie set Facebook's JavaScript SDK.
+      #
+      # @note this method can only be called once per session, as the OAuth code
+      #       Facebook supplies can only be redeemed once.  Your application
+      #       must handle cross-request storage of this information; you can no
+      #       longer call this method multiple times.  (This works out, as the
+      #       method has to make a call to FB's servers anyway, which you don't
+      #       want on every call.)
+      #
+      # @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_cookie, :get_user_info_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
+      # @option options state a unique string to serve as a CSRF (cross-site request
+      #                 forgery) token -- highly recommended for security. See
+      #                 https://developers.facebook.com/docs/howtos/login/server-side-login/
+      #
+      # @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)
+          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
+        build_url(:dialog_host, "/dialog/oauth", 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 = {
+          :client_id => @app_id,
+          :code => code,
+          :client_secret => @app_secret
+        }.merge(options)
+        build_url(: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(:dialog_host, "/dialog/#{dialog_type}", true, url_options)
+      end
+
+      # Generates a 'client code' from a server side long-lived access token. With the generated
+      # code, it can be sent to a client application which can then use it to get a long-lived
+      # access token from Facebook. After which the clients can use that access token to make
+      # requests to Facebook without having to use the server token, yet the server access token
+      # remains valid.
+      # See https://developers.facebook.com/docs/facebook-login/access-tokens/#long-via-code
+      #
+      # @param access_token a user's long lived (server) access token
+      #
+      # @raise Koala::Facebook::ServerError if Facebook returns a server error (status >= 500)
+      # @raise Koala::Facebook::OAuthTokenRequestError if Facebook returns an error response (status >= 400)
+      # @raise Koala::Facebook::BadFacebookResponse if Facebook returns a blank response
+      # @raise Koala::KoalaError if response does not contain 'code' hash key
+      #
+      # @return a string of the generated 'code'
+      def generate_client_code(access_token)
+        response = fetch_token_string({:redirect_uri => @oauth_callback_url, :access_token => access_token}, false, 'client_code')
+
+        # Facebook returns an empty body in certain error conditions
+        if response == ''
+          raise BadFacebookResponse.new(200, '', 'generate_client_code received an error: empty response body')
+        else
+          result = JSON.parse(response)
+        end
+
+        result.has_key?('code') ? result['code'] : raise(Koala::KoalaError.new("Facebook returned a valid response without the expected 'code' in the body (response = #{response})"))
+      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::OAuthTokenRequestError 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)
+          string = info["access_token"]
+        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({:grant_type => 'client_credentials'}, 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)
+          info["access_token"]
+        end
+      end
+
+      # Fetches an access_token with extended expiration time, along with any other information provided by Facebook.
+      # See https://developers.facebook.com/docs/offline-access-deprecation/#extend_token (search for fb_exchange_token).
+      #
+      # @param access_token the access token to exchange
+      # @param options any additional parameters to send to Facebook when exchanging tokens.
+      #
+      # @return the access token with extended expiration time and other information (expiration, etc.)
+      def exchange_access_token_info(access_token, options = {})
+        get_token_from_server({
+          :grant_type => 'fb_exchange_token',
+          :fb_exchange_token => access_token
+        }, true, options)
+      end
+
+      # Fetches an access token with extended expiration time (ignoring expiration and other info).
+
+      # @see exchange_access_token_info
+      #
+      # @param (see #exchange_access_token_info)
+      #
+      # @return A new access token or the existing one, set to expire in 60 days.
+      def exchange_access_token(access_token, options = {})
+        if info = exchange_access_token_info(access_token, options)
+          info["access_token"]
+        end
+      end
+
+      # Parses a signed request string provided by Facebook to canvas apps or in a secure cookie.
+      #
+      # @param input the signed request from Facebook
+      #
+      # @raise OAuthSignatureError 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 OAuthSignatureError, 'Invalid (incomplete) signature data' unless encoded_sig && encoded_envelope
+
+        signature = base64_url_decode(encoded_sig).unpack("H*").first
+        envelope = JSON.parse(base64_url_decode(encoded_envelope))
+
+        raise OAuthSignatureError, "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)
+        raise OAuthSignatureError, 'Invalid signature' if (signature != hmac)
+
+        envelope
+      end
+
+      protected
+
+      def get_token_from_server(args, post = false, options = {})
+        # fetch the result from Facebook's servers
+        response = fetch_token_string(args, post, "access_token", options)
+        parse_access_token(response)
+      end
+
+      def parse_access_token(response_text)
+        JSON.parse(response_text)
+      rescue JSON::ParserError
+        response_text.split("&").inject({}) do |hash, bit|
+          key, value = bit.split("=")
+          hash.merge!(key => value)
+        end
+      end
+
+      def parse_unsigned_cookie(fb_cookie)
+        # 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
+
+      def parse_signed_cookie(fb_cookie)
+        components = parse_signed_request(fb_cookie)
+        if code = components["code"]
+          begin
+            token_info = get_access_token_info(code, :redirect_uri => '')
+          rescue Koala::Facebook::OAuthTokenRequestError => err
+            if err.fb_error_type == 'OAuthException' && err.fb_error_message =~ /Code was invalid or expired/
+              return nil
+            else
+              raise
+            end
+          end
+
+          components.merge(token_info) if token_info
+        else
+          Koala::Utils.logger.warn("Signed cookie didn't contain Facebook OAuth code! Components: #{components}")
+          nil
+        end
+      end
+
+      def fetch_token_string(args, post = false, endpoint = "access_token", options = {})
+        response = Koala.make_request("/oauth/#{endpoint}", {
+          :client_id => @app_id,
+          :client_secret => @app_secret
+        }.merge!(args), post ? "post" : "get", {:use_ssl => true}.merge!(options))
+
+        raise ServerError.new(response.status, response.body) if response.status >= 500
+        raise OAuthTokenRequestError.new(response.status, response.body) if response.status >= 400
+
+        response.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
+
+      def server_url(type)
+        url = "https://#{Koala.config.send(type)}"
+        if version = Koala.config.api_version
+          "#{url}/#{version}"
+        else
+          url
+        end
+      end
+
+      def build_url(type, path, require_redirect_uri = false, url_options = {})
+        if require_redirect_uri && !(url_options[:redirect_uri] ||= url_options.delete(:callback) || @oauth_callback_url)
+          raise ArgumentError, "build_url must get a callback either from the OAuth object or in the parameters!"
+        end
+        params = Koala::HTTPService.encode_params(url_options)
+        "#{server_url(type)}#{path}?#{params}"
+      end
+    end
+  end
+end