koala 1.2.0 → 1.2.1

data/CHANGELOG

@@ -1,3 +1,18 @@
+v1.2.1
+New methods:
+-- RestAPI.set_app_properties handles JSON-encoding application properties
+Updated methods:
+-- OAuth.get_user_from_cookie works with the new signed cookie format (thanks, gmccreight!)
+-- Beta server URLs are now correct
+-- OAuth.parse_signed_request now raises an informative error if the signed_request is malformed
+Internal improvements:
+-- Koala::Multipart middleware properly encoding nested parameters (hashes) in POSTs
+-- Updated readme, changelog, etc.
+Testing improvements:
+-- Live tests with test users now clean up all fake users they create
+-- Removed duplicate test cases
+-- Live tests with test users no longer delete each object they create, speeding things up
+
 v1.2
 New methods:
 -- API is now the main API class, contains both Graph and REST methods

data/koala.gemspec

@@ -5,7 +5,7 @@ require 'koala/version'
 Gem::Specification.new do |s|
   s.name    = %q{koala}
   s.version = Koala::VERSION
-  s.date    = %q{2011-09-27}
+  s.date    = %q{2011-10-04}
 
   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/http_service.rb

@@ -20,7 +20,7 @@ module Koala
     @http_options ||= {}
     
     DEFAULT_MIDDLEWARE = Proc.new do |builder|
-      builder.request :multipart
+      builder.use Koala::MultipartRequest
       builder.request :url_encoded
       builder.adapter Faraday.default_adapter
     end
@@ -28,7 +28,8 @@ module Koala
     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}"
+      server.gsub!(/\.facebook/, ".beta.facebook") if options[:beta]
+      "#{options[:use_ssl] ? "https" : "http"}://#{server}"
     end
 
     def self.make_request(path, args, verb, options = {})

data/lib/koala/multipart_request.rb

@@ -0,0 +1,35 @@
+require 'faraday'
+
+module Koala
+  class MultipartRequest < Faraday::Request::Multipart
+    # Facebook expects nested parameters to be passed in a certain way
+    # Based on our testing (https://github.com/arsduo/koala/issues/125),
+    # Faraday needs two changes to make that work:
+    # 1) [] need to be escaped (e.g. params[foo]=bar ==> params%5Bfoo%5D=bar)
+    # 2) such messages need to be multipart-encoded
+    
+    self.mime_type = 'multipart/form-data'.freeze
+    
+    def process_request?(env)
+      # if the request values contain any hashes or arrays, multipart it
+      super || !!(env[:body].respond_to?(:values) && env[:body].values.find {|v| v.is_a?(Hash) || v.is_a?(Array)})
+    end   
+    
+    
+    def process_params(params, prefix = nil, pieces = nil, &block)
+      params.inject(pieces || []) do |all, (key, value)|
+        key = "#{prefix}%5B#{key}%5D" if prefix
+
+        case value
+        when Array
+          values = value.inject([]) { |a,v| a << [nil, v] }
+          process_params(values, key, all, &block)
+        when Hash
+          process_params(value, key, all, &block)
+        else
+          all << block.call(key, value)
+        end
+      end
+    end
+  end
+end

data/lib/koala/oauth.rb

@@ -27,7 +27,8 @@ module Koala
 
       def get_user_from_cookie(cookies)
         if info = get_user_info_from_cookies(cookies)
-          string = info["uid"]
+          # signed cookie has user_id, unsigned cookie has uid
+          string = info["user_id"] || info["uid"]
         end
       end
       alias_method :get_user_from_cookies, :get_user_from_cookie
@@ -85,6 +86,8 @@ module Koala
       # for a more accurate reference implementation strategy.
       def parse_signed_request(input)
         encoded_sig, encoded_envelope = input.split('.', 2)
+        raise 'SignedRequest: Invalid (incomplete) signature data' unless encoded_sig && encoded_envelope
+
         signature = base64_url_decode(encoded_sig).unpack("H*").first
         envelope = MultiJson.decode(base64_url_decode(encoded_envelope))
 
@@ -94,7 +97,7 @@ module Koala
         hmac = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, @app_secret, encoded_envelope)
         raise 'SignedRequest: Invalid signature' if (signature != hmac)
 
