koala 1.6.0 → 1.7.0rc1

data/lib/koala/api.rb

@@ -41,8 +41,13 @@ module Koala
       #
       # @return the body of the response from Facebook (unless another http_component is requested)
       def api(path, args = {}, verb = "get", options = {}, &error_checking_block)
-        # Fetches the given path in the Graph API.
-        args["access_token"] = @access_token || @app_access_token if @access_token || @app_access_token
+        # If a access token is explicitly provided, use that
+        # This is explicitly needed in batch requests so GraphCollection
+        # results preserve any specific access tokens provided
+        args["access_token"] ||= @access_token || @app_access_token if @access_token || @app_access_token
+
+        # Translate any arrays in the params into comma-separated strings
+        args = sanitize_request_parameters(args)
 
         # add a leading /
         path = "/#{path}" unless path =~ /^\//
@@ -53,7 +58,7 @@ module Koala
         if result.status.to_i >= 500
           raise Koala::Facebook::ServerError.new(result.status.to_i, result.body)
         end
-      
+
         yield result if error_checking_block
 
         # if we want a component other than the body (e.g. redirect header for images), return that
@@ -66,6 +71,26 @@ module Koala
           MultiJson.load("[#{result.body.to_s}]")[0]
         end
       end
+
+      private
+
+      # Sanitizes Ruby objects into Facebook-compatible string values.
+      #
+      # @param parameters a hash of parameters.
+      #
+      # Returns a hash in which values that are arrays of non-enumerable values
+      #         (Strings, Symbols, Numbers, etc.) are turned into comma-separated strings.
+      def sanitize_request_parameters(parameters)
+        parameters.reduce({}) do |result, (key, value)|
+          # if the parameter is an array that contains non-enumerable values,
+          # turn it into a comma-separated list
+          # in Ruby 1.8.7, strings are enumerable, but we don't care
+          if value.is_a?(Array) && value.none? {|entry| entry.is_a?(Enumerable) && !entry.is_a?(String)}
+            value = value.join(",")
+          end
+          result.merge(key => value)
+        end
+      end
     end
   end
 end

data/lib/koala/api/graph_api.rb

@@ -5,8 +5,6 @@ require 'koala/http_service/uploadable_io'
 
 module Koala
   module Facebook
-    GRAPH_SERVER = "graph.facebook.com"
-
     # Methods used to interact with the Facebook Graph API.
     #
     # See https://github.com/arsduo/koala/wiki/Graph-API for a general introduction to Koala
@@ -144,6 +142,7 @@ module Koala
       def put_connections(id, connection_name, args = {}, options = {}, &block)
         # Posts a certain connection
         raise AuthenticationError.new(nil, nil, "Write operations require an access token") unless @access_token
+
         graph_call("#{id}/#{connection_name}", args, "post", options, &block)
       end
 
@@ -178,7 +177,7 @@ module Koala
       def get_picture(object, args = {}, options = {}, &block)
         # Gets a picture object, returning the URL (which Facebook sends as a header)
         resolved_result = graph_call("#{object}/picture", args, "get", options.merge(:http_component => :headers)) do |result|
-          result["Location"]
+          result ? result["Location"] : nil
         end
         block ? block.call(resolved_result) : resolved_result
       end
@@ -228,6 +227,9 @@ module Koala
       # @param message the message to write for the wall
       # @param attachment a hash describing the wall post
       #         (see the {https://developers.facebook.com/docs/guides/attachments/ stream attachments} documentation.)
+      #         If attachment contains a properties key, this will be turned to
+      #         JSON (if it's a hash) since Facebook's API, oddly, requires
+      #         this.
       # @param target_id the target wall
       # @param options (see #get_object)
       # @param block (see Koala::Facebook::API#api)
@@ -244,6 +246,10 @@ module Koala
       # @see #put_connections
       # @return (see #put_connections)
       def put_wall_post(message, attachment = {}, target_id = "me", options = {}, &block)
+        if properties = attachment.delete(:properties) || attachment.delete("properties")
+          properties = MultiJson.dump(properties) if properties.is_a?(Hash) || properties.is_a?(Array)
+          attachment["properties"] = properties
+        end
         put_connections(target_id, "feed", attachment.merge({:message => message}), options, &block)
       end
 
@@ -368,6 +374,21 @@ module Koala
         block ? block.call(access_token) : access_token
       end
 
+      # Get an access token information
+      # The access token used to instantiate the API object needs to be
+      # the app access token or a valid User Access Token from a developer of the app.
+      # See https://developers.facebook.com/docs/howtos/login/debugging-access-tokens/#step1
+      #
+      # @param input_token the access token you want to inspect
+      # @param block (see Koala::Facebook::API#api)
+      #
+      # @return a JSON array containing data and a map of fields
+      def debug_token(input_token, &block)
+        access_token_info = graph_call("debug_token", {:input_token => input_token})
+
+        block ? block.call(access_token_info) : access_token_info
+      end
+
       # Fetches the comments from fb:comments widgets for a given set of URLs (array or comma-separated string).
       # See https://developers.facebook.com/blog/post/490.
       #
