Module: Google::Gax

Defined in:
lib/google/gax/bundling.rb,
lib/google/gax.rb,
lib/google/gax/grpc.rb,
lib/google/gax/errors.rb,
lib/google/gax/version.rb,
lib/google/gax/settings.rb,
lib/google/gax/api_callable.rb,
lib/google/gax/path_template.rb

Overview

Gax defines Google API extensions

Defined Under Namespace

Modules: Grpc Classes: BackoffSettings, BundleDescriptor, BundleOptions, CallOptions, CallSettings, Event, Executor, GaxError, PageDescriptor, PagedEnumerable, PathLex, PathParse, PathTemplate, RetryError, RetryOptions, Segment, Task, Timer

Constant Summary collapse

VERSION = 
'0.4.3'.freeze
MILLIS_PER_SECOND = 
1000.0

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Attribute Details

#backoff_settings ⇒ BackoffSettings

Returns configuring the retry exponential backoff algorithm.

Returns:

  • (BackoffSettings) —

    configuring the retry exponential backoff algorithm.




# File 'lib/google/gax.rb', line 186

#initial_retry_delay_millis ⇒ Numeric

Returns the initial delay time, in milliseconds, between the completion of the first failed request and the initiation of the first retrying request.

Returns:

  • (Numeric) —

    the initial delay time, in milliseconds, between the completion of the first failed request and the initiation of the first retrying request.




# File 'lib/google/gax.rb', line 204

#initial_rpc_timeout_millis ⇒ Numeric

Returns the initial timeout parameter to the request.

Returns:

  • (Numeric) —

    the initial timeout parameter to the request.




# File 'lib/google/gax.rb', line 204

#max_retry_delay_millis ⇒ Numeric

Returns 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.

