google-gax 0.6.0 → 0.7.0

data/lib/google/gax/path_template.rb

@@ -63,8 +63,9 @@ module Google
         raise 'path template has no segments' if segments.nil?
         segments.each do |s|
           next unless s.kind == TERMINAL && s.literal == '**'
-          raise 'path template cannot contain more than' \
-                'one path wildcard' if has_path_wildcard
+          if has_path_wildcard
+            raise 'path template cannot contain more than one path wildcard'
+          end
           has_path_wildcard = true
         end
         segments

data/lib/google/gax/settings.rb

@@ -29,6 +29,281 @@
 
 module Google
   module Gax
+    # rubocop:disable Metrics/ParameterLists
+
+    # Encapsulates the call settings for an ApiCallable
+    # @!attribute [r] timeout
+    #   @return [Numeric]
+    # @!attribute [r] retry_options
+    #   @return [RetryOptions]
+    # @!attribute [r] page_descriptor
+    #   @return [PageDescriptor]
+    # @!attribute [r] page_token
+    #   @return [Object]
+    # @!attribute [r] bundle_descriptor
+    #   @return [BundleDescriptor]
+    # @!attribute [r] kwargs
+    #   @return [Hash]
+    class CallSettings
+      attr_reader :timeout, :retry_options, :page_descriptor, :page_token,
+                  :bundler, :bundle_descriptor, :kwargs, :errors
+
+      # @param timeout [Numeric] The client-side timeout for API calls. This
+      #   parameter is ignored for retrying calls.
+      # @param retry_options [RetryOptions] The configuration for retrying upon
+      #   transient error. If set to nil, this call will not retry.
+      # @param page_descriptor [PageDescriptor] indicates the structure of page
+      #   streaming to be performed. If set to nil, page streaming is not
+      #   performed.
+      # @param page_token [Object] determines the page token used in the
+      #   page streaming request. If there is no page_descriptor, this has no
+      #   meaning.
+      # @param bundler orchestrates bundling. If nil, bundling is not
+      #   performed.
+      # @param bundle_descriptor [BundleDescriptor] indicates the structure of
+      #   the bundle. If nil, bundling is not performed.
+      # @param kwargs [Hash]
+      #   Additional keyword argments to be passed to the API call.
+      # @param errors [Array<Exception>]
+      #   Configures the exceptions to wrap with GaxError.
+      def initialize(timeout: 30, retry_options: nil, page_descriptor: nil,
+                     page_token: nil, bundler: nil, bundle_descriptor: nil,
+                     kwargs: {}, errors: [])
+        @timeout = timeout
+        @retry_options = retry_options
+        @page_descriptor = page_descriptor
+        @page_token = page_token
+        @bundler = bundler
+        @bundle_descriptor = bundle_descriptor
+        @kwargs = kwargs
+        @errors = errors
+      end
+
+      # @return true when it has retry codes.
+      def retry_codes?
+        @retry_options && @retry_options.retry_codes
+      end
+
+      # @return true when it has valid bundler configuration.
+      def bundler?
+        @bundler && @bundle_descriptor
+      end
+
+      # Creates a new CallSetting instance which is based on this but merged
+      # settings from options.
+      # @param options [CallOptions, nil] The overriding call settings.
+      # @return a new merged call settings.
+      def merge(options)
+        unless options
+          return CallSettings.new(timeout: @timeout,
+                                  retry_options: @retry_options,
+                                  page_descriptor: @page_descriptor,
+                                  page_token: @page_token,
+                                  bundler: @bundler,
+                                  bundle_descriptor: @bundle_descriptor,
+                                  kwargs: @kwargs,
+                                  errors: @errors)
+        end
+
+        timeout = if options.timeout == :OPTION_INHERIT
+                    @timeout
+                  else
+                    options.timeout
+                  end
+        retry_options = if options.retry_options == :OPTION_INHERIT
+                          @retry_options
+                        else
+                          options.retry_options
+                        end
+        page_token = if options.page_token == :OPTION_INHERIT
+                       @page_token
+                     else
+                       options.page_token
+                     end
+
+        kwargs = @kwargs.dup
+        kwargs.update(options.kwargs) if options.kwargs != :OPTION_INHERIT
+
+        CallSettings.new(timeout: timeout,
+                         retry_options: retry_options,
+                         page_descriptor: @page_descriptor,
+                         page_token: page_token,
+                         bundler: @bundler,
+                         bundle_descriptor: @bundle_descriptor,
+                         kwargs: kwargs,
+                         errors: @errors)
+      end
+    end
+
+    private_constant :CallSettings
+
+    # Encapsulates the overridable settings for a particular API call
+    # @!attribute [r] timeout
+    #   @return [Numeric, :OPTION_INHERIT]
+    # @!attribute [r] retry_options
+    #   @return [RetryOptions, :OPTION_INHERIT]
+    # @!attribute [r] page_token
+    #   @return [Object, :OPTION_INHERIT, :INITIAL_PAGE]
+    # @!attribute [r] kwargs
+    #  @return [Hash, :OPTION_INHERIT]
+    class CallOptions
+      attr_reader :timeout, :retry_options, :page_token, :kwargs
+
+      # @param timeout [Numeric, :OPTION_INHERIT]
+      #   The client-side timeout for API calls.
+      # @param retry_options [RetryOptions, :OPTION_INHERIT]
+      #   The configuration for retrying upon transient error.
+      #   If set to nil, this call will not retry.
+      # @param page_token [Object, :OPTION_INHERIT]
+      #   If set and the call is configured for page streaming, page streaming
+      #   is starting with this page_token.
+      # @param kwargs [Hash, :OPTION_INHERIT]
+      #   Additional keyword argments to be passed to the API call.
+      def initialize(timeout: :OPTION_INHERIT,
+                     retry_options: :OPTION_INHERIT,
+                     page_token: :OPTION_INHERIT,
+                     kwargs: :OPTION_INHERIT)
+        @timeout = timeout
+        @retry_options = retry_options
+        @page_token = page_token
+        @kwargs = kwargs
+      end
+    end
+
+    # Describes the structure of a page-streaming call.
+    class PageDescriptor < Struct.new(:request_page_token_field,
+                                      :response_page_token_field,
+                                      :resource_field)
+    end
+
+    # Per-call configurable settings for retrying upon transient failure.
+    class RetryOptions < Struct.new(:retry_codes, :backoff_settings)
+      # @!attribute retry_codes
+      #   @return [Array<Grpc::Code>] a list of exceptions upon which
+      #     a retry should be attempted.
+      # @!attribute backoff_settings
+      #   @return [BackoffSettings] configuring the retry exponential
+      #     backoff algorithm.
+    end
+
+    # Parameters to the exponential backoff algorithm for retrying.
+    class BackoffSettings < Struct.new(
+      :initial_retry_delay_millis,
+      :retry_delay_multiplier,
+      :max_retry_delay_millis,
+      :initial_rpc_timeout_millis,
+      :rpc_timeout_multiplier,
+      :max_rpc_timeout_millis,
+      :total_timeout_millis
+    )
+      # @!attribute initial_retry_delay_millis
+      #   @return [Numeric] the initial delay time, in milliseconds,
+      #     between the completion of the first failed request and the
+      #     initiation of the first retrying request.
+      # @!attribute retry_delay_multiplier
+      #   @return [Numeric] the multiplier by which to increase the
+      #     delay time between the completion of failed requests, and
+      #     the initiation of the subsequent retrying request.
+      # @!attribute max_retry_delay_millis
+      #   @return [Numeric] the maximum delay time, in milliseconds,
+      #     between requests. When this value is reached,
+      #     +retry_delay_multiplier+ will no longer be used to
+      #     increase delay time.
+      # @!attribute initial_rpc_timeout_millis
+      #   @return [Numeric] the initial timeout parameter to the request.
+      # @!attribute rpc_timeout_multiplier
+      #   @return [Numeric] the multiplier by which to increase the
+      #     timeout parameter between failed requests.
+      # @!attribute max_rpc_timeout_millis
+      #   @return [Numeric] the maximum timeout parameter, in
+      #     milliseconds, for a request. When this value is reached,
+      #     +rpc_timeout_multiplier+ will no longer be used to
+      #     increase the timeout.
+      # @!attribute total_timeout_millis
+      #   @return [Numeric] the total time, in milliseconds, starting
+      #     from when the initial request is sent, after which an
+      #     error will be returned, regardless of the retrying
+      #     attempts made meanwhile.
+    end
+
+    # Describes the structure of bundled call.
+    #
+    # request_discriminator_fields may include '.' as a separator, which is
+    # used to indicate object traversal.  This allows fields in nested objects
+    # to be used to determine what requests to bundle.
+    class BundleDescriptor < Struct.new(:bundled_field,
+                                        :request_discriminator_fields,
+                                        :subresponse_field)
+      # @!attribute bundled_field
+      #   @return [String] the repeated field in the request message
+      #     that will have its elements aggregated by bundling.
+      # @!attribute request_discriminator_fields
+      #   @return [Array<String>] a list of fields in the target
+      #     request message class that are used to determine which
+      #     messages should be bundled together.
+      # @!attribute subresponse_field
+      #   @return [String] an optional field, when present it
+      #     indicates the field in the response message that should be
+      #     used to demultiplex the response into multiple response
+      #     messages.
+      def initialize(bundled_field, request_discriminator_fields,
+                     subresponse_field: nil)
+        super(bundled_field, request_discriminator_fields, subresponse_field)
+      end
+    end
+
+    # Holds values used to configure bundling.
+    #
+    # The xxx_threshold attributes are used to configure when the bundled
+    # request should be made.
+    class BundleOptions < Struct.new(:element_count_threshold,
+                                     :element_count_limit,
+                                     :request_byte_threshold,
+                                     :request_byte_limit,
+                                     :delay_threshold_millis)
+      # @!attribute element_count_threshold
+      #   @return [Numeric] the bundled request will be sent once the
+      #     count of outstanding elements in the repeated field
+      #     reaches this value.
+      # @!attribute element_count_limit
+      #   @return [Numeric] represents a hard limit on the number of
+      #     elements in the repeated field of the bundle; if adding a
+      #     request to a bundle would exceed this value, the bundle is
+      #     sent and the new request is added to a fresh bundle. It is
+      #     invalid for a single request to exceed this limit.
+      # @!attribute request_byte_threshold
+      #   @return [Numeric] the bundled request will be sent once the
+      #     count of bytes in the request reaches this value. Note
+      #     that this value is pessimistically approximated by summing
+      #     the bytesizes of the elements in the repeated field, and
+      #     therefore may be an under-approximation.
+      # @!attribute request_byte_limit
+      #   @return [Numeric] represents a hard limit on the size of the
+      #     bundled request; if adding a request to a bundle would
+      #     exceed this value, the bundle is sent and the new request
+      #     is added to a fresh bundle. It is invalid for a single
+      #     request to exceed this limit. Note that this value is
+      #     pessimistically approximated by summing the bytesizes of
+      #     the elements in the repeated field, with a buffer applied
+      #     to correspond to the resulting under-approximation.
+      # @!attribute delay_threshold_millis
+      #   @return [Numeric] the bundled request will be sent this
+      #     amount of time after the first element in the bundle was
+      #     added to it.
+      def initialize(element_count_threshold: 0,
+                     element_count_limit: 0,
+                     request_byte_threshold: 0,
+                     request_byte_limit: 0,
+                     delay_threshold_millis: 0)
+        super(
+          element_count_threshold,
+          element_count_limit,
+          request_byte_threshold,
+          request_byte_limit,
+          delay_threshold_millis)
+      end
+    end
+
     # Helper for #construct_settings
     #
     # @param bundle_config A Hash specifying a bundle parameters, the value for
