datasource: retry policy for remote data source (envoyproxy#9463)

Implement a retry policy for remote data sources.

Risk Level: Low
Testing: Unit test
Docs Changes: N/A
Release Notes: added
Fixes: envoyproxy#9438

Signed-off-by: Yan Xue <[email protected]>

Author: yxue

api/envoy/api/v2/core/backoff.proto

@@ -0,0 +1,33 @@
+syntax = "proto3";
+
+package envoy.api.v2.core;
+
+import "google/protobuf/duration.proto";
+
+import "udpa/annotations/migrate.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.api.v2.core";
+option java_outer_classname = "BackoffProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_migrate).move_to_package = "envoy.config.core.v3";
+
+// [#protodoc-title: Backoff Strategy]
+
+// Configuration defining a jittered exponential back off strategy.
+message BackoffStrategy {
+  // The base interval to be used for the next back off computation. It should
+  // be greater than zero and less than or equal to :ref:`max_interval
+  // <envoy_api_field_core.BackoffStrategy.max_interval>`.
+  google.protobuf.Duration base_interval = 1 [(validate.rules).duration = {
+    required: true
+    gte {nanos: 1000000}
+  }];
+
+  // Specifies the maximum interval between retries. This parameter is optional,
+  // but must be greater than or equal to the :ref:`base_interval
+  // <envoy_api_field_core.BackoffStrategy.base_interval>` if set. The default
+  // is 10 times the :ref:`base_interval
+  // <envoy_api_field_core.BackoffStrategy.base_interval>`.
+  google.protobuf.Duration max_interval = 2 [(validate.rules).duration = {gt {}}];
+}

api/envoy/api/v2/core/base.proto

@@ -2,11 +2,13 @@ syntax = "proto3";
 
 package envoy.api.v2.core;
 
+import "envoy/api/v2/core/backoff.proto";
 import "envoy/api/v2/core/http_uri.proto";
 import "envoy/type/percent.proto";
 import "envoy/type/semantic_version.proto";
 
 import "google/protobuf/any.proto";
+import "google/protobuf/duration.proto";
 import "google/protobuf/struct.proto";
 import "google/protobuf/wrappers.proto";
 
@@ -277,13 +279,28 @@ message DataSource {
   }
 }
 
+// The message specifies the retry policy of remote data source when fetching fails.
+message RetryPolicy {
+  // Specifies parameters that control :ref:`retry backoff strategy <envoy_api_msg_core.BackoffStrategy>`.
+  // This parameter is optional, in which case the default base interval is 1000 milliseconds. The
+  // default maximum interval is 10 times the base interval.
+  BackoffStrategy retry_back_off = 1;
+
+  // Specifies the allowed number of retries. This parameter is optional and
+  // defaults to 1.
+  google.protobuf.UInt32Value num_retries = 2;
+}
+
 // The message specifies how to fetch data from remote and how to verify it.
 message RemoteDataSource {
   // The HTTP URI to fetch the remote data.
   HttpUri http_uri = 1 [(validate.rules).message = {required: true}];
 
   // SHA256 string for verifying data.
   string sha256 = 2 [(validate.rules).string = {min_bytes: 1}];
+
+  // Retry policy for fetching remote data.
+  RetryPolicy retry_policy = 3;
 }
 
 // Async data source which support async data fetch.

api/envoy/config/core/v3/backoff.proto

@@ -0,0 +1,35 @@
+syntax = "proto3";
+
+package envoy.config.core.v3;
+
+import "google/protobuf/duration.proto";
+
+import "udpa/annotations/versioning.proto";
+
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.config.core.v3";
+option java_outer_classname = "BackoffProto";
+option java_multiple_files = true;
+
+// [#protodoc-title: Backoff Strategy]
+
+// Configuration defining a jittered exponential back off strategy.
+message BackoffStrategy {
+  option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.BackoffStrategy";
+
+  // The base interval to be used for the next back off computation. It should
+  // be greater than zero and less than or equal to :ref:`max_interval
+  // <envoy_api_field_config.core.v3.BackoffStrategy.max_interval>`.
+  google.protobuf.Duration base_interval = 1 [(validate.rules).duration = {
+    required: true
+    gte {nanos: 1000000}
+  }];
+
+  // Specifies the maximum interval between retries. This parameter is optional,
+  // but must be greater than or equal to the :ref:`base_interval
+  // <envoy_api_field_config.core.v3.BackoffStrategy.base_interval>` if set. The default
+  // is 10 times the :ref:`base_interval
+  // <envoy_api_field_config.core.v3.BackoffStrategy.base_interval>`.
+  google.protobuf.Duration max_interval = 2 [(validate.rules).duration = {gt {}}];
+}

