google-gax 0.1.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4c5ff2bfbcc82e5320ab20d550923bdf003c4a7a
-  data.tar.gz: 83336c0d592b0ccfe965bc6d667ce4497ea6fbb1
+  metadata.gz: df878307196d3628c155d4de6d3b333524b93937
+  data.tar.gz: bd5b46d05109352ad29de368998e36efe1bfcd8d
 SHA512:
-  metadata.gz: d68e2841381b5ec2d8d9c4ec9f189e8c78cb9306ac4df3444133f1dc8bccc7e94faf213d47068fad5025377c33e271be2d6f6a1130c494e82eb69b79aa848244
-  data.tar.gz: b58732d2fc4a3d45fc70cc9b59a0ecd3975f385ef6062749cbc483596601c566359f5937f08c8916f47f4341683587402fa2cc9647b282e24931b14fdf22304a
+  metadata.gz: 18285c95727f2da714caf8c9ad7d8a99cb7d50bfeb2322045dbc4f4bf4f1b549441d7f0b8e035ab9d708fd820ebc9252260ec17165a90fb36d681f7fecc1e007
+  data.tar.gz: 50b8a13d7f050e099146eba2f1d11f77e123c5fa64923d731d3707ff2f539e70d71a9f6dea790143990fa47e05b801e8501cd5d3ca0b51f4291e07368e15ab7a

data/lib/google/gax.rb

@@ -36,6 +36,8 @@ require 'google/gax/version'
 
 module Google
   module Gax
+    # rubocop:disable Metrics/ParameterLists
+
     # Encapsulates the call settings for an ApiCallable
     # @!attribute [r] timeout
     #   @return [Numeric]
@@ -43,29 +45,34 @@ module Google
     #   @return [RetryOptions]
     # @!attribute [r] page_descriptor
     #   @return [PageDescriptor]
+    # @!attribute [r] page_token
+    #   @return [Object]
     # @!attribute [r] bundle_descriptor
     #   @return [BundleDescriptor]
     class CallSettings
-      attr_reader :timeout, :retry_options, :page_descriptor, :bundler,
-                  :bundle_descriptor
+      attr_reader :timeout, :retry_options, :page_descriptor, :page_token,
+                  :bundler, :bundle_descriptor
 
       # @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 None, this call will not retry.
+      #   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 None, page streaming is not
+      #   streaming to be performed. If set to nil, page streaming is not
       #   performed.
-      # @param bundler orchestrates bundling. If None, bundling is not
+      # @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 None, bundling is not performed.
-      def initialize(
-          timeout: 30, retry_options: nil, page_descriptor: nil,
-          bundler: nil, bundle_descriptor: nil)
+      #   the bundle. If nil, bundling is not performed.
+      def initialize(timeout: 30, retry_options: nil, page_descriptor: nil,
+                     page_token: nil, bundler: nil, bundle_descriptor: nil)
         @timeout = timeout
         @retry_options = retry_options
         @page_descriptor = page_descriptor
+        @page_token = page_token
         @bundler = bundler
         @bundle_descriptor = bundle_descriptor
       end
@@ -86,12 +93,12 @@ module Google
       # @return a new merged call settings.
       def merge(options)
         unless options
-          return CallSettings.new(
-            timeout: @timeout,
-            retry_options: @retry_options,
-            page_descriptor: @page_descriptor,
-            bundler: @bundler,
-            bundle_descriptor: @bundle_descriptor)
+          return CallSettings.new(timeout: @timeout,
+                                  retry_options: @retry_options,
+                                  page_descriptor: @page_descriptor,
+                                  page_token: @page_token,
+                                  bundler: @bundler,
+                                  bundle_descriptor: @bundle_descriptor)
         end
 
         timeout = if options.timeout == :OPTION_INHERIT
@@ -104,14 +111,18 @@ module Google
                         else
                           options.retry_options
                         end
-        page_descriptor = @page_descriptor if options.is_page_streaming
+        page_token = if options.page_token == :OPTION_INHERIT
+                       @page_token
+                     else
+                       options.page_token
+                     end
 
-        CallSettings.new(
-          timeout: timeout,
-          retry_options: retry_options,
-          page_descriptor: page_descriptor,
-          bundler: @bundler,
-          bundle_descriptor: @bundle_descriptor)
+        CallSettings.new(timeout: timeout,
+                         retry_options: retry_options,
+                         page_descriptor: @page_descriptor,
+                         page_token: page_token,
+                         bundler: @bundler,
+                         bundle_descriptor: @bundle_descriptor)
       end
     end
 
@@ -120,34 +131,32 @@ module Google
     #   @return [Numeric, :OPTION_INHERIT]
     # @!attribute [r] retry_options
     #   @return [RetryOptions, :OPTION_INHERIT]
-    # @!attribute [r] is_page_streaming
-    #   @return [true, false, :OPTION_INHERIT]
+    # @!attribute [r] page_token
+    #   @return [Object, :OPTION_INHERIT, :INITIAL_PAGE]
     class CallOptions
