koala 1.0.0 → 1.1.0rc

data/lib/koala/realtime_updates.rb

@@ -46,6 +46,8 @@ module Koala
           oauth = Koala::Facebook::OAuth.new(@app_id, @secret)
           @app_access_token = oauth.get_app_access_token
         end
+        
+        @graph_api = GraphAPI.new(@app_access_token)
       end
       
       # subscribes for realtime updates
@@ -59,7 +61,7 @@ module Koala
           :verify_token => verify_token
         }
         # a subscription is a success if Facebook returns a 200 (after hitting your server for verification)
-        api(subscription_path, args, 'post', :http_component => :status) == 200
+        @graph_api.graph_call(subscription_path, args, 'post', :http_component => :status) == 200
       end
           
       # removes subscription for object
@@ -67,24 +69,13 @@ module Koala
       def unsubscribe(object = nil)
         args = {}
         args[:object] = object if object
-        api(subscription_path, args, 'delete', :http_component => :status) == 200
+        @graph_api.graph_call(subscription_path, args, 'delete', :http_component => :status) == 200
       end
   
       def list_subscriptions
-        api(subscription_path)["data"]
+        @graph_api.graph_call(subscription_path)["data"]
       end
       
-      def api(*args) # same as GraphAPI
-        response = super(*args) do |response|
-          # check for subscription errors
-          if response.is_a?(Hash) && error_details = response["error"]
-            raise APIError.new(error_details)
-          end
-        end
-      
-        response
-      end    
-      
       protected
       
       def subscription_path

data/lib/koala/rest_api.rb

@@ -3,21 +3,26 @@ module Koala
     REST_SERVER = "api.facebook.com"
 
     module RestAPIMethods
-      def fql_query(fql)
-        rest_call('fql.query', 'query' => fql)
+      def fql_query(fql, args = {}, options = {})
+        rest_call('fql.query', args.merge(:query => fql), options) 
       end
 
-      def rest_call(method, args = {}, options = {})
-        options = options.merge!(:rest_api => true, :read_only => READ_ONLY_METHODS.include?(method))
+      def fql_multiquery(queries = {}, args = {}, options = {})
+        if results = rest_call('fql.multiquery', args.merge(:queries => queries.to_json), options)
+          # simplify the multiquery result format
+          results.inject({}) {|outcome, data| outcome[data["name"]] = data["fql_result_set"]; outcome}
+        end
+      end
 
