google-gax 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: df878307196d3628c155d4de6d3b333524b93937
-  data.tar.gz: bd5b46d05109352ad29de368998e36efe1bfcd8d
+  metadata.gz: f00dba40d04710327a4348f2b0919f423b81ab3d
+  data.tar.gz: 16ebb311b89300f865849238f840acedd3aec149
 SHA512:
-  metadata.gz: 18285c95727f2da714caf8c9ad7d8a99cb7d50bfeb2322045dbc4f4bf4f1b549441d7f0b8e035ab9d708fd820ebc9252260ec17165a90fb36d681f7fecc1e007
-  data.tar.gz: 50b8a13d7f050e099146eba2f1d11f77e123c5fa64923d731d3707ff2f539e70d71a9f6dea790143990fa47e05b801e8501cd5d3ca0b51f4291e07368e15ab7a
+  metadata.gz: 128e33ba96e202d5abf7b941d922737fc56115cd3c4d82b9fe3b331beb7639704f9ac1e86980f64757c2169b0fdee8e9668b985d8a81cb2f9c4aee46c3eb1255
+  data.tar.gz: 234a0c126f754c7db3690f53aeda09a689143cc52e141d787b3cd17259c7bc0db371cca13544a85253a450ed11178a45e8b05c0c06c3c342f84ceabacab465f9

data/lib/google/gax.rb

@@ -49,9 +49,11 @@ module Google
     #   @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
+                  :bundler, :bundle_descriptor, :kwargs, :errors
 
       # @param timeout [Numeric] The client-side timeout for API calls. This
       #   parameter is ignored for retrying calls.
@@ -67,14 +69,21 @@ module Google
       #   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)
+                     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.
@@ -98,7 +107,9 @@ module Google
                                   page_descriptor: @page_descriptor,
                                   page_token: @page_token,
                                   bundler: @bundler,
-                                  bundle_descriptor: @bundle_descriptor)
+                                  bundle_descriptor: @bundle_descriptor,
+                                  kwargs: @kwargs,
+                                  errors: @errors)
         end
 
         timeout = if options.timeout == :OPTION_INHERIT
@@ -117,12 +128,17 @@ module Google
                        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)
+                         bundle_descriptor: @bundle_descriptor,
+                         kwargs: kwargs,
+                         errors: @errors)
       end
     end
 
@@ -133,8 +149,10 @@ module Google
     #   @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
+      attr_reader :timeout, :retry_options, :page_token, :kwargs
 
       # @param timeout [Numeric, :OPTION_INHERIT]
       #   The client-side timeout for API calls.
@@ -144,12 +162,16 @@ module Google
       # @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)
+                     page_token: :OPTION_INHERIT,
+                     kwargs: :OPTION_INHERIT)
         @timeout = timeout
         @retry_options = retry_options
         @page_token = page_token
+        @kwargs = kwargs
       end
     end
 
@@ -243,7 +265,7 @@ module Google
                                      :element_count_limit,
                                      :request_byte_threshold,
                                      :request_byte_limit,
-                                     :delay_threshold)
+                                     :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
@@ -269,7 +291,7 @@ module Google
       #     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
+      # @!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.
@@ -277,13 +299,13 @@ module Google
                      element_count_limit: 0,
                      request_byte_threshold: 0,
                      request_byte_limit: 0,
-                     delay_threshold: 0)
+                     delay_threshold_millis: 0)
         super(
           element_count_threshold,
           element_count_limit,
           request_byte_threshold,
           request_byte_limit,
-          delay_threshold)
+          delay_threshold_millis)
       end
     end
   end

data/lib/google/gax/api_callable.rb

@@ -30,7 +30,6 @@
 require 'time'
 
 require 'google/gax/errors'
-require 'google/gax/grpc'
 
 # rubocop:disable Metrics/ModuleLength
 
@@ -45,16 +44,16 @@ 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.
+    # @example normal iteration over resources.
     #   paged_enumerable.each { |resource| puts resource }
     #
