google-gax 1.0.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8cd0a10641a7e1420289be043083df9265950f90
-  data.tar.gz: 59814b61241779e9dad2d71dbca9ddaa3f303518
+  metadata.gz: 34fe59f1bfcd32a791b319ddb7ac77d8dadf7922
+  data.tar.gz: 0d77001cd6917bc5fe0b4bc9960b189437b22e0f
 SHA512:
-  metadata.gz: c7f3f07f30bf2382ff4bf38c2a6c2142dc7a72070ccbe14071b9193ebe53ba281b9fac525669179f5dd3fbc845a1b781c7659768d968b549398cbdf2948033ac
-  data.tar.gz: 683d0a62441eabaf25a7c1c87962ffcc86bc8ee5ff3936daa3a8cc78ec20b6c4daadfb5e85d546854676604e8879eb27a4d9f359a327a3b9c9cc2844d7aeafa1
+  metadata.gz: bb35c9359dd55066155c0607a647365a7b75cf0cef86ba7e91dd539542b0437915db0b29c09b00e57a83d48f35161ecfc938e00ea47643c2dbf219c456790742
+  data.tar.gz: 00bb1dcce002d4ee67450a5825bfd02d949583b1909707c5dabed153ddf329d00d89ea364b9ac9953830952c40a7e6f8893e815e3e9b3f35d48ec2c1e94ba996

data/lib/google/gax/api_callable.rb

@@ -136,15 +136,15 @@ module Google
       # @param request [Object]
       #   The initial request object.
       # @param settings [CallSettings]
-      #   The call settings to enumerate pages.
+      #   The call settings to enumerate pages
       # @return [PagedEnumerable]
       #   returning self for further uses.
-      def start(api_call, request, settings)
+      def start(api_call, request, settings, block)
         @func = api_call
         @request = request
         page_token = settings.page_token
         @request[@request_page_token_field] = page_token if page_token
-        @page = @page.dup_with(@func.call(@request))
+        @page = @page.dup_with(@func.call(@request, block))
         self
       end
 
@@ -218,12 +218,16 @@ module Google
     # @param settings [CallSettings] provides the settings for this call
     # @param params_extractor [Proc] extracts routing header params from the
     #   request
+    # @param exception_transformer [Proc] if an API exception occurs this
+    #   transformer is given the original exception for custom processing
+    #   instead of raising the error directly
     # @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, params_extractor: nil)
-      api_caller = proc do |api_call, request|
-        api_call.call(request)
+    def create_api_call(func, settings, params_extractor: nil,
+                        exception_transformer: nil)
+      api_caller = proc do |api_call, request, _settings, block|
+        api_call.call(request, block)
       end
 
       if settings.page_descriptor
@@ -239,7 +243,7 @@ module Google
         api_caller = bundleable(settings.bundle_descriptor)
       end
 
-      proc do |request, options = nil|
+      proc do |request, options = nil, &block|
         this_settings = settings.merge(options)
         if params_extractor
           params = params_extractor.call(request)
@@ -247,16 +251,21 @@ module Google
         end
         api_call = if settings.retry_codes?
                      retryable(func, this_settings.retry_options,
-                               this_settings.kwargs)
+                               this_settings.metadata)
                    else
                      add_timeout_arg(func, this_settings.timeout,
-                                     this_settings.kwargs)
+                                     this_settings.metadata)
                    end
         begin
-          api_caller.call(api_call, request, this_settings)
+          api_caller.call(api_call, request, this_settings, block)
         rescue *settings.errors => e
-          error_class = Google::Gax.from_error e
-          raise error_class.new('RPC failed')
+          error_class = Google::Gax.from_error(e)
+          error = error_class.new('RPC failed')
+          raise error if exception_transformer.nil?
+          exception_transformer.call error
+        rescue StandardError => error
+          raise error if exception_transformer.nil?
+          exception_transformer.call error
         end
       end
     end
@@ -277,8 +286,9 @@ module Google
     # @return [Proc] A proc takes the API call's request and returns
     #   an Event object.
     def bundleable(desc)