-        response = api("method/#{method}", args.merge('format' => 'json'), 'get', options) do |response|
+      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))
+
+        api("method/#{fb_method}", args.merge('format' => 'json'), method, 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
@@ -87,4 +92,4 @@ module Koala
     end
 
   end # module Facebook
-end # module Koala
+end # module Koala

data/lib/koala/uploadable_io.rb

@@ -2,9 +2,9 @@ require 'koala'
 
 module Koala
   class UploadableIO
-    attr_reader :io_or_path, :content_type
+    attr_reader :io_or_path, :content_type, :requires_base_http_service
 
-    def initialize(io_or_path_or_mixed, content_type = nil)
+    def initialize(io_or_path_or_mixed, content_type = nil, filename = nil)
       # see if we got the right inputs
       if content_type.nil?
         parse_init_mixed_param io_or_path_or_mixed
@@ -13,19 +13,35 @@ module Koala
         @content_type = content_type
       end
       
+      # Probably a StringIO or similar object, which won't work with Typhoeus
+      @requires_base_http_service = @io_or_path.respond_to?(:read) && !@io_or_path.kind_of?(File)
+
+      # filename is used in the Ads API
+      @filename = filename || "koala-io-file.dum"
+
       raise KoalaError.new("Invalid arguments to initialize an UploadableIO") unless @io_or_path
       raise KoalaError.new("Unable to determine MIME type for UploadableIO") if !@content_type && Koala.multipart_requires_content_type?
     end
     
     def to_upload_io
-      UploadIO.new(@io_or_path, @content_type, "koala-io-file.dum")
+      UploadIO.new(@io_or_path, @content_type, @filename)
     end
     
     def to_file
       @io_or_path.is_a?(String) ? File.open(@io_or_path) : @io_or_path
     end
+    
+    def self.binary_content?(content)
+      content.is_a?(UploadableIO) || DETECTION_STRATEGIES.detect {|method| send(method, content)}
+    end
 
     private
+      DETECTION_STRATEGIES = [
+        :sinatra_param?,
+        :rails_3_param?,
+        :file_param?
+      ]
+    
       PARSE_STRATEGIES = [
         :parse_rails_3_param,
         :parse_sinatra_param,
@@ -41,24 +57,36 @@ module Koala
       end
       
       # Expects a parameter of type ActionDispatch::Http::UploadedFile
+      def self.rails_3_param?(uploaded_file)
+        uploaded_file.respond_to?(:content_type) and uploaded_file.respond_to?(:tempfile) and uploaded_file.tempfile.respond_to?(:path)
+      end
+      
       def parse_rails_3_param(uploaded_file)
-        if uploaded_file.respond_to?(:content_type) and uploaded_file.respond_to?(:tempfile) and uploaded_file.tempfile.respond_to?(:path)
+        if UploadableIO.rails_3_param?(uploaded_file) 
           @io_or_path = uploaded_file.tempfile.path
           @content_type = uploaded_file.content_type
         end
       end
       
       # Expects a Sinatra hash of file info
+      def self.sinatra_param?(file_hash)
+        file_hash.kind_of?(Hash) and file_hash.has_key?(:type) and file_hash.has_key?(:tempfile)
+      end
+      
       def parse_sinatra_param(file_hash)
-        if file_hash.kind_of?(Hash) and file_hash.has_key?(:type) and file_hash.has_key?(:tempfile)
+        if UploadableIO.sinatra_param?(file_hash)
           @io_or_path = file_hash[:tempfile]
           @content_type = file_hash[:type] || detect_mime_type(tempfile)
         end
       end
       
       # takes a file object
+      def self.file_param?(file)
+        file.kind_of?(File)
+      end
+      
       def parse_file_object(file)
-        if file.kind_of?(File)
+        if UploadableIO.file_param?(file)
           @io_or_path = file
           @content_type = detect_mime_type(file.path)
         end
@@ -112,4 +140,4 @@ module Koala
         end
       end
   end
-end
+end

data/readme.md

@@ -1,21 +1,24 @@
 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 (including photo uploads), the old REST API, realtime updates, and OAuth validation.  We wrote Koala with four goals:
+Koala (<a href="http://github.com/arsduo/koala" target="_blank">http://github.com/arsduo/koala</a>) is a new Facebook library for Ruby, supporting the Graph API (including the batch requests and photo uploads), the REST API, realtime updates, test users, 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 750 lines of code.)
 * Fast: Koala should, out of the box, be quick. In addition to supporting the vanilla Ruby networking libraries, it natively supports Typhoeus, our preferred gem for making fast HTTP requests. Of course, That brings us to our next topic:
 * Flexible: Koala should be useful to everyone, regardless of their current configuration.  (We have no dependencies beyond the JSON gem.  Koala also has a built-in mechanism for using whichever HTTP library you prefer to make requests against the graph.)
 * Tested: Koala should have complete test coverage, so you can rely on it.  (Our complete test coverage can be run against either mocked responses or the live Facebook servers.)
 
-1.0 
+Installation
 ---
-Version 1.0 is due out on May 1st, 2011 with a ton of great features.  
+
+Easy:
+    
+    [sudo|rvm] gem install koala
+    # for 1.1rc add --pre
     
-    sudo gem install koala
 
-Until then, you can install the release candidate like so:
+Or in Bundler:
   
-    sudo gem install koala --pre
+    gem "koala" # add ', "~> 1.1rc"' for the release candidate
   
 Graph API
 ----
@@ -47,6 +50,15 @@ When retrieving data that returns an array of results (for example, when calling
     # You can use those params to easily get the next (or prevous) page
     page = graph.get_page(feed.next_page_params)
 
+You can make multiple calls at once using Facebook's batch API:
+
+    # Returns an array of results as if they were called non-batch
+    graph.batch do
+      graph.get_connections('me', 'friends')
+      graph.get_object('me')
+      graph.get_picture('me')
+    end
+
 Check out the wiki for more examples.
 
 The old-school REST API
@@ -140,4 +152,4 @@ You can also run live tests against Facebook's servers:
     # Again from anywhere in the project directory:
     LIVE=true rake spec
 
-Important Note: to run the live tests, you have to provide some of your own data in spec/fixtures/facebook_data.yml: a valid OAuth access token with publish\_stream, read\_stream, and user\_photos permissions and an OAuth code that can be used to generate an access token.  You can get thisdata at the OAuth Playground; if you want to use your own app, remember to swap out the app ID, secret, and other values.  (The file also provides valid values for other tests, which you're welcome to swap out for data specific to your own application.)
+Important Note: to run the live tests, you have to provide some of your own data in spec/fixtures/facebook_data.yml: a valid OAuth access token with publish\_stream, read\_stream, and user\_photos permissions and an OAuth code that can be used to generate an access token.  You can get thisdata at the OAuth Playground; if you want to use your own app, remember to swap out the app ID, secret, and other values.  (The file also provides valid values for other tests, which you're welcome to swap out for data specific to your own application.)

data/spec/cases/api_base_spec.rb

@@ -57,14 +57,14 @@ describe "Koala::Facebook::API" do
     @service.api('anything').should == json_body
   end
 
-  it "should execute a block with the response body if passed one" do
+  it "should execute an error checking block if provided" 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|
+    @service.api('anything', {}, "get") do |arg|
       yield_test.pass
       arg.should == JSON.parse(body)
     end

data/spec/cases/graph_api_batch_spec.rb

@@ -0,0 +1,600 @@
+require 'spec_helper'
+
+describe "Koala::Facebook::GraphAPI in batch mode" do
+  include LiveTestingDataHelper
+  before :each do
+    @api = Koala::Facebook::GraphAPI.new(@token)
+    # app API
+    @oauth_data = $testing_data["oauth_test_data"]
+    @app_id = @oauth_data["app_id"]
+    @app_access_token = @oauth_data["app_access_token"]
+    @app_api = Koala::Facebook::GraphAPI.new(@app_access_token)
+  end 
+  
+  describe "BatchOperations" do
+    before :each do
+      @args = {
+        :url => "my url",
+        :args => {:a => 2, :b => 3},
+        :method => "get",
+        :access_token => "12345",
+        :http_options => {},
+        :post_processing => lambda { }
+      }
+    end
+    
+    describe "#new" do
+      it "makes http_options accessible" do
+        Koala::Facebook::BatchOperation.new(@args).http_options.should == @args[:http_options]
+      end
+      
+      it "makes post_processing accessible" do
+        Koala::Facebook::BatchOperation.new(@args).post_processing.should == @args[:post_processing]
+      end
+      
+      it "makes access_token accessible" do
+        Koala::Facebook::BatchOperation.new(@args).access_token.should == @args[:access_token]
+      end
+            
+      it "doesn't change the original http_options" do
+        @args[:http_options][:name] = "baz2"
+        expected = @args[:http_options].dup
+        Koala::Facebook::BatchOperation.new(@args).to_batch_params(nil)
+        @args[:http_options].should == expected
+      end
+      
+      it "leaves the file array nil by default" do
+        Koala::Facebook::BatchOperation.new(@args).files.should be_nil        
+      end
+      
+      it "raises a KoalaError if no access token supplied" do
+        expect { Koala::Facebook::BatchOperation.new(@args.merge(:access_token => nil)) }.to raise_exception(Koala::KoalaError)
+      end
+      
+      describe "when supplied binary files" do
+        before :each do
+          @binary = stub("Binary file")
+          @uploadable_io = stub("UploadableIO 1")
+          
+          @batch_queue = []
+          Koala::Facebook::GraphAPI.stub(:batch_calls).and_return(@batch_queue)
+          
+          Koala::UploadableIO.stub(:new).with(@binary).and_return(@uploadable_io)
+          Koala::UploadableIO.stub(:binary_content?).and_return(false)
+          Koala::UploadableIO.stub(:binary_content?).with(@binary).and_return(true)
+          Koala::UploadableIO.stub(:binary_content?).with(@uploadable_io).and_return(true)
+          @uploadable_io.stub(:is_a?).with(Koala::UploadableIO).and_return(true)
+
+          @args[:method] = "post" # files are always post
+        end
+        
+        it "adds binary files to the files attribute as UploadableIOs" do
+          @args[:args].merge!("source" => @binary)
+          batch_op = Koala::Facebook::BatchOperation.new(@args)
+          batch_op.files.should_not be_nil
+          batch_op.files.find {|k, v| v == @uploadable_io}.should_not be_nil
+        end
+        
+        it "works if supplied an UploadableIO as an argument" do
+          # as happens with put_picture at the moment
+          @args[:args].merge!("source" => @uploadable_io)
+          batch_op = Koala::Facebook::BatchOperation.new(@args)
+          batch_op.files.should_not be_nil
+          batch_op.files.find {|k, v| v == @uploadable_io}.should_not be_nil
+        end
+                
+        it "assigns each binary parameter unique name" do
+          @args[:args].merge!("source" => @binary, "source2" => @binary)
+          batch_op = Koala::Facebook::BatchOperation.new(@args)
+          # if the name wasn't unique, there'd just be one item
+          batch_op.files.should have(2).items
+        end
+        
+        it "assigns each binary parameter unique name across batch requests" do
+          @args[:args].merge!("source" => @binary, "source2" => @binary)
+          batch_op = Koala::Facebook::BatchOperation.new(@args)
+          # simulate the batch operation, since it's used in determination
+          @batch_queue << batch_op
+          batch_op2 = Koala::Facebook::BatchOperation.new(@args)
+          @batch_queue << batch_op2
+          # if the name wasn't unique, we should have < 4 items since keys would be the same
+          batch_op.files.merge(batch_op2.files).should have(4).items
+        end
+        
+        it "removes the value from the arguments" do
+          @args[:args].merge!("source" => @binary)
+          Koala::Facebook::BatchOperation.new(@args).to_batch_params(nil)[:body].should_not =~ /source=/
+        end
+      end   
+      
+    end
+    
+    describe ".to_batch_params" do    
+      describe "handling arguments and URLs" do
+        shared_examples_for "request with no body" do
+          it "adds the args to the URL string, with ? if no args previously present" do
+            test_args = "foo"
+            @args[:url] = url = "/"
+            Koala.http_service.stub(:encode_params).and_return(test_args)
+          
+            Koala::Facebook::BatchOperation.new(@args).to_batch_params(nil)[:relative_url].should == "#{url}?#{test_args}"
+          end
+        
+          it "adds the args to the URL string, with & if args previously present" do
+            test_args = "foo"
+            @args[:url] = url = "/?a=2"
+            Koala.http_service.stub(:encode_params).and_return(test_args)
+          
+            Koala::Facebook::BatchOperation.new(@args).to_batch_params(nil)[:relative_url].should == "#{url}&#{test_args}"
+          end
+          
+          it "adds nothing to the URL string if there are no args to be added" do
+            @args[:args] = {}
+            Koala::Facebook::BatchOperation.new(@args).to_batch_params(@args[:access_token])[:relative_url].should == @args[:url]            
+          end
+          
+          it "adds nothing to the body" do
+            Koala::Facebook::BatchOperation.new(@args).to_batch_params(nil)[:body].should be_nil
+          end
+        end
+        
+        shared_examples_for "requests with a body param" do
+          it "sets the body to the encoded args string, if there are args" do
+            test_args = "foo"
+            Koala.http_service.stub(:encode_params).and_return(test_args)
+          
+            Koala::Facebook::BatchOperation.new(@args).to_batch_params(nil)[:body].should == test_args
+          end
+          
+          it "does not set the body if there are no args" do
+            test_args = ""
+            Koala.http_service.stub(:encode_params).and_return(test_args)
+            Koala::Facebook::BatchOperation.new(@args).to_batch_params(nil)[:body].should be_nil
+          end
+          
+        
+          it "doesn't change the url" do
+            test_args = "foo"
+            Koala.http_service.stub(:encode_params).and_return(test_args)
+
+            Koala::Facebook::BatchOperation.new(@args).to_batch_params(nil)[:relative_url].should == @args[:url]
+          end
+        end
+            
+        context "for get operations" do
+          before :each do
+            @args[:method] = :get
+          end
+        
+          it_should_behave_like "request with no body"        
+        end
+      
+        context "for delete operations" do
+          before :each do
+            @args[:method] = :delete
+          end
+        
+          it_should_behave_like "request with no body"        
+        end
+      
+        context "for get operations" do
+          before :each do
+            @args[:method] = :put
+          end
+        
+          it_should_behave_like "requests with a body param"  
+        end
+      
+        context "for delete operations" do
+          before :each do
+            @args[:method] = :post
+          end
+        
+          it_should_behave_like "requests with a body param"       
+        end
+      end
+    
+      it "includes the access token if the token is not the main one for the request" do
+         params = Koala::Facebook::BatchOperation.new(@args).to_batch_params(nil)
+         params[:relative_url].should =~ /access_token=#{@args[:access_token]}/
+      end
+
+      it "includes the other arguments if the token is not the main one for the request" do
+        @args[:args] = {:a => 2}
+        params = Koala::Facebook::BatchOperation.new(@args).to_batch_params(nil)
+        params[:relative_url].should =~ /a=2/
+      end
+
+      it "does not include the access token if the token is the main one for the request" do
+         params = Koala::Facebook::BatchOperation.new(@args).to_batch_params(@args[:access_token])
+         params[:relative_url].should_not =~ /access_token=#{@args[:access_token]}/
+      end
+      
+      it "includes the other arguments if the token is the main one for the request" do
+        @args[:args] = {:a => 2}
+        params = Koala::Facebook::BatchOperation.new(@args).to_batch_params(@args[:access_token])
+        params[:relative_url].should =~ /a=2/
+      end
+      
+      it "includes any arguments passed as http_options[:batch_args]" do
+        batch_args = {:name => "baz", :headers => {:some_param => true}}
+        @args[:http_options][:batch_args] = batch_args
+        params = Koala::Facebook::BatchOperation.new(@args).to_batch_params(nil)
+        params.should include(batch_args)
+      end
+
+      it "includes the method" do
+        params = Koala::Facebook::BatchOperation.new(@args).to_batch_params(@args[:access_token])
+        params[:method].should == @args[:method].to_sym
+      end
+      
+      it "works with nil http_options" do
+        expect { Koala::Facebook::BatchOperation.new(@args.merge(:http_options => nil)).to_batch_params(nil) }.not_to raise_exception
+      end
+      
+      it "works with nil args" do
+        expect { Koala::Facebook::BatchOperation.new(@args.merge(:args => nil)).to_batch_params(nil) }.not_to raise_exception
+      end 
+      
+      describe "with binary files" do
+        before :each do
+          @binary = stub("Binary file")
+          Koala::UploadableIO.stub(:binary_content?).and_return(false)
+          Koala::UploadableIO.stub(:binary_content?).with(@binary).and_return(true)
+          @uploadable_io = stub("UploadableIO")
+          Koala::UploadableIO.stub(:new).with(@binary).and_return(@uploadable_io)          
+          @uploadable_io.stub(:is_a?).with(Koala::UploadableIO).and_return(true)
+
+          @batch_queue = []
+          Koala::Facebook::GraphAPI.stub(:batch_calls).and_return(@batch_queue)
+
+          @args[:method] = "post" # files are always post
+        end
+        
+        it "adds file identifiers as attached_files in a comma-separated list" do
+          @args[:args].merge!("source" => @binary, "source2" => @binary)
+          batch_op = Koala::Facebook::BatchOperation.new(@args)
+          file_ids = batch_op.files.find_all {|k, v| v == @uploadable_io}.map {|k, v| k}
+          params = batch_op.to_batch_params(nil)
+          params[:attached_files].should == file_ids.join(",")
+        end     
+      end
+    end
+    
+  end
+  
+  describe "GraphAPI batch interface" do
+    it "sets the batch_mode flag to false outside batch mode" do
+      Koala::Facebook::GraphAPI.batch_mode?.should be_false
+    end
+  
+    it "sets the batch_mode flag inside batch mode" do
+      Koala::Facebook::GraphAPI.batch do
+        Koala::Facebook::GraphAPI.batch_mode?.should be_true
+      end
+    end
+    
+    it "throws an error if you try to access the batch_calls queue outside a batch block" do
+      expect { Koala::Facebook::GraphAPI.batch_calls << BatchOperation.new(:access_token => "2") }.to raise_exception(Koala::KoalaError)
+    end
+
+    it "clears the batch queue between requests" do
+      Koala.stub(:make_request).and_return(Koala::Response.new(200, "[]", {}))
+      Koala::Facebook::GraphAPI.batch { @api.get_object("me") }
+      Koala.should_receive(:make_request).once.and_return(Koala::Response.new(200, "[]", {}))
+      Koala::Facebook::GraphAPI.batch { @api.get_object("me") }      
+    end
+    
+    it "returns nothing for a batch operation" do
+      Koala.stub(:make_request).and_return(Koala::Response.new(200, "[]", {}))
+      Koala::Facebook::GraphAPI.batch do
+        @api.get_object("me").should be_nil
+      end
+    end
+    
+    it "creates a BatchObject when making a GraphAPI request in batch mode" do
+      Koala.should_receive(:make_request).once.and_return(Koala::Response.new(200, "[]", {}))
+      
+      args = {:a => :b}
+      method = "post"
+      http_options = {:option => true}
+      url = "/a"
+      access_token = "token"
+      post_processing = lambda {}
+      op = Koala::Facebook::BatchOperation.new(:access_token => access_token, :method => :get, :url => "/")
+      Koala::Facebook::BatchOperation.should_receive(:new).with(
+        :url => url,
+        :args => args,
+        :method => method,
+        :access_token => access_token,
+        :http_options => http_options,
+        :post_processing => post_processing
+      ).and_return(op)
+      
+      Koala::Facebook::GraphAPI.batch do
+        Koala::Facebook::GraphAPI.new(access_token).graph_call(url, args, method, http_options, &post_processing)
+      end
+    end
+
+    describe "#batch_api" do
+      before :each do
+        @fake_response = Koala::Response.new(200, "[]", {})
+        Koala.stub(:make_request).and_return(@fake_response)
+      end
+      
+      describe "making the request" do
+        context "with no calls" do
+          it "does not make any requests if batch_calls is empty" do
+            Koala.should_not_receive(:make_request)
+            Koala::Facebook::GraphAPI.batch {}
+          end
+
+          it "returns []" do
+            Koala::Facebook::GraphAPI.batch {}.should == []        
+          end
+        end
+      
+        it "includes the first operation's access token as the main one in the args" do
+          access_token = "foo"
+          Koala.should_receive(:make_request).with(anything, hash_including("access_token" => access_token), anything, anything).and_return(@fake_response)
+          Koala::Facebook::GraphAPI.batch do
+            Koala::Facebook::GraphAPI.new(access_token).get_object('me')
+            Koala::Facebook::GraphAPI.new("bar").get_object('me')
+          end
+        end
+
+        it "sets args['batch'] to a json'd map of all the batch params" do
+          access_token = "bar"
+          op = Koala::Facebook::BatchOperation.new(:access_token => access_token, :method => :get, :url => "/")
+          op.stub(:to_batch_params).and_return({:a => 2})
+          Koala::Facebook::BatchOperation.stub(:new).and_return(op)
+        
+          # two requests should generate two batch operations
+          expected = [op.to_batch_params(access_token), op.to_batch_params(access_token)].to_json
+          Koala.should_receive(:make_request).with(anything, hash_including("batch" => expected), anything, anything).and_return(@fake_response)
+          Koala::Facebook::GraphAPI.batch do
+            Koala::Facebook::GraphAPI.new(access_token).get_object('me')
+            Koala::Facebook::GraphAPI.new(access_token).get_object('me')
+          end        
+        end
+        
+        it "adds any files from the batch operations to the arguments" do
+          # stub the batch operation 
+          # we test above to ensure that files are properly assimilated into the BatchOperation instance
+          # right now, we want to make sure that batch_api handles them properly
+          @key = "file0_0"
+          @uploadable_io = stub("UploadableIO")
+          batch_op = stub("Koala Batch Operation", :files => {@key => @uploadable_io}, :to_batch_params => {}, :access_token => "foo")
+          Koala::Facebook::BatchOperation.stub(:new).and_return(batch_op)
+          
+          Koala.should_receive(:make_request).with(anything, hash_including(@key => @uploadable_io), anything, anything).and_return(@fake_response)            
+          Koala::Facebook::GraphAPI.batch do
+            Koala::Facebook::GraphAPI.new("bar").put_picture("path/to/file", "image/jpeg")
+          end         
+        end
+        
+        it "preserves operation order" do
+          access_token = "bar"
+          # two requests should generate two batch operations
+          Koala.should_receive(:make_request) do |url, args, method, options| 
+            # test the batch operations to make sure they appear in the right order
+            (args ||= {})["batch"].should =~ /.*me\/farglebarg.*otheruser\/bababa/
+            @fake_response
+          end
+          Koala::Facebook::GraphAPI.batch do
+            Koala::Facebook::GraphAPI.new(access_token).get_connections('me', "farglebarg")
+            Koala::Facebook::GraphAPI.new(access_token).get_connections('otheruser', "bababa")
+          end
+        end
+      
+        it "makes a POST request" do
+          Koala.should_receive(:make_request).with(anything, anything, "post", anything).and_return(@fake_response)
+          Koala::Facebook::GraphAPI.batch do
+            Koala::Facebook::GraphAPI.new("foo").get_object('me')
+          end
+        end
+      
+        it "makes a request to /" do
+          Koala.should_receive(:make_request).with("/", anything, anything, anything).and_return(@fake_response)
+          Koala::Facebook::GraphAPI.batch do
+            Koala::Facebook::GraphAPI.new("foo").get_object('me')
+          end
+        end
+      
+        it "includes any http options specified at the top level" do
+          http_options = {"a" => "baz"}
+          Koala.should_receive(:make_request).with(anything, anything, anything, hash_including(http_options)).and_return(@fake_response)
+          Koala::Facebook::GraphAPI.batch(http_options) do
+            Koala::Facebook::GraphAPI.new("foo").get_object('me')
+          end
+        end
+      end
+      
+      describe "processing the request" do
+        it "throws an error if the response is not 200" do
+          Koala.stub(:make_request).and_return(Koala::Response.new(500, "[]", {}))
+          expect { Koala::Facebook::GraphAPI.batch do
+            Koala::Facebook::GraphAPI.new("foo").get_object('me')
+          end }.to raise_exception(Koala::Facebook::APIError)
+        end
+        
+        it "throws an error if the response is a Batch API-style error" do
+          Koala.stub(:make_request).and_return(Koala::Response.new(200, '{"error":190,"error_description":"Error validating access token."}', {}))
+          expect { Koala::Facebook::GraphAPI.batch do
+            Koala::Facebook::GraphAPI.new("foo").get_object('me')
+          end }.to raise_exception(Koala::Facebook::APIError)  
+        end
+        
+        it "returns the result status if http_component is status" do
+          Koala.stub(:make_request).and_return(Koala::Response.new(200, '[{"code":203,"headers":[{"name":"Content-Type","value":"text/javascript; charset=UTF-8"}],"body":"{\"id\":\"1234\"}"}]', {}))
+          result = Koala::Facebook::GraphAPI.batch do
+            @api.get_object("koppel", {}, :http_component => :status)
+          end
+          result[0].should == 203
+        end
+
+        it "returns the result headers as a hash if http_component is headers" do
+          Koala.stub(:make_request).and_return(Koala::Response.new(200, '[{"code":203,"headers":[{"name":"Content-Type","value":"text/javascript; charset=UTF-8"}],"body":"{\"id\":\"1234\"}"}]', {}))
+          result = Koala::Facebook::GraphAPI.batch do
+            @api.get_object("koppel", {}, :http_component => :headers)
+          end
+          result[0].should == {"Content-Type" => "text/javascript; charset=UTF-8"}
+        end
+      end
+      
+      it "is not available on the GraphAndRestAPI class" do
+        Koala::Facebook::GraphAndRestAPI.should_not respond_to(:batch)
+      end
+    end
+  end
+  
+  describe "usage tests" do
+    it "should be able get two results at once" do
+      me, koppel = Koala::Facebook::GraphAPI.batch do
+        @api.get_object('me')
+        @api.get_object('koppel')
+      end
+      me['id'].should_not be_nil
+      koppel['id'].should_not be_nil
+    end
+
+      
+    it "works with GraphAndRestAPI instances" do
+      me, koppel = Koala::Facebook::GraphAPI.batch do
+        Koala::Facebook::GraphAndRestAPI.new(@api.access_token).get_object('me')
+        @api.get_object('koppel')
+      end
+      me['id'].should_not be_nil
+      koppel['id'].should_not be_nil
+    end
+
+    it 'should be able to make mixed calls inside of a batch' do
+      me, friends = Koala::Facebook::GraphAPI.batch do
+        @api.get_object('me')
+        @api.get_connections('me', 'friends')
+      end
+      me['id'].should_not be_nil
+      friends.should be_an(Array)
+    end
+
+    it 'should be able to make a get_picture call inside of a batch' do
+      pictures = Koala::Facebook::GraphAPI.batch do
+        @api.get_picture('me')
+      end
+      pictures.first.should_not be_empty
+    end
+    
+    it "should handle requests for two different tokens" do
+      me, insights = Koala::Facebook::GraphAPI.batch do
+        @api.get_object('me')
+        @app_api.get_connections(@app_id, 'insights')
+      end
+      me['id'].should_not be_nil
+      insights.should be_an(Array)
+    end
+    
+    it "inserts errors in the appropriate place, without breaking other results" do
+      failed_insights, koppel = Koala::Facebook::GraphAPI.batch do
+        @api.get_connections(@app_id, 'insights')
+        @app_api.get_object("koppel")
+      end
+      failed_insights.should be_a(Koala::Facebook::APIError)
+      koppel["id"].should_not be_nil
+    end
+
+    it "handles different request methods" do
+      result = @api.put_wall_post("Hello, world, from the test suite batch API!")
+      wall_post = result["id"]
+      
+      wall_post, koppel = Koala::Facebook::GraphAPI.batch do
+        @api.put_like(wall_post)
+        @api.delete_object(wall_post)
+      end
+    end
+    
+    it "allows FQL" do
+      result = Koala::Facebook::GraphAPI.batch do
+        @api.graph_call("method/fql.query", {:query=>"select name from user where uid=4"}, "post")
+      end
+      
+      fql_result = result[0]
+      fql_result[0].should be_a(Hash)
+      fql_result[0]["name"].should == "Mark Zuckerberg"
+    end
+    
+    describe "binary files" do
+      it "posts binary files" do
+        file = File.open(File.join(File.dirname(__FILE__), "..", "fixtures", "beach.jpg"))
+
+        result = Koala::Facebook::GraphAPI.batch do
+          @api.put_picture(file)
+        end
+        
+        @temporary_object_id = result[0]["id"]
+        @temporary_object_id.should_not be_nil
+      end
+      
+      it "posts binary files with multiple requests" do
+        file = File.open(File.join(File.dirname(__FILE__), "..", "fixtures", "beach.jpg"))
+
+        results = Koala::Facebook::GraphAPI.batch do
+          @api.put_picture(file)
+          @api.put_picture(file, {}, "koppel")
+        end
+        results[0]["id"].should_not be_nil
+        results[1]["id"].should_not be_nil
+      end
+    end
+    
+    describe "relating requests" do
+      it "allows you create relationships between requests without omit_response_on_success" do
+        results = Koala::Facebook::GraphAPI.batch do
+          @api.get_connections("me", "friends", {:limit => 5}, :batch_args => {:name => "get-friends"})
+          @api.get_objects("{result=get-friends:$.data.*.id}")
+        end
+      
+        results[0].should be_nil
+        results[1].should be_an(Hash)
+      end
+      
+      it "allows you create relationships between requests with omit_response_on_success" do
+        results = Koala::Facebook::GraphAPI.batch do
+          @api.get_connections("me", "friends", {:limit => 5}, :batch_args => {:name => "get-friends", :omit_response_on_success => false})
+          @api.get_objects("{result=get-friends:$.data.*.id}")
+        end
+      
+        results[0].should be_an(Array)
+        results[1].should be_an(Hash)
+      end
+      
+      it "allows you to create dependencies" do
+        me, koppel = Koala::Facebook::GraphAPI.batch do
+          @api.get_object("me", {}, :batch_args => {:name => "getme"})
+          @api.get_object("koppel", {}, :batch_args => {:depends_on => "getme"})
+        end
+        
+        me.should be_nil # gotcha!  it's omitted because it's a successfully-executed dependency
+        koppel["id"].should_not be_nil
+      end
+      
+      it "properly handles dependencies that fail" do
+        data, koppel = Koala::Facebook::GraphAPI.batch do
+          @api.get_connections(@app_id, 'insights', {}, :batch_args => {:name => "getdata"})
+          @api.get_object("koppel", {}, :batch_args => {:depends_on => "getdata"})
+        end
+
+        data.should be_a(Koala::Facebook::APIError)
+        koppel.should be_nil
+      end
+      
+      it "throws an error for badly-constructed request relationships" do
+        expect { 
+          Koala::Facebook::GraphAPI.batch do
+            @api.get_connections("me", "friends", {:limit => 5})
+            @api.get_objects("{result=i-dont-exist:$.data.*.id}")
+          end
+        }.to raise_exception(Koala::Facebook::APIError)
+      end
+    end
+  end
+end