koala 1.2.0beta2 → 1.2.0

data/CHANGELOG

@@ -4,8 +4,16 @@ New methods:
   -- Old classes are aliased with deprecation warnings (non-breaking change)
 -- TestUsers#update lets you update the name or password of an existing test user
 -- API.get_page_access_token lets you easily fetch the access token for a page you manage (thanks, marcgg!)
+-- Added version.rb (Koala::VERSION)
 Updated methods:
+-- OAuth now parses Facebook's new signed cookie format
 -- API.put_picture now accepts URLs to images (thanks, marcgg!)
+-- Bug fixes to put_picture, parse_signed_request, and the test suite (thanks, johnbhall and Will S.!)
+-- Smarter GraphCollection use
+  -- Any pageable result will now become a GraphCollection
+  -- Non-pageable results from get_connections no longer error
+  -- GraphCollection.raw_results allows access to original result data
+-- Koala no longer enforces any limits on the number of test users you create at once
 Internal improvements:
 -- Koala now uses Faraday to make requests, replacing the HTTPServices (see wiki)
   -- Koala::HTTPService.http_options allows specification of default Faraday connection options
@@ -15,6 +23,7 @@ Internal improvements:
   -- Koala no longer automatically switches to Net::HTTP when uploading IO objects to Facebook
 -- RealTimeUpdates and TestUsers are no longer subclasses of API, but have their own .api objects
   -- The old .graph_api accessor is aliases to .api with a deprecation warning
+-- Removed deprecation warnings for pre-1.1 batch interface
 Testing improvements:
 -- Live test suites now run against test users by default
   -- Test suite can be repeatedly run live without having to update facebook_data.yml
@@ -22,7 +31,7 @@ Testing improvements:
 -- Faraday adapter for live tests can be specified with ADAPTER=[your adapter] in the rspec command
 -- Live tests can be run against the beta server by specifying BETA=true in the rspec command
 -- Tests now pass against all rubies on Travis CI
--- Expanded test coverage
+-- Expanded and refactored test coverage
 -- Fixed bug with YAML parsing in Ruby 1.9
 
 v1.1

data/koala.gemspec

@@ -1,9 +1,11 @@
 # -*- encoding: utf-8 -*-
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+require 'koala/version'
 
 Gem::Specification.new do |s|
   s.name    = %q{koala}
-  s.version = "1.2.0beta2"
-  s.date    = %q{2011-08-23}
+  s.version = Koala::VERSION
+  s.date    = %q{2011-09-27}
 
   s.summary     = %q{A lightweight, flexible library for Facebook with support for the Graph API, the REST API, realtime updates, and OAuth authentication.}
   s.description = %q{Koala is a lightweight, flexible Ruby SDK for Facebook.  It allows read/write access to the social graph via the Graph and REST APIs, as well as support for realtime updates and OAuth and Facebook Connect authentication.  Koala is fully tested and supports Net::HTTP and Typhoeus connections out of the box and can accept custom modules for other services.}

data/lib/koala/graph_api.rb

@@ -71,9 +71,7 @@ module Koala
 
       def get_connections(id, connection_name, args = {}, options = {})
         # Fetchs the connections for given object.
-        graph_call("#{id}/#{connection_name}", args, "get", options) do |result|
-          result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
-        end
+        graph_call("#{id}/#{connection_name}", args, "get", options)
       end
 
       def put_connections(id, connection_name, args = {}, options = {})
@@ -174,9 +172,7 @@ module Koala
 
       def search(search_terms, args = {}, options = {})
         args.merge!({:q => search_terms}) unless search_terms.nil?
-        graph_call("search", args, "get", options) do |result|
-          result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
-        end
+        graph_call("search", args, "get", options)
       end
 
       # Convenience Methods
@@ -199,14 +195,12 @@ module Koala
       def get_page(params)
         # Pages through a set of results stored in a GraphCollection
         # Used for connections and search results
-        graph_call(*params) do |result|
-          result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
-        end
+        graph_call(*params)
       end
 
       # Batch API
       def batch(http_options = {}, &block)
-        batch_client = GraphBatchAPI.new(access_token)
+        batch_client = GraphBatchAPI.new(access_token, self)
         if block
           yield batch_client
           batch_client.execute(http_options)
@@ -214,15 +208,7 @@ module Koala
           batch_client
         end
       end
-
-      def self.included(base)
-        base.class_eval do
-          def self.batch
-            raise NoMethodError, "The BatchAPI signature has changed (the original implementation was not thread-safe).  Please see https://github.com/arsduo/koala/wiki/Batch-requests.  (This message will be removed in the final 1.1 release.)"
-          end
-        end
-      end
-
+      
       # Direct access to the Facebook API
       # see any of the above methods for example invocations
       def graph_call(path, args = {}, verb = "get", options = {}, &post_processing)
