koala 0.10.0 → 1.0.0.beta

data/lib/koala/graph_api.rb

@@ -142,7 +142,7 @@ module Koala
         # Writes a wall post to the given profile's wall.
         # 
         # We default to writing to the authenticated user's wall if no
-        # profile_id is specified.
+        # profile_id is specified.  
         # 
         # attachment adds a structured attachment to the status message being
         # posted to the Wall. It should be a dictionary of the form:
@@ -155,7 +155,14 @@ module Koala
 
         self.put_object(profile_id, "feed", attachment.merge({:message => message}))
       end
-    
+      
+      def put_picture(file_hash, args = {}, target_id = "me")
+        raise APIError.new("type" => "KoalaInvaliFileFormat", "message" => "put_picture requires a hash describing the File to upload (see HTTPService::is_valid_file_hash?") unless file_hash.kind_of?(Hash)
+        
+        args["source"] = file_hash
+        self.put_object(target_id, "photos", args)
+      end
+      
       def put_comment(object_id, message)
         # Writes the given comment on the given post.
         self.put_object(object_id, "comments", {:message => message})
@@ -165,9 +172,15 @@ module Koala
         # Likes the given post.
         self.put_object(object_id, "likes")
       end
+
+      def delete_like(object_id)
+        raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Unliking requires an access token"}) unless @access_token
+        graph_call("#{object_id}/likes", {}, "delete")
+      end
     
       def delete_object(id)
         # Deletes the object with the given ID from the graph.
+        raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Unliking requires an access token"}) unless @access_token
         graph_call(id, {}, "delete")
       end
     
@@ -189,4 +202,4 @@ module Koala
       end
     end
   end
-end
+end

data/lib/koala/http_services.rb

@@ -8,62 +8,146 @@ module Koala
     end
   end
 
+  module HTTPService
+    # common functionality for all HTTP services
+    def self.included(base)
+      base.class_eval do
+        class << self
+          attr_accessor :always_use_ssl
+        end
+        
+        protected
+        def self.params_require_multipart?(param_hash)
+          param_hash.any? { |key, value| is_valid_file_hash?(value) }
+        end
+        
+        # A file hash can take two forms:
+        # - A hash with "content_type" and "path" keys where "path" is the local path
+        #   to the file to be uploaded.
+        # - A hash with the "file" key containing an already-opened IO that responds to "read"
+        #   as well as "content_type" and the "path" key to the original file
+        #   ("path"" is required by multipart-post even for opened files)
+        #
+        # Valid inputs for a file to be posted via multipart/form-data
+        # are based on the criteria for an UploadIO to be created 
+        # See : https://github.com/nicksieger/multipart-post/blob/master/lib/composite_io.rb       
+        def self.is_valid_file_hash?(value)
+          value.kind_of?(Hash) and value.key?("content_type") and value.key?("path") and (
+            !value.key?("file") or value["file"].respond_to?(:read)
+          )
+        end
+      end
+    end
+  end
+
   module NetHTTPService
     # this service uses Net::HTTP to send requests to the graph
     def self.included(base)
       base.class_eval do
-        require 'net/http' unless defined?(Net::HTTP)
-        require 'net/https'
+        require "net/http" unless defined?(Net::HTTP)
+        require "net/https"
+        require "net/http/post/multipart"
+
+        include Koala::HTTPService
 
         def self.make_request(path, args, verb, options = {})
           # We translate args to a valid query string. If post is specified,
           # we send a POST request to the given path with the given arguments.
 
+          # by default, we use SSL only for private requests
+          # this makes public requests faster
+          private_request = args["access_token"] || @always_use_ssl || options[:use_ssl]
+
           # 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"
 
           server = options[:rest_api] ? Facebook::REST_SERVER : Facebook::GRAPH_SERVER
-          http = Net::HTTP.new(server, 443)
-          http.use_ssl = true
-          # we turn off certificate validation to avoid the 
+          http = Net::HTTP.new(server, private_request ? 443 : nil)
+          http.use_ssl = true if private_request
+
+          # we turn off certificate validation to avoid the
           # "warning: peer certificate won't be verified in this SSL session" warning
           # not sure if this is the right way to handle it
           # see http://redcorundum.blogspot.com/2008/03/ssl-certificates-and-nethttps.html
           http.verify_mode = OpenSSL::SSL::VERIFY_NONE
 
