google-api-client 0.8.3 → 0.9

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

@@ -0,0 +1,288 @@
+# 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 'google/apis/core/multipart'
+require 'google/apis/core/http_command'
+require 'google/apis/core/api_command'
+require 'google/apis/errors'
+require 'addressable/uri'
+require 'mime-types'
+
+module Google
+  module Apis
+    module Core
+      # Extension of Hurley's UploadIO to add length accessor
+      class UploadIO < Hurley::UploadIO
+        OCTET_STREAM_CONTENT_TYPE = 'application/octet-stream'
+
+        # Get the length of the stream
+        # @return [Fixnum]
+        def length
+          io.respond_to?(:length) ? io.length : File.size(local_path)
+        end
+
+        # Create a new instance given a file path
+        # @param [String, File] file_name
+        #  Path to file
+        # @param [String] content_type
+        #  Optional content type. If nil, will attempt to auto-detect
+        # @return [Google::Apis::Core::UploadIO]
+        def self.from_file(file_name, content_type: nil)
+          if content_type.nil?
+            type = MIME::Types.of(file_name)
+            content_type = type.first.content_type unless type.nil? || type.empty?
+          end
+          new(file_name, content_type || OCTET_STREAM_CONTENT_TYPE)
+        end
+
+        # Wraps an IO stream in UploadIO
+        # @param [#read] io
+        #  IO to wrap
+        # @param [String] content_type
+        #  Optional content type.
+        # @return [Google::Apis::Core::UploadIO]
+        def self.from_io(io, content_type: OCTET_STREAM_CONTENT_TYPE)
+          new(io, content_type)
+        end
+      end
+
+      # Base upload command. Not intended to be used directly
+      # @private
+      class BaseUploadCommand < ApiCommand
+        UPLOAD_PROTOCOL_HEADER = 'X-Goog-Upload-Protocol'
+        UPLOAD_CONTENT_TYPE_HEADER = 'X-Goog-Upload-Header-Content-Type'
+        UPLOAD_CONTENT_LENGTH = 'X-Goog-Upload-Header-Content-Length'
+
+        # File name or IO containing the content to upload
+        # @return [String, File, #read]
+        attr_accessor :upload_source
+
+        # Content type of the upload material
+        # @return [String]
+        attr_accessor :upload_content_type
+
+        # Content, as UploadIO
+        # @return [Google::Apis::Core::UploadIO]
+        attr_accessor :upload_io
+
+        # Ensure the content is readable and wrapped in an {{Google::Apis::Core::UploadIO}} instance.
+        #
+        # @return [void]
+        # @raise [Google::Apis::ClientError] if upload source is invalid
+        def prepare!
+          super
+          if streamable?(upload_source)
+            self.upload_io = UploadIO.from_io(upload_source, content_type: upload_content_type)
+            @close_io_on_finish = false
+          elsif upload_source.is_a?(String)
+            self.upload_io = UploadIO.from_file(upload_source, content_type: upload_content_type)
+            @close_io_on_finish = true
+          else
+            fail Google::Apis::ClientError, 'Invalid upload source'
+          end
+        end
+
+        # Close IO stream when command done. Only closes the stream if it was opened by the command.
+        def release!
+          upload_io.close if @close_io_on_finish
+        end
+
+        private
+
+        def streamable?(upload_source)
+          upload_source.is_a?(IO) || upload_source.is_a?(StringIO) || upload_source.is_a?(Tempfile)
+        end
+      end
+
+      # Implementation of the raw upload protocol
+      class RawUploadCommand < BaseUploadCommand
+        RAW_PROTOCOL = 'raw'
+
+        # Ensure the content is readable and wrapped in an {{Google::Apis::Core::UploadIO}} instance.
+        #
+        # @return [void]
+        # @raise [Google::Apis::ClientError] if upload source is invalid
+        def prepare!
+          super
+          self.body = upload_io
+          header[UPLOAD_PROTOCOL_HEADER] = RAW_PROTOCOL
+          header[UPLOAD_CONTENT_TYPE_HEADER] = upload_io.content_type
+        end
+      end
+
+      # Implementation of the multipart upload protocol
+      class MultipartUploadCommand < BaseUploadCommand
+        UPLOAD_BOUNDARY = 'RubyApiClientUpload'
+        MULTIPART_PROTOCOL = 'multipart'
+        MULTIPART_RELATED = 'multipart/related'
+
+        # Encode the multipart request
+        #
+        # @return [void]
+        # @raise [Google::Apis::ClientError] if upload source is invalid
+        def prepare!
+          super
+          @multipart = Multipart.new(boundary: UPLOAD_BOUNDARY, content_type: MULTIPART_RELATED)
+          @multipart.add_json(body)
+          @multipart.add_upload(upload_io)
+          self.body = @multipart.assemble
+          header[:content_type] = @multipart.content_type
+          header[UPLOAD_PROTOCOL_HEADER] = MULTIPART_PROTOCOL
+        end
+      end
+
+      # Implementation of the resumable upload protocol
+      class ResumableUploadCommand < BaseUploadCommand
+        UPLOAD_COMMAND_HEADER = 'X-Goog-Upload-Command'
+        UPLOAD_OFFSET_HEADER = 'X-Goog-Upload-Offset'
+        BYTES_RECEIVED_HEADER = 'X-Goog-Upload-Size-Received'
+        UPLOAD_URL_HEADER = 'X-Goog-Upload-URL'
+        UPLOAD_STATUS_HEADER = 'X-Goog-Upload-Status'
+        STATUS_ACTIVE = 'active'
+        STATUS_FINAL = 'final'
+        STATUS_CANCELLED = 'cancelled'
+        RESUMABLE = 'resumable'
+        START_COMMAND = 'start'
+        QUERY_COMMAND = 'query'
+        UPLOAD_COMMAND = 'upload, finalize'
+
+        # Reset upload to initial state.
+        #
+        # @return [void]
+        # @raise [Google::Apis::ClientError] if upload source is invalid
+        def prepare!
+          @state = :start
+          @upload_url = nil
+          @offset = 0
+          super
+        end
+
+        # Check the to see if the upload is complete or needs to be resumed.
+        #
+        # @param [Fixnum] status
+        #   HTTP status code of response
+        # @param [Hurley::Header] header
+        #   Response headers
+        # @param [String, #read] body
+        #  Response body
+        # @return [Object]
+        #   Response object
+        # @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 process_response(status, header, body)
+          @offset = Integer(header[BYTES_RECEIVED_HEADER]) if header.key?(BYTES_RECEIVED_HEADER)
+          @upload_url = header[UPLOAD_URL_HEADER] if header.key?(UPLOAD_URL_HEADER)
+          upload_status = header[UPLOAD_STATUS_HEADER]
+          logger.debug { sprintf('Upload status %s', upload_status) }
+          if upload_status == STATUS_ACTIVE
+            @state = :active
+          elsif upload_status == STATUS_FINAL
+            @state = :final
+          elsif upload_status == STATUS_CANCELLED
+            @state = :cancelled
+            fail Google::Apis::ClientError, body
+          end
+          super(status, header, body)
+        end
+
+        # Send the start command to initiate the upload
+        #
+        # @param [Hurley::Client] client
+        #   HTTP client
+        # @return [Hurley::Response]
+        # @raise [Google::Apis::ServerError] Unable to send the request
+        def send_start_command(client)
+          logger.debug { sprintf('Sending upload start command to %s', url) }
+          client.send(method, url, body) do |req|
+            apply_request_options(req)
+            req.header[UPLOAD_PROTOCOL_HEADER] = RESUMABLE
+            req.header[UPLOAD_COMMAND_HEADER] = START_COMMAND
+            req.header[UPLOAD_CONTENT_LENGTH] = upload_io.length.to_s
+            req.header[UPLOAD_CONTENT_TYPE_HEADER] = upload_io.content_type
+          end
+        rescue => e
+          raise Google::Apis::ServerError, e.message
+        end
+
+        # Query for the status of an incomplete upload
+        #
+        # @param [Hurley::Client] client
+        #   HTTP client
+        # @return [Hurley::Response]
+        # @raise [Google::Apis::ServerError] Unable to send the request
+        def send_query_command(client)
+          logger.debug { sprintf('Sending upload query command to %s', @upload_url) }
+          client.post(@upload_url, nil) do |req|
+            apply_request_options(req)
+            req.header[UPLOAD_COMMAND_HEADER] = QUERY_COMMAND
+          end
+        end
+
+        # Send the actual content
+        #
+        # @param [Hurley::Client] client
+        #   HTTP client
+        # @return [Hurley::Response]
+        # @raise [Google::Apis::ServerError] Unable to send the request
+        def send_upload_command(client)
+          logger.debug { sprintf('Sending upload command to %s', @upload_url) }
+          content = upload_io
+          content.pos = @offset
+          client.post(@upload_url, content) do |req|
+            apply_request_options(req)
+            req.header[UPLOAD_COMMAND_HEADER] = UPLOAD_COMMAND
+            req.header[UPLOAD_OFFSET_HEADER] = @offset.to_s
+          end
+        end
+
+        # Execute the upload request once. This will typically perform two HTTP requests -- one to initiate or query
+        # for the status of the upload, the second to send the (remaining) content.
+        #
+        # @private
+        # @param [Hurley::Client] client
+        #   HTTP client
+        # @yield [result, err] Result or error if block supplied
+        # @return [Object]
+        # @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_once(client, &block)
+          case @state
+          when :start
+            response = send_start_command(client)
+            result = process_response(response.status_code, response.header, response.body)
+          when :active
+            response = send_query_command(client)
+            result = process_response(response.status_code, response.header, response.body)
+          when :cancelled, :final
+            error(@last_error, rethrow: true, &block)
+          end
+          if @state == :active
+            response = send_upload_command(client)
+            result = process_response(response.status_code, response.header, response.body)
+          end
+
+          success(result, &block) if @state == :final
+        rescue => e
+          # Some APIs like Youtube generate non-retriable 401 errors and mark
+          # the upload as finalized. Save the error just in case we get
+          # retried.
+          @last_error = e
+          error(e, rethrow: true, &block)
+        end
+      end
+    end
+  end
+end