@@ -383,6 +404,15 @@ module Koala
         get_object("comments", args, options, &block)
       end
 
+      # App restrictions require you to JSON-encode the restriction value. This
+      # is neither obvious nor intuitive, so this convenience method is
+      # provided.
+      #
+      # @params app_id the application to apply the restrictions to
+      # @params restrictions_hash the restrictions to apply
+      # @param args (see #get_object)
+      # @param options (see #get_object)
+      # @param block (see Koala::Facebook::API#api)
       def set_app_restrictions(app_id, restrictions_hash, args = {}, options = {}, &block)
         graph_call(app_id, args.merge(:restrictions => MultiJson.dump(restrictions_hash)), "post", options, &block)
       end

data/lib/koala/api/graph_collection.rb

@@ -6,22 +6,22 @@ module Koala
       # A light wrapper for collections returned from the Graph API.
       # It extends Array to allow you to page backward and forward through
       # result sets, and providing easy access to paging information.
-      class GraphCollection < Array        
-        
+      class GraphCollection < Array
+
         # The raw paging information from Facebook (next/previous URLs).
         attr_reader :paging
         # @return [Koala::Facebook::GraphAPI] the api used to make requests.
         attr_reader :api
         # The entire raw response from Facebook.
         attr_reader :raw_response
-    
+
         # Initialize the array of results and store various additional paging-related information.
-        # 
+        #
         # @param response the response from Facebook (a hash whose "data" key is an array)
         # @param api the Graph {Koala::Facebook::API API} instance to use to make calls
         #            (usually the API that made the original call).
         #
-        # @return [Koala::Facebook::GraphCollection] an initialized GraphCollection 
+        # @return [Koala::Facebook::GraphCollection] an initialized GraphCollection
         #         whose paging, raw_response, and api attributes are populated.
         def initialize(response, api)
           super response["data"]
@@ -31,32 +31,32 @@ module Koala
         end
 
         # @private
-        # Turn the response into a GraphCollection if they're pageable; 
+        # Turn the response into a GraphCollection if they're pageable;
         # if not, return the original response.
         # The Ads API (uniquely so far) returns a hash rather than an array when queried
-        # with get_connections. 
+        # with get_connections.
         def self.evaluate(response, api)
           response.is_a?(Hash) && response["data"].is_a?(Array) ? self.new(response, api) : response
         end
-        
+
         # Retrieve the next page of results.
-        # 
+        #
         # @return a GraphCollection array of additional results (an empty array if there are no more results)
         def next_page
           base, args = next_page_params
           base ? @api.get_page([base, args]) : nil
         end
-        
+
         # Retrieve the previous page of results.
-        # 
+        #
         # @return a GraphCollection array of additional results (an empty array if there are no earlier results)
         def previous_page
           base, args = previous_page_params
           base ? @api.get_page([base, args]) : nil
         end
-        
-        # Arguments that can be sent to {Koala::Facebook::API#graph_call} to retrieve the next page of results. 
-        # 
+
+        # Arguments that can be sent to {Koala::Facebook::API#graph_call} to retrieve the next page of results.
+        #
         # @example
         #           @api.graph_call(*collection.next_page_params)
         #
@@ -64,9 +64,9 @@ module Koala
         def next_page_params
           @paging && @paging["next"] ? parse_page_url(@paging["next"]) : nil
         end
-        
-        # Arguments that can be sent to {Koala::Facebook::API#graph_call} to retrieve the previous page of results. 
-        # 
+
+        # Arguments that can be sent to {Koala::Facebook::API#graph_call} to retrieve the previous page of results.
+        #
         # @example
         #           @api.graph_call(*collection.previous_page_params)
         #
@@ -74,7 +74,7 @@ module Koala
         def previous_page_params
           @paging && @paging["previous"] ? parse_page_url(@paging["previous"]) : nil
         end
-        
+
         # @private
         def parse_page_url(url)
           GraphCollection.parse_page_url(url)
@@ -102,9 +102,9 @@ module Koala
         end
       end
     end
-    
+
     # @private
-    # legacy support for when GraphCollection lived directly under Koala::Facebook    
+    # legacy support for when GraphCollection lived directly under Koala::Facebook
     GraphCollection = API::GraphCollection
   end
 end

data/lib/koala/api/rest_api.rb

@@ -1,8 +1,6 @@
 module Koala
   module Facebook