-      attr_reader :timeout, :retry_options, :is_page_streaming
+      attr_reader :timeout, :retry_options, :page_token
 
       # @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 is_page_streaming [true, false, :OPTION_INHERIT]
+      # @param page_token [Object, :OPTION_INHERIT]
       #   If set and the call is configured for page streaming, page streaming
-      #   is performed.
-      def initialize(
-        timeout: :OPTION_INHERIT,
-        retry_options: :OPTION_INHERIT,
-        is_page_streaming: :OPTION_INHERIT)
+      #   is starting with this page_token.
+      def initialize(timeout: :OPTION_INHERIT,
+                     retry_options: :OPTION_INHERIT,
+                     page_token: :OPTION_INHERIT)
         @timeout = timeout
         @retry_options = retry_options
-        @is_page_streaming = is_page_streaming
+        @page_token = page_token
       end
     end
 
     # Describes the structure of a page-streaming call.
-    class PageDescriptor < Struct.new(
-      :request_page_token_field,
-      :response_page_token_field,
-      :resource_field)
+    class PageDescriptor < Struct.new(:request_page_token_field,
+                                      :response_page_token_field,
+                                      :resource_field)
     end
 
     # Per-call configurable settings for retrying upon transient failure.
@@ -168,7 +177,8 @@ module Google
       :initial_rpc_timeout_millis,
       :rpc_timeout_multiplier,
       :max_rpc_timeout_millis,
-      :total_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
@@ -204,13 +214,12 @@ module Google
     # 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)
+    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
+      #     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
@@ -230,12 +239,11 @@ module Google
     #
     # 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)
+    class BundleOptions < Struct.new(:element_count_threshold,
+                                     :element_count_limit,
+                                     :request_byte_threshold,
+                                     :request_byte_limit,
+                                     :delay_threshold)
       # @!attribute element_count_threshold
       #   @return [Numeric] the bundled request will be sent once the
       #     count of outstanding elements in the repeated field
@@ -265,12 +273,11 @@ module Google
       #   @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: 0)