-    # Example 2: per-page iteration.
+    # @example per-page iteration.
     #   paged_enumerable.each_page { |page| puts page }
     #
-    # Example 3: Enumerable over pages.
+    # @example Enumerable over pages.
     #   pages = paged_enumerable.enum_for(:each_page).to_a
     #
-    # Example 4: more exact operations over pages.
+    # @example more exact operations over pages.
     #   while some_condition()
     #     page = paged_enumerable.page
     #     do_something(page)
@@ -120,35 +119,33 @@ module Google
       include Enumerable
       attr_reader :page
 
-      # @param a_func [Proc]
-      #   A proc to update the response object.
       # @param request_page_token_field [String]
       #   The name of the field in request which will have the page token.
       # @param response_page_token_field [String]
       #   The name of the field in the response which holds the next page token.
       # @param resource_field [String]
       #   The name of the field in the response which holds the resources.
-      def initialize(a_func, request_page_token_field,
+      def initialize(request_page_token_field,
                      response_page_token_field, resource_field)
-        @func = a_func
         @request_page_token_field = request_page_token_field
         @page = Page.new(nil, response_page_token_field, resource_field)
       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 api_call [Proc]
+      #   A proc to update the response object.
       # @param request [Object]
       #   The initial request object.
-      # @param kwargs [Hash]
-      #   Other keyword arguments to be passed to a_func.
+      # @param settings [CallSettings]
+      #   The call settings to enumerate pages.
       # @return [PagedEnumerable]
       #   returning self for further uses.
-      def start(page_token, request, **kwargs)
+      def start(api_call, request, settings)
+        @func = api_call
         @request = request
+        page_token = settings.page_token
         @request[@request_page_token_field] = page_token if page_token
-        @kwargs = kwargs
-        @page = @page.dup_with(@func.call(@request, **@kwargs))
+        @page = @page.dup_with(@func.call(@request))
         self
       end
 
@@ -190,7 +187,7 @@ module Google
       def next_page
         return unless next_page?
         @request[@request_page_token_field] = @page.next_page_token
-        @page = @page.dup_with(@func.call(@request, **@kwargs))
+        @page = @page.dup_with(@func.call(@request))
       end
 
       def response
@@ -219,47 +216,51 @@ module Google
     # does the signature change.
     #
     # @param func [Proc] used to make a bare rpc call
-    # @param settings [CallSettings provides the settings for this call
+    # @param settings [CallSettings] provides the settings for this call
     # @return [Proc] a bound method on a request stub used to make an rpc call
     # @raise [StandardError] if +settings+ has incompatible values,
     #   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)
-                 else
-                   add_timeout_arg(func, settings.timeout)
-                 end
+      api_caller = proc do |api_call, request|
+        api_call.call(request)
+      end
 
       if settings.page_descriptor
         if settings.bundler?
           raise 'ApiCallable has incompatible settings: ' \
               'bundling and page streaming'
         end
-        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_token
-        )
-      end
-      if settings.bundler?
-        return bundleable(api_call, settings.bundle_descriptor,
-                          settings.bundler)
+        page_descriptor = settings.page_descriptor
+        api_caller = page_streamable(page_descriptor.request_page_token_field,
+                                     page_descriptor.response_page_token_field,
+                                     page_descriptor.resource_field)
+      elsif settings.bundler?
+        api_caller = bundleable(settings.bundle_descriptor)
       end
 
-      catch_errors(api_call)
+      proc do |request, options = nil|
+        this_settings = settings.merge(options)
+        api_call = if settings.retry_codes?
+                     retryable(func, this_settings.retry_options,
+                               this_settings.kwargs)
+                   else
+                     add_timeout_arg(func, this_settings.timeout,
+                                     this_settings.kwargs)
+                   end
+        api_call = catch_errors(api_call, settings.errors)
+        api_caller.call(api_call, request, this_settings)
+      end
     end
 
     # Updates a_func to wrap exceptions with GaxError
     #
     # @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)