-      proc do |api_call, request, settings|
-        return api_call(request) unless settings.bundler
+      proc do |api_call, request, settings, block|
+        return api_call(request, block) unless settings.bundler
+        raise 'Bundling calls cannot accept blocks' if block
         the_id = Google::Gax.compute_bundle_id(
           request,
           desc.request_discriminator_fields
@@ -316,7 +326,7 @@ module Google
     def with_routing_header(settings, params)
       routing_header = params.map { |k, v| "#{k}=#{v}" }.join('&')
       options = CallOptions.new(
-        kwargs: { 'x-goog-request-params' => routing_header }
+        metadata: { 'x-goog-request-params' => routing_header }
       )
       settings.merge(options)
     end
@@ -328,8 +338,9 @@ module Google
     # @param retry_options [RetryOptions] Configures the exceptions
     #   upon which the proc should retry, and the parameters to the
     #   exponential backoff retry algorithm.
+    # @param metadata [Hash] request metadata headers
     # @return [Proc] A proc that will retry on exception.
-    def retryable(a_func, retry_options, kwargs)
+    def retryable(a_func, retry_options, metadata)
       delay_mult = retry_options.backoff_settings.retry_delay_multiplier
       max_delay = (retry_options.backoff_settings.max_retry_delay_millis /
                    MILLIS_PER_SECOND)
@@ -339,13 +350,19 @@ module Google
       total_timeout = (retry_options.backoff_settings.total_timeout_millis /
                        MILLIS_PER_SECOND)
 
-      proc do |request|
+      proc do |request, block|
         delay = retry_options.backoff_settings.initial_retry_delay_millis
         timeout = (retry_options.backoff_settings.initial_rpc_timeout_millis /
                    MILLIS_PER_SECOND)
         deadline = Time.now + total_timeout
         begin
-          a_func.call(request, deadline: Time.now + timeout, metadata: kwargs)
+          op = a_func.call(request,
+                           deadline: Time.now + timeout,
+                           metadata: metadata,
+                           return_op: true)
+          res = op.execute
+          block.call res, op if block
+          res
         rescue => exception
           unless exception.respond_to?(:code) &&
                  retry_options.retry_codes.include?(exception.code)
@@ -372,10 +389,17 @@ module Google
     # @param a_func [Proc] a proc to be updated
     # @param timeout [Numeric] to be added to the original proc as it
     #   final positional arg.
+    # @param metadata [Hash] request metadata headers
     # @return [Proc] the original proc updated to the timeout arg
-    def add_timeout_arg(a_func, timeout, kwargs)
-      proc do |request|
-        a_func.call(request, deadline: Time.now + timeout, metadata: kwargs)
+    def add_timeout_arg(a_func, timeout, metadata)
+      proc do |request, block|
+        op = a_func.call(request,
+                         deadline: Time.now + timeout,
+                         metadata: metadata,
+                         return_op: true)
+        res = op.execute
+        block.call op if block
+        res
       end
     end
 

data/lib/google/gax/settings.rb

@@ -42,11 +42,11 @@ module Google
     #   @return [Object]
     # @!attribute [r] bundle_descriptor
     #   @return [BundleDescriptor]
-    # @!attribute [r] kwargs
+    # @!attribute [r] metadata
     #   @return [Hash]
     class CallSettings
       attr_reader :timeout, :retry_options, :page_descriptor, :page_token,
-                  :bundler, :bundle_descriptor, :kwargs, :errors
+                  :bundler, :bundle_descriptor, :metadata, :errors
 
       # @param timeout [Numeric] The client-side timeout for API calls. This
       #   parameter is ignored for retrying calls.
@@ -62,20 +62,22 @@ module Google
       #   performed.
       # @param bundle_descriptor [BundleDescriptor] indicates the structure of
       #   the bundle. If nil, bundling is not performed.
+      # @param metadata [Hash] the request header params.
       # @param kwargs [Hash]
-      #   Additional keyword argments to be passed to the API call.
+      #   Deprecated, if set this will be merged with the metadata field.
       # @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: [])
+                     metadata: {}, kwargs: {}, errors: [])
         @timeout = timeout
         @retry_options = retry_options
         @page_descriptor = page_descriptor
         @page_token = page_token
         @bundler = bundler
         @bundle_descriptor = bundle_descriptor
