koala 1.0.0.beta2.1 → 1.0.0.rc

data/.gitignore

@@ -0,0 +1,3 @@
+pkg
+.project
+Gemfile.lock

data/CHANGELOG

@@ -1,11 +1,15 @@
 v1.0
 New methods:
 -- Photo and file upload now supported through #put_picture
+  -- RC: now supported natively through Typhoeus
   -- Beta 2: support for Rails 3, Sinatra, File objects, and paths (see documentation)
   -- Beta 2: Added UploadableIO class to manage file uploads
 -- Added a delete_like method (thanks to wassem)
 -- Beta 2: Added put_connection and delete_connection convenience methods
 Updated methods:
+-- RC: url_for_oauth_code can now take a :display option (thanks, netbe!)
+-- RC: Net::HTTP can now accept :timeout and :proxy options (thanks, gilles!)
+-- RC: search can now search places, checkins, etc. (thanks, rickyc!)
 -- Beta 2: TestUser#befriend now requires user info hashes (id and access token) due to Facebook API changes (thanks to pulsd/kbighorse)
 -- Beta 2: all methods now accept an http_options hash as their optional last parameter
 -- Beta 2: You can now pass :beta => true in the http options to use Facebook's beta tier.
@@ -16,11 +20,12 @@ Internal improvements:
 -- Replaced parse_signed_request with a version from Facebook that also supports the new signed params proposal
   -- Note: invalid requests will now raise exceptions rather than return nil, in keeping with other SDKs
 -- delete_object will now raise an error if there's no access token (like put_object and delete_like)
+-- Beta 2.1: Updated parse_signed_request to match Facebook's current implementation (thanks, imajes!)
 -- Beta 2: photo and file uploads now accept symbols as well as strings overall
 -- Beta 2: APIError is now < StandardError, not Exception
 -- Beta 2: Added KoalaError for non-API errors
--- Beta 3: Updated parse_signed_request to match Facebook's current implementation (thanks, imajes!)
 Test improvements:
+-- RC: Incorporated joshk's awesome rewrite of the entire Koala test suite (thanks, joshk!)
 -- Expanded HTTP service tests (added Typhoeus test suite and additional Net::HTTP test cases)
 -- Live tests now verify that the access token has the necessary permissions before starting
 -- Replaced the 50-person network test, which often took 15+ minutes to run live, with a 5-person test

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/Rakefile

@@ -1,17 +1,16 @@
-# Rakefile
-require 'rubygems'
 require 'rake'
-require 'echoe'
 
-# gem management
-Echoe.new('koala', '1.0.0.beta2.1') do |p|
-  p.summary        = "A lightweight, flexible library for Facebook with support for the Graph API, the old REST API, realtime updates, and OAuth validation."
-  p.description    = "Koala is a lightweight, flexible Ruby SDK for Facebook.  It allows read/write access to the social graph via the Graph API and the older REST API, 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."
-  p.url            = "http://github.com/arsduo/koala"
-  p.author         = ["Alex Koppel", "Chris Baclig", "Rafi Jacoby", "Context Optional"]
-  p.email          = "alex@alexkoppel.com"
-  p.ignore_pattern = ["tmp/*", "script/*", "pkg/*"]
-  p.runtime_dependencies = ["json >=1.0", "multipart-post >=1.0"]
-  p.development_dependencies = []
-  p.retain_gemspec = true
+begin
+  require 'bundler/setup'
+  Bundler::GemHelper.install_tasks
+rescue LoadError
+  puts 'although not required, bundler is recommened for running the tests'
+end
+
+
+task :default => :spec
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = ["--color", '--format doc']
 end

data/koala.gemspec

