tyler_koala 1.2.0beta

data/lib/koala/http_service.rb

@@ -0,0 +1,161 @@
+require 'faraday'
+require 'faraday_stack'
+
+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
+
+    class << self
+      attr_accessor :faraday_middleware, :faraday_options
+    end
+
+    @faraday_options ||= {}
+    
+    DEFAULT_MIDDLEWARE = Proc.new do |builder|
+      builder.request :multipart
+      builder.request :url_encoded
+      builder.adapter Faraday.default_adapter
+    end
+
+    def self.server(options = {})
+      server = "#{options[:rest_api] ? Facebook::REST_SERVER : Facebook::GRAPH_SERVER}"
+      server.gsub!(/\.facebook/, "-video.facebook") if options[:video]
+      "#{options[:use_ssl] ? "https" : "http"}://#{options[:beta] ? "beta." : ""}#{server}"
+    end
+
+    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"
+
+      # turn all the keys to strings (Faraday has issues with symbols under 1.8.7) and resolve UploadableIOs
+      params = args.inject({}) {|hash, kv| hash[kv.first.to_s] = kv.last.is_a?(UploadableIO) ? kv.last.to_upload_io : kv.last; hash}
+
+      # figure out our options for this request   
+      http_options = {:params => (verb == "get" ? params : {})}.merge(faraday_options || {}).merge(process_options(options))
+      http_options[:use_ssl] = true if args["access_token"] # require http if there's a token
+
+      # set up our Faraday connection
+      # we have to manually assign params to the URL or the
+      conn = Faraday.new(server(http_options), http_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
+
+    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]}"
+      end).join("&")
+    end
+    
+    # deprecations
+    # not elegant or compact code, but temporary
+    
+    def self.always_use_ssl
+      Koala::Utils.deprecate("HTTPService.always_use_ssl is now HTTPService.faraday_options[:use_ssl]; always_use_ssl will be removed in a future version.")
+      faraday_options[:use_ssl]
+    end
+
+    def self.always_use_ssl=(value)
+      Koala::Utils.deprecate("HTTPService.always_use_ssl is now HTTPService.faraday_options[:use_ssl]; always_use_ssl will be removed in a future version.")
+      faraday_options[:use_ssl] = value
+    end
+    
+    def self.timeout
+      Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.faraday_options[:timeout]; .timeout will be removed in a future version.")
+      faraday_options[:timeout]
+    end
+
+    def self.timeout=(value)
+      Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.faraday_options[:timeout]; .timeout will be removed in a future version.")
+      faraday_options[:timeout] = value
+    end
+    
+    def self.timeout
+      Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.faraday_options[:timeout]; .timeout will be removed in a future version.")
+      faraday_options[:timeout]
+    end
+
+    def self.timeout=(value)
+      Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.faraday_options[:timeout]; .timeout will be removed in a future version.")
+      faraday_options[:timeout] = value
+    end
+    
+    def self.proxy
+      Koala::Utils.deprecate("HTTPService.proxy is now HTTPService.faraday_options[:proxy]; .proxy will be removed in a future version.")
+      faraday_options[:proxy]
+    end
+
+    def self.proxy=(value)
+      Koala::Utils.deprecate("HTTPService.proxy is now HTTPService.faraday_options[:proxy]; .proxy will be removed in a future version.")
+      faraday_options[:proxy] = value
+    end
+    
+    def self.ca_path
+      Koala::Utils.deprecate("HTTPService.ca_path is now (HTTPService.faraday_options[:ssl] ||= {})[:ca_path]; .ca_path will be removed in a future version.")
+      (faraday_options[:ssl] || {})[:ca_path]
+    end
+
+    def self.ca_path=(value)
+      Koala::Utils.deprecate("HTTPService.ca_path is now (HTTPService.faraday_options[:ssl] ||= {})[:ca_path]; .ca_path will be removed in a future version.")
+      (faraday_options[:ssl] ||= {})[:ca_path] = value
+    end
+    
+    def self.ca_file
+      Koala::Utils.deprecate("HTTPService.ca_file is now (HTTPService.faraday_options[:ssl] ||= {})[:ca_file]; .ca_file will be removed in a future version.")
+      (faraday_options[:ssl] || {})[:ca_file]
+    end
+
+    def self.ca_file=(value)
+      Koala::Utils.deprecate("HTTPService.ca_file is now (HTTPService.faraday_options[:ssl] ||= {})[:ca_file]; .ca_file will be removed in a future version.")
+      (faraday_options[:ssl] ||= {})[:ca_file] = value
+    end
+
+    def self.verify_mode
+      Koala::Utils.deprecate("HTTPService.verify_mode is now (HTTPService.faraday_options[:ssl] ||= {})[:verify_mode]; .verify_mode will be removed in a future version.")
+      (faraday_options[:ssl] || {})[:verify_mode]
+    end
+
+    def self.verify_mode=(value)
+      Koala::Utils.deprecate("HTTPService.verify_mode is now (HTTPService.faraday_options[:ssl] ||= {})[:verify_mode]; .verify_mode will be removed in a future version.")
+      (faraday_options[:ssl] ||= {})[:verify_mode] = value
+    end
+
+    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.")
+        options = options.merge(typhoeus_options)
+      end
+      
+      if ca_file = options.delete(:ca_file)
+        Koala::Utils.deprecate("http_options[:ca_file] should now be passed inside (http_options[:ssl] = {}) -- that is, http_options[:ssl][:ca_file].  Support for this key will be removed in a future version.")
+        (options[:ssl] ||= {})[:ca_file] = ca_file
+      end
+
+      if ca_path = options.delete(:ca_path)
+        Koala::Utils.deprecate("http_options[:ca_path] should now be passed inside (http_options[:ssl] = {}) -- that is, http_options[:ssl][:ca_path].  Support for this key will be removed in a future version.")
+        (options[:ssl] ||= {})[:ca_path] = ca_path
+      end
+
+      if verify_mode = options.delete(:verify_mode)
+        Koala::Utils.deprecate("http_options[:verify_mode] should now be passed inside (http_options[:ssl] = {}) -- that is, http_options[:ssl][:verify_mode].  Support for this key will be removed in a future version.")
+        (options[:ssl] ||= {})[:verify_mode] = verify_mode
+      end
+      
+      options
+    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

