google-gax 0.1.1

data/lib/google/gax/errors.rb

@@ -0,0 +1,51 @@
+# Copyright 2016, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+#     * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+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
+        super(msg)
+        @cause = cause
+      end
+    end
+
+    # Indicates an error during automatic GAX retrying.
+    class RetryError < GaxError
+    end
+  end
+end

data/lib/google/gax/grpc.rb

@@ -0,0 +1,94 @@
+# Copyright 2016, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+#     * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (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 'grpc'
+require 'googleauth'
+
+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
+
+      API_ERRORS = [GRPC::BadStatus, GRPC::Cancelled].freeze
+
+      # rubocop:disable Metrics/ParameterLists
+
+      # Creates a gRPC client stub.
+      #
+      # @param service_path [String] The domain name of the API remote host.
+      #
+      # @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 channel [Object] A Channel object through which to make calls. If
+      #    none, a secure channel is constructed.
+      #
+      # @param updater_proc [Proc]
+      #    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.
+      #
+      # @yield [address, creds]
+      #   the generated gRPC method to create a stub.
+      #
+      # @return A gRPC client stub.
+      def create_stub(service_path,
+                      port,
+                      chan_creds: nil,
+                      channel: nil,
+                      updater_proc: nil,
+                      scopes: nil)
+        address = "#{service_path}:#{port}"
+        if channel.nil?
+          chan_creds = GRPC::Core::ChannelCredentials.new if chan_creds.nil?
+          if updater_proc.nil?
+            auth_creds = Google::Auth.get_application_default(scopes)
+            updater_proc = auth_creds.updater_proc
+          end
+          call_creds = GRPC::Core::CallCredentials.new(updater_proc)
+          chan_creds = chan_creds.compose(call_creds)
+          yield(address, chan_creds)
+        else
+          yield(address, nil, channel_override: channel)
+        end
+      end
+
+      module_function :create_stub
+    end
+  end
+end

data/lib/google/gax/path_template.rb