@@ -1,35 +1,50 @@
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
-  s.name = %q{koala}
-  s.version = "1.0.0.beta2.1"
+  s.name    = %q{koala}
+  s.version = "1.0.0.rc"
+  s.date    = %q{2011-04-18}
+
+  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.}
+  s.homepage    = %q{http://github.com/arsduo/koala}
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Alex Koppel, Chris Baclig, Rafi Jacoby, Context Optional"]
-  s.date = %q{2011-04-06}
-  s.description = %q{Koala is a lightweight, flexible Ruby SDK for Facebook.  It allows read/write access to the social graph via the Graph API and the older REST API, 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.}
-  s.email = %q{alex@alexkoppel.com}
-  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "lib/koala.rb", "lib/koala/graph_api.rb", "lib/koala/http_services.rb", "lib/koala/realtime_updates.rb", "lib/koala/rest_api.rb", "lib/koala/test_users.rb", "lib/koala/uploadable_io.rb"]
-  s.files = ["CHANGELOG", "LICENSE", "Manifest", "Rakefile", "init.rb", "koala.gemspec", "lib/koala.rb", "lib/koala/graph_api.rb", "lib/koala/http_services.rb", "lib/koala/realtime_updates.rb", "lib/koala/rest_api.rb", "lib/koala/test_users.rb", "lib/koala/uploadable_io.rb", "readme.md", "spec/facebook_data.yml", "spec/koala/api_base_tests.rb", "spec/koala/assets/beach.jpg", "spec/koala/graph_and_rest_api/graph_and_rest_api_no_token_tests.rb", "spec/koala/graph_and_rest_api/graph_and_rest_api_with_token_tests.rb", "spec/koala/graph_api/graph_api_no_access_token_tests.rb", "spec/koala/graph_api/graph_api_tests.rb", "spec/koala/graph_api/graph_api_with_access_token_tests.rb", "spec/koala/graph_api/graph_collection_tests.rb", "spec/koala/http_services/http_service_tests.rb", "spec/koala/http_services/net_http_service_tests.rb", "spec/koala/http_services/typhoeus_service_tests.rb", "spec/koala/live_testing_data_helper.rb", "spec/koala/oauth/oauth_tests.rb", "spec/koala/realtime_updates/realtime_updates_tests.rb", "spec/koala/rest_api/rest_api_no_access_token_tests.rb", "spec/koala/rest_api/rest_api_tests.rb", "spec/koala/rest_api/rest_api_with_access_token_tests.rb", "spec/koala/test_users/test_users_tests.rb", "spec/koala/uploadable_io/uploadable_io_tests.rb", "spec/koala_spec.rb", "spec/koala_spec_helper.rb", "spec/koala_spec_without_mocks.rb", "spec/mock_facebook_responses.yml", "spec/mock_http_service.rb"]
-  s.homepage = %q{http://github.com/arsduo/koala}
-  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Koala"]
-  s.require_paths = ["lib"]
-  s.rubyforge_project = %q{koala}
-  s.rubygems_version = %q{1.4.2}
-  s.summary = %q{A lightweight, flexible library for Facebook with support for the Graph API, the old REST API, realtime updates, and OAuth validation.}
+  s.email   = %q{alex@alexkoppel.com}
+
+  s.files = `git ls-files`.split("\n")
+  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+
+  s.extra_rdoc_files = ["readme.md", "CHANGELOG"]
+  s.rdoc_options     = ["--line-numbers", "--inline-source", "--title", "Koala"]
+
+  s.require_paths     = ["lib"]
+
+  s.rubygems_version  = %q{1.4.2}
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
 
   if s.respond_to? :specification_version then
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<json>, [">= 1.0"])
-      s.add_runtime_dependency(%q<multipart-post>, [">= 1.0"])
+      s.add_runtime_dependency(%q<json>,          ["~> 1.0"])
+      s.add_runtime_dependency(%q<multipart-post>,  ["~> 1.0"])
+      s.add_development_dependency(%q<rspec>,     ["~> 2.5.0"])
+      s.add_development_dependency(%q<rake>,      ["~> 0.8.7"])
+      s.add_development_dependency(%q<typhoeus>,  ["~> 0.2.4"])
     else
-      s.add_dependency(%q<json>, [">= 1.0"])
-      s.add_dependency(%q<multipart-post>, [">= 1.0"])
+      s.add_dependency(%q<json>,      ["~> 1.0"])
+      s.add_dependency(%q<multipart-post>,  ["~> 1.0"])
+      s.add_dependency(%q<rspec>,     ["~> 2.5.0"])
+      s.add_dependency(%q<rake>,      ["~> 0.8.7"])
+      s.add_dependency(%q<typhoeus>,  ["~> 0.2.4"])
     end
   else