@@ -117,8 +392,6 @@ module Google
       string.scan(/[[:upper:]][^[:upper:]]*/).map(&:downcase).join('_')
     end
 
-    # rubocop:disable Metrics/ParameterLists
-
     # Constructs a dictionary mapping method names to CallSettings.
     #
     # The +client_config+ parameter is parsed from a client configuration JSON

data/lib/google/gax/version.rb

@@ -29,6 +29,6 @@
 
 module Google
   module Gax
-    VERSION = '0.6.0'.freeze
+    VERSION = '0.7.0'.freeze
   end
 end

data/lib/google/longrunning/{operations_api.rb → operations_client.rb}

@@ -26,6 +26,7 @@ require "json"
 require "pathname"
 
 require "google/gax"
+require "google/longrunning/operations_pb"
 
 module Google
   module Longrunning
@@ -41,7 +42,7 @@ module Google
     #
     # @!attribute [r] operations_stub
     #   @return [Google::Longrunning::Operations::Stub]
-    class OperationsApi
+    class OperationsClient
       attr_reader :operations_stub
 
       # The default address of the service.
@@ -68,28 +69,6 @@ module Google
       ALL_SCOPES = [
       ].freeze
 
-      OPERATION_PATH_PATH_TEMPLATE = Google::Gax::PathTemplate.new(
-        "operations/{operation_path=**}"
-      )
-
-      private_constant :OPERATION_PATH_PATH_TEMPLATE
-
-      # Returns a fully-qualified operation_path resource name string.
-      # @param operation_path [String]
-      # @return [String]
-      def self.operation_path_path operation_path
-        OPERATION_PATH_PATH_TEMPLATE.render(
-          :"operation_path" => operation_path
-        )
-      end
-
-      # Parses the operation_path from a operation_path resource.
-      # @param operation_path_name [String]
-      # @return [String]
-      def self.match_operation_path_from_operation_path_name operation_path_name
-        OPERATION_PATH_PATH_TEMPLATE.match(operation_path_name)["operation_path"]
-      end
-
       # @param service_path [String]
       #   The domain name of the API remote host.
       # @param port [Integer]