-        @kwargs = kwargs
+        @metadata = metadata
+        @metadata.merge!(kwargs) if kwargs && metadata
         @errors = errors
       end
 
@@ -101,7 +103,7 @@ module Google
                                   page_token: @page_token,
                                   bundler: @bundler,
                                   bundle_descriptor: @bundle_descriptor,
-                                  kwargs: @kwargs,
+                                  metadata: @metadata,
                                   errors: @errors)
         end
 
@@ -121,8 +123,8 @@ module Google
                        options.page_token
                      end
 
-        kwargs = @kwargs.dup
-        kwargs.update(options.kwargs) if options.kwargs != :OPTION_INHERIT
+        metadata = (metadata.dup if metadata) || {}
+        metadata.update(options.metadata) if options.metadata != :OPTION_INHERIT
 
         CallSettings.new(timeout: timeout,
                          retry_options: retry_options,
@@ -130,7 +132,7 @@ module Google
                          page_token: page_token,
                          bundler: @bundler,
                          bundle_descriptor: @bundle_descriptor,
-                         kwargs: kwargs,
+                         metadata: metadata,
                          errors: @errors)
       end
     end
@@ -144,10 +146,13 @@ module Google
     #   @return [RetryOptions, :OPTION_INHERIT]
     # @!attribute [r] page_token
     #   @return [Object, :OPTION_INHERIT, :INITIAL_PAGE]
+    # @!attribute [r] metadata
+    #   @return [Hash, :OPTION_INHERIT]
     # @!attribute [r] kwargs
-    #  @return [Hash, :OPTION_INHERIT]
+    #   @return [Hash, :OPTION_INHERIT] deprecated, use metadata instead
     class CallOptions
-      attr_reader :timeout, :retry_options, :page_token, :kwargs
+      attr_reader :timeout, :retry_options, :page_token, :metadata
+      alias kwargs metadata
 
       # @param timeout [Numeric, :OPTION_INHERIT]
       #   The client-side timeout for API calls.
@@ -157,16 +162,19 @@ 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 metadata [Hash, :OPTION_INHERIT] the request header params.
       # @param kwargs [Hash, :OPTION_INHERIT]
-      #   Additional keyword argments to be passed to the API call.
+      #   Deprecated, if set this will be merged with the metadata field.
       def initialize(timeout: :OPTION_INHERIT,
                      retry_options: :OPTION_INHERIT,
                      page_token: :OPTION_INHERIT,
+                     metadata: :OPTION_INHERIT,
                      kwargs: :OPTION_INHERIT)
         @timeout = timeout
         @retry_options = retry_options
         @page_token = page_token
-        @kwargs = kwargs
+        @metadata = metadata
+        @metadata.merge!(kwargs) if kwargs.is_a?(Hash) && metadata.is_a?(Hash)
       end
     end
 
@@ -466,17 +474,22 @@ module Google
     # @param page_descriptors [Hash{String => PageDescriptor}] A
     #   dictionary of method names to PageDescriptor objects for
     #   methods that are page streaming-enabled.
+    # @param metadata [Hash]
+    #   Header params to be passed to the API call.
     # @param kwargs [Hash]
-    #   Additional keyword argments to be passed to the API call.
+    #   Deprecated, same as metadata and if present will be merged with metadata
     # @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: {}, kwargs: {}, errors: [])
+                           page_descriptors: {}, metadata: {}, kwargs: {},
+                           errors: [])
       defaults = {}
 
+      metadata.merge!(kwargs) if kwargs.is_a?(Hash) && metadata.is_a?(Hash)
+
       service_config = client_config.fetch('interfaces', {})[service_name]
       return nil unless service_config
 
@@ -509,7 +522,7 @@ module Google
           page_descriptor: page_descriptors[snake_name],
           bundler: construct_bundling(bundling_config, bundle_descriptor),
           bundle_descriptor: bundle_descriptor,