-    REST_SERVER = "api.facebook.com"
-
-    # Methods used to interact with Facebook's legacy REST API.  
+    # Methods used to interact with Facebook's legacy REST API.
     # Where possible, you should use the newer, faster Graph API to interact with Facebook;
     # in the future, the REST API will be deprecated.
     # For now, though, there are a few methods that can't be done through the Graph API.

data/lib/koala/http_service.rb

@@ -23,6 +23,23 @@ module Koala
       builder.adapter Faraday.default_adapter
     end
 
+    # Default servers for Facebook. These are read into the config OpenStruct,
+    # and can be overridden via Koala.config.
+    DEFAULT_SERVERS = {
+      :graph_server => 'graph.facebook.com',
+      :dialog_host => 'www.facebook.com',
+      :rest_server => 'api.facebook.com',
+      # certain Facebook services (beta, video) require you to access different
+      # servers. If you're using your own servers, for instance, for a proxy,
+      # you can change both the matcher and the replacement values.
+      # So for instance, if you're talking to fbproxy.mycompany.com, you could
+      # set up beta.fbproxy.mycompany.com for FB's beta tier, and set the
+      # matcher to /\.fbproxy/ and the beta_replace to '.beta.fbproxy'.
+      :host_path_matcher => /\.facebook/,
+      :video_replace => '-video.facebook',
+      :beta_replace => '.beta.facebook'
+    }
+
     # The address of the appropriate Facebook server.
     #
     # @param options various flags to indicate which server to use.
@@ -33,9 +50,9 @@ module Koala
     #
     # @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]
-      server.gsub!(/\.facebook/, ".beta.facebook") if options[:beta]
+      server = "#{options[:rest_api] ? Koala.config.rest_server : Koala.config.graph_server}"
+      server.gsub!(Koala.config.host_path_matcher, Koala.config.video_replace) if options[:video]
+      server.gsub!(Koala.config.host_path_matcher, Koala.config.beta_replace) if options[:beta]
       "#{options[:use_ssl] ? "https" : "http"}://#{server}"
     end
 
@@ -126,18 +143,6 @@ module Koala
       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.")
@@ -230,4 +235,4 @@ module Koala
       Faraday.default_adapter = :net_http
     end
   end
-end
+end

data/lib/koala/oauth.rb

@@ -4,9 +4,6 @@ require 'base64'
 
 module Koala
   module Facebook
-
-    DIALOG_HOST = "www.facebook.com"
-
     class OAuth
       attr_reader :app_id, :app_secret, :oauth_callback_url
 
@@ -23,9 +20,12 @@ module Koala
 
       # 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.
+      # @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.
@@ -48,6 +48,7 @@ module Koala
       #
       # @return the authenticated user's Facebook ID, or nil.
       def get_user_from_cookies(cookies)
+        Koala::Utils.deprecate("Due to Facebook changes, you can only redeem an OAuth code once; it is therefore recommended not to use this method, as it will consume the code without providing you the access token. See https://developers.facebook.com/roadmap/completed-changes/#december-2012.")
         if signed_cookie = cookies["fbsr_#{@app_id}"]
           if components = parse_signed_request(signed_cookie)
             components["user_id"]
@@ -74,6 +75,9 @@ module Koala
       #
       # @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
       #
@@ -86,7 +90,7 @@ module Koala
         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("https://#{GRAPH_SERVER}/oauth/authorize", true, url_options)
+        build_url("https://#{Koala.config.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.
@@ -110,7 +114,7 @@ module Koala
           :code => code,
           :client_secret => @app_secret
         }.merge(options)
-        build_url("https://#{GRAPH_SERVER}/oauth/access_token", true, url_options)
+        build_url("https://#{Koala.config.graph_server}/oauth/access_token", true, url_options)
       end
 
       # Builds a URL for a given dialog (feed, friends, OAuth, pay, send, etc.)
@@ -125,7 +129,7 @@ module Koala
       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)
+        build_url("http://#{Koala.config.dialog_host}/dialog/#{dialog_type}", true, url_options)
       end
 
       # access tokens
@@ -175,7 +179,7 @@ module Koala
       # @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)
+        get_token_from_server({:grant_type => 'client_credentials'}, true, options)
       end
 
       # Fetches the application's access token (ignoring expiration and other info).
@@ -346,7 +350,7 @@ module Koala
 
       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!"
+          raise ArgumentError, "build_url must get a callback either from the OAuth object or in the parameters!"
         end
 
         "#{base}?#{Koala::HTTPService.encode_params(url_options)}"

data/lib/koala/version.rb

@@ -1,3 +1,3 @@
 module Koala
-  VERSION = "1.6.0"
+  VERSION = "1.7.0rc1"
 end

data/readme.md