-    s.add_dependency(%q<json>, [">= 1.0"])
-    s.add_dependency(%q<multipart-post>, [">= 1.0"])
+    s.add_dependency(%q<json>,      ["~> 1.0"])
+    s.add_dependency(%q<multipart-post>,  ["~> 1.0"])
+    s.add_dependency(%q<rspec>,     ["~> 2.5.0"])
+    s.add_dependency(%q<rake>,      ["~> 0.8.7"])
+    s.add_dependency(%q<typhoeus>,  ["~> 0.2.4"])
   end
 end

data/lib/koala.rb

@@ -1,27 +1,17 @@
 require 'cgi'
 require 'digest/md5'
 
-# rubygems is required to support json, how facebook returns data
-require 'rubygems'
 require 'json'
 
 # 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'
-
-# add realtime update methods
 require 'koala/realtime_updates'
-
-# add test user methods
 require 'koala/test_users'
 
 # add KoalaIO class
@@ -52,7 +42,7 @@ 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
@@ -61,7 +51,7 @@ module Koala
       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 =~ /^\//
 
@@ -173,12 +163,13 @@ module Koala
         # 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 = {})
@@ -225,7 +216,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('sha256', @app_secret, encoded_envelope.tr("-_", "+/"))
+        hmac = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, @app_secret, encoded_envelope.tr("-_", "+/"))
         raise 'SignedRequest: Invalid signature' if (signature != hmac)
 
         return envelope
@@ -299,7 +290,7 @@ module Koala
       end
     end
   end
-  
+
   class KoalaError< StandardError; end
 
   # finally, set up the http service Koala methods used to make requests

data/lib/koala/graph_api.rb

@@ -171,8 +171,8 @@ module Koala
       # Search
             
       def search(search_terms, args = {}, options = {})
-        # Searches for a given term among posts visible to the current user (or public posts if no token)
-        result = graph_call("search", args.merge(:q => search_terms), "get", options)
+        args.merge!({:q => search_terms}) unless search_terms.nil?
+        result = graph_call("search", args, "get", options)
         result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
       end      
       

data/lib/koala/http_services.rb

@@ -54,7 +54,7 @@ module Koala
           # if the verb isn't get or post, send it as a post argument
           args.merge!({:method => verb}) && verb = "post" if verb != "get" && verb != "post"
 
-          http = Net::HTTP.new(server(options), private_request ? 443 : nil)
+          http = create_http(server(options), private_request, options)
           http.use_ssl = true if private_request
 
           result = http.start do |http|
@@ -87,6 +87,22 @@ module Koala
             [key, value.kind_of?(Koala::UploadableIO) ? value.to_upload_io : value]
           end.flatten]
         end
+
+        def self.create_http(server, private_request, options)
+          if options[:proxy]
+            proxy = URI.parse(options[:proxy])
+            http  = Net::HTTP.new(server, private_request ? 443 : nil,
+                                  proxy.host, proxy.port, proxy.user, proxy.password)
+          else
+            http = Net::HTTP.new(server, private_request ? 443 : nil)
+          end
+          if options[:timeout]
+            http.open_timeout = options[:timeout]
+            http.read_timeout = options[:timeout]
+          end
+          http
+        end
+
       end
     end
   end
@@ -94,11 +110,6 @@ module Koala
   module TyphoeusService
     # this service uses Typhoeus to send requests to the graph
 
-    # used for multipart file uploads (see below)
-    class NetHTTPInterface
-      include NetHTTPService
-    end
-
     def self.included(base)
       base.class_eval do
         require "typhoeus" unless defined?(Typhoeus)
@@ -107,34 +118,28 @@ module Koala
         include Koala::HTTPService
 
         def self.make_request(path, args, verb, options = {})
