gapic-common 0.18.0 → 0.21.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 609c468f1e8a7e60f8b4ba911901dd99f8816cb367371dd5479d79dcd06bca82
-  data.tar.gz: 23a01faa58af17577e262852d434a6746b33f090247b05ea9dc8ce2ae07772bb
+  metadata.gz: b7c5286b152666f59249b7c1ba16867d494b934f2252bff17b68f1135ef47e97
+  data.tar.gz: 14bbbc1179570401141d6f62520bc2ff00b27f21f55431f0e3db2d3f4e7220e1
 SHA512:
-  metadata.gz: 7fc2a7f8c0fdcc79434966a1e6431c29d957dd1a646cae5a8cd023da1320b7f5253b69f4edd915c98656b12e681aac66bf11713c2bb47f0482798601635ba948
-  data.tar.gz: 49a6c6aaa7fca24979d8707bc7a6ba2b8daed51951539d2235be32f932e73a02fa4cd8d7699f811b358bd216ca99ffbe63dab0469196b1815cdf37eb6ad4055c
+  metadata.gz: f7e29a779c1fb17a88336b5c99c5635a9f196b275f9f381d56e25e8a5edc9ccf2e5ff9096500ab8bc33725489b793c2e1593bb38671da48b83529bba379562e0
+  data.tar.gz: ceb55e48e017ba629c0b583ebb9145d541a309998b29d5b47d40ef0819b0befde3659f39e37a4362691a248070042cd86a34f104100587b76ee742a6edec9565

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Release History
 
