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'
22 # Helper class to contain a response to an individual batched call.
23 class BatchedCallResponse
25 attr_accessor :status, :headers, :body
27 def initialize(call_id, status = nil, headers = nil, body = nil)
28 @call_id, @status, @headers, @body = call_id, status, headers, body
33 # Wraps multiple API calls into a single over-the-wire HTTP request.
34 class BatchRequest < Request
35 BATCH_BOUNDARY = "-----------RubyApiBatchRequest".freeze
37 attr_reader :calls, :callbacks
40 # Creates a new batch request.
42 # @param [Hash] options
43 # Set of options for this request
45 # Callback for every call's response. Won't be called if a call defined
46 # a callback of its own.
48 # @return [Google::APIClient::BatchRequest] The constructed object.
49 def initialize(options = {}, &block)
51 @global_callback = block if block_given?
54 # TODO(sgomes): Use SecureRandom.uuid, drop UUIDTools when we drop 1.8
55 @base_id = UUIDTools::UUID.random_create.to_s
57 options[:uri] ||= 'https://www.googleapis.com/batch'
58 options[:http_method] ||= 'POST'
64 # Add a new call to the batch request.
65 # Each call must have its own call ID; if not provided, one will
66 # automatically be generated, avoiding collisions. If duplicate call IDs
67 # are provided, an error will be thrown.
69 # @param [Hash, Google::APIClient::Request] call: the call to be added.
70 # @param [String] call_id: the ID to be used for this call. Must be unique
71 # @param [Proc] block: callback for this call's response.
73 # @return [Google::APIClient::BatchRequest] The BatchRequest, for chaining
74 def add(call, call_id = nil, &block)
75 unless call.kind_of?(Google::APIClient::Reference)
76 call = Google::APIClient::Reference.new(call)
79 if @calls.assoc(call_id)
81 'A call with this ID already exists: %s' % call_id
83 callback = block_given? ? block : @global_callback
84 @calls << [call_id, call, callback]
89 # Processes the HTTP response to the batch request, issuing callbacks.
91 # @param [Faraday::Response] response: the HTTP response.
92 def process_http_response(response)
93 content_type = find_header('Content-Type', response.headers)
94 boundary = /.*boundary=(.+)/.match(content_type)[1]
95 parts = response.body.split(/--#{Regexp.escape(boundary)}/)
98 call_response = deserialize_call_response(part)
99 _, call, callback = @calls.assoc(call_response.call_id)
100 result = Google::APIClient::Result.new(call, call_response)
101 callback.call(result) if callback
106 # Return the request body for the BatchRequest's HTTP request.
108 # @return [String] The request body.
110 if @calls.nil? || @calls.empty?
111 raise BatchError, 'Cannot make an empty batch request'
113 parts = @calls.map {|(call_id, call, callback)| serialize_call(call_id, call)}
114 build_multipart(parts, 'multipart/mixed', BATCH_BOUNDARY)
122 # Helper method to find a header from its name, regardless of case.
124 # @param [String] name: The name of the header to find.
125 # @param [Hash] headers: The hash of headers and their values.
127 # @return [String] The value of the desired header.
128 def find_header(name, headers)
129 _, header = headers.detect do |h, v|
130 h.downcase == name.downcase
136 # Create a new call ID. Uses an auto-incrementing, conflict-avoiding ID.
138 # @return [String] the new, unique ID.
141 while @calls.assoc(@last_auto_id)
144 return @last_auto_id.to_s
150 # Convert a Content-ID header value to an id. Presumes the Content-ID
151 # header conforms to the format that id_to_header() returns.
153 # @param [String] header: Content-ID header value.
155 # @return [String] The extracted ID value.
156 def header_to_id(header)
157 if !header.start_with?('<') || !header.end_with?('>') ||
158 !header.include?('+')
159 raise BatchError, 'Invalid value for Content-ID: "%s"' % header
162 base, call_id = header[1...-1].split('+')
163 return Addressable::URI.unencode(call_id)
167 # Auxiliary method to split the headers from the body in an HTTP response.
169 # @param [String] response: the response to parse.
171 # @return [Array<Hash>, String] The headers and the body, separately.
172 def split_headers_and_body(response)
174 payload = response.lstrip
176 line, payload = payload.split("\n", 2)
177 line.sub!(/\s+\z/, '')
179 match = /\A([^:]+):\s*/.match(line)
181 headers[match[1]] = match.post_match
183 raise BatchError, 'Invalid header line in response: %s' % line
186 return headers, payload
190 # Convert a single batched response into a BatchedCallResponse object.
192 # @param [Google::APIClient::Reference] response:
193 # the request to deserialize.
195 # @return [BatchedCallResponse] The parsed and converted response.
196 def deserialize_call_response(call_response)
197 outer_headers, outer_body = split_headers_and_body(call_response)
198 status_line, payload = outer_body.split("\n", 2)
199 protocol, status, reason = status_line.split(' ', 3)
201 headers, body = split_headers_and_body(payload)
202 content_id = find_header('Content-ID', outer_headers)
203 call_id = header_to_id(content_id)
204 return BatchedCallResponse.new(call_id, status.to_i, headers, body)
208 # Convert a single batched call into a string.
210 # @param [Google::APIClient::Reference] call: the call to serialize.
212 # @return [StringIO] The request as a string in application/http format.
213 def serialize_call(call_id, call)
214 call.api_client = self.api_client
215 method, uri, headers, body = call.to_http_request
216 request = "#{method.to_s.upcase} #{Addressable::URI.parse(uri).path} HTTP/1.1"
217 headers.each do |header, value|
218 request << "\r\n%s: %s" % [header, value]
221 # TODO - CompositeIO if body is a stream
222 request << "\r\n\r\n"
223 if body.respond_to?(:read)
229 Faraday::UploadIO.new(StringIO.new(request), 'application/http', 'ruby-api-request', 'Content-ID' => id_to_header(call_id))
233 # Convert an id to a Content-ID header value.
235 # @param [String] call_id: identifier of individual call.
238 # A Content-ID header with the call_id encoded into it. A UUID is
239 # prepended to the value because Content-ID headers are supposed to be
240 # universally unique.
241 def id_to_header(call_id)
242 return '<%s+%s>' % [@base_id, Addressable::URI.encode(call_id)]