+      def initialize(element_count_threshold: 0,
+                     element_count_limit: 0,
+                     request_byte_threshold: 0,
+                     request_byte_limit: 0,
+                     delay_threshold: 0)
         super(
           element_count_threshold,
           element_count_limit,

data/lib/google/gax/api_callable.rb

@@ -33,6 +33,7 @@ require 'google/gax/errors'
 require 'google/gax/grpc'
 
 # rubocop:disable Metrics/ModuleLength
+
 module Google
   module Gax
     MILLIS_PER_SECOND = 1000.0
@@ -44,14 +45,37 @@ module Google
     # PagedEnumerable provides the enumerations over the resource data,
     # and also provides the enumerations over the pages themselves.
     #
+    # Example 1: normal iteration over resources.
+    #   paged_enumerable.each { |resource| puts resource }
+    #
+    # Example 2: per-page iteration.
+    #   paged_enumerable.each_page { |page| puts page }
+    #
+    # Example 3: Enumerable over pages.
+    #   pages = paged_enumerable.enum_for(:each_page).to_a
+    #
+    # Example 4: more exact operations over pages.
+    #   while some_condition()
+    #     page = paged_enumerable.page
+    #     do_something(page)
+    #     break if paged_enumerable.next_page?
+    #     paged_enumerable.next_page
+    #   end
+    #
     # @attribute [r] page
     #   @return [Page] The current page object.
+    # @attribute [r] response
+    #   @return [Object] The current response object.
+    # @attribute [r] page_token
+    #   @return [Object] The page token to be used for the next API call.
     class PagedEnumerable
       # A class to represent a page in a PagedEnumerable. This also implements
       # Enumerable, so it can iterate over the resource elements.
       #
       # @attribute [r] response
-      #   @return [Object] The actual response object.
+      #   @return [Object] the actual response object.
+      # @attribute [r] next_page_token
+      #   @return [Object] the page token to be used for the next API call.
       class Page
         include Enumerable
         attr_reader :response
@@ -112,14 +136,17 @@ module Google
       end
 
       # Initiate the streaming with the requests and keywords.
+      # @param page_token [Object]
+      #   The page token for the first page to be streamed, or nil.
       # @param request [Object]
       #   The initial request object.
       # @param kwargs [Hash]
       #   Other keyword arguments to be passed to a_func.
       # @return [PagedEnumerable]
       #   returning self for further uses.
-      def start(request, **kwargs)
+      def start(page_token, request, **kwargs)
         @request = request
+        @request[@request_page_token_field] = page_token if page_token
         @kwargs = kwargs
         @page = @page.dup_with(@func.call(@request, **@kwargs))
         self
@@ -143,9 +170,9 @@ module Google
 
       # Iterate over the pages.
       # @yield [Page] Gives the pages in the stream.
-      # @raise [RuntimeError] if it's not started yet.
+      # @raise [GaxError] if it's not started yet.
       def each_page
-        raise 'not started!' unless started?
+        raise GaxError, 'not started!' unless started?
         yield @page
         loop do
           break unless next_page?
@@ -165,6 +192,14 @@ module Google
         @request[@request_page_token_field] = @page.next_page_token
         @page = @page.dup_with(@func.call(@request, **@kwargs))
       end
+
+      def response
+        @page.response
+      end
+
+      def page_token
+        @page.next_page_token
+      end
     end
 
     # rubocop:disable Metrics/AbcSize
@@ -190,9 +225,9 @@ module Google
     #   e.g, if bundling and page_streaming are both configured
     def create_api_call(func, settings)
       api_call = if settings.retry_codes?
-                   _retryable(func, settings.retry_options)
+                   retryable(func, settings.retry_options)
                  else
-                   _add_timeout_arg(func, settings.timeout)
+                   add_timeout_arg(func, settings.timeout)
                  end
 
       if settings.page_descriptor
@@ -200,18 +235,20 @@ module Google
           raise 'ApiCallable has incompatible settings: ' \
               'bundling and page streaming'
         end
-        return _page_streamable(
+        return page_streamable(
           api_call,
           settings.page_descriptor.request_page_token_field,
           settings.page_descriptor.response_page_token_field,
-          settings.page_descriptor.resource_field)
+          settings.page_descriptor.resource_field,
+          settings.page_token
+        )
       end
       if settings.bundler?
-        return _bundleable(api_call, settings.bundle_descriptor,
-                           settings.bundler)
+        return bundleable(api_call, settings.bundle_descriptor,
+                          settings.bundler)
       end
 
-      _catch_errors(api_call)
+      catch_errors(api_call)
     end
 
     # Updates a_func to wrap exceptions with GaxError
@@ -219,16 +256,12 @@ module Google
     # @param a_func [Proc]
     # @param errors [Array<Exception>] Configures the exceptions to wrap.
     # @return [Proc] A proc that will wrap certain exceptions with GaxError
-    def _catch_errors(a_func, errors: Grpc::API_ERRORS)
+    def catch_errors(a_func, errors: Grpc::API_ERRORS)
       proc do |request, **kwargs|
         begin
           a_func.call(request, **kwargs)
-        rescue => err
-          if errors.any? { |eclass| err.is_a? eclass }
-            raise GaxError.new('RPC failed', cause: err)
-          else
-            raise err
-          end
+        rescue *errors
+          raise GaxError, 'RPC failed'
         end
       end
     end
@@ -248,11 +281,10 @@ module Google
     # @param bundler orchestrates bundling.
     # @return [Proc] A proc takes the API call's request and returns
     #   an Event object.
-    def _bundleable(a_func, desc, bundler)
+    def bundleable(a_func, desc, bundler)
       proc do |request|
-        the_id = bundling.compute_bundle_id(
-          request,
-          desc.request_discriminator_fields)
+        the_id = bundling.compute_bundle_id(request,
+                                            desc.request_discriminator_fields)
         return bundler.schedule(a_func, the_id, desc, request)
       end
     end
@@ -265,17 +297,21 @@ module Google
     # @param response_page_token_field [String] The field of the next
     #   page token in the response.
     # @param resource_field [String] The field to be streamed.
+    # @param page_token [Object] The page_token for the first page to be
+    #   streamed, or nil.
     # @return [Proc] A proc that returns an iterable over the specified field.
-    def _page_streamable(
-      a_func,
-      request_page_token_field,
-      response_page_token_field,
-      resource_field)
+    def page_streamable(a_func,
+                        request_page_token_field,
+                        response_page_token_field,
+                        resource_field,
+                        page_token)
       enumerable = PagedEnumerable.new(a_func,
                                        request_page_token_field,
                                        response_page_token_field,
                                        resource_field)
-      enumerable.method(:start)
+      proc do |request, **kwargs|
+        enumerable.start(page_token, request, **kwargs)
+      end
     end
 
     # rubocop:disable Metrics/MethodLength
@@ -288,7 +324,7 @@ module Google
     #   upon which the proc should retry, and the parameters to the
     #   exponential backoff retry algorithm.
     # @return [Proc] A proc that will retry on exception.
-    def _retryable(a_func, retry_options)
+    def retryable(a_func, retry_options)
       delay_mult = retry_options.backoff_settings.retry_delay_multiplier
       max_delay = (retry_options.backoff_settings.max_retry_delay_millis /
                    MILLIS_PER_SECOND)
@@ -302,32 +338,29 @@ module Google
         delay = retry_options.backoff_settings.initial_retry_delay_millis
         timeout = (retry_options.backoff_settings.initial_rpc_timeout_millis /
                    MILLIS_PER_SECOND)
-        exc = nil
         result = nil
         now = Time.now
         deadline = now + total_timeout
 
-        while now < deadline
+        loop do
           begin
-            exc = nil
-            result = _add_timeout_arg(a_func, timeout).call(request, **kwargs)
+            result = add_timeout_arg(a_func, timeout).call(request, **kwargs)
             break
           rescue => exception
             unless exception.respond_to?(:code) &&
                    retry_options.retry_codes.include?(exception.code)
-              raise RetryError.new('Exception occurred in retry method that ' \
-                                   'was not classified as transient',
-                                   cause: exception)
+              raise RetryError, 'Exception occurred in retry method that ' \
+                'was not classified as transient'
             end
-            exc = RetryError.new('Retry total timeout exceeded with exception',
-                                 cause: exception)
             sleep(rand(delay) / MILLIS_PER_SECOND)
             now = Time.now
             delay = [delay * delay_mult, max_delay].min
             timeout = [timeout * timeout_mult, max_timeout, deadline - now].min
+            if now >= deadline
+              raise RetryError, 'Retry total timeout exceeded with exception'
+            end
           end
         end
-        raise exc unless exc.nil?
         result
       end
     end
@@ -341,16 +374,16 @@ module Google
     # @param timeout [Numeric] to be added to the original proc as it
     #   final positional arg.
     # @return [Proc] the original proc updated to the timeout arg
-    def _add_timeout_arg(a_func, timeout)
+    def add_timeout_arg(a_func, timeout)
       proc do |request, **kwargs|
         kwargs[:timeout] = timeout
         a_func.call(request, **kwargs)
       end
     end
 
-    module_function :create_api_call, :_catch_errors, :_bundleable,
-                    :_page_streamable, :_retryable, :_add_timeout_arg
-    private_class_method :_catch_errors, :_bundleable, :_page_streamable,
-                         :_retryable, :_add_timeout_arg
+    module_function :create_api_call, :catch_errors, :bundleable,
+                    :page_streamable, :retryable, :add_timeout_arg
+    private_class_method :catch_errors, :bundleable, :page_streamable,
+                         :retryable, :add_timeout_arg
   end
 end

data/lib/google/gax/errors.rb

@@ -27,20 +27,26 @@
 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+require 'English'
+
 module Google
   module Gax
     # Common base class for exceptions raised by GAX.
     class GaxError < StandardError
-      attr_reader :cause
-
       # @param msg [String] describes the error that occurred.
-      # @param cause [Error] the exception raised by a lower layer of
-      #   the RPC stack (for example, gRPC) that caused this
-      #   exception, or None if this exception originated in GAX.
-      def initialize(msg, cause:nil)
-        msg = "GaxError #{msg}, caused by #{cause}" if cause
+      def initialize(msg)
+        msg = "GaxError #{msg}"
+        msg += ", caused by #{$ERROR_INFO}" if $ERROR_INFO
         super(msg)
-        @cause = cause
+        @cause = $ERROR_INFO
+      end
+
+      # cause is a new method introduced in 2.1.0, bring this
+      # method if it does not exist.
+      unless respond_to?(:cause)
+        define_method(:cause) do
+          @cause
+        end
       end
     end
 

data/lib/google/gax/grpc.rb

@@ -34,9 +34,11 @@ module Google
   module Gax
     # Grpc adapts the gRPC surface
     module Grpc
-      STATUS_CODE_NAMES = GRPC::Core::StatusCodes.constants.map do |sym|
-        [sym.to_s, GRPC::Core::StatusCodes.const_get(sym)]
-      end.to_h.freeze
+      STATUS_CODE_NAMES = Hash[
+        GRPC::Core::StatusCodes.constants.map do |sym|
+          [sym.to_s, GRPC::Core::StatusCodes.const_get(sym)]
+        end
+      ].freeze
 
       API_ERRORS = [GRPC::BadStatus, GRPC::Cancelled].freeze
 
@@ -48,20 +50,21 @@ module Google
       #
       # @param port [Fixnum] The port on which to connect to the remote host.
       #
-      # @param chan_creds [Object] A ClientCredentials object for use with an
-      #    SSL-enabled Channel. If none, credentials are pulled from a default
-      #    location.
+      # @param chan_creds [Grpc::Core::ChannelCredentials]
+      #   A ChannelCredentials object for use with an SSL-enabled Channel.
+      #   If nil, credentials are pulled from a default location.
       #
-      # @param channel [Object] A Channel object through which to make calls. If
-      #    none, a secure channel is constructed.
+      # @param channel [Object]
+      #   A Channel object through which to make calls. If nil, a secure
+      #   channel is constructed.
       #
       # @param updater_proc [Proc]
-      #    A function that transforms the metadata for requests, e.g., to give
-      #    OAuth credentials.
+      #   A function that transforms the metadata for requests, e.g., to give
+      #   OAuth credentials.
       #
       # @param scopes [Array<String>]
-      #    The OAuth scopes for this service. This parameter is ignored if
-      #    a custom metadata_transformer is supplied.
+      #   The OAuth scopes for this service. This parameter is ignored if
+      #   a custom metadata_transformer is supplied.
       #
       # @yield [address, creds]
       #   the generated gRPC method to create a stub.

data/lib/google/gax/path_template.rb

@@ -216,7 +216,8 @@ module Google
               i += size
             elsif segment.literal != that[i]
               throw ArgumentError.new(
-                "mismatched literal: '#{segment.literal}' != '#{that[i]}'")
+                "mismatched literal: '#{segment.literal}' != '#{that[i]}'"
+              )
             else
               i += 1
             end