-        return envelope
+        envelope
       end
 
       # from session keys

data/lib/koala/rest_api.rb

@@ -13,6 +13,11 @@ module Koala
           results.inject({}) {|outcome, data| outcome[data["name"]] = data["fql_result_set"]; outcome}
         end
       end
+      
+      def set_app_properties(properties, args = {}, options = {})
+        raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "setAppProperties requires an access token"}) unless @access_token
+        rest_call("admin.setAppProperties", args.merge(:properties => MultiJson.encode(properties)), options, "post")
+      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))

data/lib/koala/test_users.rb

@@ -31,7 +31,7 @@ module Koala
         # Creates and returns a test user
         args['installed'] = installed
         args['permissions'] = (permissions.is_a?(Array) ? permissions.join(",") : permissions) if installed
-        result = @api.graph_call(accounts_path, args, "post", options)
+        @api.graph_call(accounts_path, args, "post", options)
       end
 
       def list

data/lib/koala/version.rb

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

data/lib/koala.rb

@@ -19,6 +19,7 @@ require 'koala/test_users'
 
 # HTTP module so we can communicate with Facebook
 require 'koala/http_service'
+require 'koala/multipart_request'
 
 # add KoalaIO class
 require 'koala/uploadable_io'

data/readme.md

@@ -12,11 +12,7 @@ Koala
 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.)
+Koala 1.2 supports all of Facebook's new authentication schemes, which were introduced on October 1, 2011.  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.  For more information, see Facebook's [OAuth 2.0 and HTTPS Migration](https://developers.facebook.com/docs/oauth2-https-migration/) guide.  
 
 Installation
 ---
@@ -94,25 +90,31 @@ Of course, you can use the Graph API methods on the same object -- the power of
 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, 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_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
 	  @oauth.url_for_oauth_code
 	  # fetch the access token once you have the code
 	  @oauth.get_access_token(code)
 
 You can also get your application's own access token, which can be used without a user session for subscriptions and certain other requests:
+
     @oauth.get_app_access_token
 
 For those building apps on Facebook, parsing signed requests is simple:
+
     @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)
     @oauth.get_tokens_from_session_keys(array_of_session_keys)
 
@@ -155,12 +157,27 @@ We also support the test users API, allowing you to conjure up fake users and co
     # or, if you want to make a whole community:
     @test_users.create_network(network_size, is_app_installed, common_permissions)
 
+Talking to Facebook
+-----
+
+Koala uses Faraday to make HTTP requests, which means you have complete control over how your app makes HTTP requests to Facebook.  You can set Faraday options globally or pass them in on a per-request (or both):
+
+    # Set an SSL certificate to avoid Net::HTTP errors
+    Koala.http_service.http_options = {
+      :ssl => { :ca_path => "/etc/ssl/certs" }
+    }
+    # or on a per-request basis
+    @api.get_object(id, args_hash, { :timeout => 10 })
+  
+The <a href="https://github.com/arsduo/koala/wiki/HTTP-Services">HTTP Services wiki page</a> has more information on what options are available, as well as on how to configure your own Faraday middleware stack (for instance, to implement request logging).
+
 See examples, ask questions
 -----
 Some resources to help you as you play with Koala and the Graph API:
 
 * Complete Koala documentation <a href="http://wiki.github.com/arsduo/koala/">on the wiki</a>
 * The <a href="http://groups.google.com/group/koala-users">Koala users group</a> on Google Groups, the place for your Koala and API questions
+* Facebook's <a href="http://developers.facebook.com/tools/explorer/">Graph API Explorer</a>, where you can play with the Graph API in your browser
 * The Koala-powered <a href="http://oauth.twoalex.com" target="_blank">OAuth Playground</a>, where you can easily generate OAuth access tokens and any other data needed to test out the APIs or OAuth
 
 Testing

data/spec/cases/api_spec.rb

@@ -5,7 +5,7 @@ describe "Koala::Facebook::API" do
     @service = Koala::Facebook::API.new
   end
 