-      proc do |request, **kwargs|
+    # @return [Proc] A proc that will wrap certain exceptions with GaxError.
+    def catch_errors(a_func, errors)
+      proc do |request|
         begin
-          a_func.call(request, **kwargs)
+          a_func.call(request)
         rescue *errors
           raise GaxError, 'RPC failed'
         end
@@ -281,11 +282,12 @@ 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)
-      proc do |request|
+    def bundleable(desc)
+      proc do |api_call, request, settings|
+        return api_call(request) unless settings.bundler
         the_id = bundling.compute_bundle_id(request,
                                             desc.request_discriminator_fields)
-        return bundler.schedule(a_func, the_id, desc, request)
+        return bundler.schedule(api_call, the_id, desc, request)
       end
     end
 
@@ -300,18 +302,13 @@ module Google
     # @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,
+    def page_streamable(request_page_token_field,
                         response_page_token_field,
-                        resource_field,
-                        page_token)
-      enumerable = PagedEnumerable.new(a_func,
-                                       request_page_token_field,
+                        resource_field)
+      enumerable = PagedEnumerable.new(request_page_token_field,
                                        response_page_token_field,
                                        resource_field)
-      proc do |request, **kwargs|
-        enumerable.start(page_token, request, **kwargs)
-      end
+      enumerable.method(:start)
     end
 
     # rubocop:disable Metrics/MethodLength
@@ -324,7 +321,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, kwargs)
       delay_mult = retry_options.backoff_settings.retry_delay_multiplier
       max_delay = (retry_options.backoff_settings.max_retry_delay_millis /
                    MILLIS_PER_SECOND)
@@ -334,7 +331,7 @@ module Google
       total_timeout = (retry_options.backoff_settings.total_timeout_millis /
                        MILLIS_PER_SECOND)
 
-      proc do |request, **kwargs|
+      proc do |request|
         delay = retry_options.backoff_settings.initial_retry_delay_millis
         timeout = (retry_options.backoff_settings.initial_rpc_timeout_millis /
                    MILLIS_PER_SECOND)
@@ -344,7 +341,7 @@ module Google
 
         loop do
           begin
-            result = add_timeout_arg(a_func, timeout).call(request, **kwargs)
+            result = add_timeout_arg(a_func, timeout, kwargs).call(request)
             break
           rescue => exception
             unless exception.respond_to?(:code) &&
@@ -374,8 +371,8 @@ 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)
-      proc do |request, **kwargs|
+    def add_timeout_arg(a_func, timeout, kwargs)
+      proc do |request|
         kwargs[:timeout] = timeout
         a_func.call(request, **kwargs)
       end

data/lib/google/gax/path_template.rb

@@ -80,13 +80,13 @@ module Google
       rule 'bound_segments : bound_segment FORWARD_SLASH bound_segments
                            | bound_segment' do |segs, a_seg, _, more_segs|
         segs.value = a_seg.value
-        segs.value.push(*more_segs.value) unless more_segs.nil?
+        segs.value.concat(more_segs.value) unless more_segs.nil?
       end
 
       rule 'unbound_segments : unbound_terminal FORWARD_SLASH unbound_segments
                              | unbound_terminal' do |segs, a_term, _, more_segs|
         segs.value = a_term.value
-        segs.value.push(*more_segs.value) unless more_segs.nil?
+        segs.value.concat(more_segs.value) unless more_segs.nil?
       end
 
       rule 'bound_segment : bound_terminal
@@ -118,7 +118,7 @@ module Google
                      | LEFT_BRACE LITERAL RIGHT_BRACE' do |variable, *args|
         variable.value = [Segment.new(BINDING, args[1].value)]
         if args.size > 3
-          variable.value.push(*args[3].value)
+          variable.value.concat(args[3].value)
         else
           variable.value.push(Segment.new(TERMINAL, '*'))
           @segment_count += 1
@@ -178,7 +178,7 @@ module Google
               msg = "Value for key #{segment.literal} is not provided"
               raise(ArgumentError, msg)
             end