-          result = http.start { |http|
-            response, body = (verb == "post" ? http.post(path, encode_params(args)) : http.get("#{path}?#{encode_params(args)}"))
+          result = http.start do |http|
+            response, body = if verb == "post"
+              if params_require_multipart? args
+                http.request Net::HTTP::Post::Multipart.new path, encode_multipart_params(args)
+              else
+                http.post(path, encode_params(args))
+              end
+            else
+              http.get("#{path}?#{encode_params(args)}")
+            end
+            
             Koala::Response.new(response.code.to_i, body, response)
-          }
+          end
         end
 
         protected
         def self.encode_params(param_hash)
           # unfortunately, we can't use to_query because that's Rails, not Ruby
           # if no hash (e.g. no auth token) return empty string
-          ((param_hash || {}).collect do |key_and_value| 
+          ((param_hash || {}).collect do |key_and_value|
             key_and_value[1] = key_and_value[1].to_json if key_and_value[1].class != String
             "#{key_and_value[0].to_s}=#{CGI.escape key_and_value[1]}"
           end).join("&")
         end
+        
+        def self.encode_multipart_params(param_hash)
+          Hash[*param_hash.collect do |key, value| 
+            if is_valid_file_hash?(value)
+              if value.key?("file")
+                value = UploadIO.new(value["file"], value["content_type"], value["path"])
+              else
+                value = UploadIO.new(value["path"], value['content_type'])
+              end
+            end
+            
+            [key, value]
+          end.flatten]
+        end
       end
     end
   end
 
   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)
+        require "typhoeus" unless defined?(Typhoeus)
         include Typhoeus
+        
+        include Koala::HTTPService
 
         def self.make_request(path, args, verb, options = {})
-          # 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"
-          server = options[:rest_api] ? Facebook::REST_SERVER : Facebook::GRAPH_SERVER
-          typhoeus_options = {:params => args}.merge(options[:typhoeus_options] || {})
-          response = self.send(verb, "https://#{server}#{path}", typhoeus_options)
-          Koala::Response.new(response.code, response.body, response.headers_hash)
+          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"
+            server = options[:rest_api] ? Facebook::REST_SERVER : Facebook::GRAPH_SERVER
+
+            # 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"
+
+            response = self.send(verb, "#{prefix}://#{server}#{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
         end
       end # class_eval
     end

data/lib/koala/rest_api.rb

@@ -1,23 +1,90 @@
 module Koala
   module Facebook
     REST_SERVER = "api.facebook.com"
-    
+
     module RestAPIMethods
       def fql_query(fql)
         rest_call('fql.query', 'query' => fql)
       end
-      
-      def rest_call(method, args = {})
-        response = api("method/#{method}", args.merge('format' => 'json'), 'get', :rest_api => true) do |response|
+
+      def rest_call(method, args = {}, options = {})
+        options = options.merge!(:rest_api => true, :read_only => READ_ONLY_METHODS.include?(method))
+
+        response = api("method/#{method}", args.merge('format' => 'json'), 'get', options) do |response|
           # check for REST API-specific errors
           if response.is_a?(Hash) && response["error_code"]
             raise APIError.new("type" => response["error_code"], "message" => response["error_msg"])
           end
         end
-        
+
         response
       end
+
+      # read-only methods for which we can use API-read
+      # taken directly from the FB PHP library (https://github.com/facebook/php-sdk/blob/master/src/facebook.php)
+      READ_ONLY_METHODS = [
+        'admin.getallocation',
+        'admin.getappproperties',
+        'admin.getbannedusers',
+        'admin.getlivestreamvialink',
+        'admin.getmetrics',
+        'admin.getrestrictioninfo',
+        'application.getpublicinfo',
+        'auth.getapppublickey',
+        'auth.getsession',
+        'auth.getsignedpublicsessiondata',
+        'comments.get',
+        'connect.getunconnectedfriendscount',
+        'dashboard.getactivity',
+        'dashboard.getcount',
+        'dashboard.getglobalnews',
+        'dashboard.getnews',
+        'dashboard.multigetcount',
+        'dashboard.multigetnews',
+        'data.getcookies',
+        'events.get',
+        'events.getmembers',
+        'fbml.getcustomtags',
+        'feed.getappfriendstories',
+        'feed.getregisteredtemplatebundlebyid',
+        'feed.getregisteredtemplatebundles',
+        'fql.multiquery',
+        'fql.query',
+        'friends.arefriends',
+        'friends.get',
+        'friends.getappusers',
+        'friends.getlists',
+        'friends.getmutualfriends',
+        'gifts.get',
+        'groups.get',
+        'groups.getmembers',
+        'intl.gettranslations',
+        'links.get',
+        'notes.get',
+        'notifications.get',
+        'pages.getinfo',
+        'pages.isadmin',
+        'pages.isappadded',
+        'pages.isfan',
+        'permissions.checkavailableapiaccess',
+        'permissions.checkgrantedapiaccess',
+        'photos.get',
+        'photos.getalbums',
+        'photos.gettags',
+        'profile.getinfo',
+        'profile.getinfooptions',
+        'stream.get',
+        'stream.getcomments',
+        'stream.getfilters',
+        'users.getinfo',
+        'users.getloggedinuser',
+        'users.getstandardinfo',
+        'users.hasapppermission',
+        'users.isappuser',
+        'users.isverified',
+        'video.getuploadlimits'
+      ]
     end
-    
+
   end # module Facebook
 end # module Koala

data/readme.md

@@ -1,28 +1,28 @@
 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, 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.)
 
 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 +33,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,15 +41,15 @@ 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.)
 