@@ -1,5 +1,10 @@
 [![Build Status](https://secure.travis-ci.org/arsduo/koala.png)](http://travis-ci.org/arsduo/koala)
 
+**Note**: a recent Facebook change will cause apps that parse the cookies every
+request to fail with the error "OAuthException: This authorization code has
+been used."  If you're seeing this, please read the note in the [OAuth
+wiki](https://github.com/arsduo/koala/wiki/OAuth) for more information.
+
 Koala
 ====
 [Koala](http://github.com/arsduo/koala) is a Facebook library for Ruby, supporting the Graph API (including the batch requests and photo uploads), the REST API, realtime updates, test users, and OAuth validation.  We wrote Koala with four goals:
@@ -7,7 +12,7 @@ Koala
 * Lightweight: Koala should be as light and simple as Facebook’s own libraries, providing API accessors and returning simple JSON.
 * Fast: Koala should, out of the box, be quick. Out of the box, we use Facebook's faster read-only servers when possible and if available, the Typhoeus gem to make snappy Facebook requests.  Of course, that brings us to our next topic:
 * Flexible: Koala should be useful to everyone, regardless of their current configuration.  We support JRuby, Rubinius, and REE as well as vanilla Ruby (1.8.7, 1.9.2, and 1.9.3), and use the Faraday library to provide complete flexibility over how HTTP requests are made.
-* Tested: Koala should have complete test coverage, so you can rely on it.  Our test coverage is complete and can be run against either mocked responses or the live Facebook servers; we're also on [Travis CI](travis-ci.org/arsduo/koala/).
+* Tested: Koala should have complete test coverage, so you can rely on it.  Our test coverage is complete and can be run against either mocked responses or the live Facebook servers; we're also on [Travis CI](http://travis-ci.org/arsduo/koala/).
 
 Installation
 ---
@@ -24,9 +29,9 @@ gem "koala"
 
 Graph API
 ----
-The Graph API is the simple, slick new interface to Facebook's data.  
-Using it with Koala is quite straightforward.  First, you'll need an access token, which you can get through 
-Facebook's [Graph API Explorer](https://developers.facebook.com/tools/explorer) (click on 'Get Access Token').  
+The Graph API is the simple, slick new interface to Facebook's data.
+Using it with Koala is quite straightforward.  First, you'll need an access token, which you can get through
+Facebook's [Graph API Explorer](https://developers.facebook.com/tools/explorer) (click on 'Get Access Token').
 Then, go exploring:
 
 ```ruby
@@ -110,6 +115,23 @@ fql = @api.fql_query(my_fql_query)
 @api.put_wall_post(process_result(fql))
 ```
 
+Configuration
+----
+You can change the host that koala makes requests to (point to a mock server, apigee, runscope etc..)
+```ruby
+# config/initializers/koala.rb
+require 'koala'
+
+Koala.configure do |config|
+  config.graph_server = 'my-graph-mock.mysite.com'
+  # other common options are `rest_server` and `dialog_host`
+  # see lib/koala/http_service.rb
+end
+```
+
+Of course the defaults are the facebook endpoints and you can additionally configure the beta
+tier and video upload matching and replacement strings.
+
 OAuth
 -----
 You can use the Graph and REST APIs without an OAuth access token, but the real magic happens when you provide Facebook an OAuth token to prove you're authenticated.  Koala provides an OAuth class to make that process easy:
@@ -119,10 +141,15 @@ You can use the Graph and REST APIs without an OAuth access token, but the real
 
 If your application uses Koala and the Facebook [JavaScript SDK](http://github.com/facebook/facebook-js-sdk) (formerly Facebook Connect), you can use the OAuth class to parse the cookies:
 ```ruby
-@oauth.get_user_from_cookies(cookies) # gets the user's ID
-@oauth.get_user_info_from_cookies(cookies) # parses and returns the entire hash
+# parses and returns a hash including the token and the user id
+# 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.
+@oauth.get_user_info_from_cookies(cookies)
 ```
 And if you have to use the more complicated [redirect-based OAuth process](http://developers.facebook.com/docs/authentication/), Koala helps out there, too:
+
 ```ruby
 # generate authenticating URL
 @oauth.url_for_oauth_code
@@ -223,4 +250,4 @@ LIVE=true bundle exec rake spec
 # you can also test against Facebook's beta tier
 LIVE=true BETA=true bundle exec rake spec
 ```
-By default, the live tests are run against test users, so you can run them as frequently as you want.  If you want to run them against a real user, however, you can fill in the OAuth token, code, and access\_token values in spec/fixtures/facebook_data.yml.  See the wiki for more details.
+By default, the live tests are run against test users, so you can run them as frequently as you want.  If you want to run them against a real user, however, you can fill in the OAuth token, code, and access\_token values in spec/fixtures/facebook_data.yml.  See the wiki for more details.