-            out.push(*PathTemplate.new(bindings[literal_sym]).segments)
+            out.concat(PathTemplate.new(bindings[literal_sym]).segments)
             binding = true
           elsif segment.kind == END_BINDING
             binding = false

data/lib/google/gax/settings.rb

@@ -183,11 +183,15 @@ module Google
     # @param page_descriptors [Hash{String => PageDescriptor}] A
     #   dictionary of method names to PageDescriptor objects for
     #   methods that are page streaming-enabled.
+    # @param kwargs [Hash]
+    #   Additional keyword argments to be passed to the API call.
+    # @param errors [Array<Exception>]
+    #   Configures the exceptions to wrap with GaxError.
     # @return [CallSettings, nil] A CallSettings, or nil if the
     #   service is not found in the config.
     def construct_settings(service_name, client_config, config_overrides,
                            retry_names, timeout, bundle_descriptors: {},
-                           page_descriptors: {})
+                           page_descriptors: {}, kwargs: {}, errors: [])
       defaults = {}
 
       service_config = client_config.fetch('interfaces', {})[service_name]
@@ -220,9 +224,10 @@ module Google
                             retry_names)
           ),
           page_descriptor: page_descriptors[snake_name],
-          bundler: construct_bundling(bundling_config,
-                                      bundle_descriptor),
-          bundle_descriptor: bundle_descriptor
+          bundler: construct_bundling(bundling_config, bundle_descriptor),
+          bundle_descriptor: bundle_descriptor,
+          kwargs: kwargs,
+          errors: errors
         )
       end
 

data/lib/google/gax/version.rb

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

data/spec/google/gax/api_callable_spec.rb

@@ -56,6 +56,11 @@ describe Google::Gax do
       my_callable = Google::Gax.create_api_call(func, settings)
       expect(my_callable.call(nil)).to eq(42)
       expect(timeout_arg).to_not be_nil
+
+      new_timeout = timeout_arg + 20
+      options = Google::Gax::CallOptions.new(timeout: new_timeout)
+      expect(my_callable.call(nil, options)).to eq(42)
+      expect(timeout_arg).to eq(new_timeout)
     end
   end
 
@@ -112,7 +117,7 @@ describe Google::Gax do
 
   describe 'failures without retry' do
     it 'simply fails' do
-      settings = CallSettings.new
+      settings = CallSettings.new(errors: [GRPC::Cancelled])
       timeout_arg = nil
       call_count = 0
       func = proc do |timeout: nil|

data/spec/google/gax/settings_spec.rb

@@ -90,7 +90,9 @@ describe Google::Gax do
     defaults = Google::Gax.construct_settings(
       SERVICE_NAME, A_CONFIG, {}, RETRY_DICT, 30,
       bundle_descriptors: BUNDLE_DESCRIPTORS,
-      page_descriptors: PAGE_DESCRIPTORS
+      page_descriptors: PAGE_DESCRIPTORS,
+      kwargs: { 'key' => 'value' },
+      errors: [StandardError]
     )
     settings = defaults['bundling_method']
     expect(settings.timeout).to be(30)
@@ -103,6 +105,8 @@ describe Google::Gax do
     expect(settings.retry_options.backoff_settings).to be_a(
       Google::Gax::BackoffSettings
     )
+    expect(settings.kwargs).to match('key' => 'value')
+    expect(settings.errors).to match_array([StandardError])
 
     settings = defaults['page_streaming_method']
     expect(settings.timeout).to be(30)
@@ -114,6 +118,8 @@ describe Google::Gax do
     expect(settings.retry_options.backoff_settings).to be_a(
       Google::Gax::BackoffSettings
     )
+    expect(settings.kwargs).to match('key' => 'value')
+    expect(settings.errors).to match_array([StandardError])
   end
 
   it 'overrides settings' do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-gax
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Google API Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-05-31 00:00:00.000000000 Z
+date: 2016-07-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: googleauth
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.13.1
+        version: 0.14.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.13.1
+        version: 0.14.1
 - !ruby/object:Gem::Dependency
   name: rly
   requirement: !ruby/object:Gem::Requirement