google-api-client 0.4.3 → 0.4.4

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+# 0.4.4
+
+* Added batch execution
+* Added service accounts
+* Can now supply authorization on a per-request basis.
+
 # 0.4.3
 
 * Added media upload capabilities

data/Gemfile

@@ -0,0 +1,28 @@
+source :rubygems
+
+gem 'signet', '>= 0.3.4'
+gem 'addressable', '>= 2.2.3'
+gem 'uuidtools', '>= 2.1.0'
+gem 'autoparse', '>= 0.3.1'
+gem 'faraday', '~> 0.7.0'
+gem 'multi_json', '>= 1.3.0'
+gem 'extlib', '>= 0.9.15'
+gem 'jruby-openssl', :platforms => :jruby
+
+group :development do
+  gem 'launchy'
+  gem 'yard'
+  gem 'redcarpet'
+end
+
+group :examples do
+  gem 'sinatra'
+end
+
+group :test, :development do
+  gem 'rake', '>= 0.9.0'
+  gem 'rspec', '~> 1.2.9'
+  gem 'rcov', '>= 0.9.9', :platform => :mri_18
+end
+
+gem 'idn', :platform => :mri_18

data/Gemfile.lock

@@ -0,0 +1,61 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    addressable (2.2.8)
+    autoparse (0.3.1)
+      addressable (~> 2.2.3)
+      extlib (>= 0.9.15)
+      multi_json (>= 1.0.0)
+    extlib (0.9.15)
+    faraday (0.7.6)
+      addressable (~> 2.2)
+      multipart-post (~> 1.1)
+      rack (~> 1.1)
+    idn (0.0.2)
+    json (1.7.3)
+    jwt (0.1.4)
+      json (>= 1.2.4)
+    launchy (2.1.0)
+      addressable (~> 2.2.6)
+    multi_json (1.3.6)
+    multipart-post (1.1.5)
+    rack (1.4.1)
+    rack-protection (1.2.0)
+      rack
+    rake (0.9.2.2)
+    rcov (1.0.0)
+    redcarpet (2.1.1)
+    rspec (1.2.9)
+    signet (0.3.4)
+      addressable (~> 2.2.3)
+      faraday (~> 0.7.0)
+      jwt (>= 0.1.4)
+      multi_json (>= 1.0.0)
+    sinatra (1.3.2)
+      rack (~> 1.3, >= 1.3.6)
+      rack-protection (~> 1.2)
+      tilt (~> 1.3, >= 1.3.3)
+    tilt (1.3.3)
+    uuidtools (2.1.2)
+    yard (0.8.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  addressable (>= 2.2.3)
+  autoparse (>= 0.3.1)
+  extlib (>= 0.9.15)
+  faraday (~> 0.7.0)
+  idn
+  jruby-openssl
+  launchy
+  multi_json (>= 1.3.0)
+  rake (>= 0.9.0)
+  rcov (>= 0.9.9)
+  redcarpet
+  rspec (~> 1.2.9)
+  signet (>= 0.3.4)
+  sinatra
+  uuidtools (>= 2.1.0)
+  yard

data/README.md

@@ -7,6 +7,9 @@
   <dt>License</dt><dd>Apache 2.0</dd>
 </dl>
 
+[![Build Status](https://secure.travis-ci.org/google/google-api-ruby-client.png)](http://travis-ci.org/google/google-api-ruby-client)
+[![Dependency Status](https://gemnasium.com/google/google-api-ruby-client.png)](https://gemnasium.com/google/google-api-ruby-client)
+
 # Description
 
 The Google API Ruby Client makes it trivial to discover and access supported

data/Rakefile

@@ -40,7 +40,7 @@ PKG_FILES = FileList[
 
 RCOV_ENABLED = (RUBY_PLATFORM != 'java' && RUBY_VERSION =~ /^1\.8/)
 if RCOV_ENABLED
-  task :default => 'spec:verify'
+  task :default => 'spec:rcov'
 else
   task :default => 'spec'
 end

data/lib/google/api_client.rb

@@ -26,6 +26,8 @@ require 'google/api_client/discovery'
 require 'google/api_client/reference'
 require 'google/api_client/result'
 require 'google/api_client/media'
+require 'google/api_client/service_account'
+require 'google/api_client/batch'
 
 module Google
   # TODO(bobaman): Document all this stuff.
@@ -281,7 +283,7 @@ module Google
           "Expected String or StringIO, got #{discovery_document.class}."
       end
       @discovery_documents["#{api}:#{version}"] =
-        MultiJson.decode(discovery_document)
+        MultiJson.load(discovery_document)
     end
 
     ##
@@ -297,7 +299,7 @@ module Google
         )
         response = self.transmit(:request => request)
         if response.status >= 200 && response.status < 300
-          MultiJson.decode(response.body)
+          MultiJson.load(response.body)
         elsif response.status >= 400
           case response.status
           when 400...500
@@ -331,7 +333,7 @@ module Google
         )
         response = self.transmit(:request => request)
         if response.status >= 200 && response.status < 300
-          MultiJson.decode(response.body)
+          MultiJson.load(response.body)
         elsif response.status >= 400
           case response.status
           when 400...500
@@ -484,7 +486,7 @@ module Google
         response = self.transmit(:request => request)
         if response.status >= 200 && response.status < 300
           @certificates.merge!(
-            Hash[MultiJson.decode(response.body).map do |key, cert|
+            Hash[MultiJson.load(response.body).map do |key, cert|
               [key, OpenSSL::X509::Certificate.new(cert)]
             end]
           )
@@ -540,6 +542,7 @@ module Google
     def generate_request(options={})
       # Note: The merge method on a Hash object will coerce an API Reference
       # object into a Hash and merge with the default options.
+      
       options={
         :version => 'v1',
         :authorization => self.authorization,
@@ -547,6 +550,7 @@ module Google
         :user_ip => self.user_ip,
         :connection => Faraday.default_connection
       }.merge(options)
+      
       # The Reference object is going to need this to do method ID lookups.
       options[:client] = self
       # The default value for the :authenticated option depends on whether an
@@ -559,7 +563,7 @@ module Google
       reference = Google::APIClient::Reference.new(options)
       request = reference.to_request
       if options[:authenticated]
-        request = self.generate_authenticated_request(
+        request = options[:authorization].generate_authenticated_request(
           :request => request,
           :connection => options[:connection]
         )
@@ -573,6 +577,7 @@ module Google
     # @param [Hash] options a customizable set of options
     #
     # @return [Faraday::Request] The signed or otherwise authenticated request.
+    # @deprecated No longer used internally
     def generate_authenticated_request(options={})
       return authorization.generate_authenticated_request(options)
     end
@@ -663,22 +668,34 @@ module Google
     ##
     # Executes a request, wrapping it in a Result object.
     #
-    # @param [Google::APIClient::Method, String] api_method
-    #   The method object or the RPC name of the method being executed.
-    # @param [Hash, Array] parameters
-    #   The parameters to send to the method.
-    # @param [String] body The body of the request.
-    # @param [Hash, Array] headers The HTTP headers for the request.
-    # @option options [String] :version ("v1")
-    #   The service version. Only used if `api_method` is a `String`.
-    # @option options [#generate_authenticated_request] :authorization
-    #   The authorization mechanism for the response. Used only if
-    #   `:authenticated` is `true`.
-    # @option options [TrueClass, FalseClass] :authenticated (true)
-    #   `true` if the request must be signed or somehow
-    #   authenticated, `false` otherwise.
+    # @param [Google::APIClient::BatchRequest, Hash, Array] params
+    #   Either a Google::APIClient::BatchRequest, a Hash, or an Array.
+    #
+    #   If a Google::APIClient::BatchRequest, no other parameters are expected.
+    #
+    #   If a Hash, the below parameters are handled. If an Array, the
+    #   parameters are assumed to be in the below order:
     #
-    # @return [Google::APIClient::Result] The result from the API.
+    #   - (Google::APIClient::Method, String) api_method:
+    #     The method object or the RPC name of the method being executed.
+    #   - (Hash, Array) parameters:
+    #     The parameters to send to the method.
+    #   - (String) body: The body of the request.
+    #   - (Hash, Array) headers: The HTTP headers for the request.
+    #   - (Hash) options: A set of options for the request, of which:
+    #     - (String) :version (default: "v1") -
+    #       The service version. Only used if `api_method` is a `String`.
+    #     - (#generate_authenticated_request) :authorization (default: true) -
+    #       The authorization mechanism for the response. Used only if
+    #       `:authenticated` is `true`.
+    #     - (TrueClass, FalseClass) :authenticated (default: true) -
+    #       `true` if the request must be signed or somehow
+    #       authenticated, `false` otherwise.
+    #
+    # @return [Google::APIClient::Result] The result from the API, nil if batch.
+    #
+    # @example
+    #   result = client.execute(batch_request)
     #
     # @example
     #   result = client.execute(
@@ -688,28 +705,64 @@ module Google
     #
     # @see Google::APIClient#generate_request
     def execute(*params)
-      # This block of code allows us to accept multiple parameter passing
-      # styles, and maintaining some backwards compatibility.
-      #
-      # Note: I'm extremely tempted to deprecate this style of execute call.
-      if params.last.respond_to?(:to_hash) && params.size == 1
-        options = params.pop
+      if params.last.kind_of?(Google::APIClient::BatchRequest) &&
+          params.size == 1
+        batch = params.pop
+        options = batch.options
+        http_request = batch.to_http_request
+        request = nil
+
+        if @authorization
+          method, uri, headers, body = http_request
+          method = method.to_s.downcase.to_sym
+
+          faraday_request = Faraday::Request.create(method) do |req|
+            req.url(uri.to_s)
+            req.headers = Faraday::Utils::Headers.new(headers)
+            req.body = body
+          end
+
+          request = {
+            :request => self.generate_authenticated_request(
+              :request => faraday_request,
+              :connection => options[:connection]
+            ),
+            :connection => options[:connection]
+          }
+        else
+          request = {
+            :request => http_request,
+            :connection => options[:connection]
+          }
+        end
+
+        response = self.transmit(request)
+        batch.process_response(response)
+        return nil
       else
-        options = {}
-      end
-      options[:api_method] = params.shift if params.size > 0
-      options[:parameters] = params.shift if params.size > 0
-      options[:body] = params.shift if params.size > 0
-      options[:headers] = params.shift if params.size > 0
-      options[:client] = self
+        # This block of code allows us to accept multiple parameter passing
+        # styles, and maintaining some backwards compatibility.
+        #
+        # Note: I'm extremely tempted to deprecate this style of execute call.
+        if params.last.respond_to?(:to_hash) && params.size == 1
+          options = params.pop
+        else
+          options = {}
+        end
 
-      reference = Google::APIClient::Reference.new(options)
-      request = self.generate_request(reference)
-      response = self.transmit(
-        :request => request,
-        :connection => options[:connection]
-      )
-      return Google::APIClient::Result.new(reference, request, response)
+        options[:api_method] = params.shift if params.size > 0
+        options[:parameters] = params.shift if params.size > 0
+        options[:body] = params.shift if params.size > 0
+        options[:headers] = params.shift if params.size > 0
+        options[:client] = self
+        reference = Google::APIClient::Reference.new(options)
+        request = self.generate_request(reference)
+        response = self.transmit(
+          :request => request,
+          :connection => options[:connection]
+        )
+        return Google::APIClient::Result.new(reference, request, response)
+      end
     end
 
     ##

data/lib/google/api_client/batch.rb

@@ -0,0 +1,296 @@
+# Copyright 2012 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'addressable/uri'
+require 'uuidtools'
+
+module Google
+  class APIClient
+
+    # Helper class to contain a response to an individual batched call.
+    class BatchedCallResponse
+      attr_reader :call_id
+      attr_accessor :status, :headers, :body
+
+      def initialize(call_id, status = nil, headers = nil, body = nil)
+        @call_id, @status, @headers, @body = call_id, status, headers, body
+      end
+    end
+
+    ##
+    # Wraps multiple API calls into a single over-the-wire HTTP request.
+    class BatchRequest
+
+      BATCH_BOUNDARY = "-----------RubyApiBatchRequest".freeze
+
+      attr_accessor :options
+      attr_reader :calls, :callbacks
+
+      ##
+      # Creates a new batch request.
+      #
+      # @param [Hash] options
+      #   Set of options for this request, the only important one being
+      #   :connection, which specifies an HTTP connection to use.
+      # @param [Proc] block
+      #   Callback for every call's response. Won't be called if a call defined
+      #   a callback of its own.
+      #
+      # @return [Google::APIClient::BatchRequest] The constructed object.
+      def initialize(options = {}, &block)
+        # Request options, ignoring method and parameters.
+        @options = options
+        # Batched calls to be made, indexed by call ID.
+        @calls = {}
+        # Callbacks per batched call, indexed by call ID.
+        @callbacks = {}
+        # Order for the call IDs, since Ruby 1.8 hashes are unordered.
+        @order = []
+        # Global callback to be used for every call. If a specific callback
+        # has been defined for a request, this won't be called.
+        @global_callback = block if block_given?
+        # The last auto generated ID.
+        @last_auto_id = 0
+        # Base ID for the batch request.
+        @base_id = nil
+      end
+
+      ##
+      # Add a new call to the batch request.
+      # Each call must have its own call ID; if not provided, one will
+      # automatically be generated, avoiding collisions. If duplicate call IDs
+      # are provided, an error will be thrown.
+      #
+      # @param [Hash, Google::APIClient::Reference] call: the call to be added.
+      # @param [String] call_id: the ID to be used for this call. Must be unique
+      # @param [Proc] block: callback for this call's response.
+      #
+      # @return [Google::APIClient::BatchRequest] The BatchRequest, for chaining
+      def add(call, call_id = nil, &block)
+        unless call.kind_of?(Google::APIClient::Reference)
+          call = Google::APIClient::Reference.new(call)
+        end
+        if call_id.nil?
+          call_id = new_id
+        end
+        if @calls.include?(call_id)
+          raise BatchError,
+              'A call with this ID already exists: %s' % call_id
+        end
+        @calls[call_id] = call
+        @order << call_id
+        if block_given?
+          @callbacks[call_id] = block
+        elsif @global_callback
+          @callbacks[call_id] = @global_callback
+        end
+        return self
+      end
+
+      ##
+      # Convert this batch request into an HTTP request.
+      #
+      # @return [Array<String, String, Hash, String>]
+      #   An array consisting of, in order: HTTP method, request path, request
+      #   headers and request body.
+      def to_http_request
+        return ['POST', request_uri, request_headers, request_body]
+      end
+
+      ##
+      # Processes the HTTP response to the batch request, issuing callbacks.
+      #
+      # @param [Faraday::Response] response: the HTTP response.
+      def process_response(response)
+        content_type = find_header('Content-Type', response.headers)
+        boundary = /.*boundary=(.+)/.match(content_type)[1]
+        parts = response.body.split(/--#{Regexp.escape(boundary)}/)
+        parts = parts[1...-1]
+        parts.each do |part|
+          call_response = deserialize_call_response(part)
+          callback = @callbacks[call_response.call_id]
+          call = @calls[call_response.call_id]
+          result = Google::APIClient::Result.new(call, nil, call_response)
+          callback.call(result) if callback
+        end
+      end
+
+      private
+
+      ##
+      # Helper method to find a header from its name, regardless of case.
+      #
+      # @param [String] name: The name of the header to find.
+      # @param [Hash] headers: The hash of headers and their values.
+      #
+      # @return [String] The value of the desired header.
+      def find_header(name, headers)
+        _, header = headers.detect do |h, v|
+          h.downcase == name.downcase
+        end
+        return header
+      end
+
+      ##
+      # Create a new call ID. Uses an auto-incrementing, conflict-avoiding ID.
+      #
+      # @return [String] the new, unique ID.
+      def new_id
+        @last_auto_id += 1
+        while @calls.include?(@last_auto_id)
+          @last_auto_id += 1
+        end
+        return @last_auto_id.to_s
+      end
+
+      ##
+      # Convert an id to a Content-ID header value.
+      #
+      # @param [String] call_id: identifier of individual call.
+      #
+      # @return [String]
+      #   A Content-ID header with the call_id encoded into it. A UUID is
+      #   prepended to the value because Content-ID headers are supposed to be
+      #   universally unique.
+      def id_to_header(call_id)
+        if @base_id.nil?
+          # TODO(sgomes): Use SecureRandom.uuid, drop UUIDTools when we drop 1.8
+          @base_id = UUIDTools::UUID.random_create.to_s
+        end
+
+        return '<%s+%s>' % [@base_id, Addressable::URI.encode(call_id)]
+      end
+
+      ##
+      # Convert a Content-ID header value to an id. Presumes the Content-ID
+      # header conforms to the format that id_to_header() returns.
+      #
+      # @param [String] header: Content-ID header value.
+      #
+      # @return [String] The extracted ID value.
+      def header_to_id(header)
+        if !header.start_with?('<') || !header.end_with?('>') ||
+            !header.include?('+')
+          raise BatchError, 'Invalid value for Content-ID: "%s"' % header
+        end
+
+        base, call_id = header[1...-1].split('+')
+        return Addressable::URI.unencode(call_id)
+      end
+
+      ##
+      # Convert a single batched call into a string.
+      #
+      # @param [Google::APIClient::Reference] call: the call to serialize.
+      #
+      # @return [String] The request as a string in application/http format.
+      def serialize_call(call)
+        http_request = call.to_request
+        method = http_request.method.to_s.upcase
+        path = http_request.path.to_s
+        status_line = method + " " + path + " HTTP/1.1"
+        serialized_call = status_line
+        if http_request.headers
+          http_request.headers.each do |header, value|
+            serialized_call << "\r\n%s: %s" % [header, value]
+          end
+        end
+        if http_request.body
+          serialized_call << "\r\n\r\n"
+          serialized_call << http_request.body
+        end
+        return serialized_call
+      end
+
+      ##
+      # Auxiliary method to split the headers from the body in an HTTP response.
+      #
+      # @param [String] response: the response to parse.
+      #
+      # @return [Array<Hash>, String] The headers and the body, separately.
+      def split_headers_and_body(response)
+        headers = {}
+        payload = response.lstrip
+        while payload
+          line, payload = payload.split("\n", 2)
+          line.sub!(/\s+\z/, '')
+          break if line.empty?
+          match = /\A([^:]+):\s*/.match(line)
+          if match
+            headers[match[1]] = match.post_match
+          else
+            raise BatchError, 'Invalid header line in response: %s' % line
+          end
+        end
+        return headers, payload
+      end
+
+      ##
+      # Convert a single batched response into a BatchedCallResponse object.
+      #
+      # @param [Google::APIClient::Reference] response:
+      #   the request to deserialize.
+      #
+      # @return [BatchedCallResponse] The parsed and converted response.
+      def deserialize_call_response(call_response)
+        outer_headers, outer_body = split_headers_and_body(call_response)
+        status_line, payload = outer_body.split("\n", 2)
+        protocol, status, reason = status_line.split(' ', 3)
+
+        headers, body = split_headers_and_body(payload)
+        content_id = find_header('Content-ID', outer_headers)
+        call_id = header_to_id(content_id)
+        return BatchedCallResponse.new(call_id, status.to_i, headers, body)
+      end
+
+      ##
+      # Return the request headers for the BatchRequest's HTTP request.
+      #
+      # @return [Hash] The HTTP headers.
+      def request_headers
+        return {
+          'Content-Type' => 'multipart/mixed; boundary=%s' % BATCH_BOUNDARY
+        }
+      end
+
+      ##
+      # Return the request path for the BatchRequest's HTTP request.
+      #
+      # @return [String] The request path.
+      def request_uri
+        if @calls.nil? || @calls.empty?
+          raise BatchError, 'Cannot make an empty batch request'
+        end
+        # All APIs have the same batch path, so just get the first one.
+        return @calls.first[1].api_method.api.batch_path
+      end
+
+      ##
+      # Return the request body for the BatchRequest's HTTP request.
+      #
+      # @return [String] The request body.
+      def request_body
+        body = ""
+        @order.each do |call_id|
+          body << "--" + BATCH_BOUNDARY + "\r\n"
+          body << "Content-Type: application/http\r\n"
+          body << "Content-ID: %s\r\n\r\n" % id_to_header(call_id)
+          body << serialize_call(@calls[call_id]) + "\r\n\r\n"
+        end
+        body << "--" + BATCH_BOUNDARY + "--"
+        return body
+      end
+    end
+  end
+end