google-apis-core 0.1.0

data/lib/google/apis/core.rb

@@ -0,0 +1,20 @@
+# Copyright 2020 Google LLC
+#
+# 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.
+
+module Google
+  module Apis
+    module Core
+    end
+  end
+end

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

@@ -0,0 +1,224 @@
+# Copyright 2020 Google LLC
+#
+# 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/core/http_command'
+require 'google/apis/errors'
+require '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'
+        ERROR_REASON_MAPPING = {
+          'rateLimitExceeded' => Google::Apis::RateLimitError,
+          'userRateLimitExceeded' => Google::Apis::RateLimitError,
+          'projectNotLinked' => Google::Apis::ProjectNotLinkedError
+        }
+
+        # 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
+
+        # Client library version.
+        # @return [String]
+        attr_accessor :client_version
+
+        # @param [symbol] method
+        #   HTTP method
+        # @param [String,Addressable::URI, Addressable::Template] url
+        #   HTTP URL or template
+        # @param [String, #read] body
+        #   Request body
+        def initialize(method, url, body: nil, client_version: nil)
+          super(method, url, body: body)
+          self.client_version = client_version || '0.0'
+        end
+
+        # Serialize the request body
+        #
+        # @return [void]
+        def prepare!
+          set_api_client_header
+          set_user_project_header
+          if options&.api_format_version
+            header['X-Goog-Api-Format-Version'] = options.api_format_version.to_s
+          end
+          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
+            if options && options.skip_serialization
+              self.body = request_object
+            else
+              self.body = request_representation.new(request_object).to_json(user_options: { skip_undefined: true })
+            end
+          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 options && options.skip_deserialization
+          return super if content_type.nil?
+          return nil unless content_type.start_with?(JSON_CONTENT_TYPE)
+          body = "{}" if body.empty?
+          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 [Hash] 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
+            reason, message = parse_error(body)
+            if reason
+              message = sprintf('%s: %s', reason, message)
+              raise ERROR_REASON_MAPPING[reason].new(
+                message,
+                status_code: status,
+                header: header,
+                body: body
+              ) if ERROR_REASON_MAPPING.key?(reason)
+            end
+            super(status, header, body, message)
+          else
+            super(status, header, body, message)
+          end
+        end
+
+        def allow_form_encoding?
+          request_representation.nil? && super
+        end
+
+        private
+
+        def set_api_client_header
+          old_xgac = header
+            .find_all { |k, v| k.downcase == 'x-goog-api-client' }
+            .map { |(a, b)| b }
+            .join(' ')
+            .split
+            .find_all { |s| s !~ %r{^gl-ruby/|^gdcl/} }
+            .join(' ')
+          xgac = "gl-ruby/#{RUBY_VERSION} gdcl/#{client_version}"
+          xgac = old_xgac.empty? ? xgac : "#{old_xgac} #{xgac}"
+          header.delete_if { |k, v| k.downcase == 'x-goog-api-client' }
+          header['X-Goog-Api-Client'] = xgac
+        end
+
+        def set_user_project_header
+          quota_project_id = options.quota_project
+          if !quota_project_id && options&.authorization.respond_to?(:quota_project_id)
+            quota_project_id = options.authorization.quota_project_id
+          end
+          header['X-Goog-User-Project'] = quota_project_id if quota_project_id
+        end
+
+        # Attempt to parse a JSON error message
+        # @param [String] body
+        #  HTTP response body
+        # @return [Array<(String, String)>]
+        #   Error reason and message
+        def parse_error(body)
+          obj = JSON.load(body)
+          error = obj['error']
+          if error['details']
+            return extract_v2_error_details(error)
+          elsif error['errors']
+            return extract_v1_error_details(error)
+          else
+            fail 'Can not parse error message. No "details" or "errors" detected'
+          end
+        rescue
+          return [nil, nil]
+        end
+
+        # Extracts details from a v1 error message
+        # @param [Hash] error
+        #  Parsed JSON
+        # @return [Array<(String, String)>]
+        #   Error reason and message
+        def extract_v1_error_details(error)
+          reason = error['errors'].first['reason']
+          message = error['message']
+          return [reason, message]
+        end
+
+        # Extracts details from a v2error message
+        # @param [Hash] error
+        #  Parsed JSON
+        # @return [Array<(String, String)>]
+        #   Error reason and message
+        def extract_v2_error_details(error)
+          reason = error['status']
+          message = error['message']
+          return [reason, message]
+        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+/) do |str|
+            str.gsub(/(?:^|_)([a-z])/){ Regexp.last_match.begin(0) == 0 ? $1 : $1.upcase }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,459 @@
+# Copyright 2020 Google LLC
+#
+# 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'
+require 'google/apis/core/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/options'
+require 'googleauth'
+require 'httpclient'
+
+module Google
+  module Apis
+    module Core
+      # Helper class for enumerating over a result set requiring multiple fetches
+      class PagedResults
+        include Enumerable
+
+        attr_reader :last_result
+
+        # @param [BaseService] service
+        #   Current service instance
+        # @param [Fixnum] max
+        #   Maximum number of items to iterate over. Nil if no limit
+        # @param [Boolean] cache
+        #  True (default) if results should be cached so multiple iterations can be used.
+        # @param [Symbol] items
+        #   Name of the field in the result containing the items. Defaults to :items
+        def initialize(service, max: nil, items: :items, cache: true, response_page_token: :next_page_token, &block)
+          @service = service
+          @block = block
+          @max = max
+          @items_field = items
+          @response_page_token_field = response_page_token
+          if cache
+            @result_cache = Hash.new do |h, k|
+              h[k] = @block.call(k, @service)
+            end
+            @fetch_proc = Proc.new { |token| @result_cache[token] }
+          else
+            @fetch_proc = Proc.new { |token| @block.call(token, @service) }
+          end
+        end
+
+        # Iterates over result set, fetching additional pages as needed
+        def each
+          page_token = nil
+          item_count = 0
+          loop do
+            @last_result = @fetch_proc.call(page_token)
+            items = @last_result.send(@items_field)
+            if items.kind_of?(Array)
+              for item in items
+                item_count = item_count + 1
+                break if @max && item_count > @max
+                yield item
+              end
+            elsif items.kind_of?(Hash)
+              items.each do |key, val|
+                item_count = item_count + 1
+                break if @max && item_count > @max
+                yield key, val
+              end
+            elsif items
+              # yield singular non-nil items (for genomics API)
+              yield items
+            end
+            break if @max && item_count >= @max
+            next_page_token = @last_result.send(@response_page_token_field)
+            break if next_page_token.nil? || next_page_token == page_token
+            page_token = next_page_token
+          end
+        end
+      end
+
+      # Base service for all APIs. Not to be used directly.
+      #
+      class BaseService
+        include Logging
+
+        # 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 [HTTPClient]
+        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
+
+        # Client library name.
+        # @return [String]
+        attr_accessor :client_name
+
+        # Client library version.
+        # @return [String]
+        attr_accessor :client_version
+
+        # @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, client_name: nil, client_version: nil)
+          self.root_url = root_url
+          self.base_path = base_path
+          self.client_name = client_name || 'google-api-ruby-client'
+          self.client_version = client_version || Google::Apis::Core::VERSION
+          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 |s|
+        #     s.get_item(id1) do |res, err|
+        #       # process response for 1st call
+        #     end
+        #     # ...
+        #     s.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
+            start_batch(batch_command)
+            yield self
+          ensure
+            end_batch
+          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 |s|
+        #     s.insert_item(upload_source: 'file1.txt') do |res, err|
+        #       # process response for 1st call
+        #     end
+        #     # ...
+        #     s.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
+            start_batch(batch_command)
+            yield self
+          ensure
+            end_batch
+          end
+          batch_command.execute(client)
+        end
+
+        # Get the current HTTP client
+        # @return [HTTPClient]
+        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, client_version: client_version)
+          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
+
+        # Executes a given query with paging, automatically retrieving
+        # additional pages as necessary. Requires a block that returns the
+        # result set of a page. The current page token is supplied as an argument
+        # to the block.
+        #
+        # Note: The returned enumerable also contains a `last_result` field
+        # containing the full result of the last query executed.
+        #
+        # @param [Fixnum] max
+        #   Maximum number of items to iterate over. Defaults to nil -- no upper bound.
+        # @param [Symbol] items
+        #   Name of the field in the result containing the items. Defaults to :items
+        # @param [Boolean] cache
+        #  True (default) if results should be cached so multiple iterations can be used.
+        # @return [Enumerble]
+        # @yield [token, service]
+        #   Current page token & service instance
+        # @yieldparam [String] token
+        #   Current page token to be used in the query
+        # @yieldparam [service]
+        #   Current service instance
+        # @since 0.9.4
+        #
+        # @example Retrieve all files,
+        #   file_list = service.fetch_all { |token, s| s.list_files(page_token: token) }
+        #   file_list.each { |f| ... }
+        def fetch_all(max: nil, items: :items, cache: true, response_page_token: :next_page_token, &block)
+          fail "fetch_all may not be used inside a batch" if batch?
+          return PagedResults.new(self, max: max, items: items, cache: cache, response_page_token: response_page_token, &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, client_version: client_version)
+          else
+            command = ResumableUploadCommand.new(method, template, client_version: client_version)
+          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, client_version: client_version)
+          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)
+          full_path =
+            if path.start_with? "/"
+              path[1..-1]
+            else
+              base_path + path
+            end
+          template = Addressable::Template.new(root_url + full_path)
+          command = ApiCommand.new(method, template, client_version: client_version)
+          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
+            fail "Can not combine services in a batch" if Thread.current[:google_api_batch_service] != self
+            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
+
+        # Start a new thread-local batch context
+        # @param [Google::Apis::Core::BatchCommand] cmd
+        def start_batch(cmd)
+          fail "Batch already in progress" if batch?
+          Thread.current[:google_api_batch] = cmd
+          Thread.current[:google_api_batch_service] = self
+        end
+
+        # Clear thread-local batch context
+        def end_batch
+          Thread.current[:google_api_batch] = nil
+          Thread.current[:google_api_batch_service] = nil
+        end
+
+        # Create a new HTTP client
+        # @return [HTTPClient]
+        def new_client
+          client = ::HTTPClient.new
+
+          if client_options.transparent_gzip_decompression
+            client.transparent_gzip_decompression = client_options.transparent_gzip_decompression
+          end
+          
+          client.proxy = client_options.proxy_url if client_options.proxy_url
+
+          if client_options.open_timeout_sec
+            client.connect_timeout = client_options.open_timeout_sec
+          end
+
+          if client_options.read_timeout_sec
+            client.receive_timeout = client_options.read_timeout_sec
+          end
+
+          if client_options.send_timeout_sec
+            client.send_timeout = client_options.send_timeout_sec
+          end
+
+          client.follow_redirect_count = 5
+          client.default_header = { 'User-Agent' => user_agent }
+
+          client.debug_dev = logger if client_options.log_http_requests
+          client
+        end
+
+
+        # Build the user agent header
+        # @return [String]
+        def user_agent
+          sprintf('%s/%s %s/%s %s (gzip)',
+                  client_options.application_name,
+                  client_options.application_version,
+                  client_name,
+                  client_version,
+                  Google::Apis::OS_VERSION)
+        end
+      end
+    end
+  end
+end