@@ -0,0 +1,89 @@
+module Koala
+  module Facebook
+    module RealtimeUpdateMethods
+      # note: to subscribe to real-time updates, you must have an application access token
+
+      def self.included(base)
+        # make the attributes readable
+        base.class_eval do
+          attr_reader :api, :app_id, :app_access_token, :secret
+
+          # parses the challenge params and makes sure the call is legitimate
+          # returns the challenge string to be sent back to facebook if true
+          # returns false otherwise
+          # this is a class method, since you don't need to know anything about the app
+          # saves a potential trip fetching the app access token
+          def self.meet_challenge(params, verify_token = nil, &verification_block)
+            if params["hub.mode"] == "subscribe" &&
+                # you can make sure this is legitimate through two ways
+                # if your store the token across the calls, you can pass in the token value
+                # and we'll make sure it matches
+                (verify_token && params["hub.verify_token"] == verify_token) ||
+                # alternately, if you sent a specially-constructed value (such as a hash of various secret values)
+                # you can pass in a block, which we'll call with the verify_token sent by Facebook
+                # if it's legit, return anything that evaluates to true; otherwise, return nil or false
+                (verification_block && yield(params["hub.verify_token"]))
+              params["hub.challenge"]
+            else
+              false
+            end
+          end
+        end
+      end
+
+      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 = API.new(@app_access_token)
+      end
+
+      # subscribes for realtime updates
+      # your callback_url must be set up to handle the verification request or the subscription will not be set up
+      # http://developers.facebook.com/docs/api/realtime
+      def subscribe(object, fields, callback_url, verify_token)
+        args = {
+          :object => object,
+          :fields => fields,
+          :callback_url => callback_url,
+          :verify_token => verify_token
+        }
+        # a subscription is a success if Facebook returns a 200 (after hitting your server for verification)
+        @graph_api.graph_call(subscription_path, args, 'post', :http_component => :status) == 200
+      end
+
+      # removes subscription for object
+      # if object is nil, it will remove all subscriptions
+      def unsubscribe(object = nil)
+        args = {}
+        args[:object] = object if object
+        @graph_api.graph_call(subscription_path, args, 'delete', :http_component => :status) == 200
+      end
+
+      def list_subscriptions
+        @graph_api.graph_call(subscription_path)["data"]
+      end
+
+      def graph_api
+        Koala::Utils.deprecate("the TestUsers.graph_api accessor is deprecated and will be removed in a future version; please use .api instead.")
+        @api
+      end
+
+      protected
+
+      def subscription_path
+        @subscription_path ||= "#{@app_id}/subscriptions"
+      end
+    end
+  end
+end

data/lib/koala/rest_api.rb

@@ -0,0 +1,95 @@
+module Koala
+  module Facebook
+    REST_SERVER = "api.facebook.com"
+
+    module RestAPIMethods
+      def fql_query(fql, args = {}, options = {})
+        rest_call('fql.query', args.merge(:query => fql), options)
+      end
+
+      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
+      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