lib/google/api_client/request.rb

   1 # Copyright 2010 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 'faraday'
  16 require 'faraday/utils'
  17 require 'faraday/options'
  18 require 'faraday/request/multipart'
  19 require 'multi_json'
  20 require 'compat/multi_json'
  21 require 'addressable/uri'
  22 require 'stringio'
  23 require 'google/api_client/discovery'
  24 require 'google/api_client/logging'
  25
  26 module Google
  27   class APIClient
  28
  29     ##
  30     # Represents an API request.
  31     class Request
  32       include Google::APIClient::Logging
  33
  34       MULTIPART_BOUNDARY = "-----------RubyApiMultipartPost".freeze
  35
  36       # @return [Hash] Request parameters
  37       attr_reader :parameters
  38       # @return [Hash] Additional HTTP headers
  39       attr_reader :headers
  40       # @return [Google::APIClient::Method] API method to invoke
  41       attr_reader :api_method
  42       # @return [Google::APIClient::UploadIO] File to upload
  43       attr_accessor :media
  44       # @return [#generated_authenticated_request] User credentials
  45       attr_accessor :authorization
  46       # @return [TrueClass,FalseClass] True if request should include credentials
  47       attr_accessor :authenticated
  48       # @return [#read, #to_str] Request body
  49       attr_accessor :body
  50
  51       ##
  52       # Build a request
  53       #
  54       # @param [Hash] options
  55       # @option options [Hash, Array] :parameters
  56       #   Request parameters for the API method.
  57       # @option options [Google::APIClient::Method] :api_method
  58       #   API method to invoke. Either :api_method or :uri must be specified
  59       # @option options [TrueClass, FalseClass] :authenticated
  60       #   True if request should include credentials. Implicitly true if
  61       #   unspecified and :authorization present
  62       # @option options [#generate_signed_request] :authorization
  63       #   OAuth credentials
  64       # @option options [Google::APIClient::UploadIO] :media
  65       #   File to upload, if media upload request
  66       # @option options [#to_json, #to_hash] :body_object
  67       #   Main body of the API request. Typically hash or object that can
  68       #   be serialized to JSON
  69       # @option options [#read, #to_str] :body
  70       #   Raw body to send in POST/PUT requests
  71       # @option options [String, Addressable::URI] :uri
  72       #   URI to request. Either :api_method or :uri must be specified
  73       # @option options [String, Symbol] :http_method
  74       #   HTTP method when requesting a URI
  75       def initialize(options={})
  76         @parameters = Faraday::Utils::ParamsHash[options[:parameters] || {}]
  77         @headers = Faraday::Utils::Headers.new
  78         self.headers.merge!(options[:headers]) unless options[:headers].nil?
  79         self.api_method = options[:api_method]
  80         self.authenticated = options[:authenticated]
  81         self.authorization = options[:authorization]
  82
  83         # These parameters are handled differently because they're not
  84         # parameters to the API method, but rather to the API system.
  85         self.parameters['key'] ||= options[:key] if options[:key]
  86         self.parameters['userIp'] ||= options[:user_ip] if options[:user_ip]
  87
  88         if options[:media]
  89           self.initialize_media_upload(options)
  90         elsif options[:body]
  91           self.body = options[:body]
  92         elsif options[:body_object]
  93           self.headers['Content-Type'] ||= 'application/json'
  94           self.body = serialize_body(options[:body_object])
  95         else
  96           self.body = ''
  97         end
  98
  99         unless self.api_method
 100           self.http_method = options[:http_method] || 'GET'
 101           self.uri = options[:uri]
 102         end
 103       end
 104
 105       # @!attribute [r] upload_type
 106       # @return [String] protocol used for upload
 107       def upload_type
 108         return self.parameters['uploadType'] || self.parameters['upload_type']
 109       end
 110
 111       # @!attribute http_method
 112       # @return [Symbol] HTTP method if invoking a URI
 113       def http_method
 114         return @http_method ||= self.api_method.http_method.to_s.downcase.to_sym
 115       end
 116
 117       def http_method=(new_http_method)
 118         if new_http_method.kind_of?(Symbol)
 119           @http_method = new_http_method.to_s.downcase.to_sym
 120         elsif new_http_method.respond_to?(:to_str)
 121           @http_method = new_http_method.to_s.downcase.to_sym
 122         else
 123           raise TypeError,
 124             "Expected String or Symbol, got #{new_http_method.class}."
 125         end
 126       end
 127
 128       def api_method=(new_api_method)
 129         if new_api_method.nil? || new_api_method.kind_of?(Google::APIClient::Method)
 130           @api_method = new_api_method
 131         else
 132           raise TypeError,
 133             "Expected Google::APIClient::Method, got #{new_api_method.class}."
 134         end
 135       end
 136
 137       # @!attribute uri
 138       # @return [Addressable::URI] URI to send request
 139       def uri
 140         return @uri ||= self.api_method.generate_uri(self.parameters)
 141       end
 142
 143       def uri=(new_uri)
 144         @uri = Addressable::URI.parse(new_uri)
 145         @parameters.update(@uri.query_values) unless @uri.query_values.nil?
 146       end
 147
 148
 149       # Transmits the request with the given connection
 150       #
 151       # @api private
 152       #
 153       # @param [Faraday::Connection] connection
 154       #   the connection to transmit with
 155       #
 156       # @return [Google::APIClient::Result]
 157       #   result of API request
 158       def send(connection)
 159         env = self.to_env(connection)
 160         logger.debug  { "#{self.class} Sending API request #{env[:method]} #{env[:url].to_s} #{env[:request_headers]}" }
 161         http_response = connection.app.call(env)
 162         result = self.process_http_response(http_response)
 163
 164         logger.debug { "#{self.class} Result: #{result.status} #{result.headers}" }
 165
 166         # Resumamble slightly different than other upload protocols in that it requires at least
 167         # 2 requests.
 168         if self.upload_type == 'resumable'
 169           upload =  result.resumable_upload
 170           unless upload.complete?
 171             logger.debug { "#{self.class} Sending upload body" }
 172             result = upload.send(connection)
 173           end
 174         end
 175         return result
 176       end
 177
 178       # Convert to an HTTP request. Returns components in order of method, URI,
 179       # request headers, and body
 180       #
 181       # @api private
 182       #
 183       # @return [Array<(Symbol, Addressable::URI, Hash, [#read,#to_str])>]
 184       def to_http_request
 185         request = (
 186           if self.api_method
 187             self.api_method.generate_request(self.parameters, self.body, self.headers)
 188           elsif self.uri
 189             unless self.parameters.empty?
 190               self.uri.query = Addressable::URI.form_encode(self.parameters)
 191             end
 192             [self.http_method, self.uri.to_s, self.headers, self.body]
 193           end)
 194         return request
 195       end
 196
 197       ##
 198       # Hashified verison of the API request
 199       #
 200       # @return [Hash]
 201       def to_hash
 202         options = {}
 203         if self.api_method
 204           options[:api_method] = self.api_method
 205           options[:parameters] = self.parameters
 206         else
 207           options[:http_method] = self.http_method
 208           options[:uri] = self.uri
 209         end
 210         options[:headers] = self.headers
 211         options[:body] = self.body
 212         options[:media] = self.media
 213         unless self.authorization.nil?
 214           options[:authorization] = self.authorization
 215         end
 216         return options
 217       end
 218
 219       ##
 220       # Prepares the request for execution, building a hash of parts
 221       # suitable for sending to Faraday::Connection.
 222       #
 223       # @api private
 224       #
 225       # @param [Faraday::Connection] connection
 226       #   Connection for building the request
 227       #
 228       # @return [Hash]
 229       #   Encoded request
 230       def to_env(connection)
 231         method, uri, headers, body = self.to_http_request
 232         http_request = connection.build_request(method) do |req|
 233           req.url(uri.to_s)
 234           req.headers.update(headers)
 235           req.body = body
 236         end
 237
 238         if self.authorization.respond_to?(:generate_authenticated_request)
 239           http_request = self.authorization.generate_authenticated_request(
 240             :request => http_request,
 241             :connection => connection
 242           )
 243         end
 244
 245         request_env = http_request.to_env(connection)
 246       end
 247
 248       ##
 249       # Convert HTTP response to an API Result
 250       #
 251       # @api private
 252       #
 253       # @param [Faraday::Response] response
 254       #   HTTP response
 255       #
 256       # @return [Google::APIClient::Result]
 257       #   Processed API response
 258       def process_http_response(response)
 259         Result.new(self, response)
 260       end
 261
 262       protected
 263
 264       ##
 265       # Adjust headers & body for media uploads
 266       #
 267       # @api private
 268       #
 269       # @param [Hash] options
 270       # @option options [Hash, Array] :parameters
 271       #   Request parameters for the API method.
 272       # @option options [Google::APIClient::UploadIO] :media
 273       #   File to upload, if media upload request
 274       # @option options [#to_json, #to_hash] :body_object
 275       #   Main body of the API request. Typically hash or object that can
 276       #   be serialized to JSON
 277       # @option options [#read, #to_str] :body
 278       #   Raw body to send in POST/PUT requests
 279       def initialize_media_upload(options)
 280         self.media = options[:media]
 281         case self.upload_type
 282         when "media"
 283           if options[:body] || options[:body_object]
 284             raise ArgumentError, "Can not specify body & body object for simple uploads"
 285           end
 286           self.headers['Content-Type'] ||= self.media.content_type
 287           self.body = self.media
 288         when "multipart"
 289           unless options[:body_object]
 290             raise ArgumentError, "Multipart requested but no body object"
 291           end
 292           metadata = StringIO.new(serialize_body(options[:body_object]))
 293           build_multipart([Faraday::UploadIO.new(metadata, 'application/json', 'file.json'), self.media])
 294         when "resumable"
 295           file_length = self.media.length
 296           self.headers['X-Upload-Content-Type'] = self.media.content_type
 297           self.headers['X-Upload-Content-Length'] = file_length.to_s
 298           if options[:body_object]
 299             self.headers['Content-Type'] ||= 'application/json'
 300             self.body = serialize_body(options[:body_object])
 301           else
 302             self.body = ''
 303           end
 304         end
 305       end
 306
 307       ##
 308       # Assemble a multipart message from a set of parts
 309       #
 310       # @api private
 311       #
 312       # @param [Array<[#read,#to_str]>] parts
 313       #   Array of parts to encode.
 314       # @param [String] mime_type
 315       #   MIME type of the message
 316       # @param [String] boundary
 317       #   Boundary for separating each part of the message
 318       def build_multipart(parts, mime_type = 'multipart/related', boundary = MULTIPART_BOUNDARY)
 319         env = Faraday::Env.new
 320         env.request = Faraday::RequestOptions.new
 321         env.request.boundary = boundary
 322         env.request_headers = {'Content-Type' => "#{mime_type};boundary=#{boundary}"}
 323         multipart = Faraday::Request::Multipart.new
 324         self.body = multipart.create_multipart(env, parts.map {|part| [nil, part]})
 325         self.headers.update(env[:request_headers])
 326       end
 327
 328       ##
 329       # Serialize body object to JSON
 330       #
 331       # @api private
 332       #
 333       # @param [#to_json,#to_hash] body
 334       #   object to serialize
 335       #
 336       # @return [String]
 337       #   JSON
 338       def serialize_body(body)
 339         return body.to_json if body.respond_to?(:to_json)
 340         return MultiJson.dump(body.to_hash) if body.respond_to?(:to_hash)
 341         raise TypeError, 'Could not convert body object to JSON.' +
 342                          'Must respond to :to_json or :to_hash.'
 343       end
 344
 345     end
 346   end
 347 end