@@ -185,20 +164,20 @@ module Google
       # @return [Google::Longrunning::Operation]
       # @raise [Google::Gax::GaxError] if the RPC is aborted.
       # @example
-      #   require "google/longrunning/operations_api"
+      #   require "google/longrunning/operations_client"
       #
-      #   OperationsApi = Google::Longrunning::OperationsApi
+      #   OperationsClient = Google::Longrunning::OperationsClient
       #
-      #   operations_api = OperationsApi.new
-      #   formatted_name = OperationsApi.operation_path_path("[OPERATION_PATH]")
-      #   response = operations_api.get_operation(formatted_name)
+      #   operations_client = OperationsClient.new
+      #   name = ''
+      #   response = operations_client.get_operation(name)
 
       def get_operation \
           name,
           options: nil
-        req = Google::Longrunning::GetOperationRequest.new(
+        req = Google::Longrunning::GetOperationRequest.new({
           name: name
-        )
+        }.delete_if { |_, v| v.nil? })
         @get_operation.call(req, options)
       end
 
@@ -228,21 +207,21 @@ module Google
       #   object.
       # @raise [Google::Gax::GaxError] if the RPC is aborted.
       # @example
-      #   require "google/longrunning/operations_api"
+      #   require "google/longrunning/operations_client"
       #
