google-api-client 0.8.7 → 0.9

data/lib/google/apis/core/api_command.rb

@@ -0,0 +1,135 @@
+# Copyright 2015 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'active_support/inflector'
+require 'addressable/uri'
+require 'addressable/template'
+require 'google/apis/core/http_command'
+require 'google/apis/errors'
+require 'multi_json'
+require 'retriable'
+
+module Google
+  module Apis
+    module Core
+      # Command for executing most basic API request with JSON requests/responses
+      class ApiCommand < HttpCommand
+        JSON_CONTENT_TYPE = 'application/json'
+        FIELDS_PARAM = 'fields'
+        RATE_LIMIT_ERRORS = %w(rateLimitExceeded userRateLimitExceeded)
+
+        # JSON serializer for request objects
+        # @return [Google::Apis::Core::JsonRepresentation]
+        attr_accessor :request_representation
+
+        # Request body to serialize
+        # @return [Object]
+        attr_accessor :request_object
+
+        # JSON serializer for response objects
+        # @return [Google::Apis::Core::JsonRepresentation]
+        attr_accessor :response_representation
+
+        # Class to instantiate when de-serializing responses
+        # @return [Object]
+        attr_accessor :response_class
+
+        # Serialize the request body
+        #
+        # @return [void]
+        def prepare!
+          query[FIELDS_PARAM] = normalize_fields_param(query[FIELDS_PARAM]) if query.key?(FIELDS_PARAM)
+          if request_representation && request_object
+            header[:content_type] ||= JSON_CONTENT_TYPE
+            self.body = request_representation.new(request_object).to_json(skip_undefined: true)
+          end
+          super
+        end
+
+        # Deserialize the response body if present
+        #
+        # @param [String] content_type
+        #  Content type of body
+        # @param [String, #read] body
+        #  Response body
+        # @return [Object]
+        #   Response object
+        # noinspection RubyUnusedLocalVariable
+        def decode_response_body(content_type, body)
+          return super unless response_representation
+          return super if content_type.nil?
+          return nil unless content_type.start_with?(JSON_CONTENT_TYPE)
+          instance = response_class.new
+          response_representation.new(instance).from_json(body, unwrap: response_class)
+          instance
+        end
+
+        # Check the response and raise error if needed
+        #
+        # @param [Fixnum] status
+        #   HTTP status code of response
+        # @param [Hurley::Header] header
+        #   HTTP response headers
+        # @param [String] body
+        #   HTTP response body
+        # @param [String] message
+        #   Error message text
+        # @return [void]
+        # @raise [Google::Apis::ServerError] An error occurred on the server and the request can be retried
+        # @raise [Google::Apis::ClientError] The request is invalid and should not be retried without modification
+        # @raise [Google::Apis::AuthorizationError] Authorization is required
+        def check_status(status, header = nil, body = nil, message = nil)
+          case status
+          when 400, 402...500
+            error = parse_error(body)
+            if error
+              message = sprintf('%s: %s', error['reason'], error['message'])
+              raise Google::Apis::RateLimitError.new(message,
+                                                     status_code: status,
+                                                     header: header,
+                                                     body: body) if RATE_LIMIT_ERRORS.include?(error['reason'])
+            end
+            super(status, header, body, message)
+          else
+            super(status, header, body, message)
+          end
+        end
+
+        private
+
+        # Attempt to parse a JSON error message, returning the first found error
+        # @param [String] body
+        #  HTTP response body
+        # @return [Hash]
+        def parse_error(body)
+          hash = MultiJson.load(body)
+          hash['error']['errors'].first
+        rescue
+          nil
+        end
+
+        # Convert field names from ruby conventions to original names in JSON
+        #
+        # @param [String] fields
+        #   Value of 'fields' param
+        # @return [String]
+        #   Updated header value
+        def normalize_fields_param(fields)
+          # TODO: Generate map of parameter names during code gen. Small possibility that camelization fails
+          fields.gsub(/:/, '').gsub(/[\w_]+/) { |str| ActiveSupport::Inflector.camelize(str, false) }
+        end
+      end
+    end
+  end
+end

data/lib/google/apis/core/base_service.rb