@@ -119,7 +119,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
 

data/spec/facebook_data.yml

@@ -4,7 +4,7 @@
 # Just remember to update all fields!
  
 # You must supply this value yourself to test the GraphAPI class.
-# Your OAuth token should have publish_stream and read_stream permissions.
+# Your OAuth token should have publish_stream, read_stream, and user_photos permissions.
 oauth_token: 
 
 # for testing the OAuth class    
@@ -44,8 +44,14 @@ oauth_test_data:
   signed_request_result:
       "0": payload
       algorithm: HMAC-SHA256
-    
-  
+  # signed params
+  # examples from http://developers.facebook.com/docs/authentication/canvas/encryption_proposal
+  signed_params: t63pZQ4Q3ZTHJt0hOsKrY2pb28xRlduW0pg4lL_Zhl4.eyJhbGdvcml0aG0iOiJBRVMtMjU2LUNCQyBITUFDLVNIQTI1NiIsImlzc3VlZF9hdCI6MTI4NzYwMTk4OCwiaXYiOiJmRExKQ1cteWlYbXVOYTI0ZVNhckpnIiwicGF5bG9hZCI6IllHeW00cG9Rbk1UckVnaUFPa0ZUVkk4NWxsNVJ1VWlFbC1JZ3FmeFRPVEhRTkl2VlZJOFk4a1Z1T29lS2FXT2Vhc3NXRlRFdjBRZ183d0NDQkVlbjdsVUJCemxGSjFWNjNISjNBZjBTSW5nY3hXVEo3TDZZTGF0TW13WGdEQXZXbjVQc2ZxeldrNG1sOWg5RExuWXB0V0htREdMNmlCaU9oTjdXeUk3cDZvRXBWcmlGdUp3X2NoTG9QYjhhM3ZHRG5vVzhlMlN4eDA2QTJ4MnhraWFwdmcifQ
+  signed_params_secret: 13750c9911fec5865d01f3bd00bdf4db
+  signed_params_result:
+    access_token: "101244219942650|2.wdrSr7KyE_VwQ0fjwOfW9A__.3600.1287608400-499091902|XzxMQd-_4tjlC2VEgide4rmg6LI"
+    expires_in: 6412
+    user_id: "499091902"
 
 subscription_test_data:
   subscription_path: http://oauth.twoalex.com/subscriptions

data/spec/koala/graph_and_rest_api/graph_and_rest_api_no_token_tests.rb

@@ -3,8 +3,12 @@ class GraphAndRestAPINoTokenTests < Test::Unit::TestCase
     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/koala/graph_and_rest_api/graph_and_rest_api_with_token_tests.rb

@@ -1,11 +1,16 @@
 class GraphAndRestAPIWithTokenTests < Test::Unit::TestCase
   describe "Koala GraphAndRestAPI without an access token" do
     include LiveTestingDataHelper
-    it_should_behave_like "Koala RestAPI with an access token"
-    it_should_behave_like "Koala GraphAPI with an access token"
-    
+
     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
 end

data/spec/koala/graph_api/graph_api_no_access_token_tests.rb

@@ -1,9 +1,4 @@
 shared_examples_for "Koala GraphAPI without an access token" do
-  it "should get public data about a user" do
-    result = @api.get_object("koppel")
-    # the results should have an ID and a name, among other things
-    (result["id"] && result["name"]).should
-  end
 
   it "should not get private data about a user" do
     result = @api.get_object("koppel")
