koala 0.9.1 → 1.0.0.rc

data/lib/koala.rb

@@ -1,26 +1,24 @@
 require 'cgi'
 require 'digest/md5'
 
-# rubygems is required to support json, how facebook returns data
-require 'rubygems'
 require 'json'
 
-# openssl is required to support signed_request
+# OpenSSL and Base64 are required to support signed_request
 require 'openssl'
+require 'base64'
 
-# include default http services
+# include koala modules
 require 'koala/http_services'
-
-# add Graph API methods
 require 'koala/graph_api'
-
-# add REST API methods
 require 'koala/rest_api'
-
 require 'koala/realtime_updates'
+require 'koala/test_users'
+
+# add KoalaIO class
+require 'koala/uploadable_io'
 
 module Koala
-    
+
   module Facebook
     # Ruby client library for the Facebook Platform.
     # Copyright 2010 Facebook
@@ -36,7 +34,7 @@ module Koala
     # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
     # License for the specific language governing permissions and limitations
     # under the License.
-    # 
+    #
     # This client library is designed to support the Graph API and the official
     # Facebook JavaScript SDK, which is the canonical way to implement
     # Facebook authentication. Read more about the Graph API at
@@ -44,34 +42,35 @@ module Koala
     # JavaScript SDK at http://github.com/facebook/connect-js/.
 
     class API
-      # initialize with an access token 
+      # initialize with an access token
       def initialize(access_token = nil)
         @access_token = access_token
       end
-      
+      attr_reader :access_token
+
       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
-
+        
         # add a leading /
         path = "/#{path}" unless path =~ /^\//
 
         # make the request via the provided service
         result = Koala.make_request(path, args, verb, options)
-        
+
         # Check for any 500 errors before parsing the body
         # since we're not guaranteed that the body is valid JSON
         # in the case of a server error
         raise APIError.new({"type" => "HTTP #{result.status.to_s}", "message" => "Response body: #{result.body}"}) if result.status >= 500
-        
-        # Parse the body as JSON and check for errors if provided a mechanism to do so 
+
+        # Parse the body as JSON and check for errors if provided a mechanism to do so
         # Note: Facebook sometimes sends results like "true" and "false", which aren't strictly objects
         # and cause JSON.parse to fail -- so we account for that by wrapping the result in []
         body = response = JSON.parse("[#{result.body.to_s}]")[0]
         if error_checking_block
           yield(body)
         end
-        
+
         # now return the desired information
         if options[:http_component]
           result.send(options[:http_component])
@@ -80,51 +79,57 @@ module Koala
         end
       end
     end
-    
+
     class GraphAPI < API
       include GraphAPIMethods
     end
-    
+
     class RestAPI < API
       include RestAPIMethods
     end
-    
+
     class GraphAndRestAPI < API
       include GraphAPIMethods
       include RestAPIMethods
     end
-    
+
     class RealtimeUpdates < API
       include RealtimeUpdateMethods
     end
-    
-    class APIError < Exception
+
+    class TestUsers < API
+      include TestUserMethods
+      # make the Graph API accessible in case someone wants to make other calls to interact with their users
+      attr_reader :graph_api
+    end
+
+    class APIError < StandardError
       attr_accessor :fb_error_type
       def initialize(details = {})
-        self.fb_error_type = details["type"]  
+        self.fb_error_type = details["type"]
         super("#{fb_error_type}: #{details["message"]}")
       end
     end
-    
-    
+
+
     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 
+        @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/.
@@ -139,78 +144,82 @@ module Koala
 
           # 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 = 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}"    
+        "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)
         # 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)
       end
-      
+
       def get_access_token(code)
         # upstream methods will throw errors if needed
-        if info = get_access_token_info(code) 
-          string = info["access_token"]        
+        if info = get_access_token_info(code)
+          string = info["access_token"]
         end
       end
-      
+
       def get_app_access_token_info