Returns:

  • (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.




# File 'lib/google/gax.rb', line 204

#max_rpc_timeout_millis ⇒ Numeric

Returns 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.

Returns:

  • (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.




# File 'lib/google/gax.rb', line 204

#retry_codes ⇒ Array<Grpc::Code>

Returns a list of exceptions upon which a retry should be attempted.

Returns:

  • (Array<Grpc::Code>) —

    a list of exceptions upon which a retry should be attempted.




# File 'lib/google/gax.rb', line 186

#retry_delay_multiplier ⇒ Numeric

Returns the multiplier by which to increase the delay time between the completion of failed requests, and the initiation of the subsequent retrying request.

Returns:

  • (Numeric) —

    the multiplier by which to increase the delay time between the completion of failed requests, and the initiation of the subsequent retrying request.




# File 'lib/google/gax.rb', line 204

#rpc_timeout_multiplier ⇒ Numeric

Returns the multiplier by which to increase the timeout parameter between failed requests.

Returns:

  • (Numeric) —

    the multiplier by which to increase the timeout parameter between failed requests.




# File 'lib/google/gax.rb', line 204

#total_timeout_millis ⇒ Numeric

Returns 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.

Returns:

  • (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.




# File 'lib/google/gax.rb', line 204

Class Method Details

.compute_bundle_id(obj, discriminator_fields) ⇒ Array<Object>

Computes a bundle id from the discriminator fields of ‘obj`.

discriminator_fields may include ‘.’ as a separator, which is used to indicate object traversal. This is meant to allow fields in the computed bundle_id. the return is an array computed by going through the discriminator fields in order and obtaining the str(value) object field (or nested object field) if any discriminator field cannot be found, ValueError is raised.

Parameters:

  • obj (Object) —

    an object.

  • discriminator_fields (Array<String>) —

    a list of discriminator fields in the order to be to be used in the id.

Returns:

  • (Array<Object>) —

    array of objects computed as described above.



67
68
69
70
71
72
73
 
# File 'lib/google/gax/bundling.rb', line 67

def compute_bundle_id(obj, discriminator_fields)
  result = []
  discriminator_fields.each do |field|
    result.push(str_dotted_access(obj, field))
  end
  result
end

.construct_settings(service_name, client_config, config_overrides, retry_names, timeout, bundle_descriptors: {}, page_descriptors: {}, kwargs: {}, errors: []) ⇒ CallSettings?

Constructs a dictionary mapping method names to CallSettings.

The client_config parameter is parsed from a client configuration JSON file of the form:

{
  "interfaces": {
    "google.fake.v1.ServiceName": {
      "retry_codes": {
        "idempotent": ["UNAVAILABLE", "DEADLINE_EXCEEDED"],
        "non_idempotent": []
      },
      "retry_params": {
        "default": {
          "initial_retry_delay_millis": 100,
          "retry_delay_multiplier": 1.2,
          "max_retry_delay_millis": 1000,
          "initial_rpc_timeout_millis": 2000,
          "rpc_timeout_multiplier": 1.5,
          "max_rpc_timeout_millis": 30000,
          "total_timeout_millis": 45000
        }
      },
      "methods": {
        "CreateFoo": {
          "retry_codes_name": "idempotent",
          "retry_params_name": "default"
        },
        "Publish": {
          "retry_codes_name": "non_idempotent",
          "retry_params_name": "default",
          "bundling": {
            "element_count_threshold": 40,
            "element_count_limit": 200,
            "request_byte_threshold": 90000,
            "request_byte_limit": 100000,
            "delay_threshold_millis": 100
          }
        }
      }
    }
  }
}

Parameters:

  • service_name (String) —

    The fully-qualified name of this service, used as a key into the client config file (in the example above, this value should be ‘google.fake.v1.ServiceName’).

  • client_config (Hash) —

    A hash parsed from the standard API client config file.

  • config_overrides (Hash) —

    A hash in the same structure of client_config to override the settings.

  • retry_names (Hash) —

    A dictionary mapping the strings referring to response status codes to the Python objects representing those codes.

  • timeout (Numeric) —

    The timeout parameter for all API calls in this dictionary.

  • bundle_descriptors (Hash{String => BundleDescriptor}) (defaults to: {}) —

    A dictionary of method names to BundleDescriptor objects for methods that are bundling-enabled.

  • page_descriptors (Hash{String => PageDescriptor}) (defaults to: {}) —

    A dictionary of method names to PageDescriptor objects for methods that are page streaming-enabled.

  • kwargs (Hash) (defaults to: {}) —

    Additional keyword argments to be passed to the API call.

  • errors (Array<Exception>) (defaults to: []) —

    Configures the exceptions to wrap with GaxError.

Returns:

  • (CallSettings, nil) —

    A CallSettings, or nil if the service is not found in the config.



192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/google/gax/settings.rb', line 192

def construct_settings(service_name, client_config, config_overrides,
                       retry_names, timeout, bundle_descriptors: {},
                       page_descriptors: {}, kwargs: {}, errors: [])
  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)

    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: 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(bundling_config, bundle_descriptor),
      bundle_descriptor: bundle_descriptor,
      kwargs: kwargs,
      errors: errors
    )
  end

  defaults
end

.create_api_call(func, settings) ⇒ Proc

Converts an rpc call into an API call governed by the settings.

In typical usage, func will be a proc used to make an rpc request. This will mostly likely be a bound method from a request stub used to make an rpc call.

The result is created by applying a series of function decorators defined in this module to func. settings is used to determine which function decorators to apply.

The result is another proc which for most values of settings has the same signature as the original. Only when settings configures bundling does the signature change.

Parameters:

  • func (Proc) —

    used to make a bare rpc call

  • settings (CallSettings) —

    provides the settings for this call

Returns:

  • (Proc) —

    a bound method on a request stub used to make an rpc call

Raises:

  • (StandardError) —

    if settings has incompatible values, e.g, if bundling and page_streaming are both configured



224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
 
# File 'lib/google/gax/api_callable.rb', line 224

def create_api_call(func, settings)
  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
    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

  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

.str_dotted_access(obj, name) ⇒ String?

Helper function for #compute_bundle_id. Used to retrieve a nested field signified by name where dots in name indicate nested objects.

Parameters:

  • obj (Object) —

    an object.

  • name (String) —

    a name for a field in the object.

Returns:

  • (String, nil) —

    value of named attribute. Can be nil.



46
47
48
49
50
51
52
 
# File 'lib/google/gax/bundling.rb', line 46

def str_dotted_access(obj, name)
  name.split('.').each do |part|
    obj = obj[part]
    break if obj.nil?
  end
  obj.nil? ? nil : obj.to_s
end