data/lib/google/{api_client → apis}/errors.rb

@@ -1,4 +1,4 @@
-# Copyright 2010 Google Inc.
+# 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.
@@ -12,54 +12,65 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-
 module Google
-  class APIClient
-    ##
+  module Apis
+    # Base error, capable of wrapping another
+    class Error < StandardError
+      attr_reader :status_code
+      attr_reader :header
+      attr_reader :body
+      
+      def initialize(err, status_code: nil, header: nil, body: nil)
+        @cause = nil
+
+        if err.respond_to?(:backtrace)
+          super(err.message)
+          @cause = err
+        else
+          super(err.to_s)
+        end
+        @status_code = status_code
+        @header = header.dup unless header.nil?
+        @body = body
+      end
+
+      def backtrace
+        if @cause
+          @cause.backtrace
+        else
+          super
+        end
+      end
+    end
+    
     # An error which is raised when there is an unexpected response or other
     # transport error that prevents an operation from succeeding.
-    class TransmissionError < StandardError
-      attr_reader :result
-      def initialize(message = nil, result = nil)
-        super(message)
-        @result = result
-      end
+    class TransmissionError < Error
     end
 
-    ##
     # An exception that is raised if a redirect is required
     #
-    class RedirectError < TransmissionError
+    class RedirectError < Error
     end
 