-        # convenience method to get a the application's sessionless access token 
+        # convenience method to get a the application's sessionless access token
         get_token_from_server({:type => 'client_cred'}, true)
       end
-      
+
       def get_app_access_token
         if info = get_app_access_token_info
-          string = info["access_token"] 
+          string = info["access_token"]
         end
       end
-      
-      # signed_request
-      def parse_signed_request(request)
-        # Facebook's signed requests come in two parts -- the signature and the data payload
-        # see http://developers.facebook.com/docs/authentication/canvas
-        encoded_sig, payload = request.split(".")
-        
-        sig = base64_url_decode(encoded_sig)
 
-        # if the signature matches, return the data, decoded and parsed as JSON
-        if OpenSSL::HMAC.digest("sha256", @app_secret, payload) == sig
-          JSON.parse(base64_url_decode(payload))
-        else
-          nil
-        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 = JSON.parse(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
@@ -220,66 +229,70 @@ module Koala
           :type => 'client_cred',
           :sessions => sessions.join(",")
         }, true, "exchange_sessions")
-        
+
         # Facebook returns an empty body in certain error conditions
-        if response == "" 
-          raise APIError.new("ArgumentError", "get_token_from_session_key received an error (empty response body) for sessions #{sessions.inspect}!")
+        if response == ""
+          raise APIError.new({
+            "type" => "ArgumentError",
+            "message" => "get_token_from_session_key received an error (empty response body) for sessions #{sessions.inspect}!"
+          })
         end
-        
+
         JSON.parse(response)
       end
-  
+
       def get_tokens_from_session_keys(sessions)
         # get the original hash results
         results = get_token_info_from_session_keys(sessions)
         # now recollect them as just the access tokens
         results.collect { |r| r ? r["access_token"] : nil }
       end
-      
+
       def get_token_from_session_key(session)
         # convenience method for a single key
         # gets the overlaoded strings automatically
         get_tokens_from_session_keys([session])[0]
       end
-      
+
       protected
-      
+
       def get_token_from_server(args, post = false)
         # fetch the result from Facebook's servers
         result = fetch_token_string(args, post)
-        
+
         # if we have an error, parse the error JSON and raise an error
         raise APIError.new((JSON.parse(result)["error"] rescue nil) || {}) if result =~ /error/
 
         # otherwise, parse the access token
-        parse_access_token(result)       
+        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 
+        components
       end
 
       def fetch_token_string(args, post = false, endpoint = "access_token")
         Koala.make_request("/oauth/#{endpoint}", {
-          :client_id => @app_id, 
+          :client_id => @app_id,
           :client_secret => @app_secret
-        }.merge!(args), post ? "post" : "get").body
+        }.merge!(args), post ? "post" : "get", :use_ssl => true).body
       end
-      
+
       # base 64
-      def base64_url_decode(string)
-        # to properly decode what Facebook provides, we need to add == to the end
-        # and translate certain characters to others before running the actual decoding
-        # see http://developers.facebook.com/docs/authentication/canvas 
-        "#{string}==".tr("-_", "+/").unpack("m")[0]
+      # 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
-  
+
+  class KoalaError< StandardError; end
+
   # finally, set up the http service Koala methods used to make requests
   # you can use your own (for HTTParty, etc.) by calling Koala.http_service = YourModule
   def self.http_service=(service)
@@ -287,8 +300,9 @@ module Koala
   end
 
   # by default, try requiring Typhoeus -- if that works, use it
+  # if you have Typheous and don't want to use it (or want another service),
+  # you can run Koala.http_service = NetHTTPService (or MyHTTPService)
   begin
-    require 'typhoeus'
     Koala.http_service = TyphoeusService
   rescue LoadError
     Koala.http_service = NetHTTPService

data/readme.md

@@ -1,28 +1,34 @@
 Koala
 ====