-          unless params_require_multipart?(args)
-            # if the verb isn't get or post, send it as a post argument
-            args.merge!({:method => verb}) && verb = "post" if verb != "get" && verb != "post"
+          # if the verb isn't get or post, send it as a post argument
+          args.merge!({:method => verb}) && verb = "post" if verb != "get" && verb != "post"
 
-            # switch any UploadableIOs to the files Typhoeus expects 
-            # args.each_pair {|key, value| args[key] = value.to_file if value.is_a?(UploadableIO)}
+          # switch any UploadableIOs to the files Typhoeus expects 
+          args.each_pair {|key, value| args[key] = value.to_file if value.is_a?(UploadableIO)}
 
-            # you can pass arguments directly to Typhoeus using the :typhoeus_options key
-            typhoeus_options = {:params => args}.merge(options[:typhoeus_options] || {})
+          # you can pass arguments directly to Typhoeus using the :typhoeus_options key
+          typhoeus_options = {:params => args}.merge(options[:typhoeus_options] || {})
 
-            # by default, we use SSL only for private requests (e.g. with access token)
-            # this makes public requests faster
-            prefix = (args["access_token"] || @always_use_ssl || options[:use_ssl]) ? "https" : "http"
+          # by default, we use SSL only for private requests (e.g. with access token)
+          # this makes public requests faster
+          prefix = (args["access_token"] || @always_use_ssl || options[:use_ssl]) ? "https" : "http"
 
-            response = self.send(verb, "#{prefix}://#{server(options)}#{path}", typhoeus_options)
-            Koala::Response.new(response.code, response.body, response.headers_hash)
-          else
-            # we have to use NetHTTPService for multipart for file uploads
-            # until Typhoeus integrates support
-            Koala::TyphoeusService::NetHTTPInterface.make_request(path, args, verb, options)
-          end
+          response = self.send(verb, "#{prefix}://#{server(options)}#{path}", typhoeus_options)
+          Koala::Response.new(response.code, response.body, response.headers_hash)
         end
         
         private
-        # Typhoeus file uploads are not currently supported; this will be added when we can get them working
-        #def self.multipart_requires_content_type?
-        #  false # Typhoeus handles multipart file types, we don't have to require it
-        #end
+        
+        def self.multipart_requires_content_type?
+          false # Typhoeus handles multipart file types, we don't have to require it
+        end
       end # class_eval
     end
   end

data/lib/koala/test_users.rb

@@ -20,11 +20,11 @@ module Koala
         @graph_api = GraphAPI.new(@app_access_token)
       end
 
-      def create(installed, permissions = nil)
+      def create(installed, permissions = nil, args = {}, options = {})
         # Creates and returns a test user
-        args = {'installed' => installed}
+        args['installed'] = installed
         args['permissions'] = (permissions.is_a?(Array) ? permissions.join(",") : permissions) if installed
-        result = @graph_api.graph_call(accounts_path, args, "post")
+        result = @graph_api.graph_call(accounts_path, args, "post", options)
       end
       
       def list
@@ -49,7 +49,7 @@ module Koala
           # we explicitly raise an error here to minimize the risk of confusing output
           # if you pass in a string (as was previously supported) no local exception would be raised
           # but the Facebook call would fail
-          raise ArgumentError, "TestUsers#befriend requires hash arguments with id and access_token"
+          raise ArgumentError, "TestUsers#befriend requires hash arguments for both users with id and access_token"
         end
         
         u1_graph_api = GraphAPI.new(user1_token)

data/lib/koala/uploadable_io.rb

@@ -42,7 +42,7 @@ module Koala
       
       # Expects a parameter of type ActionDispatch::Http::UploadedFile
       def parse_rails_3_param(uploaded_file)
-        if uploaded_file.respond_to?(:content_type) and uploaded_file.respond_to?(:tempfile) and uploaded_file.respond_to?(:path)
+        if uploaded_file.respond_to?(:content_type) and uploaded_file.respond_to?(:tempfile) and uploaded_file.tempfile.respond_to?(:path)
           @io_or_path = uploaded_file.tempfile.path
           @content_type = uploaded_file.content_type
         end

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