@@ -231,10 +217,15 @@ module Koala
           raise error if error
         end
 
-        # now process as appropriate (get picture header, make GraphCollection, etc.)
+        # turn this into a GraphCollection if it's pageable
+        result = GraphCollection.evaluate(result, self)
+        
+        # now process as appropriate for the given call (get picture header, etc.)
         post_processing ? post_processing.call(result) : result
       end
 
+      private
+      
       def check_response(response)
         # check for Graph API-specific errors
         # this returns an error, which is immediately raised (non-batch)
@@ -244,8 +235,6 @@ module Koala
         end
       end
 
-      private
-
       def parse_media_args(media_args, method)
         # photo and video uploads can accept different types of arguments (see above)
         # so here, we parse the arguments into a form directly usable in put_object

data/lib/koala/graph_batch_api.rb

@@ -4,6 +4,13 @@ module Koala
 
       def self.included(base)
         base.class_eval do
+          attr_reader :original_api
+          
+          def initialize(access_token, api)
+            super(access_token)
+            @original_api = api
+          end
+
           alias_method :graph_call_outside_batch, :graph_call
           alias_method :graph_call, :graph_call_in_batch
 
@@ -46,7 +53,7 @@ module Koala
           batch_op.to_batch_params(access_token)
         })
 
-        graph_call_outside_batch('/', args, 'post', http_options) do |response|
+        batch_result = graph_call_outside_batch('/', args, 'post', http_options) do |response|
           # map the results with post-processing included
           index = 0 # keep compat with ruby 1.8 - no with_index for map
           response.map do |call_result|
@@ -80,6 +87,9 @@ module Koala
             end
           end
         end
+        
+        # turn any results that are pageable into GraphCollections
+        batch_result.inject([]) {|processed_results, raw| processed_results << GraphCollection.evaluate(raw, @original_api)}
       end
 
     end

data/lib/koala/graph_collection.rb

@@ -10,12 +10,17 @@ module Koala
       # It also allows access to paging information and the
       # ability to get the next/previous page in the collection
       # by calling next_page or previous_page.
-      attr_reader :paging
-      attr_reader :api
+      attr_reader :paging, :api, :raw_response
 
+      def self.evaluate(response, api)
+        # turn the response into a GraphCollection if it's pageable; if not, return the original response
+        response.is_a?(Hash) && response["data"].is_a?(Array) ? self.new(response, api) : response
+      end
+    
       def initialize(response, api)
         super response["data"]
         @paging = response["paging"]
+        @raw_response = response
         @api = api
       end
 

data/lib/koala/oauth.rb

@@ -9,31 +9,18 @@ module Koala
       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
+        # Parses the cookie set Facebook's JavaScript SDK.
+        # You can pass Rack/Rails/Sinatra's cookie hash directly to this method.
         #
         # If the user is logged in via Facebook, we return a dictionary with the
         # keys "uid" and "access_token". The former is the user's Facebook ID,
         # and the latter can be used to make authenticated requests to the Graph API.
         # If the user is not logged in, we return None.
-        #
-        # 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
+
+        if signed_cookie = cookie_hash["fbsr_#{@app_id}"]
+          parse_signed_cookie(signed_cookie)
+        elsif unsigned_cookie = cookie_hash["fbs_#{@app_id}"]
+          parse_unsigned_cookie(unsigned_cookie)
         end
       end
       alias_method :get_user_info_from_cookies, :get_user_info_from_cookie
@@ -70,7 +57,7 @@ module Koala
       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)
+        get_token_from_server({:code => code, :redirect_uri => options[:redirect_uri] || @oauth_callback_url}, false, options)
       end
 
       def get_access_token(code, options = {})
@@ -104,7 +91,7 @@ module Koala
         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("-_", "+/"))
+        hmac = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, @app_secret, encoded_envelope)
         raise 'SignedRequest: Invalid signature' if (signature != hmac)
 
         return envelope
@@ -162,6 +149,29 @@ module Koala
         end
         components
       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"]) && token_info = get_access_token_info(code, :redirect_uri => '')
