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 boundary = /.*boundary=(.+)/.match(content_type)[1]
143 parts = response.body.split(/--#{Regexp.escape(boundary)}/)
144 parts = parts[1...-1]
146 call_response = deserialize_call_response(part)
147 _, call, callback = @calls.assoc(call_response.call_id)
148 result = Google::APIClient::Result.new(call, call_response)
149 callback.call(result) if callback
151 Google::APIClient::Result.new(self, response)
155 # Return the request body for the BatchRequest's HTTP request.
162 if @calls.nil? || @calls.empty?
163 raise BatchError, 'Cannot make an empty batch request'
165 parts = @calls.map {|(call_id, call, callback)| serialize_call(call_id, call)}
166 build_multipart(parts, 'multipart/mixed', BATCH_BOUNDARY)
174 # Helper method to find a header from its name, regardless of case.
178 # @param [String] name
179 # the name of the header to find.
180 # @param [Hash] headers
181 # the hash of headers and their values.
184 # the value of the desired header.
185 def find_header(name, headers)
186 _, header = headers.detect do |h, v|
187 h.downcase == name.downcase
193 # Create a new call ID. Uses an auto-incrementing, conflict-avoiding ID.
198 # the new, unique ID.
201 while @calls.assoc(@last_auto_id)
204 return @last_auto_id.to_s
208 # Convert a Content-ID header value to an id. Presumes the Content-ID
209 # header conforms to the format that id_to_header() returns.
213 # @param [String] header
214 # Content-ID header value.
217 # The extracted ID value.
218 def header_to_id(header)
219 if !header.start_with?('<') || !header.end_with?('>') ||
220 !header.include?('+')
221 raise BatchError, 'Invalid value for Content-ID: "%s"' % header
224 base, call_id = header[1...-1].split('+')
225 return Addressable::URI.unencode(call_id)
229 # Auxiliary method to split the headers from the body in an HTTP response.
233 # @param [String] response
234 # the response to parse.
236 # @return [Array<Hash>, String]
237 # the headers and the body, separately.
238 def split_headers_and_body(response)
240 payload = response.lstrip
242 line, payload = payload.split("\n", 2)
243 line.sub!(/\s+\z/, '')
245 match = /\A([^:]+):\s*/.match(line)
247 headers[match[1]] = match.post_match
249 raise BatchError, 'Invalid header line in response: %s' % line
252 return headers, payload
256 # Convert a single batched response into a BatchedCallResponse object.
260 # @param [String] call_response
261 # the request to deserialize.
263 # @return [Google::APIClient::BatchedCallResponse]
264 # the parsed and converted response.
265 def deserialize_call_response(call_response)
266 outer_headers, outer_body = split_headers_and_body(call_response)
267 status_line, payload = outer_body.split("\n", 2)
268 protocol, status, reason = status_line.split(' ', 3)
270 headers, body = split_headers_and_body(payload)
271 content_id = find_header('Content-ID', outer_headers)
272 call_id = header_to_id(content_id)
273 return BatchedCallResponse.new(call_id, status.to_i, headers, body)
277 # Serialize a single batched call for assembling the multipart message
281 # @param [Google::APIClient::Request] call
282 # the call to serialize.
284 # @return [Faraday::UploadIO]
285 # the serialized request
286 def serialize_call(call_id, call)
287 method, uri, headers, body = call.to_http_request
288 request = "#{method.to_s.upcase} #{Addressable::URI.parse(uri).request_uri} HTTP/1.1"
289 headers.each do |header, value|
290 request << "\r\n%s: %s" % [header, value]
293 # TODO - CompositeIO if body is a stream
294 request << "\r\n\r\n"
295 if body.respond_to?(:read)
301 Faraday::UploadIO.new(StringIO.new(request), 'application/http', 'ruby-api-request', 'Content-ID' => id_to_header(call_id))
305 # Convert an id to a Content-ID header value.
309 # @param [String] call_id
310 # identifier of individual call.
313 # A Content-ID header with the call_id encoded into it. A UUID is
314 # prepended to the value because Content-ID headers are supposed to be
315 # universally unique.
316 def id_to_header(call_id)
317 return '<%s+%s>' % [@base_id, Addressable::URI.encode(call_id)]