@@ -226,7 +227,8 @@ module Google
         end
         if i != that.size || i != segment_count
           throw ArgumentError.new(
-            "match error: could not instantiate a path template from #{path}")
+            "match error: could not instantiate a path template from #{path}"
+          )
         end
         bindings
       end

data/lib/google/gax/settings.rb

@@ -31,32 +31,23 @@ module Google
   module Gax
     # Helper for #construct_settings
     #
-    # @param method_config A dictionary representing a single
-    #   ``methods`` entry of the standard API client config file. (See
-    #   #construct_settings for information on this yaml.)
-    # @param method_retry_override [BundleOptions, :OPTION_INHERIT, nil]
-    #   If set to :OPTION_INHERIT, the retry settings are derived from
-    #   method config. Otherwise, this parameter overrides
-    #   +method_config+.
-
+    # @param bundle_config A Hash specifying a bundle parameters, the value for
+    #   'bundling' field in a method config (See ``construct_settings()`` for
+    #   information on this config.)
     # @param bundle_descriptor [BundleDescriptor] A BundleDescriptor
     #   object describing the structure of bundling for this
     #   method. If not set, this method will not bundle.
     # @return An Executor that configures bundling, or nil if this
     #   method should not bundle.
-    def _construct_bundling(method_config, method_bundling_override,
-                            bundle_descriptor)
-      if method_config.key?('bundling') && bundle_descriptor
-        if method_bundling_override == :OPTION_INHERIT
-          options = BundleOptions.new
-          method_config['bundling'].each_pair do |key, value|
-            options[key.intern] = value
-          end
-          # TODO: comment-out when bundling is supported.
-          # Executor.new(options)
-        elsif method_bundling_override
-          # Executor.new(method_bundling_override)
+    def construct_bundling(bundle_config, bundle_descriptor)
+      if bundle_config && bundle_descriptor
+        options = BundleOptions.new
+        bundle_config.each_pair do |key, value|
+          options[key.intern] = value
         end