+          components.merge(token_info)
+        else
+          nil
+        end
+      end
 
       def fetch_token_string(args, post = false, endpoint = "access_token", options = {})
         Koala.make_request("/oauth/#{endpoint}", {

data/lib/koala/realtime_updates.rb

@@ -71,7 +71,7 @@ module Koala
       end
 
       def list_subscriptions
-        @graph_api.graph_call(subscription_path)["data"]
+        @graph_api.graph_call(subscription_path)
       end
 
       def graph_api

data/lib/koala/test_users.rb

@@ -35,7 +35,7 @@ module Koala
       end
 
       def list
-        @api.graph_call(accounts_path)["data"]
+        @api.graph_call(accounts_path)
       end
 
       def delete(test_user)
@@ -72,7 +72,6 @@ module Koala
       end
 
       def create_network(network_size, installed = true, permissions = '')
-        network_size = 50 if network_size > 50 # FB's max is 50
         users = (0...network_size).collect { create(installed, permissions) }
         friends = users.clone
         users.each do |user|

data/lib/koala/uploadable_io.rb

@@ -40,7 +40,8 @@ module Koala
       :parse_rails_3_param,
       :parse_sinatra_param,
       :parse_file_object,
-      :parse_string_path
+      :parse_string_path,
+      :parse_io
     ]
 
     def parse_init_mixed_param(mixed, content_type = nil)

data/lib/koala/version.rb

@@ -0,0 +1,3 @@
+module Koala
+  VERSION = "1.2.0"
+end

data/lib/koala.rb

@@ -8,7 +8,6 @@ require 'openssl'
 require 'base64'
 
 # include koala modules
-require 'koala/http_service'
 require 'koala/oauth'
 require 'koala/graph_api'
 require 'koala/graph_batch_api'
@@ -17,11 +16,17 @@ require 'koala/graph_collection'
 require 'koala/rest_api'
 require 'koala/realtime_updates'
 require 'koala/test_users'
-require 'koala/utils'
+
+# HTTP module so we can communicate with Facebook
+require 'koala/http_service'
 
 # add KoalaIO class
 require 'koala/uploadable_io'
 
+# miscellaneous
+require 'koala/utils'
+require 'koala/version'
+
 module Koala
 
   module Facebook

data/readme.md

@@ -9,28 +9,41 @@ Koala
 * Flexible: Koala should be useful to everyone, regardless of their current configuration.  (We support JRuby, Rubinius, and REE as well as vanilla Ruby, 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.)
 
+Facebook Changes on October 1, 2011
+---
+
+**Koala 1.2 supports all of Facebook's new authentication schemes**, which will be introduced on October 1, 2011; the old Javascript library and older authentication schemes will be deprecated at the same time. 
+
+To test your application, upgrade to the latest version of Koala (see below) and configure your application according to Facebook's [OAuth 2.0 and HTTPS Migration](https://developers.facebook.com/docs/oauth2-https-migration/) guide.  If you have the appropriate calls to get_user_info_from_cookies (apps using the Javascript SDK) and/or parse_signed_params (for Canvas and tab apps), your application should work without a hitch.
+
+_Note_: in their new secure cookie format, Facebook provides an OAuth code, which Koala automatically exchanges for an access token.  Because this involves a call to Facebook's servers, you should consider storing the user's access token in their session and only calling get_user_info_from_cookies when necessary (access_token not present, you discover it's expired, etc.).  Otherwise, you'll be calling out to Facebook each time the user loads a page, slowing down your site.  (As we figure out best practices for this, we'll update the wiki.)
+
 Installation
 ---
 
 Easy:
 
-    [sudo|rvm] gem install koala --pre # for 1.2 beta
-    [sudo|rvm] gem install koala # for 1.1
+    [sudo|rvm] gem install koala
 
 Or in Bundler:
 
-    gem "koala", "~> 1.2.0beta" 
-    gem "koala" # for 1.1 
+    gem "koala"
 
 Graph API
 ----
 The Graph API is the simple, slick new interface to Facebook's data.  Using it with Koala is quite straightforward:
-
+  
     @graph = Koala::Facebook::API.new(oauth_access_token)
+    # in 1.1 or earlier, use GraphAPI instead of API
+    
     profile = @graph.get_object("me")
     friends = @graph.get_connections("me", "friends")
     @graph.put_object("me", "feed", :message => "I am writing on my wall!")
 
+    # you can even use the new Timeline API
+    # see https://developers.facebook.com/docs/beta/opengraph/tutorial/
+    @graph.put_connections("me", "namespace:action", :object => object_url)
+
 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 API#get_connections or API#search) a GraphCollection object will be returned, which makes it easy to page through the results:
@@ -61,13 +74,18 @@ Where the Graph API and the old REST API overlap, you should choose the Graph AP
 
 Fortunately, Koala supports the REST API using the very same interface; to use this, instantiate an API:
 
-  	@rest = Koala::Facebook::API.new(oauth_access_token)
+    @rest = Koala::Facebook::API.new(oauth_access_token)
+    # in 1.1 or earlier, use RestAPI instead of API
+  	
   	@rest.fql_query(my_fql_query) # convenience method
   	@rest.fql_multiquery(fql_query_hash) # convenience method
   	@rest.rest_call("stream.publish", arguments_hash) # generic version
 
 Of course, you can use the Graph API methods on the same object -- the power of two APIs right in the palm of your hand.
 
+    @api = Koala::Facebook::API.new(oauth_access_token)
+    # in 1.1 or earlier, use GraphAndRestAPI instead of API
+    
     @api = Koala::Facebook::API.new(oauth_access_token)
     fql = @api.fql_query(my_fql_query)
     @api.put_wall_post(process_result(fql))
@@ -92,7 +110,7 @@ You can also get your application's own access token, which can be used without
     @oauth.get_app_access_token
 
 For those building apps on Facebook, parsing signed requests is simple:
-    @oauth.parse_signed_request(request)
+    @oauth.parse_signed_request(signed_request_string)
 
 Or, if for some horrible reason, you're still using session keys, despair not!  It's easy to turn them into shiny, modern OAuth tokens:
     @oauth.get_token_from_session_key(session_key)
@@ -158,5 +176,7 @@ You can also run live tests against Facebook's servers:
 
     # Again from anywhere in the project directory:
     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.

data/spec/cases/{api_base_spec.rb → api_spec.rb}

@@ -98,4 +98,29 @@ describe "Koala::Facebook::API" do
     end
   end
 
+  describe "with an access token" do
+    before(:each) do
+      @api = Koala::Facebook::API.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::API.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_and_rest_api_spec.rb

@@ -19,30 +19,4 @@ describe "Koala::Facebook::GraphAndRestAPI" do
       api = Koala::Facebook::GraphAndRestAPI.new("token")
     end
   end
-
-  describe "with an access token" do
-    before(:each) do
-      @api = Koala::Facebook::API.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::API.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_batch_spec.rb

@@ -430,7 +430,7 @@ describe "Koala::Facebook::GraphAPI in batch mode" do
   end
 
   describe "usage tests" do
-    it "can get two results at once" do
+    it "gets two results at once" do
       me, koppel = @api.batch do |batch_api|
         batch_api.get_object('me')
         batch_api.get_object(KoalaTest.user1)
@@ -439,7 +439,15 @@ describe "Koala::Facebook::GraphAPI in batch mode" do
       koppel['id'].should_not be_nil
     end
 
-    it 'should be able to make mixed calls inside of a batch' do
+    it 'makes mixed calls inside of a batch' do
+      me, friends = @api.batch do |batch_api|
+        batch_api.get_object('me')
+        batch_api.get_connections('me', 'friends')
+      end
+      friends.should be_a(Koala::Facebook::GraphCollection)
+    end
+    
+    it 'turns pageable results into GraphCollections' do
       me, friends = @api.batch do |batch_api|
         batch_api.get_object('me')
         batch_api.get_connections('me', 'friends')
@@ -448,14 +456,14 @@ describe "Koala::Facebook::GraphAPI in batch mode" do
       friends.should be_an(Array)
     end
 
-    it 'should be able to make a get_picture call inside of a batch' do
+    it 'makes a get_picture call inside of a batch' do
       pictures = @api.batch do |batch_api|
         batch_api.get_picture('me')
       end
       pictures.first.should_not be_empty
     end
 
-    it "should handle requests for two different tokens" do
+    it "handles requests for two different tokens" do
       me, insights = @api.batch do |batch_api|
         batch_api.get_object('me')
         batch_api.get_connections(@app_id, 'insights', {}, {"access_token" => @app_api.access_token})
@@ -571,30 +579,4 @@ describe "Koala::Facebook::GraphAPI in batch mode" do
       end
     end
   end
-
-  describe "new interface" do
-    it "includes a deprecation warning on GraphAPI" do
-      begin
-        Koala::Facebook::GraphAPI.batch do
-        end
-      rescue NoMethodError => @err
-      end
-
-      # verify the message points people to the wiki page
-      @err.should
-      @err.message.should =~ /https\:\/\/github.com\/arsduo\/koala\/wiki\/Batch-requests/
-    end
-
-    it "includes a deprecation warning on GraphAndRESTAPI" do
-      begin
-        Koala::Facebook::GraphAndRestAPI.batch do
-        end
-      rescue NoMethodError => @err
-      end
-
-      # verify the message points people to the wiki page
-      @err.should
-      @err.message.should =~ /https\:\/\/github.com\/arsduo\/koala\/wiki\/Batch-requests/
-    end
-  end
 end

data/spec/cases/graph_api_spec.rb

@@ -19,24 +19,4 @@ describe "Koala::Facebook::GraphAPI" do
       api = Koala::Facebook::GraphAPI.new("token")
     end
   end
-
-  context "with an access token" do
-    before :each do
-      @api = Koala::Facebook::API.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::API.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