-Koala (<a href="http://github.com/arsduo/koala" target="_blank">http://github.com/arsduo/koala</a>) is a new Facebook library for Ruby, supporting the Graph API, the old REST API, realtime updates, and OAuth validation.  We wrote Koala with four goals: 
+Koala (<a href="http://github.com/arsduo/koala" target="_blank">http://github.com/arsduo/koala</a>) is a new Facebook library for Ruby, supporting the Graph API (including photo uploads), the old REST API, realtime updates, and OAuth validation.  We wrote Koala with four goals:
 
-* Lightweight: Koala should be as light and simple as Facebook’s own new libraries, providing API accessors and returning simple JSON.  (We clock in, with comments, just over 500 lines of code.)
+* Lightweight: Koala should be as light and simple as Facebook’s own new libraries, providing API accessors and returning simple JSON.  (We clock in, with comments, just over 750 lines of code.)
 * Fast: Koala should, out of the box, be quick. In addition to supporting the vanilla Ruby networking libraries, it natively supports Typhoeus, our preferred gem for making fast HTTP requests. Of course, That brings us to our next topic:
 * Flexible: Koala should be useful to everyone, regardless of their current configuration.  (We have no dependencies beyond the JSON gem.  Koala also has a built-in mechanism for using whichever HTTP library you prefer to make requests against the graph.)
 * Tested: Koala should have complete test coverage, so you can rely on it.  (Our complete test coverage can be run against either mocked responses or the live Facebook servers.)
 
+1.0 beta
+---
+Version 1.0 is currently in beta, chock-full of great new features.  To download the beta, just add --pre when installing the gem:
+    
+    sudo gem install koala --pre
+
 Graph API
 ----
-The Graph API is the simple, slick new interface to Facebook's data.  Using it with Koala is quite straightforward: 
+The Graph API is the simple, slick new interface to Facebook's data.  Using it with Koala is quite straightforward:
 
     graph = Koala::Facebook::GraphAPI.new(oauth_access_token)
     profile = graph.get_object("me")
     friends = graph.get_connections("me", "friends")
     graph.put_object("me", "feed", :message => "I am writing on my wall!")
 
-The response of most requests is the JSON data returned from the Facebook servers as a Hash.  
+The response of most requests is the JSON data returned from the Facebook servers as a Hash.
 
 When retrieving data that returns an array of results (for example, when calling GraphAPI#get_connections or GraphAPI#search) a GraphCollection object (a sub-class of Array) will be returned, which contains added methods for getting the next and previous page of results:
-    
+
     # Returns the feed items for the currently logged-in user as a GraphCollection
     feed = graph.get_connections("me", "feed")
-    
+
     # GraphCollection is a sub-class of Array, so you can use it as a usual Array
     first_entry = feed[0]
     last_entry = feed.last
@@ -33,7 +39,7 @@ When retrieving data that returns an array of results (for example, when calling
     # Returns an array describing the URL for the next page: [path, arguments]
     # This is useful for paging across multiple requests
     next_path, next_args = feed.next_page_params
-    
+
     # You can use those params to easily get the next (or prevous) page
     page = graph.get_page(feed.next_page_params)
 
@@ -41,25 +47,26 @@ Check out the wiki for more examples.
 
 The old-school REST API
 -----
-Where the Graph API and the old REST API overlap, you should choose the Graph API.  Unfortunately, that overlap is far from complete, and there are many important API calls that can't yet be done via the Graph.  
+Where the Graph API and the old REST API overlap, you should choose the Graph API.  Unfortunately, that overlap is far from complete, and there are many important API calls that can't yet be done via the Graph.
 
 Koala now supports the old-school REST API using OAuth access tokens; to use this, instantiate your class using the RestAPI class:
 
 	@rest = Koala::Facebook::RestAPI.new(oauth_access_token)
 	@rest.fql_query(my_fql_query) # convenience method
 	@rest.rest_call("stream.publish", arguments_hash) # generic version
-	
-We reserve the right to expand the built-in REST API coverage to additional convenience methods in the future, depending on how fast Facebook moves to fill in the gaps.  
+
+We reserve the right to expand the built-in REST API coverage to additional convenience methods in the future, depending on how fast Facebook moves to fill in the gaps.
 
 (If you want the power of both APIs in the palm of your hand, try out the GraphAndRestAPI class.)
 
 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:
-    @oauth = Koala::Facebook::OAuth.new(app_id, code, callback_url)
+    @oauth = Koala::Facebook::OAuth.new(app_id, app_secret, callback_url)
 
 If your application uses Koala and the Facebook [JavaScript SDK](http://github.com/facebook/connect-js) (formerly Facebook Connect), you can use the OAuth class to parse the cookies:
-    @oauth.get_user_from_cookie(cookies)
+    @oauth.get_user_from_cookies(cookies) # gets the user's ID
+	@oauth.get_user_info_from_cookies(cookies) # parses and returns the entire hash
 
 And if you have to use the more complicated [redirect-based OAuth process](http://developers.facebook.com/docs/authentication/), Koala helps out there, too:
 	  # generate authenticating URL
@@ -118,7 +125,7 @@ Some resources to help you as you play with Koala and the Graph API:
 Testing
 -----
 
-Unit tests are provided for all of Koala's methods.  By default, these tests run against mock responses and hence are ready out of the box: 
+Unit tests are provided for all of Koala's methods.  By default, these tests run against mock responses and hence are ready out of the box:
     # From the spec directory
     spec koala_spec.rb
 
@@ -126,4 +133,4 @@ You can also run live tests against Facebook's servers:
     # Again from the spec directory
     spec koala_spec_without_mocks.rb
 
-Important Note: to run the live tests, you have to provide some of your own data: a valid OAuth access token with publish\_stream and read\_stream permissions and an OAuth code that can be used to generate an access token.  You can get these data at the OAuth Playground; if you want to use your own app, remember to swap out the app ID, secret, and other values.  (The file also provides valid values for other tests, which you're welcome to swap out for data specific to your own application.)
+Important Note: to run the live tests, you have to provide some of your own data: a valid OAuth access token with publish\_stream, read\_stream, and user\_photos permissions and an OAuth code that can be used to generate an access token.  You can get these data at the OAuth Playground; if you want to use your own app, remember to swap out the app ID, secret, and other values.  (The file also provides valid values for other tests, which you're welcome to swap out for data specific to your own application.)

data/spec/cases/api_base_spec.rb

@@ -0,0 +1,101 @@
+require 'spec_helper'
+
+describe "Koala::Facebook::API" do
+  before(:each) do
+    @service = Koala::Facebook::API.new
+  end
+
+  it "should not include an access token if none was given" do
+    Koala.should_receive(:make_request).with(
+      anything,
+      hash_not_including('access_token' => 1),
+      anything,
+      anything
+    ).and_return(Koala::Response.new(200, "", ""))
+
+    @service.api('anything')
+  end
+
+  it "should include an access token if given" do
+    token = 'adfadf'
+    service = Koala::Facebook::API.new token
+
+    Koala.should_receive(:make_request).with(
+      anything,
+      hash_including('access_token' => token),
+      anything,
+      anything
+    ).and_return(Koala::Response.new(200, "", ""))
+
+    service.api('anything')
+  end
+
+  it "should have an attr_reader for access token" do
+    token = 'adfadf'
+    service = Koala::Facebook::API.new token
+    service.access_token.should == token
+  end
+
+  it "should get the attribute of a Koala::Response given by the http_component parameter" do
+    http_component = :method_name
+
+    response = mock('Mock KoalaResponse', :body => '', :status => 200)
+    response.should_receive(http_component).and_return('')
+
+    Koala.stub(:make_request).and_return(response)
+
+    @service.api('anything', 'get', {}, :http_component => http_component)
+  end
+
+  it "should return the body of the request as JSON if no http_component is given" do
+    response = stub('response', :body => 'body', :status => 200)
+    Koala.stub(:make_request).and_return(response)
+
+    json_body = mock('JSON body')
+    JSON.stub(:parse).and_return([json_body])
+
+    @service.api('anything').should == json_body
+  end
+
+  it "should execute a block with the response body if passed one" do
+    body = '{}'
+    Koala.stub(:make_request).and_return(Koala::Response.new(200, body, {}))
+
+    yield_test = mock('Yield Tester')
+    yield_test.should_receive(:pass)
+
+    @service.api('anything') do |arg|
+      yield_test.pass
+      arg.should == JSON.parse(body)
+    end
+  end
+
+  it "should raise an API error if the HTTP response code is greater than or equal to 500" do
+    Koala.stub(:make_request).and_return(Koala::Response.new(500, 'response body', {}))
+
+    lambda { @service.api('anything') }.should raise_exception(Koala::Facebook::APIError)
+  end
+
+  it "should handle rogue true/false as responses" do
+    Koala.should_receive(:make_request).and_return(Koala::Response.new(200, 'true', {}))
+    @service.api('anything').should be_true
+
+    Koala.should_receive(:make_request).and_return(Koala::Response.new(200, 'false', {}))
+    @service.api('anything').should be_false
+  end
+
+  describe "with regard to leading slashes" do
+    it "should add a leading / to the path if not present" do
+      path = "anything"
+      Koala.should_receive(:make_request).with("/#{path}", anything, anything, anything).and_return(Koala::Response.new(200, 'true', {}))
+      @service.api(path)
+    end
+
+    it "shouldn't change the path if a leading / is present" do
+      path = "/anything"
+      Koala.should_receive(:make_request).with(path, anything, anything, anything).and_return(Koala::Response.new(200, 'true', {}))
+      @service.api(path)
+    end
+  end
+
+end

data/spec/cases/graph_and_rest_api_spec.rb

@@ -0,0 +1,31 @@
+require 'spec_helper'
+
+describe "Koala::Facebook::GraphAndRestAPI" do
+  include LiveTestingDataHelper
+
+  describe "with an access token" do
+    before(:each) do
+      @api = Koala::Facebook::GraphAndRestAPI.new(@token)
+    end
+
+    it_should_behave_like "Koala RestAPI"
+    it_should_behave_like "Koala RestAPI with an access token"
+
+    it_should_behave_like "Koala GraphAPI"
+    it_should_behave_like "Koala GraphAPI with an access token"
+    it_should_behave_like "Koala GraphAPI with GraphCollection"
+  end
+
+  describe "without an access token" do
+    before(:each) do
+      @api = Koala::Facebook::GraphAndRestAPI.new
+    end
+
+    it_should_behave_like "Koala RestAPI"
+    it_should_behave_like "Koala RestAPI without an access token"
+
+    it_should_behave_like "Koala GraphAPI"
+    it_should_behave_like "Koala GraphAPI without an access token"
+    it_should_behave_like "Koala GraphAPI with GraphCollection"
+  end
+end

data/spec/cases/graph_api_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+
+describe "Koala::Facebook::GraphAPI" do
+  include LiveTestingDataHelper
+  
+  context "with an access token" do
+    before :each do
+      @api = Koala::Facebook::GraphAPI.new(@token)
+    end
+
+    it_should_behave_like "Koala GraphAPI"
+    it_should_behave_like "Koala GraphAPI with an access token"
+    it_should_behave_like "Koala GraphAPI with GraphCollection"
+  end
+
+  context "without an access token" do
+    before :each do
+      @api = Koala::Facebook::GraphAPI.new
+    end
+
+    it_should_behave_like "Koala GraphAPI"
+    it_should_behave_like "Koala GraphAPI without an access token"
+    it_should_behave_like "Koala GraphAPI with GraphCollection"
+  end
+end