+        # TODO: comment-out when bundling is supported.
+        # Executor.new(options)
+        nil
       end
     end
 
@@ -65,11 +56,7 @@ module Google
     # @param method_config [Hash] A dictionary representing a single
     #   +methods+ entry of the standard API client config file. (See
     #   #construct_settings for information on this yaml.)
-    # @param method_retry_override [RetryOptions, :OPTION_INHERIT, nil]
-    #   If set to :OPTION_INHERIT, the retry settings are derived from
-    #     method config. Otherwise, this parameter overrides
-    #     +method_config+.
-    # @param retry_codes_def [Hash] A dictionary parsed from the
+    # @param retry_codes [Hash] A dictionary parsed from the
     #   +retry_codes_def+ entry of the standard API client config
     #   file. (See #construct_settings for information on this yaml.)
     # @param retry_params [Hash] A dictionary parsed from the
@@ -79,28 +66,55 @@ module Google
     #   used in the standard API client config file to API response
     #   status codes.
     # @return [RetryOptions, nil]
-    def _construct_retry(method_config, method_retry_override, retry_codes,
-                         retry_params, retry_names)
-      unless method_retry_override == :OPTION_INHERIT
-        return method_retry_override
-      end
-
-      retry_codes ||= {}
-      retry_codes_name = method_config['retry_codes_name']
-      codes = retry_codes.fetch(retry_codes_name, []).map do |name|
-        retry_names[name]
+    def construct_retry(method_config, retry_codes, retry_params, retry_names)
+      return nil unless method_config
+      codes = nil
+      if retry_codes && method_config.key?('retry_codes_name')
+        retry_codes_name = method_config['retry_codes_name']
+        codes = retry_codes.fetch(retry_codes_name, []).map do |name|
+          retry_names[name]
+        end
       end
 
+      backoff_settings = nil
       if retry_params && method_config.key?('retry_params_name')
         params = retry_params[method_config['retry_params_name']]
         backoff_settings = BackoffSettings.new(
-          *params.values_at(*BackoffSettings.members.map(&:to_s)))
+          *params.values_at(*BackoffSettings.members.map(&:to_s))
+        )
       end
 
       RetryOptions.new(codes, backoff_settings)
     end
 
-    def _upper_camel_to_lower_underscore(string)
+    # Helper for #construct_settings.
+    #
+    # Takes two retry options, and merges them into a single RetryOption
+    # instance.
+    #
+    # @param retry_options [RetryOptions] The base RetryOptions.
+    # @param overrides [RetryOptions] The RetryOptions used for overriding
+    #   +retry+. Use the values if it is not nil. If entire
+    #   +overrides+ is nli, ignore the base retry and return nil.
+    # @return [RetryOptions, nil]
+    def merge_retry_options(retry_options, overrides)
+      return nil if overrides.nil?
+
+      if overrides.retry_codes.nil? && overrides.backoff_settings.nil?
+        return retry_options
+      end
+
+      codes = retry_options.retry_codes
+      codes = overrides.retry_codes unless overrides.retry_codes.nil?
+      backoff_settings = retry_options.backoff_settings
+      unless overrides.backoff_settings.nil?
+        backoff_settings = overrides.backoff_settings
+      end
+
+      RetryOptions.new(codes, backoff_settings)
+    end
+
+    def upper_camel_to_lower_underscore(string)
       string.scan(/[[:upper:]][^[:upper:]]*/).map(&:downcase).join('_')
     end
 