-      #   OperationsApi = Google::Longrunning::OperationsApi
+      #   OperationsClient = Google::Longrunning::OperationsClient
       #
-      #   operations_api = OperationsApi.new
+      #   operations_client = OperationsClient.new
       #   name = ''
       #   filter = ''
       #
       #   # Iterate over all results.
-      #   operations_api.list_operations(name, filter).each do |element|
+      #   operations_client.list_operations(name, filter).each do |element|
       #     # Process element.
       #   end
       #
       #   # Or iterate over results one page at a time.
-      #   operations_api.list_operations(name, filter).each_page do |page|
+      #   operations_client.list_operations(name, filter).each_page do |page|
       #     # Process each page at a time.
       #     page.each do |element|
       #       # Process element.
@@ -254,11 +233,11 @@ module Google
           filter,
           page_size: nil,
           options: nil
-        req = Google::Longrunning::ListOperationsRequest.new(
+        req = Google::Longrunning::ListOperationsRequest.new({
           name: name,
-          filter: filter
-        )
-        req.page_size = page_size unless page_size.nil?
+          filter: filter,
+          page_size: page_size
+        }.delete_if { |_, v| v.nil? })
         @list_operations.call(req, options)
       end
 
@@ -280,21 +259,22 @@ module Google
       #   retries, etc.
       # @raise [Google::Gax::GaxError] if the RPC is aborted.
       # @example
-      #   require "google/longrunning/operations_api"
+      #   require "google/longrunning/operations_client"
       #
-      #   OperationsApi = Google::Longrunning::OperationsApi
+      #   OperationsClient = Google::Longrunning::OperationsClient
       #
-      #   operations_api = OperationsApi.new
-      #   formatted_name = OperationsApi.operation_path_path("[OPERATION_PATH]")
-      #   operations_api.cancel_operation(formatted_name)
+      #   operations_client = OperationsClient.new
+      #   name = ''
+      #   operations_client.cancel_operation(name)
 
       def cancel_operation \
           name,
           options: nil
-        req = Google::Longrunning::CancelOperationRequest.new(
+        req = Google::Longrunning::CancelOperationRequest.new({
           name: name
-        )
+        }.delete_if { |_, v| v.nil? })
         @cancel_operation.call(req, options)
+        nil
       end
 
       # Deletes a long-running operation. This method indicates that the client is
@@ -309,21 +289,22 @@ module Google
       #   retries, etc.
       # @raise [Google::Gax::GaxError] if the RPC is aborted.
       # @example
-      #   require "google/longrunning/operations_api"
+      #   require "google/longrunning/operations_client"
       #
-      #   OperationsApi = Google::Longrunning::OperationsApi
+      #   OperationsClient = Google::Longrunning::OperationsClient
       #
-      #   operations_api = OperationsApi.new
-      #   formatted_name = OperationsApi.operation_path_path("[OPERATION_PATH]")
-      #   operations_api.delete_operation(formatted_name)
+      #   operations_client = OperationsClient.new
+      #   name = ''
+      #   operations_client.delete_operation(name)
 
       def delete_operation \
           name,
           options: nil
-        req = Google::Longrunning::DeleteOperationRequest.new(
+        req = Google::Longrunning::DeleteOperationRequest.new({
           name: name
-        )
+        }.delete_if { |_, v| v.nil? })
         @delete_operation.call(req, options)
+        nil
       end
     end
   end