gapic-common 0.0.1

data/lib/gapic/common/version.rb

@@ -0,0 +1,19 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Gapic
+  module Common
+    VERSION = "0.0.1".freeze
+  end
+end

data/lib/gapic/config.rb

@@ -0,0 +1,104 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Gapic
+  ##
+  # Config is a simple DSL for creating Configuration classes.
+  #
+  # @example
+  #   require "gapic/config"
+  #
+  #   class SampleConfig
+  #     extend Gapic::Config
+  #
+  #     config_attr :name,   nil,         String, nil
+  #     config_attr :active, true,        true, false
+  #     config_attr :count,  nil,         Numeric, nil
+  #     config_attr :env,    :production, String, Symbol
+  #
+  #     def initialize parent_config = nil
+  #       @parent_config = parent_config unless parent_config.nil?
+  #       yield self if block_given?
+  #     end
+  #   end
+  #
+  #   config = SampleConfig.new
+  #
+  #   config.name             #=> nil
+  #   config.name = "thor"    #=> "thor"
+  #   config.name             #=> "thor"
+  #   config.name = :thor     # ArgumentError
+  #
+  module Config
+    ##
+    # Add configuration attribute methods to the configuratin class.
+    #
+    # @param [String, Symbol] key The name of the option
+    # @param [Object, nil] initial Initial value (nil is allowed)
+    # @param [Hash] opts Validation options
+    #
+    def config_attr name, default, *valid_values, &validator
+      name = String(name).to_sym
+      name_setter = "#{name}=".to_sym
+      raise NameError, "invalid config name #{name}" if name !~ /^[a-zA-Z]\w*$/ || name == :parent_config
+      raise NameError, "method #{name} already exists" if method_defined? name
+      raise NameError, "method #{name_setter} already exists" if method_defined? name_setter
+
+      raise ArgumentError, "validation must be provided" if validator.nil? && valid_values.empty?
+      validator ||= ->(value) { valid_values.any? { |v| v === value } }
+
+      name_ivar = "@#{name}".to_sym
+
+      create_getter name_ivar, name, default
+      create_setter name_ivar, name_setter, default, validator
+    end
+
+    private
+
+    def create_getter name_ivar, name, default
+      define_method name do
+        return instance_variable_get name_ivar if instance_variable_defined? name_ivar
+
+        if instance_variable_defined? :@parent_config
+          parent = instance_variable_get :@parent_config
+          return parent.send name if parent&.respond_to? name
+        end
+
+        default
+      end
+    end
+
+    def create_setter name_ivar, name_setter, default, validator
+      define_method name_setter do |new_value|
+        valid_value = validator.call new_value
+        if new_value.nil?
+          # Always allow nil when a default value is present
+          valid_value ||= !default.nil?
+          valid_value ||= begin
+            # Allow nil if parent config has the getter method.
+            parent = instance_variable_get :@parent_config if instance_variable_defined? :@parent_config
+            parent&.respond_to? name
+          end
+        end
+        raise ArgumentError unless valid_value
+
+        if new_value.nil?
+          remove_instance_variable name_ivar if instance_variable_defined? name_ivar
+        else
+          instance_variable_set name_ivar, new_value
+        end
+      end
+    end
+  end
+end

data/lib/gapic/config/method.rb

@@ -0,0 +1,65 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Gapic
+  module Config
+    ##
+    # Config::Method is a configuration class that represents the configuration for an API RPC call.
+    #
+    # @example
+    #   require "gapic/config"
+    #
+    #   class ServiceConfig
+    #     extend Gapic::Config
+    #
+    #     config_attr :host,     "localhost", String
+    #     config_attr :port,     443,         Integer
+    #     config_attr :timeout,  nil,         Numeric, nil
+    #     config_attr :metadata, nil,         Hash, nil
+    #
+    #     attr_reader :rpc_method
+    #
+    #     def initialize parent_config = nil
+    #       @parent_config = parent_config unless parent_config.nil?
+    #       @rpc_method = Gapic::Config::Method.new
+    #
+    #       yield self if block_given?
+    #     end
+    #   end
+    #
+    #   config = ServiceConfig.new
+    #
+    #   config.timeout = 60
+    #   config.rpc_method.timeout = 120
+    #
+    class Method
+      extend Gapic::Config
+
+      config_attr :timeout,      nil, Numeric, nil
+      config_attr :metadata,     nil, Hash, nil
+      config_attr :retry_policy, nil, Hash, Proc, nil
+
+      ##
+      # Create a new Config::Method object instance.
+      #
+      # @param parent_method [Gapic::Config::Method, nil] The config to look to values for.
+      #
+      def initialize parent_method = nil
+        @parent_config = parent_method unless parent_method.nil?
+
+        yield self if block_given?
+      end
+    end
+  end
+end