@@ -154,12 +168,10 @@ module Google
     #   service, used as a key into the client config file (in the
     #   example above, this value should be
     #   'google.fake.v1.ServiceName').
-    # @param client_config [Hash] A dictionary parsed from the
-    #     standard API client config file.
-    # @param bundling_override [Hash] A dictionary of method names to
-    #   BundleOptions override those specified in +client_config+.
-    # @param retry_override [Hash] A dictionary of method names to
-    #   RetryOptions that override those specified in +client_config+.
+    # @param client_config [Hash] A hash parsed from the standard
+    #   API client config file.
+    # @param config_overrides [Hash] A hash in the same structure of
+    #   client_config to override the settings.
     # @param retry_names [Hash] A dictionary mapping the strings
     #   referring to response status codes to the Python objects
     #   representing those codes.
@@ -173,41 +185,55 @@ module Google
     #   methods that are page streaming-enabled.
     # @return [CallSettings, nil] A CallSettings, or nil if the
     #   service is not found in the config.
-    def construct_settings(
-        service_name, client_config, bundling_override, retry_override,
-        retry_names, timeout, bundle_descriptors: {}, page_descriptors: {})
+    def construct_settings(service_name, client_config, config_overrides,
+                           retry_names, timeout, bundle_descriptors: {},
+                           page_descriptors: {})
       defaults = {}
 
       service_config = client_config.fetch('interfaces', {})[service_name]
       return nil unless service_config
 
+      overrides = config_overrides.fetch('interfaces', {})[service_name] || {}
+
       service_config['methods'].each_pair do |method_name, method_config|
-        snake_name = _upper_camel_to_lower_underscore(method_name)
+        snake_name = upper_camel_to_lower_underscore(method_name)
 
+        overriding_method =
+          overrides.fetch('methods', {}).fetch(method_name, {})
+
+        bundling_config = method_config.fetch('bundling', nil)
+        if overriding_method && overriding_method.key?('bundling')
+          bundling_config = overriding_method['bundling']
+        end
         bundle_descriptor = bundle_descriptors[snake_name]
 
         defaults[snake_name] = CallSettings.new(
           timeout: timeout,
-          retry_options: _construct_retry(
-            method_config,
-            retry_override.fetch(snake_name, :OPTION_INHERIT),
-            service_config['retry_codes'],
-            service_config['retry_params'],
-            retry_names),
+          retry_options: merge_retry_options(
+            construct_retry(method_config,
+                            service_config['retry_codes'],
+                            service_config['retry_params'],
+                            retry_names),
+            construct_retry(overriding_method,
+                            overrides['retry_codes'],
+                            overrides['retry_params'],
+                            retry_names)
+          ),
           page_descriptor: page_descriptors[snake_name],
-          bundler: _construct_bundling(
-            method_config,
-            bundling_override.fetch(snake_name, :OPTION_INHERIT),
-            bundle_descriptor),
-          bundle_descriptor: bundle_descriptor)
+          bundler: construct_bundling(bundling_config,
+                                      bundle_descriptor),
+          bundle_descriptor: bundle_descriptor
+        )
       end
 
       defaults
     end
 
-    module_function :construct_settings, :_construct_bundling,
-                    :_construct_retry, :_upper_camel_to_lower_underscore
-    private_class_method :_construct_bundling, :_construct_retry,
-                         :_upper_camel_to_lower_underscore
+    module_function :construct_settings, :construct_bundling,
+                    :construct_retry, :upper_camel_to_lower_underscore,
+                    :merge_retry_options
+    private_class_method :construct_bundling, :construct_retry,
+                         :upper_camel_to_lower_underscore,
+                         :merge_retry_options
   end
 end

data/lib/google/gax/version.rb

@@ -29,6 +29,6 @@
 
 module Google
   module Gax
-    VERSION = '0.1.3'.freeze
+    VERSION = '0.3.0'.freeze
   end
 end

data/spec/google/gax/api_callable_spec.rb

@@ -63,8 +63,8 @@ describe Google::Gax do
     page_size = 3
     pages_to_stream = 5
 
-    page_descriptor = Google::Gax::PageDescriptor.new(
-      'page_token', 'next_page_token', 'nums')
+    page_descriptor = Google::Gax::PageDescriptor.new('page_token',
+                                                      'next_page_token', 'nums')
     settings = CallSettings.new(page_descriptor: page_descriptor)
     timeout_arg = nil
     func = proc do |request, timeout: nil|
@@ -82,8 +82,9 @@ describe Google::Gax do
 
     it 'iterates over elements' do
       my_callable = Google::Gax.create_api_call(func, settings)
-      expect(my_callable.call('page_token' => 0).to_a).to eq(
-        (0...(page_size * pages_to_stream)).to_a)
+      expect(my_callable.call('page_token' => 0).to_a).to match_array(
+        (0...(page_size * pages_to_stream))
+      )
       expect(timeout_arg).to_not be_nil
     end
 