@@ -11,46 +6,14 @@ shared_examples_for "Koala GraphAPI without an access token" do
     result["updated_time"].should be_nil
   end
 
-  it "should get public data about a Page" do
-    result = @api.get_object("contextoptional")
-    # the results should have an ID and a name, among other things
-    (result["id"] && result["name"]).should
-  end
-
   it "should not be able to get data about 'me'" do
     lambda { @api.get_object("me") }.should raise_error(Koala::Facebook::APIError)
   end
 
-  it "should be able to get multiple objects" do
-    results = @api.get_objects(["contextoptional", "naitik"])
-    results.length.should == 2
-  end
-
   it "shouldn't be able to access connections from users" do
     lambda { @api.get_connections("lukeshepard", "likes") }.should raise_error(Koala::Facebook::APIError)
   end
 
-  it "should be able to access a user's picture" do
-    @api.get_picture("chris.baclig").should =~ /http\:\/\//
-  end
-
-  it "should be able to access a user's picture, given a picture type"  do
-    @api.get_picture("chris.baclig", {:type => 'large'}).should =~ /^http\:\/\//
-  end
-
-  it "should be able to access connections from public Pages" do
-    result = @api.get_connections("contextoptional", "photos")
-    result.should be_a(Array)
-  end
-  
-  # paging
-  # see also graph_collection_tests
-  it "should make a request for a page when provided a specific set of page params" do
-    query = [1, 2]
-    @api.should_receive(:graph_call).with(*query)
-    @api.get_page(query)
-  end
-
   it "should not be able to put an object" do
     lambda { @result = @api.put_object("lukeshepard", "feed", :message => "Hello, world") }.should raise_error(Koala::Facebook::APIError)
     puts "Error!  Object #{@result.inspect} somehow put onto Luke Shepard's wall!" if @result
@@ -60,7 +23,7 @@ shared_examples_for "Koala GraphAPI without an access token" do
   it "should not be able to post to a feed" do
     (lambda do
       attachment = {:name => "Context Optional", :link => "http://www.contextoptional.com/"}
-      @result = @api.put_wall_post("Hello, world", attachment, "contextoptional") 
+      @result = @api.put_wall_post("Hello, world", attachment, "contextoptional")
     end).should raise_error(Koala::Facebook::APIError)
     puts "Error!  Object #{@result.inspect} somehow put onto Context Optional's wall!" if @result
   end
@@ -68,7 +31,7 @@ shared_examples_for "Koala GraphAPI without an access token" do
   it "should not be able to comment on an object" do
     # random public post on the ContextOptional wall
     lambda { @result = @api.put_comment("7204941866_119776748033392", "The hackathon was great!") }.should raise_error(Koala::Facebook::APIError)
-    puts "Error!  Object #{@result.inspect} somehow commented on post 7204941866_119776748033392!" if @result    
+    puts "Error!  Object #{@result.inspect} somehow commented on post 7204941866_119776748033392!" if @result
   end
 
   it "should not be able to like an object" do
@@ -76,29 +39,13 @@ shared_examples_for "Koala GraphAPI without an access token" do
   end
   
   # DELETE
-  it "should not be able to delete posts" do 
+  it "should not be able to delete posts" do
     # test post on the Ruby SDK Test application
     lambda { @result = @api.delete_object("115349521819193_113815981982767") }.should raise_error(Koala::Facebook::APIError)
   end
-
-  # SEARCH
-  it "should be able to search" do
-    result = @api.search("facebook")
-    result.length.should be_an(Integer)
-  end
-
-  it_should_behave_like "Koala GraphAPI with GraphCollection"
   
-  # API
-  it "should never use the rest api server" do
-    Koala.should_receive(:make_request).with(
-      anything,
-      anything,
-      anything,
-      hash_not_including(:rest_api => true)
-    ).and_return(Koala::Response.new(200, "", {}))      
-    
-    @api.api("anything")
+  it "should not be able to delete a like" do
+    lambda { @api.delete_like("7204941866_119776748033392") }.should raise_error(Koala::Facebook::APIError)
   end
 end
 
@@ -106,9 +53,11 @@ class FacebookNoAccessTokenTests < Test::Unit::TestCase
   describe "Koala GraphAPI without an access token" do
     before :each do
       @api = Koala::Facebook::GraphAPI.new
-    end  
-    
+    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
-