data/lib/gapic/grpc.rb

@@ -0,0 +1,17 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "grpc"
+require "gapic/grpc/service_stub"
+require "gapic/grpc/status_details"

data/lib/gapic/grpc/service_stub.rb

@@ -0,0 +1,158 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "grpc"
+require "googleauth"
+require "gapic/grpc/service_stub/rpc_call"
+
+module Gapic
+  ##
+  # Gapic gRPC Stub
+  #
+  # This class wraps the actual gRPC Stub object and it's RPC methods.
+  #
+  # @!attribute [r] grpc_stub
+  #   @return [Object] The instance of the gRPC stub class (`grpc_stub_class`) constructor argument.
+  #
+  class ServiceStub
+    attr_reader :grpc_stub
+
+    ##
+    # Creates a Gapic gRPC stub object.
+    #
+    # @param grpc_stub_class [Class] gRPC stub class to create a new instance of.
+    # @param endpoint [String] The endpoint of the API.
+    # @param credentials [Google::Auth::Credentials, Signet::OAuth2::Client, String, Hash, Proc,
+    #   GRPC::Core::Channel, GRPC::Core::ChannelCredentials] Provides the means for authenticating requests made by
+    #   the client. This parameter can be many types:
+    #
+    #   * A `Google::Auth::Credentials` uses a the properties of its represented keyfile for authenticating requests
+    #     made by this client.
+    #   * A `Signet::OAuth2::Client` object used to apply the OAuth credentials.
+    #   * A `GRPC::Core::Channel` will be used to make calls through.
+    #   * A `GRPC::Core::ChannelCredentials` for the setting up the RPC client. The channel credentials should
+    #     already be composed with a `GRPC::Core::CallCredentials` object.
+    #   * A `Proc` will be used as an updater_proc for the Grpc channel. The proc transforms the metadata for
+    #     requests, generally, to give OAuth credentials.
+    # @param channel_args [Hash] The channel arguments. (This argument is ignored when `credentials` is
+    #     provided as a `GRPC::Core::Channel`.)
+    # @param interceptors [Array<GRPC::ClientInterceptor>] An array of {GRPC::ClientInterceptor} objects that will
+    #   be used for intercepting calls before they are executed Interceptors are an EXPERIMENTAL API.
+    #
+    def initialize grpc_stub_class, endpoint:, credentials:, channel_args: nil, interceptors: nil
+      raise ArgumentError, "grpc_stub_class is required" if grpc_stub_class.nil?
+      raise ArgumentError, "endpoint is required" if endpoint.nil?
+      raise ArgumentError, "credentials is required" if credentials.nil?
+
+      channel_args = Hash channel_args
+      interceptors = Array interceptors
+
+      @grpc_stub = if credentials.is_a? GRPC::Core::Channel
+                     grpc_stub_class.new endpoint, nil, channel_override: credentials,
+                                                        interceptors:     interceptors
+                   elsif credentials.is_a? GRPC::Core::ChannelCredentials
+                     grpc_stub_class.new endpoint, credentials, channel_args: channel_args,
+                                                                interceptors: interceptors
+                   else
+                     updater_proc = credentials.updater_proc if credentials.respond_to? :updater_proc
+                     updater_proc ||= credentials if credentials.is_a? Proc
+                     raise ArgumentError, "invalid credentials (#{credentials.class})" if updater_proc.nil?
+
+                     call_creds = GRPC::Core::CallCredentials.new updater_proc
+                     chan_creds = GRPC::Core::ChannelCredentials.new.compose call_creds
+                     grpc_stub_class.new endpoint, chan_creds, channel_args: channel_args,
+                                                               interceptors: interceptors
+                   end
+    end
+
+    ##
+    # Invoke the specified RPC call.
+    #
+    # @param method_name [Symbol] The RPC method name.
+    # @param request [Object] The request object.
+    # @param options [Gapic::CallOptions, Hash] The options for making the RPC call. A Hash can be provided to
+    #   customize the options object, using keys that match the arguments for {Gapic::CallOptions.new}. This object
+    #   should only be used once.
+    #
+    # @yield [response, operation] Access the response along with the RPC operation.
+    # @yieldparam response [Object] The response object.
+    # @yieldparam operation [GRPC::ActiveCall::Operation] The RPC operation for the response.
+    #
+    # @return [Object] The response object.
+    #
+    # @example
+    #   require "google/showcase/v1beta1/echo_pb"
+    #   require "google/showcase/v1beta1/echo_services_pb"
+    #   require "gapic"
+    #   require "gapic/grpc"
+    #
+    #   echo_channel = GRPC::Core::Channel.new(
+    #     "localhost:7469", nil, :this_channel_is_insecure
+    #   )
+    #   echo_stub = Gapic::ServiceStub.new(
+    #     Google::Showcase::V1beta1::Echo::Stub,
+    #     endpoint: "localhost:7469", credentials: echo_channel
+    #   )
+    #
+    #   request = Google::Showcase::V1beta1::EchoRequest.new
+    #   response = echo_stub.call_rpc :echo, request
+    #
+    # @example Using custom call options:
+    #   require "google/showcase/v1beta1/echo_pb"
+    #   require "google/showcase/v1beta1/echo_services_pb"
+    #   require "gapic"
+    #   require "gapic/grpc"
+    #
+    #   echo_channel = GRPC::Core::Channel.new(
+    #     "localhost:7469", nil, :this_channel_is_insecure
+    #   )
+    #   echo_stub = Gapic::ServiceStub.new(
+    #     Google::Showcase::V1beta1::Echo::Stub,
+    #     endpoint: "localhost:7469", credentials: echo_channel
+    #   )
+    #
+    #   request = Google::Showcase::V1beta1::EchoRequest.new
+    #   options = Gapic::CallOptions.new(
+    #     retry_policy = {
+    #       retry_codes: [GRPC::Core::StatusCodes::UNAVAILABLE]
+    #     }
+    #   )
+    #   response = echo_stub.call_rpc :echo, request
+    #                                 options: options
+    #
+    # @example Accessing the response and RPC operation using a block:
+    #   require "google/showcase/v1beta1/echo_pb"
+    #   require "google/showcase/v1beta1/echo_services_pb"
+    #   require "gapic"
+    #   require "gapic/grpc"
+    #
+    #   echo_channel = GRPC::Core::Channel.new(
+    #     "localhost:7469", nil, :this_channel_is_insecure
+    #   )
+    #   echo_stub = Gapic::ServiceStub.new(
+    #     Google::Showcase::V1beta1::Echo::Stub,
+    #     endpoint: "localhost:7469", credentials: echo_channel
+    #   )
+    #
+    #   request = Google::Showcase::V1beta1::EchoRequest.new
+    #   echo_stub.call_rpc :echo, request do |response, operation|
+    #     operation.trailing_metadata
+    #   end
+    #
+    def call_rpc method_name, request, options: nil, &block
+      rpc_call = RpcCall.new @grpc_stub.method method_name
+      rpc_call.call request, options: options, &block
+    end
+  end
+end