@@ -99,14 +100,59 @@ describe Google::Gax do
       stream = my_callable.call('page_token' => 0)
       expect(stream.enum_for(:each_page).to_a.size).to eq(pages_to_stream + 1)
     end
+
+    it 'starts from the specified page_token' do
+      my_settings = settings.merge(Google::Gax::CallOptions.new(page_token: 3))
+      my_callable = Google::Gax.create_api_call(func, my_settings)
+      expect(my_callable.call({}).to_a).to match_array(
+        3...(page_size * pages_to_stream)
+      )
+    end
+  end
+
+  describe 'failures without retry' do
+    it 'simply fails' do
+      settings = CallSettings.new
+      timeout_arg = nil
+      call_count = 0
+      func = proc do |timeout: nil|
+        timeout_arg = timeout
+        call_count += 1
+        raise GRPC::Cancelled, ''
+      end
+      my_callable = Google::Gax.create_api_call(func, settings)
+      begin
+        my_callable.call
+        expect(true).to be false # should not reach to this line.
+      rescue Google::Gax::GaxError => exc
+        expect(exc.cause).to be_a(GRPC::Cancelled)
+      end
+      expect(timeout_arg).to_not be_nil
+      expect(call_count).to eq(1)
+    end
+
+    it 'does not wrap unknown errors' do
+      settings = CallSettings.new
+      timeout_arg = nil
+      call_count = 0
+      func = proc do |timeout: nil|
+        timeout_arg = timeout
+        call_count += 1
+        raise CustomException.new('', FAKE_STATUS_CODE_1)
+      end
+      my_callable = Google::Gax.create_api_call(func, settings)
+      expect { my_callable.call }.to raise_error(CustomException)
+      expect(timeout_arg).to_not be_nil
+      expect(call_count).to eq(1)
+    end
   end
 
   describe 'retryable' do
     RetryOptions = Google::Gax::RetryOptions
     BackoffSettings = Google::Gax::BackoffSettings
 
-    retry_options = RetryOptions.new(
-      [FAKE_STATUS_CODE_1], BackoffSettings.new(0, 0, 0, 0, 0, 0, 1))
+    retry_options = RetryOptions.new([FAKE_STATUS_CODE_1],
+                                     BackoffSettings.new(0, 0, 0, 0, 0, 0, 1))
     settings = CallSettings.new(timeout: 0, retry_options: retry_options)
 
     it 'retries the API call' do
@@ -138,7 +184,8 @@ describe Google::Gax do
         raise CustomException.new('', FAKE_STATUS_CODE_1)
       end
       my_callable = Google::Gax.create_api_call(
-        func, CallSettings.new(timeout: 0, retry_options: retry_options))
+        func, CallSettings.new(timeout: 0, retry_options: retry_options)
+      )
       expect { my_callable.call }.to raise_error(Google::Gax::RetryError)
       expect(call_count).to eq(1)
     end
@@ -160,7 +207,8 @@ describe Google::Gax do
 
       time_now = Time.now
       allow(Time).to receive(:now).exactly(4).times.and_return(
-        *([time_now] * to_attempt + [time_now + 2]))
+        *([time_now] * to_attempt + [time_now + 2])
+      )
 
       func = proc do
         call_count += 1
@@ -170,7 +218,7 @@ describe Google::Gax do
       my_callable = Google::Gax.create_api_call(func, settings)
       begin
         my_callable.call
-        except(true).to be false # should not reach to this line.
+        expect(true).to be false # should not reach to this line.
       rescue Google::Gax::RetryError => exc
         expect(exc.cause).to be_a(CustomException)
       end
@@ -210,7 +258,8 @@ describe Google::Gax do
       backoff = BackoffSettings.new(3, 2, 24, 5, 2, 80, 2500)
       retry_options = RetryOptions.new([FAKE_STATUS_CODE_1], backoff)
       my_callable = Google::Gax.create_api_call(
-        func, CallSettings.new(timeout: 0, retry_options: retry_options))
+        func, CallSettings.new(timeout: 0, retry_options: retry_options)
+      )
 
       begin
         my_callable.call(0)

data/spec/google/gax/path_template_spec.rb

@@ -69,7 +69,8 @@ describe Google::Gax::PathTemplate do
       template = PathTemplate.new('hello/world')
       expect { template.match('hello') }.to raise_error(ArgumentError)
       expect { template.match('hello/world/fail') }.to raise_error(
-        ArgumentError)
+        ArgumentError
+      )
     end
 
     it 'should fail on mismatched literal' do

data/spec/google/gax/settings_spec.rb