-          kwargs: kwargs,
+          metadata: metadata,
           errors: errors
         )
       end

data/lib/google/gax/version.rb

@@ -29,6 +29,6 @@
 
 module Google
   module Gax
-    VERSION = '1.0.1'.freeze
+    VERSION = '1.2.0'.freeze
   end
 end

data/spec/google/gax/api_callable_spec.rb

@@ -56,10 +56,15 @@ describe Google::Gax do
     it 'calls api call' do
       settings = CallSettings.new
       deadline_arg = nil
+
+      op = double('op')
+      allow(op).to receive(:execute) { 42 }
+
       func = proc do |deadline: nil, **_kwargs|
         deadline_arg = deadline
-        42
+        op
       end
+
       my_callable = Google::Gax.create_api_call(func, settings)
       expect(my_callable.call(nil)).to eq(42)
       expect(deadline_arg).to be_a(Time)
@@ -71,10 +76,65 @@ describe Google::Gax do
     end
   end
 
+  describe 'create_api_call with block options' do
+    it 'calls with block' do
+      adder = 0
+      settings = CallSettings.new
+
+      op = double('op', request: 3)
+      allow(op).to receive(:execute) { 2 + op.request + adder }
+
+      func = proc do |request, _deadline: nil, **_kwargs|
+        expect(request).to eq(3)
+        op
+      end
+
+      my_callable = Google::Gax.create_api_call(func, settings)
+      expect(my_callable.call(3)).to eq(5)
+      expect(my_callable.call(3) { adder = 5 }).to eq(5)
+      expect(my_callable.call(3)).to eq(10)
+    end
+  end
+
+  describe 'custom exceptions' do
+    it 'traps an exception' do
+      settings = CallSettings.new
+
+      transformer = proc do |ex|
+        expect(ex).to be_a(Google::Gax::RetryError)
+        raise CustomException.new('', FAKE_STATUS_CODE_2)
+      end
+
+      func = proc do
+        raise Google::Gax::RetryError.new('')
+      end
+      my_callable = Google::Gax.create_api_call(
+        func, settings, exception_transformer: transformer
+      )
+      expect { my_callable.call }.to raise_error(CustomException)
+    end
+
+    it 'traps a wrapped exception' do
+      settings = CallSettings.new(errors: [CustomException])
+
+      transformer = proc do |ex|
+        expect(ex).to be_a(Google::Gax::GaxError)
+        raise Exception.new('')
+      end
+
+      func = proc do
+        raise CustomException.new('', :FAKE_STATUS_CODE_1)
+      end
+      my_callable = Google::Gax.create_api_call(
+        func, settings, exception_transformer: transformer
+      )
+      expect { my_callable.call }.to raise_error(Exception)
+    end
+  end
+
   describe 'page streaming' do
     page_size = 3
     pages_to_stream = 5
-
     page_descriptor = Google::Gax::PageDescriptor.new('page_token',
                                                       'next_page_token', 'nums')
     settings = CallSettings.new(page_descriptor: page_descriptor)
@@ -93,7 +153,13 @@ describe Google::Gax do
     end
 
     it 'iterates over elements' do
-      my_callable = Google::Gax.create_api_call(func, settings)
+      func2 = proc do |request, **kwargs|
+        op = double('op')
+        allow(op).to receive(:execute) { func.call(request, **kwargs) }
+        op
+      end
+
+      my_callable = Google::Gax.create_api_call(func2, settings)
       expect(my_callable.call('page_token' => 0).to_a).to match_array(
         (0...(page_size * pages_to_stream))
       )
@@ -101,7 +167,13 @@ describe Google::Gax do
     end
 
     it 'offers interface for pages' do
-      my_callable = Google::Gax.create_api_call(func, settings)
+      func2 = proc do |request, **kwargs|
+        op = double('op')
+        allow(op).to receive(:execute) { func.call(request, **kwargs) }
+        op
+      end
+
+      my_callable = Google::Gax.create_api_call(func2, settings)
       stream = my_callable.call('page_token' => 0)
       page = stream.page
       expect(page.to_a).to eq((0...page_size).to_a)
