feat: use retry policy in regapic templates (#854)

* feat: use retry policy in regapic templates
googleapis · Nov 18, 2022 · b67e8b0 · b67e8b0
1 parent 1ddc351
commit b67e8b0
Show file tree

Hide file tree

Showing 15 changed files with 551 additions and 317 deletions.
diff --git a/gapic-generator/templates/default/service/rest/client/_config.erb b/gapic-generator/templates/default/service/rest/client/_config.erb
@@ -4,7 +4,11 @@
 # Configuration class for the <%= service.name %> REST API.
 #
 # This class represents the configuration for <%= service.name %> REST,
-# providing control over credentials, timeouts, retry behavior, logging. 
+# providing control over timeouts, retry behavior, logging, transport
+# parameters, and other low-level controls. Certain parameters can also be
+# applied individually to specific RPCs. See
+# {<%= service.rest.client_name_full %>::Configuration::Rpcs}
+# for a list of RPCs that can be configured independently.
 #
 # Configuration can be applied globally to all clients, or to a single client
 # on construction.
@@ -13,17 +17,17 @@
 # @example
 #
 #   # Modify the global config, setting the timeout for
-#   # <%= method_service.methods.first.name %> to 20 seconds,
+#   # <%= method_service.rest.methods.first.name %> to 20 seconds,
 #   # and all remaining timeouts to 10 seconds.
-#   <%= service.client_name_full %>.configure do |config|
+#   <%= service.rest.client_name_full %>.configure do |config|
 #     config.timeout = 10.0
-#     config.rpcs.<%= method_service.methods.first.name %>.timeout = 20.0
+#     config.rpcs.<%= method_service.rest.methods.first.name %>.timeout = 20.0
 #   end
 #
 #   # Apply the above configuration only to a new client.
-#   client = <%= service.client_name_full %>.new do |config|
+#   client = <%= service.rest.client_name_full %>.new do |config|
 #     config.timeout = 10.0
-#     config.rpcs.<%= method_service.methods.first.name %>.timeout = 20.0
+#     config.rpcs.<%= method_service.rest.methods.first.name %>.timeout = 20.0
 #   end
 #
 <%- end -%>
@@ -56,6 +60,14 @@
 # @!attribute [rw] metadata
 #   Additional headers to be sent with the call.
 #   @return [::Hash{::Symbol=>::String}]
+# @!attribute [rw] retry_policy
+#   The retry policy. The value is a hash with the following keys:
+#    *  `:initial_delay` (*type:* `Numeric`) - The initial delay in seconds.
+#    *  `:max_delay` (*type:* `Numeric`) - The max delay in seconds.
+#    *  `:multiplier` (*type:* `Numeric`) - The incremental backoff multiplier.
+#    *  `:retry_codes` (*type:* `Array<String>`) - The error codes that should
+#       trigger a retry.
+#   @return [::Hash]
 # @!attribute [rw] quota_project
 #   A separate project against which to charge quota.
 #   @return [::String]
@@ -73,6 +85,7 @@ class Configuration
   config_attr :lib_version,   nil, ::String, nil
   config_attr :timeout,       nil, ::Numeric, nil
   config_attr :metadata,      nil, ::Hash, nil
+  config_attr :retry_policy,  nil, ::Hash, ::Proc, nil
   config_attr :quota_project, nil, ::String, nil
 
   # @private
@@ -102,9 +115,14 @@ class Configuration
   # the following configuration fields:
   #
   #  *  `timeout` (*type:* `Numeric`) - The call timeout in seconds
-  #
-  # there is one other field (`retry_policy`) that can be set
-  # but is currently not supported for REST Gapic libraries.
+  #  *  `metadata` (*type:* `Hash{Symbol=>String}`) - Additional headers
+  #  *  `retry_policy (*type:* `Hash`) - The retry policy. The policy fields
+  #     include the following keys:
+  #      *  `:initial_delay` (*type:* `Numeric`) - The initial delay in seconds.
+  #      *  `:max_delay` (*type:* `Numeric`) - The max delay in seconds.
+  #      *  `:multiplier` (*type:* `Numeric`) - The incremental backoff multiplier.
+  #      *  `:retry_codes` (*type:* `Array<String>`) - The error codes that should
+  #         trigger a retry.
   # 
   class Rpcs
   <%- method_service.rest.methods.each do |method| -%>

diff --git a/gapic-generator/templates/default/service/rest/client/method/def/_options_defaults.erb b/gapic-generator/templates/default/service/rest/client/method/def/_options_defaults.erb
@@ -14,7 +14,9 @@ call_metadata[:"x-goog-api-client"] ||= ::Gapic::Headers.x_goog_api_client \
 call_metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
 
 options.apply_defaults timeout:      @config.rpcs.<%= method.name %>.timeout,
-                       metadata:     call_metadata
+                       metadata:     call_metadata,
+                       retry_policy: @config.rpcs.<%= method.name %>.retry_policy
 
 options.apply_defaults timeout:      @config.timeout,
-                       metadata:     @config.metadata
+                       metadata:     @config.metadata,
+                       retry_policy: @config.retry_policy
diff --git a/gapic-generator/templates/default/service/rest/client/method/docs/_request.erb b/gapic-generator/templates/default/service/rest/client/method/docs/_request.erb
@@ -8,8 +8,6 @@
 #     parameters, or to keep all the default parameter values, pass an empty Hash.
 #   @param options [::Gapic::CallOptions, ::Hash]
 #     Overrides the default settings for this call, e.g, timeout, retries etc. Optional.
-#     Note: currently retry functionality is not implemented. While it is possible
-#     to set it using ::Gapic::CallOptions, it will not be applied
 <%-if method.arguments.any?-%>
 #
 <%- arg_list = method.arguments.map { |arg| "#{arg.name}: nil"}.join ", " -%>

diff --git a/shared/output/cloud/compute_small/lib/google/cloud/compute/v1/addresses/rest/client.rb b/shared/output/cloud/compute_small/lib/google/cloud/compute/v1/addresses/rest/client.rb
@@ -159,8 +159,6 @@ def initialize
               #     parameters, or to keep all the default parameter values, pass an empty Hash.
               #   @param options [::Gapic::CallOptions, ::Hash]
               #     Overrides the default settings for this call, e.g, timeout, retries etc. Optional.
-              #     Note: currently retry functionality is not implemented. While it is possible
-              #     to set it using ::Gapic::CallOptions, it will not be applied
               #
               # @overload aggregated_list(filter: nil, include_all_scopes: nil, max_results: nil, order_by: nil, page_token: nil, project: nil, return_partial_success: nil)
               #   Pass arguments to `aggregated_list` via keyword arguments. Note that at
@@ -218,10 +216,12 @@ def aggregated_list request, options = nil
                 call_metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
 
                 options.apply_defaults timeout:      @config.rpcs.aggregated_list.timeout,
-                                       metadata:     call_metadata
+                                       metadata:     call_metadata,
+                                       retry_policy: @config.rpcs.aggregated_list.retry_policy
 
                 options.apply_defaults timeout:      @config.timeout,
-                                       metadata:     @config.metadata
+                                       metadata:     @config.metadata,
+                                       retry_policy: @config.retry_policy
 
                 @addresses_stub.aggregated_list request, options do |result, response|
                   result = ::Gapic::Rest::PagedEnumerable.new @addresses_stub, :aggregated_list, "items", request, result, options
@@ -248,8 +248,6 @@ def aggregated_list request, options = nil
               #     parameters, or to keep all the default parameter values, pass an empty Hash.
               #   @param options [::Gapic::CallOptions, ::Hash]
               #     Overrides the default settings for this call, e.g, timeout, retries etc. Optional.
-              #     Note: currently retry functionality is not implemented. While it is possible
-              #     to set it using ::Gapic::CallOptions, it will not be applied
               #
               # @overload delete(address: nil, project: nil, region: nil, request_id: nil)
               #   Pass arguments to `delete` via keyword arguments. Note that at
@@ -295,10 +293,12 @@ def delete request, options = nil
                 call_metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
 
                 options.apply_defaults timeout:      @config.rpcs.delete.timeout,
-                                       metadata:     call_metadata
+                                       metadata:     call_metadata,
+                                       retry_policy: @config.rpcs.delete.retry_policy
 
                 options.apply_defaults timeout:      @config.timeout,
-                                       metadata:     @config.metadata
+                                       metadata:     @config.metadata,
+                                       retry_policy: @config.retry_policy
 
                 @addresses_stub.delete request, options do |result, response|
                   result = ::Google::Cloud::Compute::V1::RegionOperations::Rest::NonstandardLro.create_operation(
@@ -333,8 +333,6 @@ def delete request, options = nil
               #     parameters, or to keep all the default parameter values, pass an empty Hash.
               #   @param options [::Gapic::CallOptions, ::Hash]
               #     Overrides the default settings for this call, e.g, timeout, retries etc. Optional.
-              #     Note: currently retry functionality is not implemented. While it is possible
-              #     to set it using ::Gapic::CallOptions, it will not be applied
               #
               # @overload get(address: nil, project: nil, region: nil)
               #   Pass arguments to `get` via keyword arguments. Note that at
@@ -374,10 +372,12 @@ def get request, options = nil
                 call_metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
 
                 options.apply_defaults timeout:      @config.rpcs.get.timeout,
-                                       metadata:     call_metadata
+                                       metadata:     call_metadata,
+                                       retry_policy: @config.rpcs.get.retry_policy
 
                 options.apply_defaults timeout:      @config.timeout,
-                                       metadata:     @config.metadata
+                                       metadata:     @config.metadata,
+                                       retry_policy: @config.retry_policy
 
                 @addresses_stub.get request, options do |result, response|
                   yield result, response if block_given?
@@ -403,8 +403,6 @@ def get request, options = nil
               #     parameters, or to keep all the default parameter values, pass an empty Hash.
               #   @param options [::Gapic::CallOptions, ::Hash]
               #     Overrides the default settings for this call, e.g, timeout, retries etc. Optional.
-              #     Note: currently retry functionality is not implemented. While it is possible
-              #     to set it using ::Gapic::CallOptions, it will not be applied
               #
               # @overload insert(address_resource: nil, project: nil, region: nil, request_id: nil)
               #   Pass arguments to `insert` via keyword arguments. Note that at
@@ -450,10 +448,12 @@ def insert request, options = nil
                 call_metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
 
                 options.apply_defaults timeout:      @config.rpcs.insert.timeout,
-                                       metadata:     call_metadata
+                                       metadata:     call_metadata,
+                                       retry_policy: @config.rpcs.insert.retry_policy
 
                 options.apply_defaults timeout:      @config.timeout,
-                                       metadata:     @config.metadata
+                                       metadata:     @config.metadata,
+                                       retry_policy: @config.retry_policy
 
                 @addresses_stub.insert request, options do |result, response|
                   result = ::Google::Cloud::Compute::V1::RegionOperations::Rest::NonstandardLro.create_operation(
@@ -488,8 +488,6 @@ def insert request, options = nil
               #     parameters, or to keep all the default parameter values, pass an empty Hash.
               #   @param options [::Gapic::CallOptions, ::Hash]
               #     Overrides the default settings for this call, e.g, timeout, retries etc. Optional.
-              #     Note: currently retry functionality is not implemented. While it is possible
-              #     to set it using ::Gapic::CallOptions, it will not be applied
               #
               # @overload list(filter: nil, max_results: nil, order_by: nil, page_token: nil, project: nil, region: nil, return_partial_success: nil)
               #   Pass arguments to `list` via keyword arguments. Note that at
@@ -547,10 +545,12 @@ def list request, options = nil
                 call_metadata[:"x-goog-user-project"] = @quota_project_id if @quota_project_id
 
                 options.apply_defaults timeout:      @config.rpcs.list.timeout,
-                                       metadata:     call_metadata
+                                       metadata:     call_metadata,
+                                       retry_policy: @config.rpcs.list.retry_policy
 
                 options.apply_defaults timeout:      @config.timeout,
-                                       metadata:     @config.metadata
+                                       metadata:     @config.metadata,
+                                       retry_policy: @config.retry_policy
 
                 @addresses_stub.list request, options do |result, response|
                   result = ::Gapic::Rest::PagedEnumerable.new @addresses_stub, :list, "items", request, result, options
@@ -569,7 +569,11 @@ def list request, options = nil
               # Configuration class for the Addresses REST API.
               #
               # This class represents the configuration for Addresses REST,
-              # providing control over credentials, timeouts, retry behavior, logging.
+              # providing control over timeouts, retry behavior, logging, transport
+              # parameters, and other low-level controls. Certain parameters can also be
+              # applied individually to specific RPCs. See
+              # {::Google::Cloud::Compute::V1::Addresses::Rest::Client::Configuration::Rpcs}
+              # for a list of RPCs that can be configured independently.
               #
               # Configuration can be applied globally to all clients, or to a single client
               # on construction.
@@ -579,13 +583,13 @@ def list request, options = nil
               #   # Modify the global config, setting the timeout for
               #   # aggregated_list to 20 seconds,
               #   # and all remaining timeouts to 10 seconds.
-              #   ::Google::Cloud::Compute::V1::Addresses::Client.configure do |config|
+              #   ::Google::Cloud::Compute::V1::Addresses::Rest::Client.configure do |config|
               #     config.timeout = 10.0
               #     config.rpcs.aggregated_list.timeout = 20.0
               #   end
               #
               #   # Apply the above configuration only to a new client.
-              #   client = ::Google::Cloud::Compute::V1::Addresses::Client.new do |config|
+              #   client = ::Google::Cloud::Compute::V1::Addresses::Rest::Client.new do |config|
               #     config.timeout = 10.0
               #     config.rpcs.aggregated_list.timeout = 20.0
               #   end
@@ -619,6 +623,14 @@ def list request, options = nil
               # @!attribute [rw] metadata
               #   Additional headers to be sent with the call.
               #   @return [::Hash{::Symbol=>::String}]
+              # @!attribute [rw] retry_policy
+              #   The retry policy. The value is a hash with the following keys:
+              #    *  `:initial_delay` (*type:* `Numeric`) - The initial delay in seconds.
+              #    *  `:max_delay` (*type:* `Numeric`) - The max delay in seconds.
+              #    *  `:multiplier` (*type:* `Numeric`) - The incremental backoff multiplier.
+              #    *  `:retry_codes` (*type:* `Array<String>`) - The error codes that should
+              #       trigger a retry.
+              #   @return [::Hash]
               # @!attribute [rw] quota_project
               #   A separate project against which to charge quota.
               #   @return [::String]
@@ -636,6 +648,7 @@ class Configuration
                 config_attr :lib_version,   nil, ::String, nil
                 config_attr :timeout,       nil, ::Numeric, nil
                 config_attr :metadata,      nil, ::Hash, nil
+                config_attr :retry_policy,  nil, ::Hash, ::Proc, nil
                 config_attr :quota_project, nil, ::String, nil
 
                 # @private
@@ -665,9 +678,14 @@ def rpcs
                 # the following configuration fields:
                 #
                 #  *  `timeout` (*type:* `Numeric`) - The call timeout in seconds
-                #
-                # there is one other field (`retry_policy`) that can be set
-                # but is currently not supported for REST Gapic libraries.
+                #  *  `metadata` (*type:* `Hash{Symbol=>String}`) - Additional headers
+                #  *  `retry_policy (*type:* `Hash`) - The retry policy. The policy fields
+                #     include the following keys:
+                #      *  `:initial_delay` (*type:* `Numeric`) - The initial delay in seconds.
+                #      *  `:max_delay` (*type:* `Numeric`) - The max delay in seconds.
+                #      *  `:multiplier` (*type:* `Numeric`) - The incremental backoff multiplier.
+                #      *  `:retry_codes` (*type:* `Array<String>`) - The error codes that should
+                #         trigger a retry.
                 #
                 class Rpcs
                   ##