@@ -0,0 +1,317 @@
+# Copyright 2015 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'addressable/uri'
+require 'addressable/template'
+require 'google/apis/version'
+require 'google/apis/core/api_command'
+require 'google/apis/core/batch'
+require 'google/apis/core/upload'
+require 'google/apis/core/download'
+require 'google/apis/core/http_client_adapter'
+require 'google/apis/options'
+require 'googleauth'
+require 'hurley'
+require 'hurley/addressable'
+
+module Google
+  module Apis
+    module Core
+      # Base service for all APIs. Not to be used directly.
+      #
+      class BaseService
+        # Root URL (host/port) for the API
+        # @return [Addressable::URI]
+        attr_accessor :root_url
+
+        # Additional path prefix for all API methods
+        # @return [Addressable::URI]
+        attr_accessor :base_path
+
+        # Alternate path prefix for media uploads
+        # @return [Addressable::URI]
+        attr_accessor :upload_path
+
+        # Alternate path prefix for all batch methods
+        # @return [Addressable::URI]
+        attr_accessor :batch_path
+
+        # HTTP client
+        # @return [Hurley::Client]
+        attr_accessor :client
+
+        # General settings
+        # @return [Google::Apis::ClientOptions]
+        attr_accessor :client_options
+
+        # Default options for all requests
+        # @return [Google::Apis::RequestOptions]
+        attr_accessor :request_options
+
+        # @param [String,Addressable::URI] root_url
+        #   Root URL for the API
+        # @param [String,Addressable::URI] base_path
+        #   Additional path prefix for all API methods
+        # @api private
+        def initialize(root_url, base_path)
+          self.root_url = root_url
+          self.base_path = base_path
+          self.upload_path = "upload/#{base_path}"
+          self.batch_path = 'batch'
+          self.client_options = Google::Apis::ClientOptions.default.dup
+          self.request_options = Google::Apis::RequestOptions.default.dup
+        end
+
+        # @!attribute [rw] authorization
+        # @return [Signet::OAuth2::Client]
+        #  OAuth2 credentials
+        def authorization=(authorization)
+          request_options.authorization = authorization
+        end
+
+        def authorization
+          request_options.authorization
+        end
+
+        # TODO: with(options) method
+
+        # Perform a batch request. Calls made within the block are sent in a single network
+        # request to the server.
+        #
+        # @example
+        #   service.batch do |service|
+        #     service.get_item(id1) do |res, err|
+        #       # process response for 1st call
+        #     end
+        #     # ...
+        #     service.get_item(idN) do |res, err|
+        #       # process response for Nth call
+        #     end
+        #   end
+        #
+        # @param [Hash, Google::Apis::RequestOptions] options
+        #  Request-specific options
+        # @yield [self]
+        # @return [void]
+        def batch(options = nil)
+          batch_command = BatchCommand.new(:post, Addressable::URI.parse(root_url + batch_path))
+          batch_command.options = request_options.merge(options)
+          apply_command_defaults(batch_command)
+          begin
+            Thread.current[:google_api_batch] = batch_command
+            yield self
+          ensure
+            Thread.current[:google_api_batch] = nil
+          end
+          batch_command.execute(client)
+        end
+
+        # Perform a batch upload request. Calls made within the block are sent in a single network
+        # request to the server. Batch uploads are useful for uploading multiple small files. For larger
+        # files, use single requests which use a resumable upload protocol.
+        #
+        # @example
+        #   service.batch do |service|
+        #     service.insert_item(upload_source: 'file1.txt') do |res, err|
+        #       # process response for 1st call
+        #     end
+        #     # ...
+        #     service.insert_item(upload_source: 'fileN.txt') do |res, err|
+        #       # process response for Nth call
+        #     end
+        #   end
+        #
+        # @param [Hash, Google::Apis::RequestOptions] options
+        #  Request-specific options
+        # @yield [self]
+        # @return [void]
+        def batch_upload(options = nil)
+          batch_command = BatchUploadCommand.new(:put, Addressable::URI.parse(root_url + upload_path))
+          batch_command.options = request_options.merge(options)
+          apply_command_defaults(batch_command)
+          begin
+            Thread.current[:google_api_batch] = batch_command
+            yield self
+          ensure
+            Thread.current[:google_api_batch] = nil
+          end
+          batch_command.execute(client)
+        end
+
+        # Get the current HTTP client
+        # @return [Hurley::Client]
+        def client
+          @client ||= new_client
+        end
+
+
+        # Simple escape hatch for making API requests directly to a given
+        # URL. This is not intended to be used as a generic HTTP client
+        # and should be used only in cases where no service method exists
+        # (e.g. fetching an export link for a Google Drive file.)
+        #
+        # @param [Symbol] method
+        #   HTTP method as symbol (e.g. :get, :post, :put, ...)
+        # @param [String] url
+        #   URL to call
+        # @param [Hash<String,String>] params
+        #   Optional hash of query parameters
+        # @param [#read] body
+        #   Optional body for POST/PUT
+        # @param [IO, String] download_dest
+        #   IO stream or filename to receive content download
+        # @param [Google::Apis::RequestOptions] options
+        #   Request-specific options
+        #
+        # @yield [result, err] Result & error if block supplied
+        # @yieldparam result [String] HTTP response body
+        # @yieldparam err [StandardError] error object if request failed
+        #
+        # @return [String] HTTP response body
+        def http(method, url, params: nil, body: nil, download_dest: nil, options: nil, &block)
+          if download_dest
+            command = DownloadCommand.new(method, url, body: body)
+          else
+            command = HttpCommand.new(method, url, body: body)
+          end
+          command.options = request_options.merge(options)
+          apply_command_defaults(command)
+          command.query.merge(Hash(params))
+          execute_or_queue_command(command, &block)
+        end
+
+        protected
+
+        # Create a new upload command.
+        #
+        # @param [symbol] method
+        #   HTTP method for uploading (typically :put or :post)
+        # @param [String] path
+        #  Additional path to upload endpoint, appended to API base path
+        # @param [Hash, Google::Apis::RequestOptions] options
+        #  Request-specific options
+        # @return [Google::Apis::Core::UploadCommand]
+        def make_upload_command(method, path, options)
+          template = Addressable::Template.new(root_url + upload_path + path)
+          if batch?
+            command = MultipartUploadCommand.new(method, template)
+          else
+            command = ResumableUploadCommand.new(method, template)
+          end
+          command.options = request_options.merge(options)
+          apply_command_defaults(command)
+          command
+        end
+
+        # Create a new download command.
+        #
+        # @param [symbol] method
+        #   HTTP method for uploading (typically :get)
+        # @param [String] path
+        #  Additional path to download endpoint, appended to API base path
+        # @param [Hash, Google::Apis::RequestOptions] options
+        #  Request-specific options
+        # @return [Google::Apis::Core::DownloadCommand]
+        def make_download_command(method, path, options)
+          template = Addressable::Template.new(root_url + base_path + path)
+          command = DownloadCommand.new(method, template)
+          command.options = request_options.merge(options)
+          command.query['alt'] = 'media'
+          apply_command_defaults(command)
+          command
+        end
+
+        # Create a new command.
+        #
+        # @param [symbol] method
+        #   HTTP method (:get, :post, :delete, etc...)
+        # @param [String] path
+        #  Additional path, appended to API base path
+        # @param [Hash, Google::Apis::RequestOptions] options
+        #  Request-specific options
+        # @return [Google::Apis::Core::DownloadCommand]
+        def make_simple_command(method, path, options)
+          template = Addressable::Template.new(root_url + base_path + path)
+          command = ApiCommand.new(method, template)
+          command.options = request_options.merge(options)
+          apply_command_defaults(command)
+          command
+        end
+
+        # Execute the request. If a batch is in progress, the request is added to the batch instead.
+        #
+        # @param [Google::Apis::Core::HttpCommand] command
+        #   Command to execute
+        # @return [Object] response object if command executed and no callback supplied
+        # @yield [result, err] Result & error if block supplied
+        # @raise [Google::Apis::ServerError] An error occurred on the server and the request can be retried
+        # @raise [Google::Apis::ClientError] The request is invalid and should not be retried without modification
+        # @raise [Google::Apis::AuthorizationError] Authorization is required
+        def execute_or_queue_command(command, &callback)
+          batch_command = current_batch
+          if batch_command
+            batch_command.add(command, &callback)
+            nil
+          else
+            command.execute(client, &callback)
+          end
+        end
+
+        # Update commands with service-specific options. To be implemented by subclasses
+        # @param [Google::Apis::Core::HttpCommand] _command
+        def apply_command_defaults(_command)
+        end
+
+        private
+
+        # Get the current batch context
+        #
+        # @return [Google:Apis::Core::BatchRequest]
+        def current_batch
+          Thread.current[:google_api_batch]
+        end
+
+        # Check if a batch is in progress
+        # @return [Boolean]
+        def batch?
+          !current_batch.nil?
+        end
+
+        # Create a new HTTP client
+        # @return [Hurley::Client]
+        def new_client
+          client = Hurley::Client.new
+          client.connection = Google::Apis::Core::HttpClientAdapter.new unless client_options.use_net_http
+          client.request_options.timeout = request_options.timeout_sec
+          client.request_options.open_timeout = request_options.open_timeout_sec
+          client.request_options.proxy = client_options.proxy_url
+          client.request_options.query_class = Hurley::Query::Flat
+          client.ssl_options.ca_file = File.join(Google::Apis::ROOT, 'lib', 'cacerts.pem')
+          client.header[:user_agent] = user_agent
+          client
+        end
+
+        # Build the user agent header
+        # @return [String]
+        def user_agent
+          sprintf('%s/%s google-api-ruby-client/%s %s (gzip)',
+                  client_options.application_name,
+                  client_options.application_version,
+                  Google::Apis::VERSION,
+                  Google::Apis::OS_VERSION)
+        end
+      end
+    end
+  end
+end