+### 0.21.1 (2023-12-14)
+
+#### Bug Fixes
+
+* add missing module import for universe_domain_concerns ([#1016](https://github.com/googleapis/gapic-generator-ruby/issues/1016)) 
+
+### 0.21.0 (2023-12-13)
+
+#### Features
+
+* Drop support for Ruby 2.6 ([#1009](https://github.com/googleapis/gapic-generator-ruby/issues/1009)) 
+* Honor universe domain in stubs ([#1008](https://github.com/googleapis/gapic-generator-ruby/issues/1008)) 
+
+### 0.20.0 (2023-08-31)
+
+#### Features
+
+* Add channel pooling for gapic clients ([#969](https://github.com/googleapis/gapic-generator-ruby/issues/969)) 
+* Add LRU hash ([#970](https://github.com/googleapis/gapic-generator-ruby/issues/970)) 
+#### Documentation
+
+* Minor fixes to YARD documentation links and parameters ([#959](https://github.com/googleapis/gapic-generator-ruby/issues/959)) 
+
+### 0.19.1 (2023-05-30)
+
+#### Bug Fixes
+
+* Fixed handling of optional fields in coerce ([#954](https://github.com/googleapis/gapic-generator-ruby/issues/954)) 
+
+### 0.19.0 (2023-05-26)
+
+#### Features
+
+* Compatibility with protobuf v23 generated map fields ([#948](https://github.com/googleapis/gapic-generator-ruby/issues/948)) 
+
 ### 0.18.0 (2023-02-27)
 
 #### Features

data/lib/gapic/call_options.rb

@@ -37,7 +37,7 @@ module Gapic
     # @param timeout [Numeric] The client-side timeout for RPC calls.
     # @param metadata [Hash] The request header params.
     # @param retry_policy [Hash, RetryPolicy, Proc] The policy for error retry. A Hash can be provided to
-    #   customize the policy object, using keys that match the arguments for {RetryPolicy.new}.
+    #   customize the policy object, using keys that match the arguments for {RetryPolicy.initialize}.
     #
     #   A Proc object can also be provided. The Proc should accept an error as an argument, and return `true` if the
     #   error should be retried or `false` if not. If the error is to be retried, the Proc object must also block
@@ -59,9 +59,8 @@ module Gapic
     #
     # @param timeout [Numeric] The client-side timeout for RPC calls.
     # @param metadata [Hash] the request header params.
-    # @param retry_policy [Hash] the policy for error retry.
     # @param retry_policy [Hash] The policy for error retry. keys must match the arguments for
-    #   {RetryPolicy.new}.
+    #   {RetryPolicy.initialize}.
     #
     def apply_defaults timeout: nil, metadata: nil, retry_policy: nil
       @timeout ||= timeout

data/lib/gapic/common/version.rb

@@ -14,6 +14,6 @@
 
 module Gapic
   module Common
-    VERSION = "0.18.0".freeze
+    VERSION = "0.21.1".freeze
   end
 end

data/lib/gapic/config.rb

@@ -44,13 +44,13 @@ module Gapic
     ##
     # 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
+    # @param [String, Symbol] name The name of the option
+    # @param [Object, nil] default Initial value (nil is allowed)
+    # @param [Array] valid_values A list of valid types
     #
     def config_attr name, default, *valid_values, &validator
       name = String(name).to_sym
-      name_setter = "#{name}=".to_sym
+      name_setter = :"#{name}="
       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
@@ -58,7 +58,7 @@ module Gapic
       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
+      name_ivar = :"@#{name}"
 
       create_getter name_ivar, name, default
       create_setter name_ivar, name_setter, default, validator

data/lib/gapic/generic_lro/operation.rb

@@ -90,7 +90,7 @@ module Gapic
       #
       def results
         return error if error?
-        return response if response?
+        response if response?
       end
 
       ##
@@ -196,7 +196,7 @@ module Gapic
       # @param retry_policy [RetryPolicy, Hash, Proc] The policy for retry. A custom proc that takes the error as an
       #   argument and blocks can also be provided.
       #
-      # @yield operation [Gapic::GenericLRO::Operation] Yields the finished Operation.
+      # @yieldparam operation [Gapic::GenericLRO::Operation] Yields the finished Operation.
       #
       def wait_until_done! retry_policy: nil
         retry_policy = ::Gapic::Operation::RetryPolicy.new(**retry_policy) if retry_policy.is_a? Hash
@@ -216,7 +216,7 @@ module Gapic
       # Registers a callback to be run when an operation is being reloaded. If the operation has completed
       # prior to a call to this function the callback will NOT be called or registered.
       #
-      # @yield operation [Gapic::Operation] Yields the finished Operation.
+      # @yieldparam operation [Gapic::Operation] Yields the finished Operation.
       #
       def on_reload &block
         return if done?
@@ -227,7 +227,7 @@ module Gapic
       # Registers a callback to be run when a refreshed operation is marked as done. If the operation has completed
       # prior to a call to this function the callback will be called instead of registered.
       #
-      # @yield operation [Gapic::Operation] Yields the finished Operation.
+      # @yieldparam operation [Gapic::Operation] Yields the finished Operation.
       #
       def on_done &block
         if done?

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

@@ -0,0 +1,100 @@
+# Copyright 2023 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
+  class ServiceStub
+    ##
+    # @private
+    #
+    # Gapic gRPC ServiceStub Channel.
+    #
+    # This class wraps the gRPC stub object and its RPC methods.
+    #
+    class Channel
+      attr_reader :concurrent_streams
+
+      ##
+      # Creates a new Channel instance
+      #
+      def initialize grpc_stub_class, endpoint:, credentials:, channel_args: nil, interceptors: nil,
+                     on_channel_create: nil
+        @grpc_stub_class = grpc_stub_class
+        @endpoint = endpoint
+        @credentials = credentials
+        @channel_args = Hash channel_args
+        @interceptors = Array interceptors
+        @concurrent_streams = 0
+        @mutex = Mutex.new
+        setup_grpc_stub
+        on_channel_create&.call self
+      end
+
+      ##
+      # Creates a gRPC stub object
+      #
+      def setup_grpc_stub
+        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?
+
+        @grpc_stub = case @credentials
+                     when ::GRPC::Core::Channel
+                       @grpc_stub_class.new @endpoint, nil, channel_override: @credentials, interceptors: @interceptors
+                     when ::GRPC::Core::ChannelCredentials, Symbol
+                       @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.
+      #
+      def call_rpc method_name, request, options: nil, &block
+        @mutex.synchronize { @concurrent_streams += 1 }
+        begin
+          rpc_call = RpcCall.new @grpc_stub.method method_name
+          response = rpc_call.call request, options: options, &block
+          response
+        ensure
+          @mutex.synchronize { @concurrent_streams -= 1 }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,113 @@
+# Copyright 2023 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/config"
+
+
+module Gapic
+  class ServiceStub
+    ##
+    # @private
+    #
+    # Gapic gRPC ServiceStub ChannelPool
+    #
+    # This class wraps multiple channels for sending RPCs.
+    #
+    class ChannelPool
+      ##
+      # Initialize an instance of ServiceStub::ChannelPool
+      #
+      def initialize grpc_stub_class, endpoint:, credentials:, channel_args: nil, interceptors: nil, config: nil
+        if credentials.is_a? ::GRPC::Core::Channel
+          raise ArgumentError, "Can't create a channel pool with GRPC::Core::Channel as credentials"
+        end
+
+        @grpc_stub_class = grpc_stub_class
+        @endpoint = endpoint
+        @credentials = credentials
+        @channel_args = channel_args
+        @interceptors = interceptors
+        @config = config || Configuration.new
+
+        @channels = (1..@config.channel_count).map { create_channel }
+      end
+
+      ##
+      # Creates a new channel.
+      def create_channel
+        Channel.new @grpc_stub_class, endpoint: @endpoint, credentials: @credentials, channel_args: @channel_args,
+                    interceptors: @interceptors, on_channel_create: @config.on_channel_create
+      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.
+      #
+      def call_rpc method_name, request, options: nil, &block
+        unless @config.channel_selection == :least_loaded
+          warn "Invalid channel selection configuration, resorting to least loaded channel"
+        end
+        channel = least_loaded_channel
+        channel.call_rpc method_name, request, options: options, &block
+      end
+
+
+      private
+
+      ##
+      # Return the least loaded channel in the pool
+      #
+      # @return [::Grpc::ServiceStub::Channel]
+      #
+      def least_loaded_channel
+        @channels.min_by(&:concurrent_streams)
+      end
+
+      ##
+      # Configuration class for ChannelPool
+      #
+      # @!attribute [rw] channel_count
+      #  The number of channels in the channel pool.
+      #  return [Integer]
+      # @!attribute [rw] on_channel_create
+      #  Proc to run at the end of each channel initialization.
+      #  Proc is provided ::Gapic::ServiceStub::Channel object as input.
+      #  return [Proc]
+      # @!attribute [rw] channel_selection
+      #  The algorithm for selecting a channel for an RPC.
+      #  return [Symbol]
+      #
+      class Configuration
+        extend ::Gapic::Config
+
+        config_attr :channel_count, 1, ::Integer
+        config_attr :on_channel_create, nil, ::Proc
+        config_attr :channel_selection, :least_loaded, :least_loaded
+      end
+    end
+  end
+end

data/lib/gapic/grpc/service_stub.rb

@@ -15,24 +15,37 @@
 require "grpc"
 require "googleauth"
 require "gapic/grpc/service_stub/rpc_call"
+require "gapic/grpc/service_stub/channel"
+require "gapic/grpc/service_stub/channel_pool"
+require "gapic/universe_domain_concerns"
 
 module Gapic
   ##
   # Gapic gRPC Stub
   #
-  # This class wraps the actual gRPC Stub object and it's RPC methods.
+  # This class wraps the actual gRPC Stub and ChannelPool objects.
   #
   # @!attribute [r] grpc_stub
   #   @return [Object] The instance of the gRPC stub class (`grpc_stub_class`) constructor argument.
+  # @!attribute [r] channel_pool
+  #   @return [Gapic::ServiceStub::ChannelPool] The instance of the ChannelPool class.
   #
   class ServiceStub
+    include UniverseDomainConcerns
+
     attr_reader :grpc_stub
+    attr_reader :channel_pool
 
     ##
     # 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 endpoint [String] The endpoint of the API. Overrides any endpoint_template.
+    # @param endpoint_template [String] The endpoint of the API, where the
+    #   universe domain component of the hostname is marked by the string in
+    #   the constant {UniverseDomainConcerns::ENDPOINT_SUBSTITUTION}.
+    # @param universe_domain [String] The universe domain in which calls should
+    #   be made. Defaults to `googleapis.com`.
     # @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:
@@ -49,22 +62,57 @@ module Gapic
     #     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
+    # @param channel_pool_config [::Gapic::ServiceStub:ChannelPool::Configuration] The configuration for channel
+    #     pool. This argument will raise error when `credentials` is provided as a `::GRPC::Core::Channel`.
+    #
+    def initialize grpc_stub_class,
+                   credentials:,
+                   endpoint: nil,
+                   endpoint_template: nil,
+                   universe_domain: nil,
+                   channel_args: nil,
+                   interceptors: nil,
+                   channel_pool_config: 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?
 
+      setup_universe_domain universe_domain: universe_domain,
+                            endpoint: endpoint,
+                            endpoint_template: endpoint_template,
+                            credentials: credentials
+
+      @channel_pool = nil
+      @grpc_stub = nil
       channel_args = Hash channel_args
       interceptors = Array interceptors
 
+      if channel_pool_config && channel_pool_config.channel_count > 1
+        create_channel_pool grpc_stub_class, endpoint: self.endpoint, credentials: self.credentials,
+                            channel_args: channel_args, interceptors: interceptors,
+                            channel_pool_config: channel_pool_config
+      else
+        create_grpc_stub grpc_stub_class, endpoint: self.endpoint, credentials: self.credentials,
+                         channel_args: channel_args, interceptors: interceptors
+      end
+    end
+
+    def create_channel_pool grpc_stub_class, endpoint:, credentials:, channel_args: nil,
+                            interceptors: nil, channel_pool_config: nil
+      if credentials.is_a? ::GRPC::Core::Channel
+        raise ArgumentError, "Cannot create a channel pool with GRPC::Core::Channel as credentials"
+      end
+      @channel_pool = ChannelPool.new grpc_stub_class, endpoint: endpoint, credentials: credentials,
+                        channel_args: channel_args, interceptors: interceptors,
+                        config: channel_pool_config
+    end
+
+    def create_grpc_stub grpc_stub_class, endpoint:, credentials:, channel_args: nil, interceptors: nil
       @grpc_stub = case credentials
                    when ::GRPC::Core::Channel
                      grpc_stub_class.new endpoint, nil, channel_override: credentials,
-                                                        interceptors:     interceptors
+                                         interceptors: interceptors
                    when ::GRPC::Core::ChannelCredentials, Symbol
                      grpc_stub_class.new endpoint, credentials, channel_args: channel_args,
-                                                                interceptors: interceptors
+                                         interceptors: interceptors
                    else
                      updater_proc = credentials.updater_proc if credentials.respond_to? :updater_proc
                      updater_proc ||= credentials if credentials.is_a? Proc
@@ -73,7 +121,7 @@ module Gapic
                      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
+                                         interceptors: interceptors
                    end
     end
 
@@ -152,8 +200,12 @@ module Gapic
     #   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
+      if @channel_pool.nil?
+        rpc_call = RpcCall.new @grpc_stub.method method_name
+        rpc_call.call request, options: options, &block
+      else
+        @channel_pool.call_rpc method_name, request, options: options, &block
+      end
     end
   end
 end

data/lib/gapic/lru_hash.rb

@@ -0,0 +1,106 @@
+# Copyright 2023 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
+  ##
+  # @private
+  #
+  # Linked list based hash maintaining the order of
+  # access/creation of the keys.
+  #
+  class LruHash
+    def initialize size = 1
+      raise ArgumentError, "The size of LRU hash can't be < 1" unless size > 1
+      @start = nil
+      @end = nil
+      @size = size
+      @cache = {}
+    end
+
+    def get key
+      return nil unless @cache.key? key
+      node = @cache[key]
+      move_to_top node
+      node.value
+    end
+
+    def put key, value
+      if @cache.key? key
+        node = @cache[key]
+        node.value = value
+        move_to_top node
+      else
+        remove_tail if @cache.size >= @size
+        new_node = Node.new key, value
+        insert_at_top new_node
+        @cache[key] = new_node
+      end
+    end
+
+    private
+
+    def move_to_top node
+      return if node.equal? @start
+
+      if node.equal? @end
+        @end = node.prev
+        @end.next = nil
+      else
+        node.prev.next = node.next
+        node.next.prev = node.prev
+      end
+
+      node.prev = nil
+      node.next = @start
+      @start.prev = node
+      @start = node
+    end
+
+    def remove_tail
+      @cache.delete @end.key
+      @end = @end.prev
+      @end.next = nil if @end
+    end
+
+    def insert_at_top node
+      if @start.nil?
+        @start = node
+        @end = node
+      else
+        node.next = @start
+        @start.prev = node
+        @start = node
+      end
+    end
+
+    ##
+    # @private
+    #
+    # Node class for linked list.
+    #
+    class Node
+      attr_accessor :key
+      attr_accessor :value
+      attr_accessor :prev
+      attr_accessor :next
+
+      def initialize key, value
+        @key = key
+        @value = value
+        @prev = nil
+        @next = nil
+      end
+    end
+  end
+end

data/lib/gapic/operation.rb

@@ -99,10 +99,10 @@ module Gapic
     # returned. Otherwise returns nil.
     #
     # @return [Object, Google::Rpc::Status, nil] The result of the operation. If it is an error a
-    #   {Google::Rpc::Status} will be returned.
+    #   `Google::Rpc::Status` will be returned.
     def results
       return error if error?
-      return response if response?
+      response if response?
     end
 
     ##
@@ -119,7 +119,7 @@ module Gapic
     # Returns the metadata of an operation. If a type is provided, the metadata will be unpacked using the type
     # provided; returning nil if the metadata is not of the type provided. If the type is not of provided, the
     # metadata will be unpacked using the metadata's type_url if the type_url is found in the
-    # {Google::Protobuf::DescriptorPool.generated_pool}. If the type cannot be found the raw metadata is retuned.
+    # `Google::Protobuf::DescriptorPool.generated_pool`. If the type cannot be found the raw metadata is retuned.
     #
     # @return [Object, nil] The metadata of the operation. Can be nil.
     #
@@ -250,7 +250,7 @@ module Gapic
     # @param retry_policy [RetryPolicy, Hash, Proc] The policy for retry. A custom proc that takes the error as an
     #   argument and blocks can also be provided.
     #
-    # @yield operation [Gapic::Operation] Yields the finished Operation.
+    # @yieldparam operation [Gapic::Operation] Yields the finished Operation.
     #
     def wait_until_done! retry_policy: nil
       retry_policy = RetryPolicy.new(**retry_policy) if retry_policy.is_a? Hash
@@ -270,7 +270,7 @@ module Gapic
     # Registers a callback to be run when a refreshed operation is marked as done. If the operation has completed
     # prior to a call to this function the callback will be called instead of registered.
     #
-    # @yield operation [Gapic::Operation] Yields the finished Operation.
+    # @yieldparam operation [Gapic::Operation] Yields the finished Operation.
     #
     def on_done &block
       if done?

data/lib/gapic/paged_enumerable.rb

@@ -250,7 +250,7 @@ module Gapic
       # @return [Boolean]
       #
       def next_page_token?
-        return if @response.nil?
+        return if @response.nil? # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
 
         !@response.next_page_token.empty?
       end

data/lib/gapic/protobuf.rb

@@ -16,7 +16,8 @@ require "google/protobuf/timestamp_pb"
 
 module Gapic
   ##
-  # TODO: Describe Protobuf
+  # A set of internal utilities for coercing data to protobuf messages.
+  #
   module Protobuf
     ##
     # Creates an instance of a protobuf message from a hash that may include nested hashes. `google/protobuf` allows
@@ -30,11 +31,15 @@ module Gapic
     # @return [Object] An instance of the given message class.
     def self.coerce hash, to:
       return hash if hash.is_a? to
+      return nil if hash.nil?
+
+      # Special case handling of certain types
+      return time_to_timestamp hash if to == Google::Protobuf::Timestamp && hash.is_a?(Time)
 
       # Sanity check: input must be a Hash
       raise ArgumentError, "Value #{hash} must be a Hash or a #{to.name}" unless hash.is_a? Hash
 
-      hash = coerce_submessages hash, to
+      hash = coerce_submessages hash, to.descriptor
       to.new hash
     end
 
@@ -44,89 +49,58 @@ module Gapic
     # @private
     #
     # @param hash [Hash] The hash whose nested hashes will be coerced.
-    # @param message_class [Class] The corresponding protobuf message class of the given hash.
+    # @param message_descriptor [Google::Protobuf::Descriptor] The protobuf descriptor for the message.
     #
     # @return [Hash] A hash whose nested hashes have been coerced.
-    def self.coerce_submessages hash, message_class
+    def self.coerce_submessages hash, message_descriptor
       return nil if hash.nil?
       coerced = {}
-      message_descriptor = message_class.descriptor
       hash.each do |key, val|
         field_descriptor = message_descriptor.lookup key.to_s
-        coerced[key] = if field_descriptor && field_descriptor.type == :message
-                         coerce_submessage val, field_descriptor
-                       elsif field_descriptor && field_descriptor.type == :bytes &&
-                             (val.is_a?(IO) || val.is_a?(StringIO))
-                         val.binmode.read
-                       else
-                         # `google/protobuf` should throw an error if no field descriptor is
-                         # found. Simply pass through.
-                         val
-                       end
+        coerced[key] =
+          if field_descriptor&.type == :message
+            coerce_submessage val, field_descriptor
+          elsif field_descriptor&.type == :bytes && (val.is_a?(IO) || val.is_a?(StringIO))
+            val.binmode.read
+          else
+            # For non-message fields, just pass the scalar value through.
+            # Note: if field_descriptor is not found, we just pass the value
+            # through and let protobuf raise an error.
+            val
+          end
       end
       coerced
     end
 
     ##
-    # Coerces the value of a field to be acceptable by the instantiation method of the wrapping message.
+    # Coerces a message-typed field.
+    # The field can be a normal single message, a repeated message, or a map.
     #
     # @private
     #
-    # @param val [Object] The value to be coerced.
-    # @param field_descriptor [Google::Protobuf::FieldDescriptor] The field descriptor of the value.
+    # @param val [Object] The value to coerce
+    # @param field_descriptor [Google::Protobuf::FieldDescriptor] The field descriptor.
     #
-    # @return [Object] The coerced version of the given value.
     def self.coerce_submessage val, field_descriptor
-      if (field_descriptor.label == :repeated) && !(map_field? field_descriptor)
-        coerce_array val, field_descriptor
-      elsif field_descriptor.subtype.msgclass == Google::Protobuf::Timestamp && val.is_a?(Time)
-        time_to_timestamp val
+      if val.is_a? Array
+        # Assume this is a repeated message field, iterate over it and coerce
+        # each to the message class.
+        # Protobuf will raise an error if this assumption is incorrect.
+        val.map do |elem|
+          coerce elem, to: field_descriptor.subtype.msgclass
+        end
+      elsif field_descriptor.label == :repeated
+        # Non-array passed to a repeated field: assume this is a map, and that
+        # a hash is being passed, and let protobuf handle the conversion.
+        # Protobuf will raise an error if this assumption is incorrect.
+        val
       else
-        coerce_value val, field_descriptor
+        # Assume this is a normal single message, and coerce to the message
+        # class.
+        coerce val, to: field_descriptor.subtype.msgclass
       end
     end
 
-    ##
-    # Coerces the values of an array to be acceptable by the instantiation method the wrapping message.
-    #
-    # @private
-    #
-    # @param array [Array<Object>] The values to be coerced.
-    # @param field_descriptor [Google::Protobuf::FieldDescriptor] The field descriptor of the values.
-    #
-    # @return [Array<Object>] The coerced version of the given values.
-    def self.coerce_array array, field_descriptor
-      raise ArgumentError, "Value #{array} must be an array" unless array.is_a? Array
-      array.map do |val|
-        coerce_value val, field_descriptor
-      end
-    end
-
-    ##
-    # Hack to determine if field_descriptor is for a map.
-    #
-    # TODO(geigerj): Remove this once protobuf Ruby supports an official way
-    # to determine if a FieldDescriptor represents a map.
-    # See: https://github.com/google/protobuf/issues/3425
-    def self.map_field? field_descriptor
-      (field_descriptor.label == :repeated) &&
-        (field_descriptor.subtype.name.include? "_MapEntry_")
-    end
-
-    ##
-    # Coerces the value of a field to be acceptable by the instantiation method of the wrapping message.
-    #
-    # @private
-    #
-    # @param val [Object] The value to be coerced.
-    # @param field_descriptor [Google::Protobuf::FieldDescriptor] The field descriptor of the value.
-    #
-    # @return [Object] The coerced version of the given value.
-    def self.coerce_value val, field_descriptor
-      return val unless (val.is_a? Hash) && !(map_field? field_descriptor)
-      coerce val, to: field_descriptor.subtype.msgclass
-    end
-
     ##
     # Utility for converting a Google::Protobuf::Timestamp instance to a Ruby time.
     #
@@ -147,6 +121,6 @@ module Gapic
       Google::Protobuf::Timestamp.new seconds: time.to_i, nanos: time.nsec
     end
 
-    private_class_method :coerce_submessages, :coerce_submessage, :coerce_array, :coerce_value, :map_field?
+    private_class_method :coerce_submessages, :coerce_submessage
   end
 end

data/lib/gapic/rest/client_stub.rb

@@ -14,6 +14,7 @@
 
 require "googleauth"
 require "gapic/rest/faraday_middleware"
+require "gapic/universe_domain_concerns"
 require "faraday/retry"
 
 module Gapic
@@ -26,9 +27,16 @@ module Gapic
     #   - store credentials and add auth information to the request
     #
     class ClientStub
+      include UniverseDomainConcerns
+
       ##
       # Initializes with an endpoint and credentials
-      # @param endpoint [String] an endpoint for the service that this stub will send requests to
+      # @param endpoint [String] The endpoint of the API. Overrides any endpoint_template.
+      # @param endpoint_template [String] The endpoint of the API, where the
+      #   universe domain component of the hostname is marked by the string in
+      #   the constant {UniverseDomainConcerns::ENDPOINT_SUBSTITUTION}.
+      # @param universe_domain [String] The universe domain in which calls
+      #   should be made. Defaults to `googleapis.com`.
       # @param credentials [Google::Auth::Credentials]
       #   Credentials to send with calls in form of a googleauth credentials object.
       #   (see the [googleauth docs](https://googleapis.dev/ruby/googleauth/latest/index.html))
@@ -42,19 +50,28 @@ module Gapic
       #
       # @yield [Faraday::Connection]
       #
-      def initialize endpoint:, credentials:, numeric_enums: false, raise_faraday_errors: true
-        @endpoint = endpoint
-        @endpoint = "https://#{endpoint}" unless /^https?:/.match? endpoint
-        @endpoint = @endpoint.sub %r{/$}, ""
+      def initialize credentials:,
+                     endpoint: nil,
+                     endpoint_template: nil,
+                     universe_domain: nil,
+                     numeric_enums: false,
+                     raise_faraday_errors: true
+        setup_universe_domain universe_domain: universe_domain,
+                              endpoint: endpoint,
+                              endpoint_template: endpoint_template,
+                              credentials: credentials
+
+        endpoint_url = self.endpoint
+        endpoint_url = "https://#{endpoint_url}" unless /^https?:/.match? endpoint_url
+        endpoint_url = endpoint_url.sub %r{/$}, ""
 
-        @credentials = credentials
         @numeric_enums = numeric_enums
 
         @raise_faraday_errors = raise_faraday_errors
 
-        @connection = Faraday.new url: @endpoint do |conn|
+        @connection = Faraday.new url: endpoint_url do |conn|
           conn.headers = { "Content-Type" => "application/json" }
-          conn.request :google_authorization, @credentials unless @credentials.is_a? ::Symbol
+          conn.request :google_authorization, self.credentials unless self.credentials.is_a? ::Symbol
           conn.request :retry
           conn.response :raise_error
           conn.adapter :net_http

data/lib/gapic/rest/grpc_transcoder.rb

@@ -117,7 +117,7 @@ module Gapic
           field_value = extract_scalar_value! request_hash, field_path_camel, field_binding.regex
 
           if field_value
-            field_value = field_value.split("/").map { |segment| percent_escape(segment) }.join("/")
+            field_value = field_value.split("/").map { |segment| percent_escape segment }.join("/")
           end
 
           [field_binding.field_path, field_value]
@@ -126,7 +126,7 @@ module Gapic
 
       # Percent-escapes a string.
       # @param str [String] String to escape.
-      # @return str [String] Escaped string.
+      # @return [String] Escaped string.
       def percent_escape str
         # `+` to represent spaces is not currently supported in Showcase server.
         CGI.escape(str).gsub("+", "%20")
@@ -218,7 +218,7 @@ module Gapic
 
         # Covers the case where in `foo.bar.baz`, `baz` is still a submessage or an array.
         return nil if value.is_a?(::Hash) || value.is_a?(::Array)
-        return value.to_s if value.to_s =~ regex
+        value.to_s if value.to_s =~ regex
       end
 
       # Finds a value in the hash by path.

data/lib/gapic/rest/transport_operation.rb

@@ -28,7 +28,7 @@ module Gapic
 
       ##
       # @private
-      # @param request [::Object, nil, ::Faraday::Response]
+      # @param underlying_op [::Object, nil, ::Faraday::Response]
       #   The underlying transport's library object that describes the active call, if any.
       def initialize underlying_op
         @underlying_op = underlying_op

data/lib/gapic/universe_domain_concerns.rb

@@ -0,0 +1,84 @@
+# Copyright 2023 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/common/error"
+
+module Gapic
+  ##
+  # A mixin module that provides methods for obtaining the effective universe
+  # domain, endpoint, and credentials for a stub. This is included in
+  # Grpc::ServiceStub and Rest::ClientStub.
+  #
+  module UniverseDomainConcerns
+    ##
+    # A substitution string for the universe domain in an endpoint template
+    # @return [String]
+    #
+    ENDPOINT_SUBSTITUTION = "$UNIVERSE_DOMAIN$".freeze
+
+    ##
+    # The effective endpoint
+    # @return [String]
+    #
+    attr_reader :endpoint
+
+    ##
+    # The effective universe domain
+    # @return [String]
+    #
+    attr_reader :universe_domain
+
+    ##
+    # The effective credentials
+    #
+    # @return [Google::Auth::Credentials, Signet::OAuth2::Client, Proc,
+    #   ::GRPC::Core::Channel, ::GRPC::Core::ChannelCredentials]
+    #
+    attr_reader :credentials
+
+    protected
+
+    ##
+    # @private
+    # Called from the stub constructor to populate the data.
+    #
+    def setup_universe_domain universe_domain: nil,
+                              endpoint: nil,
+                              endpoint_template: nil,
+                              credentials: nil
+      raise ArgumentError, "endpoint or endpoint_template is required" if endpoint.nil? && endpoint_template.nil?
+      raise ArgumentError, "credentials is required" if credentials.nil?
+
+      # TODO: The env logic should live in google-cloud-env
+      universe_domain ||= ENV["GOOGLE_CLOUD_UNIVERSE_DOMAIN"] || "googleapis.com"
+      endpoint ||= endpoint_template.sub ENDPOINT_SUBSTITUTION, universe_domain
+
+      if credentials.respond_to?(:universe_domain) && credentials.universe_domain != universe_domain
+        raise UniverseDomainMismatch,
+              "Universe domain is #{universe_domain} but credentials are in #{credentials.universe_domain}"
+      end
+
+      @universe_domain = universe_domain
+      @endpoint = endpoint
+      @credentials = credentials
+    end
+  end
+
+  ##
+  # Raised when the configured universe domain does not match the universe
+  # domain of the credentials.
+  #
+  class UniverseDomainMismatch < ::Gapic::Common::Error
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gapic-common
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.21.1
 platform: ruby
 authors:
 - Google API Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-02-27 00:00:00.000000000 Z
+date: 2023-12-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -56,7 +56,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.12
+        version: 1.4.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 2.a
@@ -66,7 +66,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.12
+        version: 1.4.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 2.a
@@ -76,7 +76,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.1
+        version: 1.11.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 2.a
@@ -86,7 +86,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.1
+        version: 1.11.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 2.a
@@ -96,182 +96,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.9'
 - !ruby/object:Gem::Dependency
   name: google-protobuf
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.14'
+        version: '3.18'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.14'
+        version: '3.18'
 - !ruby/object:Gem::Dependency
   name: grpc
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.36'
+        version: '1.59'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.36'
-- !ruby/object:Gem::Dependency
-  name: google-cloud-core
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.5'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.5'
-- !ruby/object:Gem::Dependency
-  name: google-style
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.26.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.26.0
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.16'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.16'
-- !ruby/object:Gem::Dependency
-  name: minitest-autotest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: minitest-focus
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.1'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.1'
-- !ruby/object:Gem::Dependency
-  name: minitest-rg
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.2'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '5.2'
-- !ruby/object:Gem::Dependency
-  name: pry
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.14'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.14'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '12.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '12.0'
-- !ruby/object:Gem::Dependency
-  name: redcarpet
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: yard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.9'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.9'
+        version: '1.59'
 description: 
 email:
 - googleapis-packages@google.com
@@ -300,9 +160,12 @@ files:
 - lib/gapic/grpc.rb
 - lib/gapic/grpc/errors.rb
 - lib/gapic/grpc/service_stub.rb
+- lib/gapic/grpc/service_stub/channel.rb
+- lib/gapic/grpc/service_stub/channel_pool.rb
 - lib/gapic/grpc/service_stub/rpc_call.rb
 - lib/gapic/grpc/status_details.rb
 - lib/gapic/headers.rb
+- lib/gapic/lru_hash.rb
 - lib/gapic/operation.rb
 - lib/gapic/operation/retry_policy.rb
 - lib/gapic/paged_enumerable.rb
@@ -319,6 +182,7 @@ files:
 - lib/gapic/rest/threaded_enumerator.rb
 - lib/gapic/rest/transport_operation.rb
 - lib/gapic/stream_input.rb
+- lib/gapic/universe_domain_concerns.rb
 homepage: https://github.com/googleapis/gapic-generator-ruby
 licenses:
 - Apache-2.0
@@ -331,14 +195,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.2
+rubygems_version: 3.4.19
 signing_key: 
 specification_version: 4
 summary: Common code for GAPIC-generated API clients