[protobuf] Update protobuf definitions to v1.40.2

api/src/main/proto/envoy/admin/v3/memory.proto

@@ -15,7 +15,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // Proto representation of the internal memory consumption of an Envoy instance. These represent
 // values extracted from an internal TCMalloc instance. For more information, see the section of the
-// docs entitled ["Generic Tcmalloc Status"](https://gperftools.github.io/gperftools/tcmalloc.html).
+// docs entitled `"Generic Tcmalloc Status" <https://gperftools.github.io/gperftools/tcmalloc.html>`_.
 // [#next-free-field: 7]
 message Memory {
   option (udpa.annotations.versioning).previous_message_type = "envoy.admin.v2alpha.Memory";

api/src/main/proto/envoy/admin/v3/mutex_stats.proto

@@ -15,11 +15,11 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // Proto representation of the statistics collected upon absl::Mutex contention, if Envoy is run
 // under :option:`--enable-mutex-tracing`. For more information, see the ``absl::Mutex``
-// [docs](https://abseil.io/about/design/mutex#extra-features).
+// `docs <https://abseil.io/about/design/mutex#extra-features>`__.
 //
 // *NB*: The wait cycles below are measured by ``absl::base_internal::CycleClock``, and may not
 // correspond to core clock frequency. For more information, see the ``CycleClock``
-// [docs](https://github.com/abseil/abseil-cpp/blob/master/absl/base/internal/cycleclock.h).
+// `docs <https://github.com/abseil/abseil-cpp/blob/master/absl/base/internal/cycleclock.h>`__.
 message MutexStats {
   option (udpa.annotations.versioning).previous_message_type = "envoy.admin.v2alpha.MutexStats";
 

api/src/main/proto/envoy/config/bootstrap/v3/bootstrap.proto

@@ -431,7 +431,8 @@ message Bootstrap {
   GrpcAsyncClientManagerConfig grpc_async_client_manager_config = 40;
 
   // Optional configuration for memory allocation manager.
-  // Memory releasing is only supported for `tcmalloc allocator <https://github.com/google/tcmalloc>`_.
+  // Memory releasing is supported with `tcmalloc <https://github.com/google/tcmalloc>`_ and
+  // `gperftools <https://github.com/gperftools/gperftools>`_.
   MemoryAllocatorManager memory_allocator_manager = 41;
 
   // When enabled, Envoy pins each worker thread to a distinct CPU from the process affinity mask,
@@ -790,13 +791,14 @@ message CustomInlineHeader {
 
 // [#next-free-field: 6]
 message MemoryAllocatorManager {
-  // Configures tcmalloc to perform background release of free memory in amount of bytes per ``memory_release_interval`` interval.
-  // If equals to ``0``, no memory release will occur. Defaults to ``0``.
+  // Configures tcmalloc to perform background release of free memory in amount of bytes per
+  // ``memory_release_interval`` interval. If equals to ``0``, no memory release will occur.
+  // Defaults to ``0``.
   uint64 bytes_to_release = 1;
 
-  // Interval in milliseconds for memory releasing. If specified, during every
-  // interval Envoy will try to release ``bytes_to_release`` of free memory back to operating system for reuse.
-  // Defaults to ``1000`` milliseconds.
+  // Interval in milliseconds for memory releasing. If specified, during every interval Envoy will
+  // try to release ``bytes_to_release`` of free memory back to operating system for reuse. If set
+  // to ``0``, no memory release will occur. Defaults to ``1000`` milliseconds.
   google.protobuf.Duration memory_release_interval = 2;
 
   // Sets the soft memory limit for tcmalloc. When the total memory used by tcmalloc exceeds this

api/src/main/proto/envoy/config/cluster/v3/cluster.proto

@@ -13,6 +13,8 @@ import "envoy/config/core/v3/health_check.proto";
 import "envoy/config/core/v3/protocol.proto";
 import "envoy/config/core/v3/resolver.proto";
 import "envoy/config/endpoint/v3/endpoint.proto";
+import "envoy/config/metrics/v3/stats.proto";
+import "envoy/type/matcher/v3/metadata.proto";
 import "envoy/type/metadata/v3/metadata.proto";
 import "envoy/type/v3/percent.proto";
 
@@ -46,7 +48,7 @@ message ClusterCollection {
 }
 
 // Configuration for a single upstream cluster.
-// [#next-free-field: 61]
+// [#next-free-field: 63]
 message Cluster {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Cluster";
 
@@ -753,6 +755,18 @@ message Cluster {
     // harm latency more than the preconnecting helps.
     google.protobuf.DoubleValue predictive_preconnect_ratio = 2
         [(validate.rules).double = {lte: 3.0 gte: 1.0}];
+
+    // Restricts anticipatory connections to hosts whose endpoint metadata matches this matcher.
+    // Non-matching hosts are never preconnected, and instead get connections only on demand, as they
+    // serve real requests. If unset, all healthy hosts are eligible.
+    type.matcher.v3.MetadataMatcher preconnect_enabled_metadata = 3;
+  }
+
+  // Queueing policies for the cluster.
+  message QueuingPolicies {
+    // Queue policy for cluster pending requests. If unset, Envoy uses the FIFO queue policy.
+    // [#extension-category: envoy.queue_policy]
+    core.v3.TypedExtensionConfig pending_rq_policy = 1;
   }
 
   reserved 12, 15, 7, 11, 35;
@@ -866,6 +880,12 @@ message Cluster {
   //   :ref:`Router Filter Header <config_http_filters_router_x-envoy-upstream-alt-stat-name>`.
   string alt_stat_name = 28 [(udpa.annotations.field_migrate).rename = "observability_name"];
 
+  // Optional stats matcher that can be used to configure which stats are instantiated for this
+  // cluster. If configured, this overrides the bootstrap :ref:`stats_config
+  // <envoy_v3_api_field_config.bootstrap.v3.Bootstrap.stats_config>` stats matcher configuration
+  // for this cluster.
+  metrics.v3.StatsMatcher stats_matcher = 61;
+
   oneof cluster_discovery_type {
     // The :ref:`service discovery type <arch_overview_service_discovery_types>`
     // to use for resolving the cluster.
@@ -914,7 +934,7 @@ message Cluster {
   // configuration for the cluster. If no
   // configuration is specified no health checking will be done and all cluster
   // members will be considered healthy at all times.
-  repeated core.v3.HealthCheck health_checks = 8;
+  repeated core.v3.HealthCheck health_checks = 8 [(validate.rules).repeated = {max_items: 8}];
 
   // Optional maximum requests for a single upstream connection. This parameter
   // is respected by both the HTTP/1.1 and HTTP/2 connection pool
@@ -1303,6 +1323,9 @@ message Cluster {
   // If ``connection_pool_per_downstream_connection`` is true, the cluster will use a separate
   // connection pool for every downstream connection
   bool connection_pool_per_downstream_connection = 51;
+
+  // Queueing policies for the cluster (e.g. the queue policy for cluster pending requests).
+  QueuingPolicies queuing_policies = 62;
 }
 
 // Extensible load balancing policy configuration.

api/src/main/proto/envoy/config/core/v3/address.proto

@@ -103,7 +103,7 @@ message SocketAddress {
   // network namespace.
   //
   // .. note::
-  //    Setting this parameter requires Envoy to run with the ``CAP_NET_ADMIN`` capability.
+  //    Setting this parameter requires Envoy to run with the ``CAP_SYS_ADMIN`` capability.
   //
   // .. attention::
   //     Network namespaces are only configurable on Linux. Otherwise, this field has no effect.
@@ -144,7 +144,7 @@ message ExtraSourceAddress {
   SocketOptionsOverride socket_options = 2;
 }
 
-// [#next-free-field: 7]
+// [#next-free-field: 8]
 message BindConfig {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.BindConfig";
 
@@ -180,6 +180,24 @@ message BindConfig {
   // <envoy_v3_api_msg_config.upstream.local_address_selector.v3.DefaultLocalAddressSelector>`).
   // [#extension-category: envoy.upstream.local_address_selector]
   TypedExtensionConfig local_address_selector = 6;
+
+  // If set to true, the :ref:`network_namespace_filepath
+  // <envoy_v3_api_field_config.core.v3.SocketAddress.network_namespace_filepath>` of every source
+  // address in this bind config is validated when the configuration is loaded, and the
+  // configuration is rejected if a referenced network namespace cannot be opened.
+  //
+  // By default no such validation is performed: a network namespace that does not exist when the
+  // configuration is loaded may be created later, before connections are actually established, so
+  // eager validation would wrongly reject such configurations. If a namespace is unavailable when
+  // a connection is created, the connection attempt fails gracefully.
+  //
+  // Listener addresses do not need an equivalent option: a listener creates and binds its socket
+  // in the configured network namespace when the listener configuration is loaded, so an
+  // unavailable namespace always rejects the listener configuration.
+  //
+  // .. attention::
+  //     Network namespaces are only configurable on Linux. Otherwise, this field has no effect.
+  bool validate_network_namespaces = 7;
 }
 
 // Addresses specify either a logical or physical address and port, which are

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

@@ -486,6 +486,11 @@ message HeaderValueOption {
 
   // Is the header value allowed to be empty? If false (default), custom headers with empty values are dropped,
   // otherwise they are added.
+  //
+  // .. note::
+  //   In any context other than the router filter, we always act as if keep_empty_value is true,
+  //   regardless of the setting of this field.
+  //
   bool keep_empty_value = 4;
 }
 

api/src/main/proto/envoy/config/core/v3/config_source.proto

@@ -157,22 +157,25 @@ message RateLimitSettings {
 
 // Local filesystem path configuration source.
 message PathConfigSource {
-  // Path on the filesystem to source and watch for configuration updates.
-  // When sourcing configuration for a :ref:`secret <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.Secret>`,
-  // the certificate and key files are also watched for updates.
+  // Path on the filesystem from which to source configuration updates.
+  // When sourcing configuration for a
+  // :ref:`secret <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.Secret>`, file-based secret
+  // data supported for SDS rotation is also monitored for updates.
   //
   // .. note::
   //
   //  The path to the source must exist at config load time.
   //
   // .. note::
   //
-  //   If ``watched_directory`` is *not* configured, Envoy will watch the file path for *moves*.
-  //   This is because in general only moves are atomic. The same method of swapping files as is
-  //   demonstrated in the :ref:`runtime documentation <config_runtime_symbolic_link_swap>` can be
-  //   used here also. If ``watched_directory`` is configured, no watch will be placed directly on
-  //   this path. Instead, the configured ``watched_directory`` will be used to trigger reloads of
-  //   this path. This is required in certain deployment scenarios. See below for more information.
+  //   If neither ``poll_interval`` nor ``watched_directory`` is configured, Envoy will watch the
+  //   file path for *moves*. This is because in general only moves are atomic. The same method of
+  //   swapping files as is demonstrated in the
+  //   :ref:`runtime documentation <config_runtime_symbolic_link_swap>` can be used here also.
+  //   One of ``poll_interval`` and ``watched_directory`` can also be configured; the configuration
+  //   is rejected if both are set. With ``poll_interval``, the same path is reloaded periodically.
+  //   With ``watched_directory``, no watch is placed directly on this path; events in the
+  //   configured directory trigger this path to be reloaded.
   string path = 1 [(validate.rules).string = {min_len: 1}];
 
   // If configured, this directory will be watched for *moves*. When an entry in this directory is
@@ -188,7 +191,24 @@ message PathConfigSource {
   //
   // The above configuration will ensure that Envoy watches the owning directory for moves which is
   // required due to how Kubernetes manages ConfigMap symbolic links during atomic updates.
+  //
+  // This field cannot be used together with ``poll_interval``.
   WatchedDirectory watched_directory = 2;
+
+  // If configured, the ``path`` will be polled at this interval instead of watched for filesystem
+  // events on either the file or ``watched_directory``. This is useful when the underlying
+  // filesystem does not reliably provide change notifications, or when a custom deployment model
+  // does not generate the move or modification events handled by watching the path or directory.
+  // The file is read on every poll, but an update is delivered only when its parsed contents
+  // change.
+  //
+  // When this configuration source provides a
+  // :ref:`Secret <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.Secret>`, the same secret
+  // files that are watched in event-based mode are polled at this interval. The last successfully
+  // loaded configuration or secret remains active when a poll fails.
+  //
+  // This field cannot be used together with ``watched_directory`` and must be at least 1ms.
+  google.protobuf.Duration poll_interval = 3 [(validate.rules).duration = {gte {nanos: 1000000}}];
 }
 
 // Configuration for :ref:`listeners <config_listeners>`, :ref:`clusters

api/src/main/proto/envoy/config/core/v3/health_check.proto

@@ -63,7 +63,7 @@ message HealthStatusSet {
       [(validate.rules).repeated = {items {enum {defined_only: true}}}];
 }
 
-// [#next-free-field: 27]
+// [#next-free-field: 28]
 message HealthCheck {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.HealthCheck";
 
@@ -83,7 +83,7 @@ message HealthCheck {
     }
   }
 
-  // [#next-free-field: 15]
+  // [#next-free-field: 16]
   message HttpHealthCheck {
     option (udpa.annotations.versioning).previous_message_type =
         "envoy.api.v2.core.HealthCheck.HttpHealthCheck";
@@ -152,9 +152,24 @@ message HealthCheck {
     // non-200 response will result in the host being marked unhealthy.
     repeated type.v3.Int64Range retriable_statuses = 12;
 
-    // Use specified application protocol for health checks.
+    // Use specified application protocol for health checks. With :ref:`use_alpn_protocol
+    // <envoy_v3_api_field_config.core.v3.HealthCheck.HttpHealthCheck.use_alpn_protocol>` this is
+    // the codec used when ALPN settles on neither ``h2`` nor ``http/1.1``.
     type.v3.CodecClientType codec_client_type = 10 [(validate.rules).enum = {defined_only: true}];
 
+    // Select the codec from the protocol negotiated by ALPN on the health check connection: HTTP/2
+    // when ``h2`` is negotiated, HTTP/1.1 when ``http/1.1`` is negotiated, and otherwise
+    // ``codec_client_type``, including when nothing is negotiated. With ``codec_client_type`` at
+    // its default this is the same mapping as the cluster's :ref:`auto_config
+    // <envoy_v3_api_field_extensions.upstreams.http.v3.HttpProtocolOptions.auto_config>`. Like
+    // ``auto_config``, it requires a transport socket that supports ALPN such as TLS and is
+    // rejected on a cluster whose transport sockets do not, unless the
+    // ``config.do_not_validate_alpn_support`` runtime key is set, as for ``auto_config``. It
+    // cannot be combined with ``codec_client_type`` ``HTTP3``. See :ref:`tls_options
+    // <envoy_v3_api_field_config.core.v3.HealthCheck.tls_options>` for what the connection
+    // advertises.
+    bool use_alpn_protocol = 15;
+
     // An optional service name parameter which is used to validate the identity of
     // the health checked cluster using a :ref:`StringMatcher
     // <envoy_v3_api_msg_type.matcher.v3.StringMatcher>`. See the :ref:`architecture overview
@@ -260,12 +275,21 @@ message HealthCheck {
     // Specifies the ALPN protocols for health check connections. This is useful if the
     // corresponding upstream is using ALPN-based :ref:`FilterChainMatch
     // <envoy_v3_api_msg_config.listener.v3.FilterChainMatch>` along with different protocols for health checks
-    // versus data connections. If empty, no ALPN protocols will be set on health check connections.
+    // versus data connections. If empty, health check connections advertise the ALPN protocols of
+    // the cluster's TLS context, if any. With :ref:`use_alpn_protocol
+    // <envoy_v3_api_field_config.core.v3.HealthCheck.HttpHealthCheck.use_alpn_protocol>`,
+    // the negotiated protocol selects the health check codec.
     repeated string alpn_protocols = 1;
   }
 
   reserved 10;
 
+  // Optional name for this health checker. When set, per-checker stats are emitted under
+  // ``health_check.name.<name>.<stat>`` instead of ``health_check.<stat>``.
+  //
+  // This is required if multiple health checks are configured on a cluster.
+  string name = 27;
+
   // The time to wait for a health check response. If the timeout is reached the
   // health check attempt will be considered a failure.
   google.protobuf.Duration timeout = 1 [(validate.rules).duration = {

api/src/main/proto/envoy/config/core/v3/proxy_protocol.proto

@@ -109,6 +109,7 @@ message ProxyProtocolConfig {
 }
 
 message PerHostConfig {
-  // Enables per-host configuration for Proxy Protocol.
+  // Enables per-host configuration for Proxy Protocol. Only the static ``value`` of each
+  // ``TlvEntry`` is applied to host-level TLVs. The ``format_string`` field is not evaluated here.
   repeated TlvEntry added_tlvs = 1;
 }

api/src/main/proto/envoy/config/core/v3/substitution_format_string.proto

@@ -105,13 +105,11 @@ message SubstitutionFormatString {
   //
   // * for ``text_format``, the output of the empty operator is changed from ``-`` to an
   //   empty string, so that empty values are omitted entirely.
-  // * for ``json_format`` the keys with null values are omitted in the output structure.
-  //
-  // .. note::
-  //   This option does not work perfectly with ``json_format`` as keys with ``null`` values
-  //   will still be included in the output. See https://github.com/envoyproxy/envoy/issues/37941
-  //   for more details.
+  // * for ``json_format``, the keys with null values are omitted in the output structure. Nested
+  //   objects whose values are all omitted are removed as well, while empty arrays are preserved.
+  //   The root object is always emitted, so a fully empty structure is rendered as ``{}``.
   //
+  // Defaults to false.
   bool omit_empty_values = 3;
 
   // Specify a ``content_type`` field.