@@ -71,7 +71,8 @@ A_CONFIG = {
 
 PAGE_DESCRIPTORS = {
   'page_streaming_method' => Google::Gax::PageDescriptor.new(
-    'page_token', 'next_page_token', 'page_streams')
+    'page_token', 'next_page_token', 'page_streams'
+  )
 }.freeze
 
 BUNDLE_DESCRIPTORS = {
@@ -87,9 +88,10 @@ RETRY_DICT = {
 describe Google::Gax do
   it 'creates settings' do
     defaults = Google::Gax.construct_settings(
-      SERVICE_NAME, A_CONFIG, {}, {}, RETRY_DICT, 30,
+      SERVICE_NAME, A_CONFIG, {}, RETRY_DICT, 30,
       bundle_descriptors: BUNDLE_DESCRIPTORS,
-      page_descriptors: PAGE_DESCRIPTORS)
+      page_descriptors: PAGE_DESCRIPTORS
+    )
     settings = defaults['bundling_method']
     expect(settings.timeout).to be(30)
     # TODO: uncomment this when bundling is added.
@@ -99,7 +101,8 @@ describe Google::Gax do
     expect(settings.retry_options).to be_a(Google::Gax::RetryOptions)
     expect(settings.retry_options.retry_codes).to be_a(Array)
     expect(settings.retry_options.backoff_settings).to be_a(
-      Google::Gax::BackoffSettings)
+      Google::Gax::BackoffSettings
+    )
 
     settings = defaults['page_streaming_method']
     expect(settings.timeout).to be(30)
@@ -109,17 +112,28 @@ describe Google::Gax do
     expect(settings.retry_options).to be_a(Google::Gax::RetryOptions)
     expect(settings.retry_options.retry_codes).to be_a(Array)
     expect(settings.retry_options.backoff_settings).to be_a(
-      Google::Gax::BackoffSettings)
+      Google::Gax::BackoffSettings
+    )
   end
 
   it 'overrides settings' do
-    bundling_override = { 'bundling_method' => nil }
-    retry_override = { 'page_streaming_method' => nil }
+    overrides = {
+      'interfaces' => {
+        SERVICE_NAME => {
+          'methods' => {
+            'PageStreamingMethod' => nil,
+            'BundlingMethod' => {
+              'bundling' => nil
+            }
+          }
+        }
+      }
+    }
     defaults = Google::Gax.construct_settings(
-      SERVICE_NAME, A_CONFIG, bundling_override, retry_override,
-      RETRY_DICT, 30,
+      SERVICE_NAME, A_CONFIG, overrides, RETRY_DICT, 30,
       bundle_descriptors: BUNDLE_DESCRIPTORS,
-      page_descriptors: PAGE_DESCRIPTORS)
+      page_descriptors: PAGE_DESCRIPTORS
+    )
 
     settings = defaults['bundling_method']
     expect(settings.timeout).to be(30)
@@ -131,4 +145,60 @@ describe Google::Gax do
     expect(settings.page_descriptor).to be_a(Google::Gax::PageDescriptor)
     expect(settings.retry_options).to be_nil
   end
+
+  it 'overrides settings more precisely' do
+    override = {
+      'interfaces' => {
+        SERVICE_NAME => {
+          'retry_codes' => {
+            'bar_retry' => [],
+            'baz_retry' => ['code_a']
+          },
+          'retry_params' => {
+            'default' => {
+              'initial_retry_delay_millis' => 1000,
+              'retry_delay_multiplier' => 1.2,
+              'max_retry_delay_millis' => 10_000,
+              'initial_rpc_timeout_millis' => 3000,
+              'rpc_timeout_multiplier' => 1.3,
+              'max_rpc_timeout_millis' => 30_000,
+              'total_timeout_millis' => 300_000
+            }
+          },
+          'methods' => {
+            'BundlingMethod' => {
+              'retry_params_name' => 'default',
+              'retry_codes_name' => 'baz_retry'
+            }
+          }
+        }
+      }
+    }
+    defaults = Google::Gax.construct_settings(
+      SERVICE_NAME, A_CONFIG, override, RETRY_DICT, 30,
+      bundle_descriptors: BUNDLE_DESCRIPTORS,
+      page_descriptors: PAGE_DESCRIPTORS
+    )
+
+    settings = defaults['bundling_method']
+    backoff = settings.retry_options.backoff_settings
+    expect(backoff.initial_retry_delay_millis).to be(1000)
+    expect(settings.retry_options.retry_codes).to match_array(
+      [RETRY_DICT['code_a']]
+    )
+    expect(settings.bundler).to be(nil)
+    expect(settings.bundle_descriptor).to be_a(Google::Gax::BundleDescriptor)
+
+    # page_streaming_method is unaffected because it's not specified in
+    # overrides. 'bar_retry' or 'default' definitions in overrides should
+    # not affect the methods which are not in the overrides.
+    settings = defaults['page_streaming_method']
+    backoff = settings.retry_options.backoff_settings
+    expect(backoff.initial_retry_delay_millis).to be(100)
+    expect(backoff.retry_delay_multiplier).to be(1.2)
+    expect(backoff.max_retry_delay_millis).to be(1000)
+    expect(settings.retry_options.retry_codes).to match_array(
+      [RETRY_DICT['code_c']]
+    )
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-gax
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.3.0
 platform: ruby
 authors:
 - Google API Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-05-04 00:00:00.000000000 Z
+date: 2016-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: googleauth
@@ -52,20 +52,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.2.3
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.9'
 - !ruby/object:Gem::Dependency
   name: codecov
   requirement: !ruby/object:Gem::Requirement
@@ -167,7 +153,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="