1 # Copyright 2012 Google Inc.
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
7 # http://www.apache.org/licenses/LICENSE-2.0
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.
15 require 'addressable/uri'
16 require 'google/api_client/reference'
17 require 'securerandom'
23 # Helper class to contain a response to an individual batched call.
26 class BatchedCallResponse
27 # @return [String] UUID of the call
29 # @return [Fixnum] HTTP status code
31 # @return [Hash] HTTP response headers
32 attr_accessor :headers
33 # @return [String] HTTP response body
37 # Initialize the call response
39 # @param [String] call_id
40 # UUID of the original call
41 # @param [Fixnum] status
43 # @param [Hash] headers
44 # HTTP response headers
45 # @param [#read, #to_str] body
47 def initialize(call_id, status = nil, headers = nil, body = nil)
48 @call_id, @status, @headers, @body = call_id, status, headers, body
52 # Wraps multiple API calls into a single over-the-wire HTTP request.
56 # client = Google::APIClient.new
57 # urlshortener = client.discovered_api('urlshortener')
58 # batch = Google::APIClient::BatchRequest.new do |result|
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' })
65 # client.execute(batch)
67 class BatchRequest < Request
68 BATCH_BOUNDARY = "-----------RubyApiBatchRequest".freeze
71 # @return [Array<(String,Google::APIClient::Request,Proc)] List of API calls in the batch
75 # Creates a new batch request.
77 # @param [Hash] options
78 # Set of options for this request.
80 # Callback for every call's response. Won't be called if a call defined
81 # a callback of its own.
83 # @return [Google::APIClient::BatchRequest]
84 # The constructed object.
86 # @yield [Google::APIClient::Result]
87 # block to be called when result ready
88 def initialize(options = {}, &block)
90 @global_callback = block if block_given?
93 @base_id = SecureRandom.uuid
95 options[:uri] ||= 'https://www.googleapis.com/batch'
96 options[:http_method] ||= 'POST'
102 # Add a new call to the batch request.
103 # Each call must have its own call ID; if not provided, one will
104 # automatically be generated, avoiding collisions. If duplicate call IDs
105 # are provided, an error will be thrown.
107 # @param [Hash, Google::APIClient::Request] call
108 # the call to be added.
109 # @param [String] call_id
110 # the ID to be used for this call. Must be unique
111 # @param [Proc] block
112 # callback for this call's response.
114 # @return [Google::APIClient::BatchRequest]
115 # the BatchRequest, for chaining
117 # @yield [Google::APIClient::Result]
118 # block to be called when result ready
119 def add(call, call_id = nil, &block)
120 unless call.kind_of?(Google::APIClient::Reference)
121 call = Google::APIClient::Reference.new(call)
124 if @calls.assoc(call_id)
126 'A call with this ID already exists: %s' % call_id
128 callback = block_given? ? block : @global_callback
129 @calls << [call_id, call, callback]
134 # Processes the HTTP response to the batch request, issuing callbacks.
138 # @param [Faraday::Response] response
140 def process_http_response(response)
141 content_type = find_header('Content-Type', response.headers)
142 m = /.*boundary=(.+)/.match(content_type)
145 parts = response.body.split(/--#{Regexp.escape(boundary)}/)
146 parts = parts[1...-1]
148 call_response = deserialize_call_response(part)
149 _, call, callback = @calls.assoc(call_response.call_id)
150 result = Google::APIClient::Result.new(call, call_response)
151 callback.call(result) if callback
154 Google::APIClient::Result.new(self, response)
158 # Return the request body for the BatchRequest's HTTP request.
165 if @calls.nil? || @calls.empty?
166 raise BatchError, 'Cannot make an empty batch request'
168 parts = @calls.map {|(call_id, call, callback)| serialize_call(call_id, call)}
169 build_multipart(parts, 'multipart/mixed', BATCH_BOUNDARY)
177 # Helper method to find a header from its name, regardless of case.
181 # @param [String] name
182 # the name of the header to find.
183 # @param [Hash] headers
184 # the hash of headers and their values.
187 # the value of the desired header.
188 def find_header(name, headers)
189 _, header = headers.detect do |h, v|
190 h.downcase == name.downcase
196 # Create a new call ID. Uses an auto-incrementing, conflict-avoiding ID.
201 # the new, unique ID.
204 while @calls.assoc(@last_auto_id)
207 return @last_auto_id.to_s
211 # Convert a Content-ID header value to an id. Presumes the Content-ID
212 # header conforms to the format that id_to_header() returns.
216 # @param [String] header
217 # Content-ID header value.
220 # The extracted ID value.
221 def header_to_id(header)
222 if !header.start_with?('<') || !header.end_with?('>') ||
223 !header.include?('+')
224 raise BatchError, 'Invalid value for Content-ID: "%s"' % header
227 base, call_id = header[1...-1].split('+')
228 return Addressable::URI.unencode(call_id)
232 # Auxiliary method to split the headers from the body in an HTTP response.
236 # @param [String] response
237 # the response to parse.
239 # @return [Array<Hash>, String]
240 # the headers and the body, separately.
241 def split_headers_and_body(response)
243 payload = response.lstrip
245 line, payload = payload.split("\n", 2)
246 line.sub!(/\s+\z/, '')
248 match = /\A([^:]+):\s*/.match(line)
250 headers[match[1]] = match.post_match
252 raise BatchError, 'Invalid header line in response: %s' % line
255 return headers, payload
259 # Convert a single batched response into a BatchedCallResponse object.
263 # @param [String] call_response
264 # the request to deserialize.
266 # @return [Google::APIClient::BatchedCallResponse]
267 # the parsed and converted response.
268 def deserialize_call_response(call_response)
269 outer_headers, outer_body = split_headers_and_body(call_response)
270 status_line, payload = outer_body.split("\n", 2)
271 protocol, status, reason = status_line.split(' ', 3)
273 headers, body = split_headers_and_body(payload)
274 content_id = find_header('Content-ID', outer_headers)
275 call_id = header_to_id(content_id)
276 return BatchedCallResponse.new(call_id, status.to_i, headers, body)
280 # Serialize a single batched call for assembling the multipart message
284 # @param [Google::APIClient::Request] call
285 # the call to serialize.
287 # @return [Faraday::UploadIO]
288 # the serialized request
289 def serialize_call(call_id, call)
290 method, uri, headers, body = call.to_http_request
291 request = "#{method.to_s.upcase} #{Addressable::URI.parse(uri).request_uri} HTTP/1.1"
292 headers.each do |header, value|
293 request << "\r\n%s: %s" % [header, value]
296 # TODO - CompositeIO if body is a stream
297 request << "\r\n\r\n"
298 if body.respond_to?(:read)
304 Faraday::UploadIO.new(StringIO.new(request), 'application/http', 'ruby-api-request', 'Content-ID' => id_to_header(call_id))
308 # Convert an id to a Content-ID header value.
312 # @param [String] call_id
313 # identifier of individual call.
316 # A Content-ID header with the call_id encoded into it. A UUID is
317 # prepended to the value because Content-ID headers are supposed to be
318 # universally unique.
319 def id_to_header(call_id)
320 return '<%s+%s>' % [@base_id, Addressable::URI.encode(call_id)]