data/lib/gapic/grpc/service_stub/rpc_call.rb

@@ -0,0 +1,149 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "gapic/call_options"
+
+module Gapic
+  class ServiceStub
+    class RpcCall
+      attr_reader :stub_method
+
+      ##
+      # Creates an API object for making a single RPC call.
+      #
+      # In typical usage, `stub_method` 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 `stub_method`.
+      #
+      # The result is another proc which has the same signature as the original.
+      #
+      # @param stub_method [Proc] Used to make a bare rpc call.
+      #
+      def initialize stub_method
+        @stub_method = stub_method
+      end
+
+      ##
+      # Invoke the RPC call.
+      #
+      # @param request [Object] The request object.
+      # @param options [Gapic::CallOptions, Hash] The options for making the RPC call. A Hash can be provided to
+      #   customize the options object, using keys that match the arguments for {Gapic::CallOptions.new}. This object
+      #   should only be used once.
+      #
+      # @yield [response, operation] Access the response along with the RPC operation.
+      # @yieldparam response [Object] The response object.
+      # @yieldparam operation [GRPC::ActiveCall::Operation] The RPC operation for the response.
+      #
+      # @return [Object] The response object.
+      #
+      # @example
+      #   require "google/showcase/v1beta1/echo_pb"
+      #   require "google/showcase/v1beta1/echo_services_pb"
+      #   require "gapic"
+      #   require "gapic/grpc"
+      #
+      #   echo_channel = GRPC::Core::Channel.new(
+      #     "localhost:7469", nil, :this_channel_is_insecure
+      #   )
+      #   echo_stub = Gapic::ServiceStub.new(
+      #     Google::Showcase::V1beta1::Echo::Stub,
+      #     endpoint: "localhost:7469", credentials: echo_channel
+      #   )
+      #   echo_call = Gapic::ServiceStub::RpcCall.new echo_stub.method :echo
+      #
+      #   request = Google::Showcase::V1beta1::EchoRequest.new
+      #   response = echo_call.call request
+      #
+      # @example Using custom call options:
+      #   require "google/showcase/v1beta1/echo_pb"
+      #   require "google/showcase/v1beta1/echo_services_pb"
+      #   require "gapic"
+      #   require "gapic/grpc"
+      #
+      #   echo_channel = GRPC::Core::Channel.new(
+      #     "localhost:7469", nil, :this_channel_is_insecure
+      #   )
+      #   echo_stub = Gapic::ServiceStub.new(
+      #     Google::Showcase::V1beta1::Echo::Stub,
+      #     endpoint: "localhost:7469", credentials: echo_channel
+      #   )
+      #   echo_call = Gapic::ServiceStub::RpcCall.new echo_stub.method :echo
+      #
+      #   request = Google::Showcase::V1beta1::EchoRequest.new
+      #   options = Gapic::CallOptions.new(
+      #     retry_policy = {
+      #       retry_codes: [GRPC::Core::StatusCodes::UNAVAILABLE]
+      #     }
+      #   )
+      #   response = echo_call.call request, options: options
+      #
+      # @example Accessing the response and RPC operation using a block:
+      #   require "google/showcase/v1beta1/echo_pb"
+      #   require "google/showcase/v1beta1/echo_services_pb"
+      #   require "gapic"
+      #   require "gapic/grpc"
+      #
+      #   echo_channel = GRPC::Core::Channel.new(
+      #     "localhost:7469", nil, :this_channel_is_insecure
+      #   )
+      #   echo_stub = Gapic::ServiceStub.new(
+      #     Google::Showcase::V1beta1::Echo::Stub,
+      #     endpoint: "localhost:7469", credentials: echo_channel
+      #   )
+      #   echo_call = Gapic::ServiceStub::RpcCall.new echo_stub.method :echo
+      #
+      #   request = Google::Showcase::V1beta1::EchoRequest.new
+      #   echo_call.call request do |response, operation|
+      #     operation.trailing_metadata
+      #   end
+      #
+      def call request, options: nil
+        # Converts hash and nil to an options object
+        options = Gapic::CallOptions.new options.to_h if options.respond_to? :to_h
+        deadline = calculate_deadline options
+        metadata = options.metadata
+
+        begin
+          operation = stub_method.call request, deadline: deadline, metadata: metadata, return_op: true
+          response = operation.execute
+          yield response, operation if block_given?
+          response
+        rescue StandardError => e
+          if check_retry? deadline
+            retry if options.retry_policy.call e
+          end
+
+          raise e
+        end
+      end
+
+      private
+
+      def calculate_deadline options
+        return if options.timeout.nil?
+        return if options.timeout.negative?
+
+        Time.now + options.timeout
+      end
+
+      def check_retry? deadline
+        return true if deadline.nil?
+
+        deadline > Time.now
+      end
+    end
+  end
+end