-    ##
-    # An exception that is raised if a method is called with missing or
-    # invalid parameter values.
-    class ValidationError < StandardError
+    # A 4xx class HTTP error occurred.
+    class ClientError < Error
     end
 
-    ##
     # A 4xx class HTTP error occurred.
-    class ClientError < TransmissionError
+    class RateLimitError < Error
     end
 
-    ##
     # A 401 HTTP error occurred.
-    class AuthorizationError < ClientError
+    class AuthorizationError < Error
     end
 
-    ##
     # A 5xx class HTTP error occurred.
-    class ServerError < TransmissionError
-    end
-
-    ##
-    # An exception that is raised if an ID token could not be validated.
-    class InvalidIDTokenError < StandardError
+    class ServerError < Error
     end
 
     # Error class for problems in batch requests.
-    class BatchError < StandardError
+    class BatchError < Error
     end
   end
 end

data/lib/google/apis/generator/annotator.rb

@@ -0,0 +1,295 @@
+# 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 'logger'
+require 'erb'
+require 'yaml'
+require 'multi_json'
+require 'active_support/inflector'
+require 'google/apis/core/logging'
+require 'google/apis/generator/template'
+require 'google/apis/generator/model'
+require 'google/apis/generator/helpers'
+require 'addressable/uri'
+
+module Google
+  module Apis
+    # @private
+    class Generator
+      # Helper for picking names for methods, properties, types, etc. Performs various normaliations
+      # as well as allows for overriding individual names from a configuration file for cases
+      # where algorithmic approaches produce poor APIs.
+      class Names
+        include Google::Apis::Core::Logging
+        include NameHelpers
+
+        def initialize(file_path = nil)
+          if file_path
+            logger.info { sprintf('Loading API names from %s', file_path) }
+            @names = YAML.load(File.read(file_path)) || {}
+          else
+            @names = {}
+          end
+          @path = []
+        end
+
+        def with_path(path)
+          @path.push(path)
+          begin
+            yield
+          ensure
+            @path.pop
+          end
+        end
+
+        def infer_parameter_name
+          pick_name(normalize_param_name(@path.last))
+        end
+
+        # Determine the ruby method name to generate for a given method in discovery.
+        # @param [Google::Apis::DiscoveryV1::RestMethod] method
+        #  Fragment of the discovery doc describing the method
+        def infer_method_name(method)
+          pick_name(infer_method_name_for_rpc(method) || infer_method_name_from_id(method))
+        end
+
+        def infer_property_name
+          pick_name(normalize_property_name(@path.last))
+        end
+
+        def pick_name(alt_name)
+          preferred_name = @names[key]
+          if preferred_name && preferred_name == alt_name
+            logger.warn { sprintf("Unnecessary name override '%s': %s", key, alt_name) }
+          elsif preferred_name.nil?
+            preferred_name = @names[key] = alt_name
+          end
+          preferred_name
+        end
+
+        def []=(key, value)
+          @names[key] = value
+        end
+
+        def dump
+          YAML.dump(@names)
+        end
+
+        def key
+          @path.reduce('') { |a, e| a + '/' + e }
+        end
+
+        def option(opt_name)
+          @names[sprintf('%s?%s', key, opt_name)]
+        end
+
+        private
+
+        # For RPC style methods, pick a name based off the request objects.
+        # @param [Google::Apis::DiscoveryV1::RestMethod] method
+        #  Fragment of the discovery doc describing the method
+        def infer_method_name_for_rpc(method)
+          return nil if method.request.nil?
+          parts = method.id.split('.')
+          parts.shift
+          verb = ActiveSupport::Inflector.underscore(parts.pop)
+          match = method.request._ref.match(/(.*)(?i:request)/)
+          return nil if match.nil?
+          name = ActiveSupport::Inflector.underscore(match[1])
+          return nil unless name == verb || name.start_with?(verb + '_')
+          if !parts.empty?
+            resource_name = ActiveSupport::Inflector.singularize(parts.pop)
+            resource_name = ActiveSupport::Inflector.underscore(resource_name)
+            if !name.include?(resource_name)
+              name = name.split('_').insert(1, resource_name).join('_')
+            end
+          end
+          name
+        end
+
+        # For REST style methods, build a method name from the verb/resource(s) in the method
+        # id. IDs are in the form <api>.<resource>.<verb>
+        # @param [Google::Apis::DiscoveryV1::RestMethod] method
+        #  Fragment of the discovery doc describing the method
+        def infer_method_name_from_id(method)
+          parts = method.id.split('.')
+          parts.shift
+          verb = ActiveSupport::Inflector.underscore(parts.pop)
+          return verb if parts.empty?
+          resource_name = ActiveSupport::Inflector.underscore(parts.pop)
+          if pluralize_method?(verb)
+            resource_name = ActiveSupport::Inflector.pluralize(resource_name)
+          else
+            resource_name = ActiveSupport::Inflector.singularize(resource_name)
+          end
+          if parts.empty?
+            resource_path = resource_name
+          else
+            resource_path = parts.map do |p|
+              p = ActiveSupport::Inflector.singularize(p)
+              ActiveSupport::Inflector.underscore(p)
+            end.join('_') + '_' + resource_name
+          end
+          method_name = verb.split('_').insert(1, resource_path.split('_')).join('_')
+          method_name
+        end
+      end
+
+      # Modifies an API description to support ruby code generation. Primarily does:
+      # - Ensure all names follow appopriate ruby conventions
+      # - Maps types to ruby types, classes, and resolves $refs
+      # - Attempts to simplify names where possible to make APIs more sensible
+      class Annotator
+        include NameHelpers
+        include Google::Apis::Core::Logging
+
+        # Don't expose these in the API directly.
+        PARAMETER_BLACKLIST = %w(alt access_token bearer_token oauth_token pp prettyPrint
+                                 $.xgafv callback upload_protocol uploadType)
+
+        # Prepare the API for the templates.
+        # @param [Google::Apis::DiscoveryV1::RestDescription] description
+        #  API Description
+        def self.process(description, api_names = nil)
+          Annotator.new(description, api_names).annotate_api
+        end
+
+        # @param [Google::Apis::DiscoveryV1::RestDescription] description
+        #  API Description
+        # @param [Google::Api::Generator::Names] api_names
+        #  Name helper instanace
+        def initialize(description, api_names = nil)
+          api_names = Names.new if api_names.nil?
+          @names = api_names
+          @rest_description = description
+          @registered_types = []
+          @deferred_types = []
+          @strip_prefixes = []
+          @all_methods = {}
+          @path = []
+        end
+
+        def annotate_api
+          @names.with_path(@rest_description.id) do
+            @strip_prefixes << @rest_description.name
+            if @rest_description.auth
+              @rest_description.auth.oauth2.scopes.each do |key, value|
+                value.constant = constantize_scope(key)
+              end
+            end
+            @rest_description.force_alt_json = @names.option('force_alt_json')
+            @rest_description.parameters.reject! { |k, _v| PARAMETER_BLACKLIST.include?(k) }
+            annotate_parameters(@rest_description.parameters)
+            annotate_resource(@rest_description.name, @rest_description)
+            @rest_description.schemas.each do |k, v|
+              annotate_type(k, v, @rest_description)
+            end unless @rest_description.schemas.nil?
+          end
+          resolve_type_references
+          resolve_variants
+        end
+
+        def annotate_type(name, type, parent)
+          @names.with_path(name) do
+            type.name = name
+            type.path = @names.key
+            type.generated_name = @names.infer_property_name
+            if type.type == 'object'
+              type.generated_class_name = ActiveSupport::Inflector.camelize(type.generated_name)
+              @registered_types << type
+            end
+            type.parent = parent
+            @deferred_types << type if type._ref
+            type.properties.each do |k, v|
+              annotate_type(k, v, type)
+            end unless type.properties.nil?
+            if type.additional_properties
+              type.type = 'hash'
+              annotate_type(ActiveSupport::Inflector.singularize(type.generated_name), type.additional_properties,
+                            parent)
+            end
+            annotate_type(ActiveSupport::Inflector.singularize(type.generated_name), type.items, parent) if type.items
+          end
+        end
+
+        def annotate_resource(name, resource, parent_resource = nil)
+          @strip_prefixes << name
+          resource.parent = parent_resource unless parent_resource.nil?
+          resource.api_methods.each do |_k, v|
+            annotate_method(v, resource)
+          end unless resource.api_methods.nil?
+
+          resource.resources.each do |k, v|
+            annotate_resource(k, v, resource)
+          end unless resource.resources.nil?
+        end
+
+        def annotate_method(method, parent_resource = nil)
+          @names.with_path(method.id) do
+            method.parent = parent_resource
+            method.generated_name = @names.infer_method_name(method)
+            check_duplicate_method(method)
+            annotate_parameters(method.parameters)
+          end
+        end
+
+        def annotate_parameters(parameters)
+          parameters.each do |key, value|
+            @names.with_path(key) do
+              value.name = key
+              value.generated_name = @names.infer_parameter_name
+              @deferred_types << value if value._ref
+            end
+          end unless parameters.nil?
+        end
+
+        def resolve_type_references
+          @deferred_types.each do |type|
+            if type._ref
+              ref = @rest_description.schemas[type._ref]
+              ivars = ref.instance_variables - [:@name, :@generated_name]
+              (ivars).each do |var|
+                type.instance_variable_set(var, ref.instance_variable_get(var))
+              end
+            end
+          end
+        end
+
+        def resolve_variants
+          @deferred_types.each do |type|
+            if type.variant
+              type.variant.map.each do |v|
+                ref = @rest_description.schemas[v._ref]
+                ref.base_ref = type
+                ref.discriminant = type.variant.discriminant
+                ref.discriminant_value = v.type_value
+              end
+            end
+          end
+        end
+
+        def check_duplicate_method(m)
+          if @all_methods.include?(m.generated_name)
+            logger.error do
+              sprintf('Duplicate method %s generated, path %s',
+                m.generated_name, @names.key)
+            end
+            fail 'Duplicate name generated'
+          end
+          @all_methods[m.generated_name] = m
+        end
+      end
+    end
+  end
+end