data/lib/google/apis/core/batch.rb

@@ -0,0 +1,239 @@
+# Copyright 2015 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# Copyright 2015 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'hurley'
+require 'google/apis/core/multipart'
+require 'google/apis/core/http_command'
+require 'google/apis/core/upload'
+require 'google/apis/core/download'
+require 'addressable/uri'
+require 'securerandom'
+module Google
+  module Apis
+    module Core
+      # Wrapper request for batching multiple calls in a single server request
+      class BatchCommand < HttpCommand
+        BATCH_BOUNDARY = 'RubyApiBatchRequest'.freeze
+        MULTIPART_MIXED = 'multipart/mixed'
+
+        # @param [symbol] method
+        #   HTTP method
+        # @param [String,Addressable::URI, Addressable::Template] url
+        #   HTTP URL or template
+        def initialize(method, url)
+          super(method, url)
+          @calls = []
+          @base_id = SecureRandom.uuid
+        end
+
+        ##
+        # Add a new call to the batch request.
+        #
+        # @param [Google::Apis::Core::HttpCommand] call API Request to add
+        # @yield [result, err] Result & error when response available
+        # @return [Google::Apis::Core::BatchCommand] self
+        def add(call, &block)
+          ensure_valid_command(call)
+          @calls << [call, block]
+          self
+        end
+
+        protected
+
+        ##
+        # Deconstruct the batch response and process the individual results
+        #
+        # @param [String] content_type
+        #  Content type of body
+        # @param [String, #read] body
+        #  Response body
+        # @return [Object]
+        #   Response object
+        def decode_response_body(content_type, body)
+          m = /.*boundary=(.+)/.match(content_type)
+          if m
+            parts = split_parts(body, m[1])
+            deserializer = CallDeserializer.new
+            parts.each_index do |index|
+              response = deserializer.to_http_response(parts[index])
+              outer_header = response.shift
+              call_id = header_to_id(outer_header[:content_id]) || index
+              call, callback = @calls[call_id]
+              begin
+                result = call.process_response(*response) unless call.nil?
+                success(result, &callback)
+              rescue => e
+                error(e, &callback)
+              end
+            end
+          end
+          nil
+        end
+
+        def split_parts(body, boundary)
+          parts = body.split(/\r?\n?--#{Regexp.escape(boundary)}/)
+          parts[1...-1]
+        end
+
+        # Encode the batch request
+        # @return [void]
+        # @raise [Google::Apis::BatchError] if batch is empty
+        def prepare!
+          fail BatchError, 'Cannot make an empty batch request' if @calls.empty?
+
+          serializer = CallSerializer.new
+          multipart = Multipart.new(boundary: BATCH_BOUNDARY, content_type: MULTIPART_MIXED)
+          @calls.each_index do |index|
+            call, _ = @calls[index]
+            content_id = id_to_header(index)
+            io = serializer.to_upload_io(call)
+            multipart.add_upload(io, content_id: content_id)
+          end
+          self.body = multipart.assemble
+
+          header[:content_type] = multipart.content_type
+          header[:content_length] = "#{body.length}"
+          super
+        end
+
+        def ensure_valid_command(command)
+          if command.is_a?(Google::Apis::Core::BaseUploadCommand) || command.is_a?(Google::Apis::Core::DownloadCommand)
+            fail Google::Apis::ClientError, 'Can not include media requests in batch'
+          end
+          fail Google::Apis::ClientError, 'Invalid command object' unless command.is_a?(HttpCommand)
+        end
+
+        def id_to_header(call_id)
+          return sprintf('<%s+%i>', @base_id, call_id)
+        end
+
+        def header_to_id(content_id)
+          match = /<response-.*\+(\d+)>/.match(content_id)
+          return match[1].to_i if match
+          return nil
+        end
+
+      end
+
+      # Wrapper request for batching multiple uploads in a single server request
+      class BatchUploadCommand < BatchCommand
+        def ensure_valid_command(command)
+          fail Google::Apis::ClientError, 'Can only include upload commands in batch' \
+            unless command.is_a?(Google::Apis::Core::BaseUploadCommand)
+        end
+
+        def prepare!
+          header['X-Goog-Upload-Protocol'] = 'batch'
+          super
+        end
+      end
+
+      # Serializes a command for embedding in a multipart batch request
+      # @private
+      class CallSerializer
+        HTTP_CONTENT_TYPE = 'application/http'
+
+        ##
+        # Serialize a single batched call for assembling the multipart message
+        #
+        # @param [Google::Apis::Core::HttpCommand] call
+        #   the call to serialize.
+        # @return [Hurley::UploadIO]
+        #   the serialized request
+        def to_upload_io(call)
+          call.prepare!
+          parts = []
+          parts << build_head(call)
+          parts << build_body(call) unless call.body.nil?
+          length = parts.inject(0) { |a, e| a + e.length }
+          Hurley::UploadIO.new(Hurley::CompositeReadIO.new(length, *parts),
+                               HTTP_CONTENT_TYPE,
+                               'ruby-api-request')
+        end
+
+        protected
+
+        def build_head(call)
+          request_head = "#{call.method.to_s.upcase} #{Addressable::URI.parse(call.url).request_uri} HTTP/1.1"
+          call.header.each do |key, value|
+            request_head << sprintf("\r\n%s: %s", key, value)
+          end
+          request_head << sprintf("\r\nHost: %s", call.url.host)
+          request_head << "\r\n\r\n"
+          StringIO.new(request_head)
+        end
+
+        def build_body(call)
+          return nil if call.body.nil?
+          return call.body if call.body.respond_to?(:read)
+          StringIO.new(call.body)
+        end
+      end
+
+      # Deconstructs a raw HTTP response part
+      # @private
+      class CallDeserializer
+        # Parse a batched response.
+        #
+        # @param [String] call_response
+        #   the response to parse.
+        # @return [Array<(Fixnum, Hurley::Header, String)>]
+        #   Status, header, and response body.
+        def to_http_response(call_response)
+          outer_header, outer_body = split_header_and_body(call_response)
+          status_line, payload = outer_body.split(/\n/, 2)
+          _, status = status_line.split(' ', 3)
+
+          header, body = split_header_and_body(payload)
+          [outer_header, status.to_i, header, body]
+        end
+
+        protected
+
+        # Auxiliary method to split the header from the body in an HTTP response.
+        #
+        # @param [String] response
+        #   the response to parse.
+        # @return [Array<(Hurley::Header, String)>]
+        #   the header and the body, separately.
+        def split_header_and_body(response)
+          header = Hurley::Header.new
+          payload = response.lstrip
+          while payload
+            line, payload = payload.split(/\n/, 2)
+            line.sub!(/\s+\z/, '')
+            break if line.empty?
+            match = /\A([^:]+):\s*/.match(line)
+            fail BatchError, sprintf('Invalid header line in response: %s', line) if match.nil?
+            header[match[1]] = match.post_match
+          end
+          [header, payload]
+        end
+      end
+    end
+  end
+end