sdk/ruby-google-api-client/lib/google/api_client/batch.rb

   1 # Copyright 2012 Google Inc.
   2 #
   3 # Licensed under the Apache License, Version 2.0 (the "License");
   4 # you may not use this file except in compliance with the License.
   5 # You may obtain a copy of the License at
   6 #
   7 #      http://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 # See the License for the specific language governing permissions and
  13 # limitations under the License.
  14
  15 require 'addressable/uri'
  16 require 'google/api_client/reference'
  17 require 'securerandom'
  18
  19 module Google
  20   class APIClient
  21
  22     ##
  23     # Helper class to contain a response to an individual batched call.
  24     #
  25     # @api private
  26     class BatchedCallResponse
  27       # @return [String] UUID of the call
  28       attr_reader :call_id
  29       # @return [Fixnum] HTTP status code
  30       attr_accessor :status
  31       # @return [Hash] HTTP response headers
  32       attr_accessor :headers
  33       # @return [String] HTTP response body
  34       attr_accessor :body
  35
  36       ##
  37       # Initialize the call response
  38       #
  39       # @param [String] call_id
  40       #   UUID of the original call
  41       # @param [Fixnum] status
  42       #   HTTP status
  43       # @param [Hash] headers
  44       #   HTTP response headers
  45       # @param [#read, #to_str] body
  46       #   Response body
  47       def initialize(call_id, status = nil, headers = nil, body = nil)
  48         @call_id, @status, @headers, @body = call_id, status, headers, body
  49       end
  50     end
  51
  52     # Wraps multiple API calls into a single over-the-wire HTTP request.
  53     #
  54     # @example
  55     #
  56     #     client = Google::APIClient.new
  57     #     urlshortener = client.discovered_api('urlshortener')
  58     #     batch = Google::APIClient::BatchRequest.new do |result|
  59     #        puts result.data
  60     #     end
  61     #
  62     #     batch.add(:api_method => urlshortener.url.insert, :body_object => { 'longUrl' => 'http://example.com/foo' })
  63     #     batch.add(:api_method => urlshortener.url.insert, :body_object => { 'longUrl' => 'http://example.com/bar' })
  64     #
  65     #     client.execute(batch)
  66     #
  67     class BatchRequest < Request
  68       BATCH_BOUNDARY = "-----------RubyApiBatchRequest".freeze
  69
  70       # @api private
  71       # @return [Array<(String,Google::APIClient::Request,Proc)] List of API calls in the batch
  72       attr_reader :calls
  73
  74       ##
  75       # Creates a new batch request.
  76       #
  77       # @param [Hash] options
  78       #   Set of options for this request.
  79       # @param [Proc] block
  80       #   Callback for every call's response. Won't be called if a call defined
  81       #   a callback of its own.
  82       #
  83       # @return [Google::APIClient::BatchRequest]
  84       #   The constructed object.
  85       #
  86       # @yield [Google::APIClient::Result]
  87       #   block to be called when result ready
  88       def initialize(options = {}, &block)
  89         @calls = []
  90         @global_callback = nil
  91         @global_callback = block if block_given?
  92         @last_auto_id = 0
  93
  94         @base_id = SecureRandom.uuid
  95
  96         options[:uri] ||= 'https://www.googleapis.com/batch'
  97         options[:http_method] ||= 'POST'
  98
  99         super options
 100       end
 101
 102       ##
 103       # Add a new call to the batch request.
 104       # Each call must have its own call ID; if not provided, one will
 105       # automatically be generated, avoiding collisions. If duplicate call IDs
 106       # are provided, an error will be thrown.
 107       #
 108       # @param [Hash, Google::APIClient::Request] call
 109       #   the call to be added.
 110       # @param [String] call_id
 111       #   the ID to be used for this call. Must be unique
 112       # @param [Proc] block
 113       #   callback for this call's response.
 114       #
 115       # @return [Google::APIClient::BatchRequest]
 116       #   the BatchRequest, for chaining
 117       #
 118       # @yield [Google::APIClient::Result]
 119       #   block to be called when result ready
 120       def add(call, call_id = nil, &block)
 121         unless call.kind_of?(Google::APIClient::Reference)
 122           call = Google::APIClient::Reference.new(call)
 123         end
 124         call_id ||= new_id
 125         if @calls.assoc(call_id)
 126           raise BatchError,
 127               'A call with this ID already exists: %s' % call_id
 128         end
 129         callback = block_given? ? block : @global_callback
 130         @calls << [call_id, call, callback]
 131         return self
 132       end
 133
 134       ##
 135       # Processes the HTTP response to the batch request, issuing callbacks.
 136       #
 137       # @api private
 138       #
 139       # @param [Faraday::Response] response
 140       #   the HTTP response.
 141       def process_http_response(response)
 142         content_type = find_header('Content-Type', response.headers)
 143         m = /.*boundary=(.+)/.match(content_type)
 144         if m
 145           boundary = m[1]
 146           parts = response.body.split(/--#{Regexp.escape(boundary)}/)
 147           parts = parts[1...-1]
 148           parts.each do |part|
 149             call_response = deserialize_call_response(part)
 150             _, call, callback = @calls.assoc(call_response.call_id)
 151             result = Google::APIClient::Result.new(call, call_response)
 152             callback.call(result) if callback
 153           end
 154         end
 155         Google::APIClient::Result.new(self, response)
 156       end
 157
 158       ##
 159       # Return the request body for the BatchRequest's HTTP request.
 160       #
 161       # @api private
 162       #
 163       # @return [String]
 164       #   the request body.
 165       def to_http_request
 166         if @calls.nil? || @calls.empty?
 167           raise BatchError, 'Cannot make an empty batch request'
 168         end
 169         parts = @calls.map {|(call_id, call, _callback)| serialize_call(call_id, call)}
 170         build_multipart(parts, 'multipart/mixed', BATCH_BOUNDARY)
 171         super
 172       end
 173
 174
 175       protected
 176
 177       ##
 178       # Helper method to find a header from its name, regardless of case.
 179       #
 180       # @api private
 181       #
 182       # @param [String] name
 183       #   the name of the header to find.
 184       # @param [Hash] headers
 185       #   the hash of headers and their values.
 186       #
 187       # @return [String]
 188       #   the value of the desired header.
 189       def find_header(name, headers)
 190         _, header = headers.detect do |h, v|
 191           h.downcase == name.downcase
 192         end
 193         return header
 194       end
 195
 196       ##
 197       # Create a new call ID. Uses an auto-incrementing, conflict-avoiding ID.
 198       #
 199       # @api private
 200       #
 201       # @return [String]
 202       #  the new, unique ID.
 203       def new_id
 204         @last_auto_id += 1
 205         while @calls.assoc(@last_auto_id)
 206           @last_auto_id += 1
 207         end
 208         return @last_auto_id.to_s
 209       end
 210
 211       ##
 212       # Convert a Content-ID header value to an id. Presumes the Content-ID
 213       # header conforms to the format that id_to_header() returns.
 214       #
 215       # @api private
 216       #
 217       # @param [String] header
 218       #   Content-ID header value.
 219       #
 220       # @return [String]
 221       #   The extracted ID value.
 222       def header_to_id(header)
 223         if !header.start_with?('<') || !header.end_with?('>') ||
 224             !header.include?('+')
 225           raise BatchError, 'Invalid value for Content-ID: "%s"' % header
 226         end
 227
 228         _base, call_id = header[1...-1].split('+')
 229         return Addressable::URI.unencode(call_id)
 230       end
 231
 232       ##
 233       # Auxiliary method to split the headers from the body in an HTTP response.
 234       #
 235       # @api private
 236       #
 237       # @param [String] response
 238       #   the response to parse.
 239       #
 240       # @return [Array<Hash>, String]
 241       #   the headers and the body, separately.
 242       def split_headers_and_body(response)
 243         headers = {}
 244         payload = response.lstrip
 245         while payload
 246           line, payload = payload.split("\n", 2)
 247           line.sub!(/\s+\z/, '')
 248           break if line.empty?
 249           match = /\A([^:]+):\s*/.match(line)
 250           if match
 251             headers[match[1]] = match.post_match
 252           else
 253             raise BatchError, 'Invalid header line in response: %s' % line
 254           end
 255         end
 256         return headers, payload
 257       end
 258
 259       ##
 260       # Convert a single batched response into a BatchedCallResponse object.
 261       #
 262       # @api private
 263       #
 264       # @param [String] call_response
 265       #   the request to deserialize.
 266       #
 267       # @return [Google::APIClient::BatchedCallResponse]
 268       #   the parsed and converted response.
 269       def deserialize_call_response(call_response)
 270         outer_headers, outer_body = split_headers_and_body(call_response)
 271         status_line, payload = outer_body.split("\n", 2)
 272         _protocol, status, _reason = status_line.split(' ', 3)
 273
 274         headers, body = split_headers_and_body(payload)
 275         content_id = find_header('Content-ID', outer_headers)
 276         call_id = header_to_id(content_id)
 277         return BatchedCallResponse.new(call_id, status.to_i, headers, body)
 278       end
 279
 280       ##
 281       # Serialize a single batched call for assembling the multipart message
 282       #
 283       # @api private
 284       #
 285       # @param [Google::APIClient::Request] call
 286       #   the call to serialize.
 287       #
 288       # @return [Faraday::UploadIO]
 289       #   the serialized request
 290       def serialize_call(call_id, call)
 291         method, uri, headers, body = call.to_http_request
 292         request = "#{method.to_s.upcase} #{Addressable::URI.parse(uri).request_uri} HTTP/1.1"
 293         headers.each do |header, value|
 294           request << "\r\n%s: %s" % [header, value]
 295         end
 296         if body
 297           # TODO - CompositeIO if body is a stream
 298           request << "\r\n\r\n"
 299           if body.respond_to?(:read)
 300             request << body.read
 301           else
 302             request << body.to_s
 303           end
 304         end
 305         Faraday::UploadIO.new(StringIO.new(request), 'application/http', 'ruby-api-request', 'Content-ID' => id_to_header(call_id))
 306       end
 307
 308       ##
 309       # Convert an id to a Content-ID header value.
 310       #
 311       # @api private
 312       #
 313       # @param [String] call_id
 314       #   identifier of individual call.
 315       #
 316       # @return [String]
 317       #   A Content-ID header with the call_id encoded into it. A UUID is
 318       #   prepended to the value because Content-ID headers are supposed to be
 319       #   universally unique.
 320       def id_to_header(call_id)
 321         return '<%s+%s>' % [@base_id, Addressable::URI.encode(call_id)]
 322       end
 323
 324     end
 325   end
 326 end