api/envoy/config/core/v3/base.proto

@@ -2,11 +2,13 @@ syntax = "proto3";
 
 package envoy.config.core.v3;
 
+import "envoy/config/core/v3/backoff.proto";
 import "envoy/config/core/v3/http_uri.proto";
 import "envoy/type/v3/percent.proto";
 import "envoy/type/v3/semantic_version.proto";
 
 import "google/protobuf/any.proto";
+import "google/protobuf/duration.proto";
 import "google/protobuf/struct.proto";
 import "google/protobuf/wrappers.proto";
 
@@ -299,6 +301,20 @@ message DataSource {
   }
 }
 
+// The message specifies the retry policy of remote data source when fetching fails.
+message RetryPolicy {
+  option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.RetryPolicy";
+
+  // Specifies parameters that control :ref:`retry backoff strategy <envoy_api_msg_config.core.v3.BackoffStrategy>`.
+  // This parameter is optional, in which case the default base interval is 1000 milliseconds. The
+  // default maximum interval is 10 times the base interval.
+  BackoffStrategy retry_back_off = 1;
+
+  // Specifies the allowed number of retries. This parameter is optional and
+  // defaults to 1.
+  google.protobuf.UInt32Value num_retries = 2;
+}
+
 // The message specifies how to fetch data from remote and how to verify it.
 message RemoteDataSource {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.RemoteDataSource";
@@ -308,6 +324,9 @@ message RemoteDataSource {
 
   // SHA256 string for verifying data.
   string sha256 = 2 [(validate.rules).string = {min_bytes: 1}];
+
+  // Retry policy for fetching remote data.
+  RetryPolicy retry_policy = 3;
 }
 
 // Async data source which support async data fetch.

docs/root/api-v2/common_messages/common_messages.rst

@@ -7,6 +7,7 @@ Common messages
 
   ../api/v2/core/base.proto
   ../api/v2/core/address.proto
+  ../api/v2/core/backoff.proto
   ../api/v2/core/protocol.proto
   ../api/v2/discovery.proto
   ../api/v2/core/config_source.proto

docs/root/api-v3/common_messages/common_messages.rst

@@ -7,6 +7,7 @@ Common messages
 
   ../config/core/v3/base.proto
   ../config/core/v3/address.proto
+  ../config/core/v3/backoff.proto
   ../config/core/v3/protocol.proto
   ../service/discovery/v3/discovery.proto
   ../config/core/v3/config_source.proto

docs/root/intro/version_history.rst

@@ -10,6 +10,7 @@ Version history
 * admin: added support for displaying ip address subject alternate names in :ref:`certs<operations_admin_interface_certs>` end point.
 * buffer: force copy when appending small slices to OwnedImpl buffer to avoid fragmentation.
 * config: use type URL to select an extension whenever the config type URL (or its previous versions) uniquely identify a typed extension, see :ref:`extension configuration <config_overview_extension_configuration>`.
+* datasource: added retry policy for remote async data source.
 * dns: the STRICT_DNS cluster now only resolves to 0 hosts if DNS resolution successfully returns 0 hosts.
 * dns: added support for :ref:`dns_failure_refresh_rate <envoy_api_field_config.common.dynamic_forward_proxy.v2alpha.DnsCacheConfig.dns_failure_refresh_rate>` for the :ref:`dns cache <envoy_api_msg_config.common.dynamic_forward_proxy.v2alpha.DnsCacheConfig>` to set the DNS refresh rate during failures.
 * http filters: http filter extensions use the "envoy.filters.http" name space. A mapping

generated_api_shadow/envoy/api/v2/core/backoff.proto

@@ -52,6 +52,7 @@ envoy_cc_library(
         "//include/envoy/api:api_interface",
         "//include/envoy/init:manager_interface",
         "//include/envoy/upstream:cluster_manager_interface",
+        "//source/common/common:backoff_lib",
         "//source/common/common:empty_string",
         "//source/common/init:target_lib",
         "//source/common/protobuf:utility_lib",