@@ -0,0 +1,248 @@
+# Copyright 2016, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+#     * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (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 'rly'
+
+module Google
+  # Gax defines Google API extensions
+  module Gax
+    # Lexer for the path_template language
+    class PathLex < Rly::Lex
+      token :FORWARD_SLASH, %r{/}
+      token :LEFT_BRACE, /\{/
+      token :RIGHT_BRACE, /\}/
+      token :EQUALS, /=/
+      token :PATH_WILDCARD, /\*\*/ # has to occur before WILDCARD
+      token :WILDCARD, /\*/
+      token :LITERAL, %r{[^*=\}\{\/ ]+}
+
+      on_error do |t|
+        raise t ? "Syntax error at '#{t.value}'" : 'Syntax error at EOF'
+      end
+    end
+
+    # Parser for the path_template language
+    class PathParse < Rly::Yacc
+      attr_reader :segment_count, :binding_var_count
+
+      def initialize(*args)
+        super
+        @segment_count = 0
+        @binding_var_count = 0
+      end
+
+      def parse(*args)
+        segments = super
+        has_path_wildcard = false
+        raise 'path template has no segments' if segments.nil?
+        segments.each do |s|
+          next unless s.kind == TERMINAL && s.literal == '**'
+          if has_path_wildcard
+            raise 'path template cannot contain more than one path wildcard'
+          else
+            has_path_wildcard = true
+          end
+        end
+        segments
+      end
+
+      rule 'template : FORWARD_SLASH bound_segments
+                     | bound_segments' do |template, *segments|
+        template.value = segments[-1].value
+      end
+
+      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?
+      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?
+      end
+
+      rule 'bound_segment : bound_terminal
+                          | variable' do |segment, term_or_var|
+        segment.value = term_or_var.value
+      end
+
+      rule 'unbound_terminal : WILDCARD
+                             | PATH_WILDCARD
+                             | LITERAL' do |term, literal|
+        term.value = [Segment.new(TERMINAL, literal.value)]
+        @segment_count += 1
+      end
+
+      rule 'bound_terminal : unbound_terminal' do |bound, unbound|
+        if ['*', '**'].include?(unbound.value[0].literal)
+          bound.value = [
+            Segment.new(BINDING, format('$%d', @binding_var_count)),
+            unbound.value[0],
+            Segment.new(END_BINDING, '')
+          ]
+          @binding_var_count += 1
+        else
+          bound.value = unbound.value
+        end
+      end
+
+      rule 'variable : LEFT_BRACE LITERAL EQUALS unbound_segments RIGHT_BRACE
+                     | 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)
+        else
+          variable.value.push(Segment.new(TERMINAL, '*'))
+          @segment_count += 1
+        end
+        variable.value.push(Segment.new(END_BINDING, ''))
+      end
+    end
+
+    # PathTemplate parses and format resource names
+    class PathTemplate
+      attr_reader :segments, :size
+
+      def initialize(data)
+        parser = PathParse.new(PathLex.new)
+        @segments = parser.parse(data)
+        @size = parser.segment_count
+      end
+
+      # Formats segments as a string.
+      #
+      # @param [Array<Segments>]
+      #   The segments to be formatted
+      # @return [String] the formatted output
+      def self.format_segments(*segments)
+        template = ''
+        slash = true
+        segments.each do |segment|
+          if segment.kind == TERMINAL
+            template += '/' if slash
+            template += segment.literal.to_s
+            next
+          end
+          slash = true
+          if segment.kind == BINDING
+            template += "/{#{segment.literal}="
+            slash = false
+          else
+            template += "#{segment.literal}}"
+          end
+        end
+        template[1, template.length] # exclude the initial slash
+      end
+
+      # Renders a path template using the provided bindings.
+      # @param binding [Hash]
+      #   A mapping of var names to binding strings.
+      # @return [String] A rendered representation of this path template.
+      # @raise [ArgumentError] If a key isn't provided or if a sub-template
+      #   can't be parsed.
+      def render(**bindings)
+        out = []
+        binding = false
+        @segments.each do |segment|
+          if segment.kind == BINDING
+            literal_sym = segment.literal.to_sym
+            unless bindings.key?(literal_sym)
+              msg = "Value for key #{segment.literal} is not provided"
+              raise(ArgumentError, msg)
+            end
+            out.push(*PathTemplate.new(bindings[literal_sym]).segments)
+            binding = true
+          elsif segment.kind == END_BINDING
+            binding = false
+          else
+            next if binding
+            out << segment
+          end
+        end
+        path = self.class.format_segments(*out)
+        match(path)
+        path
+      end
+
+      # Matches a fully qualified path template string.
+      # @param path [String]
+      #   A fully qualified path template string.
+      # @return [Hash] Var names to matched binding values.
+      # @raise [ArgumentError] If path can't be matched to the template.
+      def match(path)
+        that = path.split('/')
+        current_var = nil
+        bindings = {}
+        segment_count = @size
+        i = 0
+        @segments.each do |segment|
+          break if i >= that.size
+          if segment.kind == TERMINAL
+            if segment.literal == '*'
+              bindings[current_var] = that[i]
+              i += 1
+            elsif segment.literal == '**'
+              size = that.size - segment_count + 1
+              segment_count += size - 1
+              bindings[current_var] = that[i, size].join('/')
+              i += size
+            elsif segment.literal != that[i]
+              throw ArgumentError.new(
+                "mismatched literal: '#{segment.literal}' != '#{that[i]}'")
+            else
+              i += 1
+            end
+          elsif segment.kind == BINDING
+            current_var = segment.literal
+          end
+        end
+        if i != that.size || i != segment_count
+          throw ArgumentError.new(
+            "match error: could not instantiate a path template from #{path}")
+        end
+        bindings
+      end
+
+      def to_s
+        self.class.format_segments(*@segments)
+      end
+    end
+
+    Segment = Struct.new(:kind, :literal)
+
+    # Private constants/methods/classes
+    BINDING = 1
+    END_BINDING = 2
+    TERMINAL = 3
+
+    private_constant :BINDING, :END_BINDING, :TERMINAL
+  end
+end

data/lib/google/gax/settings.rb

@@ -0,0 +1,213 @@
+# Copyright 2016, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+#     * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+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_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)
+        end
+      end
+    end
+
+    # Helper for #construct_settings
+    #
+    # @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
+    #   +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
+    #   +retry_params+ entry of the standard API client config
+    #   file. (See #construct_settings for information on this yaml.)
+    # @param retry_names [Hash] A dictionary mapping the string names
+    #   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]
+      end
+
+      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)))
+      end
+
+      RetryOptions.new(codes, backoff_settings)
+    end
+
+    def _upper_camel_to_lower_underscore(string)
+      string.scan(/[[:upper:]][^[:upper:]]*/).map(&:downcase).join('_')
+    end
+
+    # rubocop:disable Metrics/ParameterLists
+
+    # 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
+    #             }
+    #           }
+    #         }
+    #       }
+    #     }
+    #   }
+    #
+    # @param 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').
+    # @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 retry_names [Hash] A dictionary mapping the strings
+    #   referring to response status codes to the Python objects
+    #   representing those codes.
+    # @param timeout [Numeric] The timeout parameter for all API calls
+    #   in this dictionary.
+    # @param bundle_descriptors [Hash{String => BundleDescriptor}]
+    #   A dictionary of method names to BundleDescriptor objects for
+    #   methods that are bundling-enabled.
+    # @param page_descriptors [Hash{String => PageDescriptor}] A
+    #   dictionary of method names to PageDescriptor objects for
+    #   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: {})
+      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
+
+    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
+  end
+end