Module: Google::Gax

Defined in:
lib/google/gax/path_template.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

Overview

Gax defines Google API extensions

Defined Under Namespace

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

Constant Summary collapse

VERSION = 
'0.1.1'.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 155

#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 172

#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 172

#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 172

#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 172

#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 155

#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 172

#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 172

#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 172

Class Method Details

.construct_settings(service_name, client_config, bundling_override, retry_override, retry_names, timeout, bundle_descriptors: {}, page_descriptors: {}) ⇒ 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 dictionary parsed from the standard API client config file.

  • bundling_override (Hash) —

    A dictionary of method names to BundleOptions override those specified in client_config.

  • retry_override (Hash) —

    A dictionary of method names to RetryOptions that override those specified in client_config.

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

Returns:

  • (CallSettings, nil) —

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



176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/google/gax/settings.rb', line 176

def construct_settings(
    service_name, client_config, bundling_override, retry_override,
    retry_names, timeout, bundle_descriptors: {}, page_descriptors: {})
  defaults = {}

  service_config = client_config.fetch('interfaces', {})[service_name]
  return nil unless service_config

  service_config['methods'].each_pair do |method_name, method_config|
    snake_name = _upper_camel_to_lower_underscore(method_name)

    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),
      page_descriptor: page_descriptors[snake_name],
      bundler: _construct_bundling(
        method_config,
        bundling_override.fetch(snake_name, :OPTION_INHERIT),
        bundle_descriptor),
      bundle_descriptor: bundle_descriptor)
  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) —

    ettings [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



191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
 
# File 'lib/google/gax/api_callable.rb', line 191

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

  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)
  end
  if settings.bundler?
    return _bundleable(api_call, settings.bundle_descriptor,
                       settings.bundler)
  end

  _catch_errors(api_call)
end