-  it "should not include an access token if none was given" do
+  it "doesn't include an access token if none was given" do
     Koala.should_receive(:make_request).with(
       anything,
       hash_not_including('access_token' => 1),
@@ -16,7 +16,7 @@ describe "Koala::Facebook::API" do
     @service.api('anything')
   end
 
-  it "should include an access token if given" do
+  it "includes an access token if given" do
     token = 'adfadf'
     service = Koala::Facebook::API.new token
 
@@ -30,13 +30,13 @@ describe "Koala::Facebook::API" do
     service.api('anything')
   end
 
-  it "should have an attr_reader for access token" do
+  it "has 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
+  it "gets the attribute of a Koala::Response given by the http_component parameter" do
     http_component = :method_name
 
     response = mock('Mock KoalaResponse', :body => '', :status => 200)
@@ -47,7 +47,7 @@ describe "Koala::Facebook::API" do
     @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
+  it "returns 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)
 
@@ -57,7 +57,7 @@ describe "Koala::Facebook::API" do
     @service.api('anything').should == json_body
   end
 
-  it "should execute an error checking block if provided" do
+  it "executes an error checking block if provided" do
     body = '{}'
     Koala.stub(:make_request).and_return(Koala::Response.new(200, body, {}))
 
@@ -70,13 +70,13 @@ describe "Koala::Facebook::API" do
     end
   end
 
-  it "should raise an API error if the HTTP response code is greater than or equal to 500" do
+  it "raises 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
+  it "handles rogue true/false as responses" do
     Koala.should_receive(:make_request).and_return(Koala::Response.new(200, 'true', {}))
     @service.api('anything').should be_true
 
@@ -85,13 +85,13 @@ describe "Koala::Facebook::API" do
   end
 
   describe "with regard to leading slashes" do
-    it "should add a leading / to the path if not present" do
+    it "adds 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
+    it "doesn'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)

data/spec/cases/http_service_spec.rb

@@ -20,6 +20,7 @@ describe "Koala::HTTPService" do
       @builder = stub("Faraday connection builder")
       @builder.stub(:request)
       @builder.stub(:adapter)
+      @builder.stub(:use)
     end
 
     it "is defined" do
@@ -27,7 +28,7 @@ describe "Koala::HTTPService" do
     end
 
     it "adds multipart" do
-      @builder.should_receive(:request).with(:multipart)
+      @builder.should_receive(:use).with(Koala::MultipartRequest)
       Koala::HTTPService::DEFAULT_MIDDLEWARE.call(@builder)
     end
 
@@ -63,12 +64,12 @@ describe "Koala::HTTPService" do
 
       it "returns the beta REST server if options[:rest_api]" do
         server = Koala::HTTPService.server(@options.merge(:rest_api => true))
-        server.should =~ Regexp.new("beta.#{Koala::Facebook::REST_SERVER}")
+        server.should =~ Regexp.new(Koala::Facebook::REST_SERVER.gsub(/\.facebook/, ".beta.facebook"))
       end
 
       it "returns the beta rest server if !options[:rest_api]" do
         server = Koala::HTTPService.server(@options)
-        server.should =~ Regexp.new("beta.#{Koala::Facebook::GRAPH_SERVER}")
+        server.should =~ Regexp.new(Koala::Facebook::GRAPH_SERVER.gsub(/\.facebook/, ".beta.facebook"))
       end
     end
 
@@ -77,12 +78,12 @@ describe "Koala::HTTPService" do
         @options = {:video => true}
       end
 
-      it "should return the REST video server if options[:rest_api]" do
+      it "returns the REST video server if options[:rest_api]" do
         server = Koala::HTTPService.server(@options.merge(:rest_api => true))
         server.should =~ Regexp.new(Koala::Facebook::REST_SERVER.gsub(/\.facebook/, "-video.facebook"))
       end
 
-      it "should return the graph video server if !options[:rest_api]" do
+      it "returns the graph video server if !options[:rest_api]" do
         server = Koala::HTTPService.server(@options)
         server.should =~ Regexp.new(Koala::Facebook::GRAPH_SERVER.gsub(/\.facebook/, "-video.facebook"))
       end
@@ -90,11 +91,11 @@ describe "Koala::HTTPService" do
   end
 
   describe "#encode_params" do
-    it "should return an empty string if param_hash evaluates to false" do
+    it "returns an empty string if param_hash evaluates to false" do
       Koala::HTTPService.encode_params(nil).should == ''
     end
 
-    it "should convert values to JSON if the value is not a String" do
+    it "converts values to JSON if the value is not a String" do
       val = 'json_value'
       not_a_string = 'not_a_string'
       not_a_string.stub(:is_a?).and_return(false)
@@ -113,7 +114,7 @@ describe "Koala::HTTPService" do
       end.should be_true
     end
 
-    it "should escape all values" do
+    it "escapes all values" do
       args = Hash[*(1..4).map {|i| [i.to_s, "Value #{i}($"]}.flatten]
 
       result = Koala::HTTPService.encode_params(args)
@@ -123,7 +124,7 @@ describe "Koala::HTTPService" do
       end
     end
 
-    it "should convert all keys to Strings" do
+    it "converts all keys to Strings" do
       args = Hash[*(1..4).map {|i| [i, "val#{i}"]}.flatten]
 
       result = Koala::HTTPService.encode_params(args)
@@ -427,16 +428,16 @@ describe "Koala::HTTPService" do
       :net_http => Koala::NetHTTPService
     }.each_pair do |adapter, module_class|
       describe module_class.to_s do