@@ -114,8 +186,14 @@ describe Google::Gax do
     end
 
     it 'starts from the specified page_token' do
+      func2 = proc do |request, **kwargs|
+        op = double('op')
+        allow(op).to receive(:execute) { func.call(request, **kwargs) }
+        op
+      end
+
       my_settings = settings.merge(Google::Gax::CallOptions.new(page_token: 3))
-      my_callable = Google::Gax.create_api_call(func, my_settings)
+      my_callable = Google::Gax.create_api_call(func2, my_settings)
       expect(my_callable.call({}).to_a).to match_array(
         3...(page_size * pages_to_stream)
       )
@@ -188,8 +266,13 @@ describe Google::Gax do
       func = proc do |request, _|
         request['elements'].count
       end
+      func2 = proc do |request, **kwargs|
+        op = double('op')
+        allow(op).to receive(:execute) { func.call(request, **kwargs) }
+        op
+      end
 
-      callable = Google::Gax.create_api_call(func, settings)
+      callable = Google::Gax.create_api_call(func2, settings)
 
       first = callable.call('elements' => [0] * 5)
       expect(first).to be_an_instance_of Google::Gax::Event
@@ -207,11 +290,16 @@ describe Google::Gax do
         metadata_arg = metadata
         42
       end
+      func2 = proc do |request, **kwargs|
+        op = double('op')
+        allow(op).to receive(:execute) { func.call(request, **kwargs) }
+        op
+      end
       params_extractor = proc do |request|
         { 'name' => request[:name], 'book.read' => request[:book][:read] }
       end
       my_callable = Google::Gax.create_api_call(
-        func, settings, params_extractor: params_extractor
+        func2, settings, params_extractor: params_extractor
       )
       expect(my_callable.call(name: 'foo', book: { read: true })).to eq(42)
       expect(metadata_arg).to eq(
@@ -241,7 +329,13 @@ describe Google::Gax do
         raise CustomException.new('', FAKE_STATUS_CODE_1) if to_attempt > 0
         1729
       end
-      my_callable = Google::Gax.create_api_call(func, settings)
+      func2 = proc do |request, **kwargs|
+        op = double('op')
+        allow(op).to receive(:execute) { func.call(request, **kwargs) }
+        op
+      end
+
+      my_callable = Google::Gax.create_api_call(func2, settings)
       expect(my_callable.call).to eq(1729)
       expect(to_attempt).to eq(0)
       expect(deadline_arg).to be_a(Time)
@@ -318,7 +412,12 @@ describe Google::Gax do
 
     it 'does not retry even when no responses' do
       func = proc { nil }
-      my_callable = Google::Gax.create_api_call(func, settings)
+      func2 = proc do |request, **kwargs|
+        op = double('op')
+        allow(op).to receive(:execute) { func.call(request, **kwargs) }
+        op
+      end
+      my_callable = Google::Gax.create_api_call(func2, settings)
       expect(my_callable.call).to be_nil
     end
 

data/spec/google/gax/settings_spec.rb

@@ -91,7 +91,7 @@ describe Google::Gax do
       SERVICE_NAME, A_CONFIG, {}, RETRY_DICT, 30,
       bundle_descriptors: BUNDLE_DESCRIPTORS,
       page_descriptors: PAGE_DESCRIPTORS,
-      kwargs: { 'key' => 'value' },
+      metadata: { 'key' => 'value' },
       errors: [StandardError]
     )
     settings = defaults['bundling_method']
@@ -104,7 +104,7 @@ 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.metadata).to match('key' => 'value')
     expect(settings.errors).to match_array([StandardError])
 
     settings = defaults['some_https_page_streaming_method']
@@ -117,7 +117,7 @@ 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.metadata).to match('key' => 'value')
     expect(settings.errors).to match_array([StandardError])
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-gax
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Google API Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-12-21 00:00:00.000000000 Z
+date: 2018-04-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: googleauth
@@ -215,7 +215,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.12
+rubygems_version: 2.6.14
 signing_key: 
 specification_version: 4
 summary: Aids the development of APIs for clients and servers based on GRPC and Google