-        it "should respond to deprecated_interface" do
+        it "responds to deprecated_interface" do
            module_class.should respond_to(:deprecated_interface)
         end
       
-        it "should issue a deprecation warning" do
+        it "issues a deprecation warning" do
           Koala::Utils.should_receive(:deprecate)
           module_class.deprecated_interface
         end
       
-        it "should set the default adapter to #{adapter}" do
+        it "sets the default adapter to #{adapter}" do
           module_class.deprecated_interface
           Faraday.default_adapter.should == adapter
         end

data/spec/cases/multipart_request_spec.rb

@@ -0,0 +1,66 @@
+require 'spec_helper'
+
+describe Koala::MultipartRequest do
+  it "is a subclass of Faraday::Request::Multipart" do
+    Koala::MultipartRequest.superclass.should == Faraday::Request::Multipart
+  end
+  
+  it "defines mime_type as multipart/form-data" do
+    Koala::MultipartRequest.mime_type.should == 'multipart/form-data'
+  end
+  
+  describe ".process_request?" do
+    before :each do
+      @env = {}
+      @multipart = Koala::MultipartRequest.new
+      @multipart.stub(:request_type).and_return("")
+    end
+    
+    # no way to test the call to super, unfortunately
+    it "returns true if env[:body] is a hash with at least one hash in its values" do
+      @env[:body] = {:a => {:c => 2}}
+      @multipart.process_request?(@env).should be_true
+    end
+
+    it "returns true if env[:body] is a hash with at least one array in its values" do
+      @env[:body] = {:a => [:c, 2]}
+      @multipart.process_request?(@env).should be_true
+    end
+
+    it "returns true if env[:body] is a hash with mixed objects in its values" do
+      @env[:body] = {:a => [:c, 2], :b => {:e => :f}}
+      @multipart.process_request?(@env).should be_true
+    end
+
+    it "returns false if env[:body] is a string" do
+      @env[:body] = "my body"
+      @multipart.process_request?(@env).should be_false
+    end
+
+    it "returns false if env[:body] is a hash without an array or hash value" do
+      @env[:body] = {:a => 3}
+      @multipart.process_request?(@env).should be_false
+    end    
+  end
+  
+  describe ".process_params" do
+    before :each do
+      @parent = Faraday::Request::Multipart.new
+      @multipart = Koala::MultipartRequest.new 
+      @block = lambda {|k, v| "#{k}=#{v}"}     
+    end
+    
+    it "is identical to the parent for requests without a prefix" do
+      hash = {:a => 2, :c => "3"}
+      @multipart.process_params(hash, &@block).should == @parent.process_params(hash, &@block)
+    end
+    
+    it "replaces encodes [ and ] if the request has a prefix" do
+      hash = {:a => 2, :c => "3"}
+      prefix = "foo"
+      # process_params returns an array
+      @multipart.process_params(hash, prefix, &@block).join("&").should == @parent.process_params(hash, prefix, &@block).join("&").gsub(/\[/, "%5B").gsub(/\]/, "%5D")
+    end
+  end
+  
+end