From 7c5957ac69b9559bc1529c853c48a71f71d489cb Mon Sep 17 00:00:00 2001 From: Kannan J Date: Mon, 31 Aug 2026 11:27:35 +0000 Subject: [PATCH 1/2] Import the latest commit of envoyproxy protos. --- xds/third_party/envoy/import.sh | 2 +- .../envoy/config/bootstrap/v3/bootstrap.proto | 72 ++- .../config/cluster/v3/circuit_breaker.proto | 20 + .../envoy/config/cluster/v3/cluster.proto | 39 +- .../config/cluster/v3/outlier_detection.proto | 17 +- .../proto/envoy/config/core/v3/address.proto | 3 +- .../proto/envoy/config/core/v3/base.proto | 17 + .../envoy/config/core/v3/http_service.proto | 9 +- .../proto/envoy/config/core/v3/protocol.proto | 115 ++++- .../envoy/config/core/v3/socket_option.proto | 20 +- .../core/v3/substitution_format_string.proto | 10 +- .../endpoint/v3/endpoint_components.proto | 17 +- .../envoy/config/listener/v3/listener.proto | 76 ++- .../proto/envoy/config/metrics/v3/stats.proto | 14 + .../envoy/config/overload/v3/overload.proto | 16 + .../config/route/v3/route_components.proto | 150 +++++- .../envoy/config/trace/v3/opentelemetry.proto | 28 +- .../proto/envoy/config/trace/v3/zipkin.proto | 8 +- .../envoy/data/accesslog/v3/accesslog.proto | 1 + .../filters/http/composite/v3/composite.proto | 29 ++ .../filters/http/ext_authz/v3/ext_authz.proto | 78 ++- .../filters/http/ext_proc/v3/ext_proc.proto | 37 +- .../http/ext_proc/v3/processing_mode.proto | 152 +++--- .../filters/http/gcp_authn/v3/gcp_authn.proto | 26 +- .../v3/rate_limit_quota.proto | 2 - .../v3/http_connection_manager.proto | 148 +++++- .../v3/client_side_weighted_round_robin.proto | 35 +- .../common/v3/common.proto | 27 ++ .../v3/upstream_http_11_connect.proto | 8 + .../transport_sockets/tls/v3/common.proto | 63 ++- .../transport_sockets/tls/v3/tls.proto | 25 +- .../ext_proc/v3/external_processor.proto | 457 +++++++++++------- .../service/rate_limit_quota/v3/rlqs.proto | 3 - .../proto/envoy/type/matcher/v3/address.proto | 6 + .../src/main/proto/envoy/type/v3/http.proto | 5 - .../proto/envoy/type/v3/token_bucket.proto | 5 +- 36 files changed, 1374 insertions(+), 366 deletions(-) diff --git a/xds/third_party/envoy/import.sh b/xds/third_party/envoy/import.sh index 55481d29b76..97ad0e90aa9 100755 --- a/xds/third_party/envoy/import.sh +++ b/xds/third_party/envoy/import.sh @@ -17,7 +17,7 @@ set -e # import VERSION from the google internal go/envoy-import-status -VERSION=a0b3df32ba54c92a08d3636a9a36013cb920e471 +VERSION=ddf9f6788e3b5c103c496784f04890acbc6628e5 DOWNLOAD_URL="https://github.com/envoyproxy/envoy/archive/${VERSION}.tar.gz" DOWNLOAD_BASE_DIR="envoy-${VERSION}" SOURCE_PROTO_BASE_DIR="${DOWNLOAD_BASE_DIR}/api" diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/bootstrap/v3/bootstrap.proto b/xds/third_party/envoy/src/main/proto/envoy/config/bootstrap/v3/bootstrap.proto index 7b862c1021a..90c2b62d5c5 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/bootstrap/v3/bootstrap.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/bootstrap/v3/bootstrap.proto @@ -42,7 +42,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // ` for more detail. // Bootstrap :ref:`configuration overview `. -// [#next-free-field: 43] +// [#next-free-field: 44] message Bootstrap { option (udpa.annotations.versioning).previous_message_type = "envoy.config.bootstrap.v2.Bootstrap"; @@ -433,6 +433,17 @@ message Bootstrap { // Optional configuration for memory allocation manager. // Memory releasing is only supported for `tcmalloc allocator `_. MemoryAllocatorManager memory_allocator_manager = 41; + + // When enabled, Envoy pins each worker thread to a distinct CPU from the process affinity mask, + // worker ``i`` to the ``i-th`` CPU in ascending order. This improves CPU cache and ``NUMA`` + // locality for high concurrency deployments on bare metal. It is available on Linux only and is + // ignored on other platforms. Pinning requires a worker count no greater than the number of CPUs + // in the process affinity mask. When the worker count exceeds the available CPUs no worker is + // pinned. Pinning is applied once when the workers start, so a later change to the process + // affinity mask does not re-pin. + // + // Defaults to ``false``. + bool enable_worker_cpu_affinity = 43; } // Administration interface :ref:`operations documentation @@ -469,6 +480,8 @@ message Admin { bool ignore_global_conn_limit = 6; // List of admin paths that are accessible. If not specified, all admin endpoints are accessible. + // Matchers are evaluated against the request path. For endpoints commonly queried with + // parameters (for example ``/stats?format=...``), prefer ``prefix`` matchers. // // When specified, only paths in this list will be accessible, all others will return ``HTTP 403 Forbidden``. // @@ -477,7 +490,8 @@ message Admin { // .. code-block:: yaml // // allow_paths: - // - exact: /stats + // - prefix: /stats + // - prefix: /config_dump // - exact: /ready // - prefix: /healthcheck // @@ -774,6 +788,7 @@ message CustomInlineHeader { InlineHeaderType inline_header_type = 2 [(validate.rules).enum = {defined_only: true}]; } +// [#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``. @@ -783,4 +798,57 @@ message MemoryAllocatorManager { // interval Envoy will try to release ``bytes_to_release`` of free memory back to operating system for reuse. // 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 + // limit, background release will be performed more aggressively to bring memory usage below the + // limit. If not set, no soft memory limit is applied. + // + // .. note:: + // This is currently only supported with tcmalloc and not with ``gperftools``. + // + google.protobuf.UInt64Value soft_memory_limit_bytes = 3; + + // Sets the maximum per-CPU cache size in bytes for tcmalloc. Smaller values reduce per-CPU + // memory overhead at the cost of increased contention on the central free list. If not set, + // tcmalloc's default is used. + // + // .. note:: + // This is currently only supported with tcmalloc and not with ``gperftools``. + // + google.protobuf.UInt32Value max_per_cpu_cache_size_bytes = 4; + + // The threshold of unfreed memory in bytes that triggers the heap shrinker to release memory + // back to the OS. When the difference between physical memory used and application-allocated + // memory exceeds this threshold, free memory is released. + // + // Defaults to ``104857600`` (100 MB). + uint64 max_unfreed_memory_bytes = 5; +} + +// A placeholder proto so that users can explicitly configure the standard +// Listener Manager via the bootstrap's :ref:`listener_manager `. +// [#not-implemented-hide:] +message ListenerManager { +} + +// A placeholder proto so that users can explicitly configure the standard +// Validation Listener Manager via the bootstrap's :ref:`listener_manager `. +// [#not-implemented-hide:] +message ValidationListenerManager { +} + +// A placeholder proto so that users can explicitly configure the API +// Listener Manager via the bootstrap's :ref:`listener_manager `. +// [#not-implemented-hide:] +message ApiListenerManager { + enum ThreadingModel { + // Handle HTTP requests on the main Envoy thread which also processes platform-raised events and runs xDS clients. + MAIN_THREAD_ONLY = 0; + + // Handle HTTP requests on a standalone worker thread. + STANDALONE_WORKER_THREAD = 1; + } + + // Default to MainThreadOnly. + ThreadingModel threading_model = 1; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/circuit_breaker.proto b/xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/circuit_breaker.proto index fe798ceb090..fdc0af5460a 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/circuit_breaker.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/circuit_breaker.proto @@ -5,6 +5,7 @@ package envoy.config.cluster.v3; import "envoy/config/core/v3/base.proto"; import "envoy/type/v3/percent.proto"; +import "google/protobuf/duration.proto"; import "google/protobuf/wrappers.proto"; import "udpa/annotations/status.proto"; @@ -43,6 +44,25 @@ message CircuitBreakers { // This parameter is optional. Defaults to 20%. type.v3.Percent budget_percent = 1; + // An optional duration in which requests will be considered when calculating + // the budget for retries. This parameter alters the way in which the retry budget + // is calculated, overriding the default behavior when specified. + // + // By default, when budget_interval is set to 0ms, only presently active + // and pending requests are considered when calculating the retry budget. + // + // When a non-zero budget_interval is specified, new requests are + // considered for the duration of budget_interval when calculating + // the retry budget. + // + // For example, if 10 requests start at the same time, with a specified budget_interval + // of 100ms, all 10 requests will be considered when calculating the retry + // budget for the next 100ms, regardless of if they have completed. + // All 10 requests will expire after the budget_interval duration. + // + // This parameter is optional. Defaults to 0ms. + google.protobuf.Duration budget_interval = 3; + // Specifies the minimum retry concurrency allowed for the retry budget. The limit on the // number of active retries may never go below this number. // diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/cluster.proto b/xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/cluster.proto index 192409096af..f9ae4dd194b 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/cluster.proto +++ b/xds/third_party/envoy/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: 60] +// [#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 `. 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 + // ` stats matcher configuration + // for this cluster. + metrics.v3.StatsMatcher stats_matcher = 61; + oneof cluster_discovery_type { // The :ref:`service discovery type ` // to use for resolving the cluster. @@ -887,6 +907,12 @@ message Cluster { google.protobuf.UInt32Value per_connection_buffer_limit_bytes = 5 [(udpa.annotations.security).configure_for_untrusted_upstream = true]; + // Optional timeout that controls how long an upstream connection is allowed to stay above the + // configured buffer high watermark before it is closed. If this timeout is not specified, or + // explicitly set to 0, connections will not be closed due to buffer high watermark usage. + google.protobuf.Duration per_connection_buffer_high_watermark_timeout = 60 + [(validate.rules).duration = {gte {}}]; + // The :ref:`load balancer type ` to use // when picking a host in the cluster. LbPolicy lb_policy = 6 [(validate.rules).enum = {defined_only: true}]; @@ -1297,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. @@ -1343,14 +1372,18 @@ message UpstreamConnectionOptions { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.UpstreamConnectionOptions"; + // [#comment: Keep this list of address types in sync with api/config/core/v3/address.proto.] enum FirstAddressFamilyVersion { - // respect the native ranking of destination ip addresses returned from dns - // resolution + // Use the first address family encountered in the address list. DEFAULT = 0; V4 = 1; V6 = 2; + + PIPE = 3; + + INTERNAL = 4; } message HappyEyeballsConfig { diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/outlier_detection.proto b/xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/outlier_detection.proto index 822d81da850..2cd3bb943e4 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/outlier_detection.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/cluster/v3/outlier_detection.proto @@ -21,7 +21,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // See the :ref:`architecture overview ` for // more information on outlier detection. -// [#next-free-field: 26] +// [#next-free-field: 27] message OutlierDetection { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.cluster.OutlierDetection"; @@ -29,6 +29,8 @@ message OutlierDetection { // The number of consecutive server-side error responses (for HTTP traffic, // 5xx responses; for TCP traffic, connection failures; for Redis, failure to // respond PONG; etc.) before a consecutive 5xx ejection occurs. Defaults to 5. + // + // If set to 0 explicitly, consecutive 5xx ejection will be disabled. google.protobuf.UInt32Value consecutive_5xx = 1; // The time interval between ejection analysis sweeps. This can result in @@ -80,6 +82,8 @@ message OutlierDetection { // The number of consecutive gateway failures (502, 503, 504 status codes) // before a consecutive gateway failure ejection occurs. Defaults to 5. + // + // If set to 0 explicitly, consecutive gateway failure ejection will be disabled. google.protobuf.UInt32Value consecutive_gateway_failure = 10; // The % chance that a host will be actually ejected when an outlier status @@ -101,6 +105,8 @@ message OutlierDetection { // occurs. Defaults to 5. Parameter takes effect only when // :ref:`split_external_local_origin_errors` // is set to true. + // + // If set to 0 explicitly, consecutive locally originated failure ejection will be disabled. google.protobuf.UInt32Value consecutive_local_origin_failure = 13; // The % chance that a host will be actually ejected when an outlier status @@ -177,4 +183,13 @@ message OutlierDetection { // If enabled, at least one host is ejected regardless of the value of :ref:`max_ejection_percent`. // Defaults to false. google.protobuf.BoolValue always_eject_one_host = 25; + + // If set to true, outlier detection will mark hosts as degraded when they return + // the ``x-envoy-degraded`` header. + // Degraded hosts are deprioritized in load balancing but are not ejected from the cluster. + // The degraded state is cleared using the same backoff algorithm as ejection, with the degradation + // period calculated as ``base_ejection_time`` multiplied by the number of times the host + // has been marked as degraded, capped by ``max_ejection_time``. + // Defaults to false. + google.protobuf.BoolValue detect_degraded_hosts = 26; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/address.proto b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/address.proto index 17a68269e34..6e8205d7cbe 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/address.proto +++ b/xds/third_party/envoy/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. @@ -188,6 +188,7 @@ message BindConfig { message Address { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.Address"; + // [#comment: Keep this list of address types in sync with UpstreamConnectionOptions.FirstAddressFamilyVersion in api/envoy/config/cluster/v3/cluster.proto.] oneof address { option (validate.required) = true; diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/base.proto b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/base.proto index 978f365d5f9..8d2ede9e65e 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/base.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/base.proto @@ -269,6 +269,15 @@ message RuntimeUInt32 { string runtime_key = 3; } +// Runtime derived uint64 with a default when not specified. +message RuntimeUInt64 { + // Default value if runtime value is not available. + uint64 default_value = 2; + + // Runtime key to get value for comparison. This value is used if defined. + string runtime_key = 3; +} + // Runtime derived percentage with a default when not specified. message RuntimePercent { // Default value if runtime value is not available. @@ -493,6 +502,14 @@ message HeaderMap { message WatchedDirectory { // Directory path to watch. string path = 1 [(validate.rules).string = {min_len: 1}]; + + // If set to true, the watcher will also subscribe to file modification events + // (``IN_MODIFY`` on Linux) in addition to move events (``IN_MOVED_TO``). This allows + // in-place file writes to trigger reload callbacks. Use this when the writing process + // cannot use atomic rename (e.g. certain secret managers that write certificate files + // directly). By default, only move/rename events are watched, which is the safe choice + // for atomic updates (e.g. Kubernetes ConfigMap symlink swaps). + bool watch_modify = 2; } // Data source consisting of a file, an inline value, or an environment variable. diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/http_service.proto b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/http_service.proto index 426994c033c..63dc2e5ebcd 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/http_service.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/http_service.proto @@ -3,6 +3,7 @@ syntax = "proto3"; package envoy.config.core.v3; import "envoy/config/core/v3/base.proto"; +import "envoy/config/core/v3/extension.proto"; import "envoy/config/core/v3/http_uri.proto"; import "udpa/annotations/status.proto"; @@ -29,7 +30,13 @@ message HttpService { HttpUri http_uri = 1; // Specifies a list of HTTP headers that should be added to each request - // handled by this virtual host. + // handled by this virtual host. Substitution formatters are supported. repeated HeaderValueOption request_headers_to_add = 2 [(validate.rules).repeated = {max_items: 1000}]; + + // Specifies a collection of Formatter plugins that can be used in substitution formatters + // in ``request_headers_to_add``. + // See the formatters extensions documentation for details. + // [#extension-category: envoy.formatter] + repeated TypedExtensionConfig formatters = 3; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/protocol.proto b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/protocol.proto index 63e189e689e..a2cfc6d4fca 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/protocol.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/protocol.proto @@ -57,7 +57,7 @@ message QuicKeepAliveSettings { } // QUIC protocol options which apply to both downstream and upstream connections. -// [#next-free-field: 12] +// [#next-free-field: 14] message QuicProtocolOptions { // Config for QUIC connection migration across network interfaces, i.e. cellular to WIFI, upon // network change events from the platform, i.e. the current network gets @@ -173,6 +173,17 @@ message QuicProtocolOptions { // If absent, the feature will be disabled. // [#not-implemented-hide:] ConnectionMigrationSettings connection_migration = 11; + + // Timeout for a QUIC connection to schedule memory reduction callback when the network has been idle for a while. + // This value should be smaller than the idle timeout to take effect. + // If not specified, memory reduction is set to infinite by QUIC connection (disabled). + google.protobuf.Duration memory_reduction_timeout = 12 + [(validate.rules).duration = {gte {seconds: 1}}]; + + // If true, the QUIC connection will signal support for `SCONE `_ (Standard + // Communication with Network Elements) and process SCONE packets. + // If not present, the QUICHE default behavior will be used. + google.protobuf.BoolValue enable_scone = 13; } message UpstreamHttpProtocolOptions { @@ -273,7 +284,7 @@ message AlternateProtocolsCacheOptions { repeated string canonical_suffixes = 5; } -// [#next-free-field: 8] +// [#next-free-field: 9] message HttpProtocolOptions { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.HttpProtocolOptions"; @@ -327,6 +338,22 @@ message HttpProtocolOptions { // `. google.protobuf.Duration max_connection_duration = 3; + // Percentage-based jitter for ``max_connection_duration``. If set, the actual connection duration + // limit is extended by a random duration up to ``max_connection_duration * jitter / 100``. + // This staggers connection teardowns across time and prevents a thundering-herd of reconnects + // when many connections are established at roughly the same time. + // This field is ignored if ``max_connection_duration`` is not set. If not set, no jitter is added. + // + // .. note:: + // This field is currently only honored for downstream connections by the HTTP connection + // manager. It is not yet supported for upstream cluster connections. + // + // This is analogous to + // :ref:`max_downstream_connection_duration_jitter_percentage + // ` + // in the TCP proxy filter. + type.v3.Percent max_connection_duration_jitter = 8; + // The maximum number of headers (request headers if configured on HttpConnectionManager, // response headers when configured on a cluster). // If unconfigured, the default maximum number of headers allowed is ``100``. @@ -350,8 +377,10 @@ message HttpProtocolOptions { // // Currently some protocol codecs impose limits on the maximum size of a single header. // - // * HTTP/2 (when using ``nghttp2``) limits a single header to around ``100kb``. - // * HTTP/3 limits a single header to around ``1024kb``. + // * HTTP/2 (when using nghttp2) limits a single header to around 100 KB by default. This can be + // adjusted via :ref:`max_header_field_size_kb + // `. + // * HTTP/3 limits a single header to around 1024 KB. // google.protobuf.UInt32Value max_response_headers_kb = 7 [(validate.rules).uint32 = {lte: 8192 gt: 0}]; @@ -432,8 +461,8 @@ message Http1ProtocolOptions { // This is a no-op if ``accept_http_10`` is not true. string default_host_for_http_10 = 3; - // Describes how the keys for response headers should be formatted. By default, all header keys - // are lower cased. + // Describes how the keys for headers encoded by the HTTP/1 codec should be formatted. By + // default, all header keys are lower cased. HeaderKeyFormat header_key_format = 4; // Enables trailers for HTTP/1. By default the HTTP/1 codec drops proxied trailers. @@ -539,7 +568,7 @@ message KeepaliveSettings { [(validate.rules).duration = {gte {nanos: 1000000}}]; } -// [#next-free-field: 19] +// [#next-free-field: 23] message Http2ProtocolOptions { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.Http2ProtocolOptions"; @@ -656,7 +685,7 @@ message Http2ProtocolOptions { // the connection is terminated. For downstream connections the ``opened_streams`` is incremented when // Envoy receives complete response headers from the upstream server. For upstream connections the // ``opened_streams`` is incremented when Envoy sends the ``HEADERS`` frame for a new stream. The - // ``http2.inbound_priority_frames_flood`` stat tracks the number of connections terminated due to + // ``http2.inbound_window_update_frames_flood`` stat tracks the number of connections terminated due to // flood mitigation. The default ``max_inbound_window_update_frames_per_data_frame_sent`` value is ``10``. // Setting this to ``1`` should be enough to support HTTP/2 implementations with basic flow control, // but more complex implementations that try to estimate available bandwidth require at least ``2``. @@ -736,6 +765,68 @@ message Http2ProtocolOptions { // worth the network bandwidth saved e.g. for localhost. // If unset, uses the data plane's default value. google.protobuf.BoolValue enable_huffman_encoding = 18; + + // Configures the maximum wire-encoded size in KB of an individual header field (name or value) + // that the ``nghttp2`` HPACK inflater will accept. This limit applies to the HPACK-compressed + // length on the wire, not the decoded length. If not specified, defaults to ``64`` KB + // which is the ``nghttp2`` default. + // + // This limit applies to headers received by the codec. When configured on the downstream + // HTTP Connection Manager, it limits individual request header fields. When configured on an + // upstream cluster, it limits individual response header fields. + // + // Due to Huffman encoding, the decoded header size that passes a given wire limit depends + // on the compression ratio of the content. For example, at the default ``64`` KB wire + // limit, highly compressible header values can be approximately ``100`` KB when decoded. + // Increasing this limit allows accepting larger individual headers at the cost of increased + // memory usage during HPACK decompression. + // + // This option only applies when using ``nghttp2``. It is a no-op for ``oghttp2``. The configured + // value of this field sets the per-header field size limit, which must not exceed the + // applicable aggregate total header size limit. Since a single header field cannot be larger + // than the total size allowed for all headers combined, this value is validated against + // :ref:`max_request_headers_kb ` + // when configured on the downstream HTTP Connection Manager, and against + // :ref:`max_response_headers_kb ` + // when configured on an upstream cluster. + // + // Since ``Http2ProtocolOptions`` is configured independently for downstream and upstream, + // different per-header field limits can be set for each direction without requiring separate + // request and response fields. + // + // .. note:: + // + // When increasing this limit, ensure that upstream services and other proxies in the request + // path can also handle the larger individual header sizes. Mismatched limits may result in + // request failures. + google.protobuf.UInt32Value max_header_field_size_kb = 19 + [(validate.rules).uint32 = {lte: 256 gte: 64}]; + + // Whether to disallow obsolete text for oghttp2 in header field values. + // If not set, it defaults to false. + // From RFC 9110, https://www.rfc-editor.org/rfc/rfc9110.html#section-5.5: + // obs-text = %x80-FF + google.protobuf.BoolValue disallow_obs_text = 20; + + // Configures the initial token count for the RST_STREAM rate limiter used by the ``nghttp2`` + // server-side connection. This uses a token-bucket algorithm where each received RST_STREAM + // frame consumes one token, and tokens are replenished at :ref:`stream_reset_rate + // ` per second. + // When no tokens remain, ``nghttp2`` sends GOAWAY with ``INTERNAL_ERROR`` to close the + // connection, protecting against CVE-2023-44487 (HTTP/2 Rapid Reset). Defaults to ``1000``. + // + // This option only applies when using ``nghttp2`` as a server. It has no effect on ``oghttp2`` + // or on client-side connections. + google.protobuf.UInt64Value stream_reset_burst = 21; + + // Configures the token replenishment rate (tokens per second) for the RST_STREAM rate limiter + // used by the ``nghttp2`` server-side connection. See :ref:`stream_reset_burst + // ` for details. + // Defaults to ``33``. + // + // This option only applies when using ``nghttp2`` as a server. It has no effect on ``oghttp2`` + // or on client-side connections. + google.protobuf.UInt64Value stream_reset_rate = 22; } // [#not-implemented-hide:] @@ -747,7 +838,7 @@ message GrpcProtocolOptions { } // A message which allows using HTTP/3. -// [#next-free-field: 9] +// [#next-free-field: 10] message Http3ProtocolOptions { QuicProtocolOptions quic_protocol_options = 1; @@ -789,6 +880,12 @@ message Http3ProtocolOptions { // Disables connection level flow control for HTTP/3 streams. This is useful in situations where the streams share the same connection // but originate from different end-clients, so that each stream can make progress independently at non-front-line proxies. bool disable_connection_flow_control_for_streams = 8; + + // Whether to disallow obsolete text in header field values. + // If not set, it defaults to true for alignment with current behavior. + // As defined in RFC 9110, https://www.rfc-editor.org/rfc/rfc9110.html#section-5.5: + // an obs-text character is a character in the range %x80-FF + google.protobuf.BoolValue disallow_obs_text = 9; } // A message to control transformations to the :scheme header diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/socket_option.proto b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/socket_option.proto index ad73d72e490..623ba26fab0 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/socket_option.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/socket_option.proto @@ -36,7 +36,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // :ref:`admin's ` socket_options etc. // // It should be noted that the name or level may have different values on different platforms. -// [#next-free-field: 8] +// [#next-free-field: 9] message SocketOption { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.core.SocketOption"; @@ -51,6 +51,19 @@ message SocketOption { STATE_LISTENING = 2; } + // The `socket IP version `_ to apply the + // socket option to. + enum SocketIpVersion { + // Apply the socket option to all socket IP versions. + SOCKET_IP_VERSION_UNSPECIFIED = 0; + + // Apply the socket option to the IPv4 socket type. + SOCKET_IP_VERSION_IPV4 = 1; + + // Apply the socket option to the IPv6 socket type. + SOCKET_IP_VERSION_IPV6 = 2; + } + // The `socket type `_ to apply the socket option to. // Only one field should be set. If multiple fields are set, the precedence order will determine // the selected one. If none of the fields is set, the socket option will be applied to all socket types. @@ -101,6 +114,11 @@ message SocketOption { // Apply the socket option to the specified `socket type `_. // If not specified, the socket option will be applied to all socket types. SocketType type = 7; + + // Apply the socket option to the specified `socket Ip version + // `_. If not specified, the socket option + // will be applied to all socket ip versions. + SocketIpVersion ip_version = 8; } message SocketOptionsOverride { diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/substitution_format_string.proto b/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/substitution_format_string.proto index 3edbf5f5f00..48c3cbc7eea 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/core/v3/substitution_format_string.proto +++ b/xds/third_party/envoy/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. diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/endpoint/v3/endpoint_components.proto b/xds/third_party/envoy/src/main/proto/envoy/config/endpoint/v3/endpoint_components.proto index eacc555df73..16e795d0e14 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/endpoint/v3/endpoint_components.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/endpoint/v3/endpoint_components.proto @@ -25,6 +25,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: Endpoints] // Upstream host identifier. +// [#next-free-field: 6] message Endpoint { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.endpoint.Endpoint"; @@ -97,6 +98,20 @@ message Endpoint { // sorted by preference order of the addresses. This will only be supported // for STATIC and EDS clusters. repeated AdditionalAddress additional_addresses = 4; + + // Optional alternative stat name for this endpoint. If not specified, the main address will be used + // as the stat name and be extracted as ``envoy.endpoint_address`` tag value in generated stats. + // If specified, the ``observability_name`` here will be used to replace the main address. + // + // .. note:: + // + // This field is ignored for logical DNS host implementation.. + // + // This is useful when there are duplicate addresses in the cluster, for example when multiple + // endpoints share the same address but have different hostnames or metadata. + // In this case, the observability name can be used to differentiate between these endpoints in + // stats and logs. + string observability_name = 5; } // An Endpoint that Envoy can route traffic to. @@ -139,7 +154,7 @@ message LbEndpoint { // LbEndpoint list collection. Entries are `LbEndpoint` resources or references. // [#not-implemented-hide:] message LbEndpointCollection { - xds.core.v3.CollectionEntry entries = 1; + repeated xds.core.v3.CollectionEntry entries = 1; } // A configuration for an LEDS collection. diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/listener.proto b/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/listener.proto index 54ef2cfed38..e463c1246dd 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/listener.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/listener/v3/listener.proto @@ -11,6 +11,7 @@ import "envoy/config/core/v3/socket_option.proto"; import "envoy/config/listener/v3/api_listener.proto"; import "envoy/config/listener/v3/listener_components.proto"; import "envoy/config/listener/v3/udp_listener_config.proto"; +import "envoy/config/metrics/v3/stats.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/wrappers.proto"; @@ -61,7 +62,7 @@ message ListenerCollection { repeated xds.core.v3.CollectionEntry entries = 1; } -// [#next-free-field: 38] +// [#next-free-field: 40] message Listener { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Listener"; @@ -106,6 +107,29 @@ message Listener { "envoy.api.v2.Listener.ConnectionBalanceConfig.ExactBalance"; } + // A connection balancer that steers each new TCP connection to the worker thread pinned to the + // CPU that received the connection, using a kernel ``SO_REUSEPORT`` BPF program. This removes + // the lock that the :ref:`exact balancer + // ` takes on + // every accept and keeps each connection on a single worker for cache and ``NUMA`` locality. To + // realize locality the operator should align ``NIC`` receive steering so connections arrive on + // the worker CPUs, for example with receive side scaling or ``IRQ`` affinity. + // + // It is available on Linux only and requires :ref:`enable_worker_cpu_affinity + // ` so worker ``i`` + // is pinned to the CPU the program steers to it, :ref:`enable_reuse_port + // `, a kernel that supports + // reuse port BPF steering, and a worker count no greater than the number of CPUs in the process + // affinity mask. When any of these is not met, or if the kernel rejects the steering program at + // runtime, the listener keeps serving with the kernel default reuse port hashing and without CPU + // locality. + // + // Worker affinity is fixed when the worker threads start, so a listener added dynamically via LDS + // steers with the same mapping. During a hot restart new connections may be steered to the + // draining parent process until it exits. + message CpuLocalityBalance { + } + oneof balance_type { option (validate.required) = true; @@ -114,8 +138,16 @@ message Listener { // The listener will use the connection balancer according to ``type_url``. If ``type_url`` is invalid, // Envoy will not attempt to balance active connections between worker threads. - // [#extension-category: envoy.network.connection_balance] + // The ``envoy.network.connection_balance`` extension category is currently empty + // because the only registered member (``envoy.network.connection_balance.dlb``) + // is disabled. See https://github.com/envoyproxy/envoy/issues/45491. core.v3.TypedExtensionConfig extend_balance = 2; + + // If specified, the listener will steer new connections to worker threads using a kernel + // ``SO_REUSEPORT`` BPF program. See :ref:`CpuLocalityBalance + // ` + // for the requirements and fallback behavior. + CpuLocalityBalance cpu_locality_balance = 3; } } @@ -166,6 +198,12 @@ message Listener { // ``listener..``. string stat_prefix = 28; + // Optional stats matcher that can be used to configure which stats are instantiated for this + // listener. If configured, this overrides the bootstrap :ref:`stats_config + // ` stats matcher configuration + // for this listener. + metrics.v3.StatsMatcher stats_matcher = 39; + // A list of filter chains to consider for this listener. The // :ref:`FilterChain ` with the most specific // :ref:`FilterChainMatch ` criteria is used on a @@ -215,7 +253,23 @@ message Listener { google.protobuf.UInt32Value per_connection_buffer_limit_bytes = 5 [(udpa.annotations.security).configure_for_untrusted_downstream = true]; + // Optional timeout that controls how long a connection is allowed to stay above the configured + // buffer high watermark before it is closed. If this timeout is not specified, or explicitly set + // to 0, connections will not be closed due to buffer high watermark usage. + google.protobuf.Duration per_connection_buffer_high_watermark_timeout = 38 + [(validate.rules).duration = {gte {}}]; + // Listener metadata. + // + // The following pre-defined metadata could be used by Envoy to manipulate the listener behavior: + // + // * ``envoy.stats_matcher``: this metadata could be used to customize the stats emitted by the + // listener. See :ref:`well-known metadata + // ` for more details. + // If :ref:`stats_matcher + // ` is configured, this metadata + // is ignored. The ``stats_matcher`` field should be preferred. + // core.v3.Metadata metadata = 6; // [#not-implemented-hide:] @@ -435,21 +489,3 @@ message Listener { // to explicitly configure TCP keepalive settings for individual additional addresses. core.v3.TcpKeepalive tcp_keepalive = 37; } - -// A placeholder proto so that users can explicitly configure the standard -// Listener Manager via the bootstrap's :ref:`listener_manager `. -// [#not-implemented-hide:] -message ListenerManager { -} - -// A placeholder proto so that users can explicitly configure the standard -// Validation Listener Manager via the bootstrap's :ref:`listener_manager `. -// [#not-implemented-hide:] -message ValidationListenerManager { -} - -// A placeholder proto so that users can explicitly configure the API -// Listener Manager via the bootstrap's :ref:`listener_manager `. -// [#not-implemented-hide:] -message ApiListenerManager { -} diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/metrics/v3/stats.proto b/xds/third_party/envoy/src/main/proto/envoy/config/metrics/v3/stats.proto index 0fcf36c1c71..46331c1abf0 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/metrics/v3/stats.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/metrics/v3/stats.proto @@ -44,6 +44,7 @@ message StatsSink { } // Statistics configuration such as tagging. +// [#next-free-field: 6] message StatsConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.config.metrics.v2.StatsConfig"; @@ -104,6 +105,19 @@ message StatsConfig { // 3600000 // ] repeated HistogramBucketSettings histogram_bucket_settings = 4; + + // When set to ``true``, tag extractors specified in :ref:`stats_tags + // ` take precedence over the built-in + // default tag extractors that share the same ``tag_name``, instead of the default taking + // precedence. This allows overriding individual default Envoy tags (for example + // ``envoy.cluster_name``) while keeping :ref:`use_all_default_tags + // ` enabled, so it is not + // necessary to disable all defaults and re-declare every extractor. + // + // Has no effect when ``use_all_default_tags`` is ``false`` (no default extractors are added in + // that case). If not provided, the value is assumed to be false, preserving existing behavior + // where the default extractor takes precedence over custom extractors with the same ``tag_name``. + google.protobuf.BoolValue allow_default_tag_overrides = 5; } // Configuration for disabling stat instantiation. diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/overload/v3/overload.proto b/xds/third_party/envoy/src/main/proto/envoy/config/overload/v3/overload.proto index b5bc2c4d830..05e6b2a1293 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/overload/v3/overload.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/overload/v3/overload.proto @@ -6,6 +6,7 @@ import "envoy/type/v3/percent.proto"; import "google/protobuf/any.proto"; import "google/protobuf/duration.proto"; +import "google/protobuf/wrappers.proto"; import "udpa/annotations/status.proto"; import "udpa/annotations/versioning.proto"; @@ -137,6 +138,21 @@ message ScaleTimersOverloadActionConfig { repeated ScaleTimer timer_scale_factors = 1 [(validate.rules).repeated = {min_items: 1}]; } +// Typed configuration for the "envoy.overload_actions.shrink_heap" action. +// See :ref:`the docs ` for an example of how to configure +// this action. +message ShrinkHeapConfig { + // The interval at which shrink heap action checks if memory should be released. + // If not specified, defaults to 10 seconds. + google.protobuf.Duration timer_interval = 1 [(validate.rules).duration = {gte {seconds: 1}}]; + + // Maximum amount of unfreed memory in bytes to keep before releasing memory + // back to the system. This is used as the threshold passed to + // tcmalloc::MallocExtension::ReleaseMemoryToSystem(). + // If not specified, defaults to 104857600 (100MB). + google.protobuf.UInt64Value max_unfreed_memory_bytes = 2; +} + message OverloadAction { option (udpa.annotations.versioning).previous_message_type = "envoy.config.overload.v2alpha.OverloadAction"; diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/route/v3/route_components.proto b/xds/third_party/envoy/src/main/proto/envoy/config/route/v3/route_components.proto index 4587ef10487..f864497f093 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/route/v3/route_components.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/route/v3/route_components.proto @@ -7,6 +7,7 @@ import "envoy/config/core/v3/base.proto"; import "envoy/config/core/v3/extension.proto"; import "envoy/config/core/v3/proxy_protocol.proto"; import "envoy/config/core/v3/substitution_format_string.proto"; +import "envoy/type/matcher/v3/address.proto"; import "envoy/type/matcher/v3/filter_state.proto"; import "envoy/type/matcher/v3/metadata.proto"; import "envoy/type/matcher/v3/regex.proto"; @@ -15,6 +16,7 @@ import "envoy/type/metadata/v3/metadata.proto"; import "envoy/type/tracing/v3/custom_tag.proto"; import "envoy/type/v3/percent.proto"; import "envoy/type/v3/range.proto"; +import "envoy/type/v3/ratelimit_unit.proto"; import "google/protobuf/any.proto"; import "google/protobuf/duration.proto"; @@ -1563,7 +1565,7 @@ message RouteAction { } // HTTP retry :ref:`architecture overview `. -// [#next-free-field: 14] +// [#next-free-field: 15] message RetryPolicy { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RetryPolicy"; @@ -1787,6 +1789,20 @@ message RetryPolicy { // HTTP headers which must be present in the request for retries to be attempted. repeated HeaderMatcher retriable_request_headers = 10; + + // By default, the target upstream cluster of a retry request is the same as the original request, + // and Envoy will not try to refresh it when retrying. + // If this field is set to true, Envoy will try to refresh the target upstream cluster when + // retrying a request. This is useful when users want to try different upstream cluster for + // each retry attempt. + // + // .. note:: + // This currently works when the route cluster specifier support the dynamic refresh, + // e.g. :ref:`matcher cluster specifier + // ` + // and :ref:`dynamic modules cluster specifier + // `. + bool refresh_cluster_on_retry = 14; } // HTTP request hedging :ref:`architecture overview `. @@ -1825,7 +1841,7 @@ message HedgePolicy { bool hedge_on_per_try_timeout = 3; } -// [#next-free-field: 10] +// [#next-free-field: 11] message RedirectAction { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RedirectAction"; @@ -1921,6 +1937,21 @@ message RedirectAction { // would do a case-insensitive match and transform path ``/aaa/XxX/bbb`` to // ``/aaa/yyy/bbb``. type.matcher.v3.RegexMatchAndSubstitute regex_rewrite = 9; + + // The path portion of the URL will be set to this value and supports + // :ref:`substitution format specifiers ` and CEL + // expressions. + // + // For example, with the following config: + // + // .. code-block:: yaml + // + // path_rewrite: "/new/%REQ(x-version)%" + // + // Would redirect to ``/new/v2`` given a request header ``x-version: v2``. + // If the substitution produces an empty string the path redirect is ignored + // and the original path is preserved. + string path_rewrite = 10; } // The HTTP status code to use in the redirect response. The default response @@ -2080,11 +2111,32 @@ message VirtualCluster { // Global rate limiting :ref:`architecture overview `. // Also applies to Local rate limiting :ref:`using descriptors `. -// [#next-free-field: 7] +// [#next-free-field: 8] message RateLimit { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RateLimit"; - // [#next-free-field: 13] + enum XRateLimitOption { + // X-RateLimit headers is not specified. When this enum is used at descriptor level, + // the behavior is to inherit the setting from the filter. + UNSPECIFIED = 0; + + // X-RateLimit headers disabled. + OFF = 1; + + // Use `draft RFC Version 03 `_ + // where 3 headers will be added: + // + // * ``X-RateLimit-Limit`` - indicates the request-quota associated to the + // client in the current time-window followed by the description of the + // quota policy. The value is returned by the maximum tokens of the token bucket. + // * ``X-RateLimit-Remaining`` - indicates the remaining requests in the + // current time-window. The value is returned by the remaining tokens in the token bucket. + // * ``X-RateLimit-Reset`` - indicates the number of seconds until reset of + // the current time-window. The value is returned by the remaining fill interval of the token bucket. + DRAFT_VERSION_03 = 2; + } + + // [#next-free-field: 14] message Action { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RateLimit.Action"; @@ -2370,6 +2422,16 @@ message RateLimit { // Query :ref:`route entry metadata ` ROUTE_ENTRY = 1; + + // Query :ref:`cluster metadata ` + CLUSTER_ENTRY = 2; + + // Query :ref:`cluster locality metadata ` + // Cluster locality metadata is available after upstream host selection only. To populate descriptors + // with cluster locality metadata it needs to be have the + // :ref:`apply_on_stream_done field ` + // set to ``true`` or host selection completed before the rate limit filter is executed. + CLUSTER_LOCALITY_ENTRY = 3; } // The key to use in the descriptor entry. @@ -2465,6 +2527,53 @@ message RateLimit { [(validate.rules).repeated = {min_items: 1}]; } + // The following descriptor entry is appended to the descriptor: + // + // .. code-block:: cpp + // + // ("remote_address_match", "") + message RemoteAddressMatch { + // Descriptor value of entry. + // + // The same :ref:`format specifier ` as used for + // :ref:`HTTP access logging ` applies here, however + // unknown specifier values are replaced with the empty string instead of ``-``. + // + // .. note:: + // + // The format string can contain multiple valid substitution fields. If multiple + // substitution fields are present, their results will be concatenated to form the + // final descriptor value. If it contains no substitution fields, the value will be + // used as is. All substitution fields will be evaluated and their results concatenated. + // If the final concatenated result is empty and ``default_value`` is set, the + // ``default_value`` will be used. If ``default_value`` is not set and the result is + // empty, this descriptor will be skipped and not included in the rate limit call. + // + // For example, ``static_value`` will be used as is since there are no substitution fields. + // ``%REQ(:method)%`` will be replaced with the HTTP method, and + // ``%REQ(:method)%%REQ(:path)%`` will be replaced with the concatenation of the HTTP method and path. + // ``%CEL(request.headers['user-id'])%`` will use CEL to extract the user ID from request headers. + // + string descriptor_value = 1 [(validate.rules).string = {min_len: 1}]; + + // The key to use in the descriptor entry. + // + // Defaults to ``remote_address_match``. + string descriptor_key = 2; + + // An optional value to use if the final concatenated ``descriptor_value`` result is empty. + string default_value = 3; + + // Specifies an address matcher that controls whether the rate limit action is applied. + // The matcher checks the remote address (trusted address from + // :ref:`x-forwarded-for `) + // against the specified CIDR ranges. The rate limit action will be applied if + // the remote address matches any of the CIDR ranges (or does not match any if + // ``invert_match`` is set to true in the address matcher). + type.matcher.v3.AddressMatcher address_matcher = 4 + [(validate.rules).message = {required: true}]; + } + oneof action_specifier { option (validate.required) = true; @@ -2517,6 +2626,9 @@ message RateLimit { // Rate limit on the existence of query parameters. QueryParameterValueMatch query_parameter_value_match = 11; + + // Rate limit on remote address match. + RemoteAddressMatch remote_address_match = 13; } } @@ -2530,11 +2642,23 @@ message RateLimit { type.metadata.v3.MetadataKey metadata_key = 1 [(validate.rules).message = {required: true}]; } + // Rate limit to apply to this descriptor. + message RateLimitOverride { + // The number of requests per unit of time. + uint32 requests_per_unit = 1; + + // The unit of time. + type.v3.RateLimitUnit unit = 2; + } + oneof override_specifier { option (validate.required) = true; // Limit override from dynamic metadata. DynamicMetadata dynamic_metadata = 1; + + // Static limit override. + RateLimitOverride rate_limit = 2; } } @@ -2563,6 +2687,11 @@ message RateLimit { // // One of the ``number`` or ``format`` fields should be set but not both. string format = 2 [(validate.rules).string = {prefix: "%" suffix: "%" ignore_empty: true}]; + + // If true, the hits addend value will be treated as negative, effectively adding to + // the rate limit budget instead of consuming from it. This can be used to refill previously consumed + // rate limit tokens. + bool is_negative_hits = 3; } // Refers to the stage set in the filter. The rate limit configuration only @@ -2601,9 +2730,13 @@ message RateLimit { // ` for more information. // // .. note:: - // This is not supported if the rate limit action is configured in the ``typed_per_filter_config`` like - // :ref:`VirtualHost.typed_per_filter_config` or - // :ref:`Route.typed_per_filter_config`, etc. + // For the global HTTP :ref:`rate limit filter + // `, this is supported both at the route/virtual host + // level and when the rate limit configuration is supplied via the filter's + // ``rate_limits`` field or the ``typed_per_filter_config`` + // (:ref:`RateLimitPerRoute `). + // This is not supported by the :ref:`local rate limit filter + // `. Override limit = 4; // An optional hits addend to be appended to the descriptor produced by this rate limit @@ -2631,6 +2764,9 @@ message RateLimit { // // Currently, this is only supported by the HTTP global rate filter. bool apply_on_stream_done = 6; + + // Descriptor level X-RateLimit headers options which may override the filter level setting. + XRateLimitOption x_ratelimit_option = 7; } // .. attention:: diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/opentelemetry.proto b/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/opentelemetry.proto index 5260d9bd6af..0576ff735b1 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/opentelemetry.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/opentelemetry.proto @@ -21,7 +21,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // Configuration for the OpenTelemetry tracer. // [#extension: envoy.tracers.opentelemetry] -// [#next-free-field: 7] +// [#next-free-field: 10] message OpenTelemetryConfig { // The upstream gRPC cluster that will receive OTLP traces. // Note that the tracer drops traces if the server does not read data fast enough. @@ -36,11 +36,9 @@ message OpenTelemetryConfig { // // .. note:: // - // Note: The ``request_headers_to_add`` property in the OTLP HTTP exporter service - // does not support the :ref:`format specifier ` as used for - // :ref:`HTTP access logging `. - // The values configured are added as HTTP headers on the OTLP export request - // without any formatting applied. + // The ``request_headers_to_add`` property in the OTLP HTTP exporter service supports + // substitution formatters. The formatters cannot access any HTTP or connection properties, but + // can load content such as environment variables or files or secrets. core.v3.HttpService http_service = 3 [(udpa.annotations.field_migrate).oneof_promotion = "otlp_exporter"]; @@ -64,4 +62,22 @@ message OpenTelemetryConfig { // This field specifies the maximum number of spans that can be cached. If not specified, the // default is 1024. google.protobuf.UInt32Value max_cache_size = 6; + + // Specifies whether to set the telemetry SDK resource attributes. + // The following attributes will be set: + // + // - telemetry.sdk.language + // - telemetry.sdk.name + // - telemetry.sdk.version + // + // If not specified, the default is to set these attributes. + google.protobuf.BoolValue set_telemetry_sdk_resource_attributes = 7; + + // Specifies whether to set the ``service.name`` resource attribute. + // If not specified, the default is to set this attribute. + google.protobuf.BoolValue set_service_name_resource_attribute = 8; + + // Specifies whether to set the instrumentation scope name ("envoy") and version on emitted traces. + // If not specified, the default is to set the instrumentation scope name and version. + google.protobuf.BoolValue set_instrumentation_scope = 9; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/zipkin.proto b/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/zipkin.proto index 2364983efc5..00623ae60fa 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/zipkin.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/config/trace/v3/zipkin.proto @@ -22,7 +22,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // Configuration for the Zipkin tracer. // [#extension: envoy.tracers.zipkin] -// [#next-free-field: 10] +// [#next-free-field: 11] message ZipkinConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.config.trace.v2.ZipkinConfig"; @@ -173,4 +173,10 @@ message ZipkinConfig { // * Hostname: Uses cluster name as fallback // * Path: ``/api/v2/spans`` core.v3.HttpService collector_service = 9; + + // Determines whether trace IDs will include a timestamp in the first 4 bytes. + // When enabled, trace IDs are generated with the format: [32-bit epoch seconds][32-bit random]. + // The default value is false, which results in fully random trace IDs. + // For 128-bit trace IDs, the timestamp is encoded in the high 32 bits of the high 64-bit word. + bool timestamp_trace_ids = 10; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/data/accesslog/v3/accesslog.proto b/xds/third_party/envoy/src/main/proto/envoy/data/accesslog/v3/accesslog.proto index da029b7da2e..6f476c6ed64 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/data/accesslog/v3/accesslog.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/data/accesslog/v3/accesslog.proto @@ -36,6 +36,7 @@ enum AccessLogType { NotSet = 0; TcpUpstreamConnected = 1; TcpPeriodic = 2; + TcpConnectionStart = 14; TcpConnectionEnd = 3; DownstreamStart = 4; DownstreamPeriodic = 5; diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/composite/v3/composite.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/composite/v3/composite.proto index 1ab6c5eb1ef..00ee5cd8bae 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/composite/v3/composite.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/composite/v3/composite.proto @@ -6,6 +6,8 @@ import "envoy/config/core/v3/base.proto"; import "envoy/config/core/v3/config_source.proto"; import "envoy/config/core/v3/extension.proto"; +import "xds/type/matcher/v3/matcher.proto"; + import "udpa/annotations/migrate.proto"; import "udpa/annotations/status.proto"; import "validate/validate.proto"; @@ -38,6 +40,33 @@ message Composite { // This is useful when the same filter chain needs to be applied across many routes, // as it avoids duplicating the filter chain configuration. map named_filter_chains = 1; + + // The match tree that will be used to select an action to execute. The action type should be + // :ref:`ExecuteFilterAction + // `. + // + // .. warning:: + // This should only be set when using the Composite filter as in the :ref:`http_filters + // `. + // Never set this field when using the Composite filter with the :ref:`ExtensionWithMatcher + // ` which will result in + // undefined behavior. + // + xds.type.matcher.v3.Matcher matcher = 2; +} + +// Per-route configuration for the Composite filter. +message CompositePerRoute { + // Override of the match tree for this route. + // + // .. warning:: + // This should only be set when using the Composite filter as in the :ref:`http_filters + // `. + // Never set this field when using the Composite filter with the :ref:`ExtensionWithMatcher + // ` which will result in + // undefined behavior. + // + xds.type.matcher.v3.Matcher matcher = 1 [(validate.rules).message = {required: true}]; } // A list of filter configurations to be called in order. Note that this can be used as the type diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto index 7f70b70013b..2b565dea339 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/ext_authz/v3/ext_authz.proto @@ -30,7 +30,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // External Authorization :ref:`configuration overview `. // [#extension: envoy.filters.http.ext_authz] -// [#next-free-field: 32] +// [#next-free-field: 33] message ExtAuthz { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.ext_authz.v3.ExtAuthz"; @@ -88,6 +88,17 @@ message ExtAuthz { // alter another client request header. // // Defaults to ``false``. + // + // .. attention:: + // + // Enabling this option can cause Envoy to recompute route matching after earlier HTTP filters + // have already processed the request. This can be security-sensitive when route-dependent + // authorization filters, such as the RBAC filter, run before ext_authz. + // + // Operators should avoid enabling this option for authorization services that are not fully + // trusted to influence routing. When possible, filters that mutate route-matching inputs and + // clear the route cache should run before route-dependent authorization filters. Operators can + // also use decoder_header_mutation_rules to restrict sensitive request header mutations. bool clear_route_cache = 6; // Sets the HTTP status that is returned to the client when the authorization server returns an error @@ -359,6 +370,64 @@ message ExtAuthz { // // Defaults to ``false``. bool enforce_response_header_limits = 31; + + // When set to ``true``, the filter operates in shadow mode. In shadow mode the + // filter still calls the external authorization service and processes the response, + // but never terminates the request. Instead of sending a local reply on a denied or + // error response, the filter writes the authorization decision (engine result, status + // code, response headers) into the request's + // :ref:`FilterState ` as a + // :ref:`ShadowDecision + // ` object so + // that subsequent filters can read and optionally enforce it. + // + // The FilterState key is the filter's configured ``name`` in the filter chain with a + // ``.shadow`` suffix (``envoy.filters.http.ext_authz.shadow`` by default). Multiple ext_authz + // filters in the same chain must already have distinct names and therefore write to distinct + // keys automatically. + // + // The auth server's denied-response body is intentionally **not** carried on the + // ShadowDecision: bodies can be arbitrarily large and no downstream consumer in the + // shadow-comparison flow needs them. A consumer that wants to reproduce the auth + // server's full denied response must read it from its own source of truth rather + // than replaying it from FilterState. + // + // Header and query-parameter mutations from an OK response are still applied to the + // request as usual. + // + // Defaults to ``false``. + bool shadow_mode = 32; +} + +// Serialized form of the shadow-mode authorization decision written to FilterState +// when :ref:`shadow_mode +// ` is +// enabled. Consumed by a downstream filter that decides whether to enforce the +// decision. +message ShadowDecision { + // The decision the auth server returned. + enum CheckResult { + UNSPECIFIED = 0; + OK = 1; + DENIED = 2; + ERROR = 3; + } + + // The decision the auth server returned. + CheckResult check_result = 1; + + // Response status code associated with the decision. For ``DENIED`` and ``ERROR`` this is + // the code the filter would have set on termination (the auth server's code for ``DENIED``, + // or :ref:`status_on_error + // ` fallback + // for ``ERROR``). For ``OK`` this defaults to ``200`` so consumers always see a populated + // value — the upstream response code is not known at shadow-decision time. + uint32 status_code = 2 [(validate.rules).uint32 = {lte: 599 gte: 100 ignore_empty: true}]; + + // Response headers the auth server asked to set on a denied response + // (e.g. ``WWW-Authenticate``, ``Set-Cookie``). Populated for ``DENIED`` only. + // Preserves ordering and duplicate header names. + repeated config.core.v3.HeaderValue response_headers = 3; } // Configuration for buffering the request data. @@ -426,7 +495,7 @@ message BufferSettings { // metadata as well as body may be added to the client's response. See :ref:`allowed_client_headers // ` // for details. -// [#next-free-field: 10] +// [#next-free-field: 11] message HttpService { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.http.ext_authz.v2.HttpService"; @@ -437,8 +506,13 @@ message HttpService { config.core.v3.HttpUri server_uri = 1; // Sets a prefix to the value of authorization request header ``Path``. + // Only one of ``path_prefix`` or ``path_override`` may be set. string path_prefix = 2; + // Replaces the value of authorization request header ``Path`` with this value. + // Only one of ``path_prefix`` or ``path_override`` may be set. + string path_override = 10; + // Settings used for controlling authorization request metadata. AuthorizationRequest authorization_request = 7; diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/ext_proc.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/ext_proc.proto index b07811d5235..5f298f1b729 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/ext_proc.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/ext_proc.proto @@ -98,7 +98,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // ` object in a namespace matching the filter // name. // -// [#next-free-field: 26] +// [#next-free-field: 27] message ExternalProcessor { // Describes the route cache action to be taken when an external processor response // is received in response to request headers. @@ -285,14 +285,6 @@ message ExternalProcessor { // // 3. External processor may still close the stream to indicate that no more messages are needed. // - // .. warning:: - // - // Flow control is a necessary mechanism to prevent the fast sender (either downstream client or upstream server) - // from overwhelming the external processor when its processing speed is slower. - // This protective measure is being explored and developed but has not been ready yet, so please use your own - // discretion when enabling this feature. - // This work is currently tracked under https://github.com/envoyproxy/envoy/issues/33319. - // bool observability_mode = 17; // Prevents clearing the route-cache when the @@ -307,6 +299,17 @@ message ExternalProcessor { // received in response to request headers. It is recommended to set this field rather than set // :ref:`disable_clear_route_cache `. // Only one of ``disable_clear_route_cache`` or ``route_cache_action`` can be set. + // + // .. attention:: + // + // Clearing the route cache can cause Envoy to recompute route matching after earlier HTTP + // filters have already processed the request. This can be security-sensitive when filters + // that make route-dependent authorization decisions, such as the RBAC filter, run before + // ext_proc and ext_proc mutates route-matching inputs. + // + // Operators should only enable route cache clearing for trusted external processors, should + // carefully order route-dependent authorization filters, and should use mutation_rules to + // restrict sensitive mutations when appropriate. RouteCacheAction route_cache_action = 18 [(udpa.annotations.field_migrate).oneof_promotion = "clear_route_cache_type"]; @@ -369,6 +372,20 @@ message ExternalProcessor { // // The default status is ``HTTP 500 Internal Server Error``. type.v3.HttpStatus status_on_error = 24; + + // If true, the filter will not remove the ``content-length`` header from the request/response after external processing. + // It is typically used in + // :ref:`FULL_DUPLEX_STREAMED ` + // mode. If the original body has been modified, the external processing server needs to set the correct content-length header in HeaderMutation + // that matches the modified body length. + // + // .. warning:: + // + // This configuration should only be used if you are sure that the content length matches + // the body length after external processing. Otherwise, it may cause vulnerability issues such as + // request smuggling. Thus, please use your own discretion when enabling this feature. + // + bool allow_content_length_header = 26; } // ExtProcHttpService is used for HTTP communication between the filter and the external processing service. @@ -399,7 +416,7 @@ message MetadataOptions { // Describes which typed or untyped filter dynamic metadata namespaces to accept from // the external processing server. Set to empty or leave unset to disallow writing - // any received dynamic metadata. Receiving of typed metadata is not supported. + // any received dynamic metadata. MetadataNamespaces receiving_namespaces = 2; // Describes which cluster metadata namespaces to forward to diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/processing_mode.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/processing_mode.proto index e2ec8946283..05f64b35d48 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/processing_mode.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/ext_proc/v3/processing_mode.proto @@ -20,20 +20,20 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#next-free-field: 7] message ProcessingMode { - // Control how headers and trailers are handled + // Control how headers and trailers are handled. enum HeaderSendMode { - // When used to configure the ext_proc filter :ref:`processing_mode - // `, - // the default HeaderSendMode depends on which part of the message is being processed. By + // When used to configure the ext_proc filter + // :ref:`processing_mode `, + // the default ``HeaderSendMode`` depends on which part of the message is being processed. By // default, request and response headers are sent, while trailers are skipped. // - // When used in :ref:`mode_override - // ` or - // :ref:`allowed_override_modes - // `, - // a value of DEFAULT indicates that there is no change from the behavior that is configured for - // the filter in :ref:`processing_mode - // `. + // When used in + // :ref:`mode_override ` + // or + // :ref:`allowed_override_modes `, + // a value of ``DEFAULT`` indicates that there is no change from the behavior that is configured + // for the filter in + // :ref:`processing_mode `. DEFAULT = 0; // Send the header or trailer. @@ -43,24 +43,27 @@ message ProcessingMode { SKIP = 2; } - // Control how the request and response bodies are handled - // When body mutation by external processor is enabled, ext_proc filter will always remove - // the content length header in four cases below because content length can not be guaranteed - // to be set correctly: - // 1) STREAMED BodySendMode: header processing completes before body mutation comes back. - // 2) BUFFERED_PARTIAL BodySendMode: body is buffered and could be injected in different phases. - // 3) BUFFERED BodySendMode + SKIP HeaderSendMode: header processing (e.g., update content-length) is skipped. - // 4) FULL_DUPLEX_STREAMED BodySendMode: header processing completes before body mutation comes back. + // Control how the request and response bodies are handled. // - // In Envoy's http1 codec implementation, removing content length will enable chunked transfer - // encoding whenever feasible. The recipient (either client or server) must be able - // to parse and decode the chunked transfer coding. + // When body mutation by the external processor is enabled, the ext_proc filter will always remove the + // content length header in the following four cases, unless + // :ref:`allow_content_length_header ` + // is enabled. This is because the content length cannot be guaranteed to be set correctly: + // + // 1) ``STREAMED`` BodySendMode: header processing completes before body mutation comes back. + // 2) ``BUFFERED_PARTIAL`` BodySendMode: body is buffered and could be injected in different phases. + // 3) ``BUFFERED`` BodySendMode + ``SKIP`` HeaderSendMode: header processing (e.g., update content-length) is skipped. + // 4) ``FULL_DUPLEX_STREAMED`` BodySendMode: header processing completes before body mutation comes back. + // + // In Envoy's HTTP/1 codec implementation, removing content length will enable chunked transfer + // encoding whenever feasible. The recipient (either client or server) must be able to parse and + // decode the chunked transfer coding // (see `details in RFC9112 `_). // - // In BUFFERED BodySendMode + SEND HeaderSendMode, content length header is allowed but it is - // external processor's responsibility to set the content length correctly matched to the length - // of mutated body. If they don't match, the corresponding body mutation will be rejected and - // local reply will be sent with an error message. + // In ``BUFFERED`` BodySendMode + ``SEND`` HeaderSendMode, content length header is allowed but it + // is the external processor's responsibility to set the content length correctly matched to the + // length of the mutated body. If they don't match, the corresponding body mutation will be + // rejected and a local reply will be sent with an error message. enum BodySendMode { // Do not send the body at all. This is the default. NONE = 0; @@ -80,73 +83,88 @@ message ProcessingMode { // The ext_proc client (the data plane) streams the body to the server in pieces as they arrive. // - // 1) The server may choose to buffer any number chunks of data before processing them. - // After it finishes buffering, the server processes the buffered data. Then it splits the processed - // data into any number of chunks, and streams them back to the ext_proc client one by one. - // The server may continuously do so until the complete body is processed. - // The individual response chunk size is recommended to be no greater than 64K bytes, or - // :ref:`max_receive_message_length ` - // if EnvoyGrpc is used. + // 1) The server may choose to buffer any number of chunks of data before processing them. + // After it finishes buffering, the server processes the buffered data. Then it splits the + // processed data into any number of chunks, and streams them back to the ext_proc client one + // by one. The server may continuously do so until the complete body is processed. The + // individual response chunk size is recommended to be no greater than 64K bytes, or + // :ref:`max_receive_message_length ` + // if EnvoyGrpc is used. // - // 2) The server may also choose to buffer the entire message, including the headers (if header mode is - // ``SEND``), the entire body, and the trailers (if present), before sending back any response. - // The server response has to maintain the headers-body-trailers ordering. + // 2) The server may also choose to buffer the entire message, including the headers (if header + // mode is ``SEND``), the entire body, and the trailers (if present), before sending back any + // response. The server response has to maintain the headers-body-trailers ordering. // - // 3) Note that the server might also choose not to buffer data. That is, upon receiving a - // body request, it could process the data and send back a body response immediately. + // 3) Note that the server might also choose not to buffer data. That is, upon receiving a body + // request, it could process the data and send back a body response immediately. // // In this body mode: + // // * The corresponding trailer mode has to be set to ``SEND``. - // * The client will send body and trailers (if present) to the server as they arrive. - // Sending the trailers (if present) is to inform the server the complete body arrives. - // In case there are no trailers, then the client will set + // * The client will send body and trailers (if present) to the server as they arrive. Sending + // the trailers (if present) is to inform the server that the complete body has arrived. In + // case there are no trailers, then the client will set // :ref:`end_of_stream ` - // to true as part of the last body chunk request to notify the server that no other data is to be sent. + // to ``true`` as part of the last body chunk request to notify the server that no other data + // is to be sent. // * The server needs to send // :ref:`StreamedBodyResponse ` // to the client in the body response. - // * The client will stream the body chunks in the responses from the server to the upstream/downstream as they arrive. - + // * The client will stream the body chunks in the responses from the server to the + // upstream/downstream as they arrive. FULL_DUPLEX_STREAMED = 4; // [#not-implemented-hide:] - // A mode for gRPC traffic. This is similar to ``FULL_DUPLEX_STREAMED``, - // except that instead of sending raw chunks of the HTTP/2 DATA frames, - // the ext_proc client will de-frame the individual gRPC messages inside - // the HTTP/2 DATA frames, and as each message is de-framed, it will be - // sent to the ext_proc server as a :ref:`request_body - // ` - // or :ref:`response_body - // `. + // A mode for gRPC traffic. This is similar to ``FULL_DUPLEX_STREAMED``, except that instead of + // sending raw chunks of the HTTP/2 DATA frames, the ext_proc client will de-frame the + // individual gRPC messages inside the HTTP/2 DATA frames, and as each message is de-framed, it + // will be sent to the ext_proc server as a + // :ref:`request_body ` + // or + // :ref:`response_body `. // The ext_proc server will stream back individual gRPC messages in the // :ref:`StreamedBodyResponse ` - // field, but the number of messages sent by the ext_proc server - // does not need to equal the number of messages sent by the data - // plane. This allows the ext_proc server to change the number of - // messages sent on the stream. - // In this mode, the client will send body and trailers to the server as - // they arrive. + // field, but the number of messages sent by the ext_proc server does not need to equal the + // number of messages sent by the data plane. This allows the ext_proc server to change the + // number of messages sent on the stream. In this mode, the client will send body and trailers + // to the server as they arrive. GRPC = 5; } - // How to handle the request header. Default is "SEND". - // Note this field is ignored in :ref:`mode_override - // `, since mode - // overrides can only affect messages exchanged after the request header is processed. + // How to handle the request header. + // + // .. note:: + // + // This field is ignored in + // :ref:`mode_override `, + // since mode overrides can only affect messages exchanged after the request header is + // processed. + // + // Defaults to ``SEND``. HeaderSendMode request_header_mode = 1 [(validate.rules).enum = {defined_only: true}]; - // How to handle the response header. Default is "SEND". + // How to handle the response header. + // + // Defaults to ``SEND``. HeaderSendMode response_header_mode = 2 [(validate.rules).enum = {defined_only: true}]; - // How to handle the request body. Default is "NONE". + // How to handle the request body. + // + // Defaults to ``NONE``. BodySendMode request_body_mode = 3 [(validate.rules).enum = {defined_only: true}]; - // How do handle the response body. Default is "NONE". + // How to handle the response body. + // + // Defaults to ``NONE``. BodySendMode response_body_mode = 4 [(validate.rules).enum = {defined_only: true}]; - // How to handle the request trailers. Default is "SKIP". + // How to handle the request trailers. + // + // Defaults to ``SKIP``. HeaderSendMode request_trailer_mode = 5 [(validate.rules).enum = {defined_only: true}]; - // How to handle the response trailers. Default is "SKIP". + // How to handle the response trailers. + // + // Defaults to ``SKIP``. HeaderSendMode response_trailer_mode = 6 [(validate.rules).enum = {defined_only: true}]; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/gcp_authn/v3/gcp_authn.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/gcp_authn/v3/gcp_authn.proto index f4646389f7e..b741120c190 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/gcp_authn/v3/gcp_authn.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/gcp_authn/v3/gcp_authn.proto @@ -64,7 +64,31 @@ message GcpAuthnFilterConfig { // Audience is the URL of the receiving service that performs token authentication. // It will be provided to the filter through cluster's typed_filter_metadata. message Audience { - string url = 1 [(validate.rules).string = {min_len: 1}]; + message AccessToken { + } + + message BoundJwt { + // The audience URL, used for fetching bound JWT token. + string url = 1 [(validate.rules).string = {min_len: 1}]; + } + + message BoundAccessToken { + } + + // The audience URL, used for fetching unbound JWT token. + string url = 1; + + // If defined, the filter will fetch unbound Access Token instead of JWT. + // It takes precedence over ``url``. + AccessToken access_token = 2; + + // If defined, the filter will fetch bound JWT token instead of unbound. + // It takes precedence over ``access_token`` and ``url``. + BoundJwt bound_jwt = 3; + + // If defined, the filter will fetch bound Access Token instead of unbound. + // It takes precedence over ``bound_jwt``, ``access_token`` and ``url``. + BoundAccessToken bound_access_token = 4; } // Token Cache configuration. diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/rate_limit_quota/v3/rate_limit_quota.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/rate_limit_quota/v3/rate_limit_quota.proto index 57b8bdecd78..db190536baa 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/rate_limit_quota/v3/rate_limit_quota.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/http/rate_limit_quota/v3/rate_limit_quota.proto @@ -12,7 +12,6 @@ import "google/protobuf/duration.proto"; import "google/protobuf/wrappers.proto"; import "google/rpc/status.proto"; -import "xds/annotations/v3/status.proto"; import "xds/type/matcher/v3/matcher.proto"; import "udpa/annotations/status.proto"; @@ -23,7 +22,6 @@ option java_outer_classname = "RateLimitQuotaProto"; option java_multiple_files = true; option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/http/rate_limit_quota/v3;rate_limit_quotav3"; option (udpa.annotations.file_status).package_version_status = ACTIVE; -option (xds.annotations.v3.file_status).work_in_progress = true; // [#protodoc-title: Rate Limit Quota] // Rate Limit Quota :ref:`configuration overview `. diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto index 9d8cf8bf4fd..00a347eda6c 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto @@ -39,7 +39,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // HTTP connection manager :ref:`configuration overview `. // [#extension: envoy.filters.network.http_connection_manager] -// [#next-free-field: 61] +// [#next-free-field: 63] message HttpConnectionManager { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager"; @@ -141,7 +141,18 @@ message HttpConnectionManager { UNESCAPE_AND_FORWARD = 4; } - // [#next-free-field: 13] + // The format to use when writing the + // :ref:`config_http_conn_man_headers_x-forwarded-client-cert` (XFCC) header value. + enum ForwardClientCertFormat { + // Use the :ref:`text format `. + // This is the default. + TEXT = 0; + + // Use the :ref:`JSON format `. + JSON = 1; + } + + // [#next-free-field: 14] message Tracing { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager.Tracing"; @@ -243,6 +254,20 @@ message HttpConnectionManager { // :ref:`HTTP access logging ` applies here, however // unknown specifier values are replaced with the empty string instead of ``-``. string upstream_operation = 12; + + // If set to true, trace context propagation is disabled, meaning that trace context headers + // (e.g. ``traceparent``, ``tracestate`` for OpenTelemetry/W3C, or ``X-B3-*`` headers for Zipkin) + // will not be injected when proxying requests to upstreams. + // + // This is useful for scenarios where you want to report spans from a proxy (e.g., an egress + // gateway) while preventing trace context from being propagated to external services, + // effectively stopping the trace at the mesh boundary. + // + // Note that span reporting is still performed when this is set to true - only context + // propagation is disabled. + // + // Default: false (context propagation is enabled) + bool no_context_propagation = 13; } message InternalAddressConfig { @@ -258,7 +283,7 @@ message HttpConnectionManager { repeated config.core.v3.CidrRange cidr_ranges = 2; } - // [#next-free-field: 7] + // [#next-free-field: 9] message SetCurrentClientCertDetails { option (udpa.annotations.versioning).previous_message_type = "envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager." @@ -287,14 +312,29 @@ message HttpConnectionManager { // Whether to forward the URI type Subject Alternative Name of the client cert. Defaults to // false. bool uri = 5; + + // Whether to forward the issuer of the client cert. Defaults to false. + bool issuer = 8; + + // The format for the header. When the :ref:`forward_client_cert_details + // ` + // is APPEND_FORWARD and an existing XFCC header is present, the format of the existing header + // is used. The configured format is used when there is no existing header value + // (APPEND_FORWARD with no prior XFCC header, or SANITIZE_SET which always replaces the value). + ForwardClientCertFormat format = 7; } - // The configuration for forwarding client cert details. + // The configuration for forwarding client cert details, used as the action config in a + // :ref:`forward_client_cert_matcher + // `. message ForwardClientCertConfig { // How to handle the XFCC header. ForwardClientCertDetails forward_client_cert_details = 1; - // How to set the current client cert details. + // The fields in the client certificate to forward. See + // :ref:`set_current_client_cert_details + // ` + // for details. SetCurrentClientCertDetails set_current_client_cert_details = 2; } @@ -539,14 +579,16 @@ message HttpConnectionManager { // // Currently some protocol codecs impose limits on the maximum size of a single header. // - // * HTTP/2 (when using nghttp2) limits a single header to around 100kb. - // * HTTP/3 limits a single header to around 1024kb. + // * HTTP/2 (when using nghttp2) limits a single header to around 100 KB by default. This can be + // adjusted via :ref:`max_header_field_size_kb + // `. + // * HTTP/3 limits a single header to around 1024 KB. // google.protobuf.UInt32Value max_request_headers_kb = 29 [(validate.rules).uint32 = {lte: 8192 gt: 0}]; // The stream idle timeout for connections managed by the connection manager. - // If not specified, this defaults to 5 minutes. The default value was selected + // If not specified, this defaults to ``5 minutes``. The default value was selected // so as not to interfere with any smaller configured timeouts that may have // existed in configurations prior to the introduction of this feature, while // introducing robustness to TCP connections that terminate without a FIN. @@ -555,28 +597,29 @@ message HttpConnectionManager { // :ref:`route-level idle_timeout // `. Even on a stream in // which the override applies, prior to receipt of the initial request - // headers, the :ref:`stream_idle_timeout - // ` - // applies. Each time an encode/decode event for headers or data is processed - // for the stream, the timer will be reset. If the timeout fires, the stream - // is terminated with a 408 Request Timeout error code if no upstream response - // header has been received, otherwise a stream reset occurs. - // - // If the :ref:`overload action ` "envoy.overload_actions.reduce_timeouts" - // is configured, this timeout is scaled according to the value for + // headers, the ``stream_idle_timeout`` applies. Each time an encode/decode event + // for headers or data is processed for the stream, the timer will be reset. If the + // timeout fires, the stream is terminated with a ``408 Request Timeout`` error code + // if no upstream response header has been received, otherwise a stream reset occurs. + // + // If the :ref:`overload action ` + // ``envoy.overload_actions.reduce_timeouts`` is configured, this timeout is scaled + // according to the value for // :ref:`HTTP_DOWNSTREAM_STREAM_IDLE `. // - // Note that it is possible to idle timeout even if the wire traffic for a stream is non-idle, due - // to the granularity of events presented to the connection manager. For example, while receiving - // very large request headers, it may be the case that there is traffic regularly arriving on the - // wire while the connection manage is only able to observe the end-of-headers event, hence the - // stream may still idle timeout. + // .. note:: // - // A value of 0 will completely disable the connection manager stream idle + // It is possible to idle timeout even if the wire traffic for a stream is non-idle, due + // to the granularity of events presented to the connection manager. For example, while receiving + // very large request headers, it may be the case that there is traffic regularly arriving on the + // wire while the connection manager is only able to observe the end-of-headers event, hence the + // stream may still idle timeout. + // + // A value of ``0`` will completely disable the connection manager stream idle // timeout, although per-route idle timeout overrides will continue to apply. // - // This timeout is also used as the default value for :ref:`stream_flush_timeout - // `. + // This timeout is also used as the default value for + // :ref:`stream_flush_timeout `. google.protobuf.Duration stream_idle_timeout = 24 [(udpa.annotations.security).configure_for_untrusted_downstream = true]; @@ -624,6 +667,18 @@ message HttpConnectionManager { // 5000 milliseconds (5 seconds) if this option is not specified. google.protobuf.Duration drain_timeout = 12; + // Percentage-based jitter for ``drain_timeout``. If set, the actual drain grace period + // is extended by a random duration up to ``drain_timeout * jitter / 100`` per connection. + // This staggers the final GOAWAY (and connection close) across time so that connections + // entering the drain state simultaneously do not all complete draining at the same instant, + // mitigating thundering-herd reconnects. If not set, no jitter is added. + // + // This is analogous to + // :ref:`max_connection_duration_jitter + // `, + // but applied to the drain grace timer rather than the connection duration timer. + type.v3.Percent drain_timeout_jitter = 62; + // The delayed close timeout is for downstream connections managed by the HTTP connection manager. // It is defined as a grace period after connection close processing has been locally initiated // during which Envoy will wait for the peer to close (i.e., a TCP FIN/RST is received by Envoy @@ -1051,6 +1106,49 @@ message HttpConnectionManager { // This should be set to ``false`` in cases where Envoy's view of the downstream address may not correspond to the // actual client address, for example, if there's another proxy in front of the Envoy. google.protobuf.BoolValue add_proxy_protocol_connection_state = 53; + + // Configuration for controlling how the ``x-forwarded-proto`` header is set. + // This allows customization of protocol inference, including support for inferring the original + // protocol (HTTP or HTTPS) from the PROXY protocol destination port. + // + // This is useful when a Layer 4 load balancer (such as AWS NLB) terminates TLS and uses + // PROXY protocol to communicate with Envoy. + // + // When configured and the local address was restored from PROXY protocol (indicating the + // original destination address is available), the ``x-forwarded-proto`` header will be set + // based on whether the destination port is in ``https_destination_ports`` or + // ``http_destination_ports``. + // + // Example configuration: + // + // .. code-block:: yaml + // + // http_connection_manager: + // forward_proto_config: + // https_destination_ports: [443, 8443] + // http_destination_ports: [80, 8080] + // + // If not configured, defaults to disabled and the standard behavior applies (using connection + // TLS status or trusted downstream headers). + ForwardProtoConfig forward_proto_config = 61; +} + +// Configuration options for setting the ``x-forwarded-proto`` header. +// This message provides flexibility for future enhancements to protocol inference. +message ForwardProtoConfig { + // List of destination ports that should be treated as HTTPS. + // When the PROXY protocol destination port matches one of these ports, + // ``x-forwarded-proto`` will be set to ``https``. + // + // Common values: 443, 8443 + repeated uint32 https_destination_ports = 1; + + // List of destination ports that should be treated as HTTP. + // When the PROXY protocol destination port matches one of these ports, + // ``x-forwarded-proto`` will be set to ``http``. + // + // Common values: 80, 8080 + repeated uint32 http_destination_ports = 2; } // The configuration to customize local reply returned by Envoy. diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto index c55d30b89e0..dade9fde0e3 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin.proto @@ -26,13 +26,20 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // the endpoint weights are sent by the control plane via EDS. However, // in this policy, the endpoint weights are instead determined via qps (queries // per second), eps (errors per second), and utilization metrics sent by the -// endpoint using the Open Request Cost Aggregation (ORCA) protocol. Utilization -// is determined by using the ORCA application_utilization field, if set, or -// else falling back to the cpu_utilization field. All queries count toward qps, -// regardless of result. Only failed queries count toward eps. A config -// parameter error_utilization_penalty controls the penalty to adjust endpoint -// weights using eps and qps. The weight of a given endpoint is computed as: -// ``qps / (utilization + eps/qps * error_utilization_penalty)``. +// endpoint using the Open Request Cost Aggregation (ORCA) protocol. All queries +// count toward qps, regardless of result. Only failed queries count toward eps. +// A config parameter error_utilization_penalty controls the penalty to adjust +// endpoint weights using eps and qps. The weight of a given endpoint is computed +// as: ``qps / (utilization + eps/qps * error_utilization_penalty)``. +// +// For a load report to update an endpoint's weight, it must set :ref:`rps_fractional +// ` (used as +// qps) greater than 0, and the final utilization (resolved utilization plus any +// error penalty) must be greater than 0. Resolved utilization (see +// :ref:`metric_names_for_computing_utilization +// `) +// is used as the baseline. Reports that fail to do so are ignored, and an endpoint +// with no valid weight is assigned the median weight of the endpoints that have one. // // Note that Envoy will forward the ORCA response headers/trailers from the upstream // cluster to the downstream client. This means that if the downstream client is also @@ -44,7 +51,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // See the :ref:`load balancing architecture // overview` for more information. // -// [#next-free-field: 9] +// [#next-free-field: 10] message ClientSideWeightedRoundRobin { // Whether to enable out-of-band utilization reporting collection from // the endpoints. By default, per-request utilization reporting is used. @@ -79,13 +86,19 @@ message ClientSideWeightedRoundRobin { // Default is 1.0. google.protobuf.FloatValue error_utilization_penalty = 6 [(validate.rules).float = {gte: 0.0}]; - // By default, endpoint weight is computed based on the :ref:`application_utilization ` field reported by the endpoint. - // If that field is not set, then utilization will instead be computed by taking the max of the values of the metrics specified here. + // Specifies the metrics used to compute the endpoint utilization from which weight is derived. // For map fields in the ORCA proto, the string will be of the form ``.``. For example, the string ``named_metrics.foo`` will mean to look for the key ``foo`` in the ORCA :ref:`named_metrics ` field. - // If none of the specified metrics are present in the load report, then :ref:`cpu_utilization ` is used instead. + // Utilization is the max of the values of the metrics specified here, when that max is greater than 0. + // Otherwise :ref:`application_utilization ` is used if greater than 0, with :ref:`cpu_utilization ` as the final fallback. + // Disabling the runtime flag ``envoy.reloadable_features.orca_weight_manager_use_named_metrics_first`` restores the legacy order, preferring ``application_utilization`` over these metrics. repeated string metric_names_for_computing_utilization = 7; // Configuration for slow start mode. // If this configuration is not set, slow start will not be not enabled. common.v3.SlowStartConfig slow_start_config = 8; + + // Optional overrides for the OOB reporting connection (alternative port, + // ``:authority``, transport socket selection). Honored only when + // ``enable_oob_load_report`` is true. + common.v3.OrcaOobReportingConfig oob_reporting_config = 9; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/common/v3/common.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/common/v3/common.proto index 22faf11b9c5..5064b1aa2c1 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/common/v3/common.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/load_balancing_policies/common/v3/common.proto @@ -7,6 +7,7 @@ import "envoy/config/route/v3/route_components.proto"; import "envoy/type/v3/percent.proto"; import "google/protobuf/duration.proto"; +import "google/protobuf/struct.proto"; import "google/protobuf/wrappers.proto"; import "envoy/annotations/deprecation.proto"; @@ -159,3 +160,29 @@ message ConsistentHashingLbConfig { // will be ignored. repeated config.route.v3.RouteAction.HashPolicy hash_policy = 3; } + +// Connection overrides for the ORCA out-of-band (OOB) reporting stream, used by +// load balancing policies that consume ORCA load reports (e.g. +// :ref:`client_side_weighted_round_robin +// `). +// Whether and when OOB reporting runs is controlled by the embedding policy. +message OrcaOobReportingConfig { + // Optional alternative port for the OOB reporting connection, for example an + // ORCA reporting sidecar listening on a dedicated port. If 0 or unset, the + // port of the host's ORCA reporting address is used. Ignored for non-IP + // (pipe/UDS) host addresses. + uint32 port_value = 1 [(validate.rules).uint32 = {lte: 65535}]; + + // Value of the ``:authority`` header on the OOB gRPC stream. If empty, the + // endpoint hostname is used, then the dialed address, then the cluster name. + string authority = 2 + [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}]; + + // Optional key/value pairs used to select a transport socket from the + // cluster's :ref:`transport_socket_matches + // ` + // for the OOB connection. If unset, or if no match is found, the cluster's + // default transport socket is used. ALPN ``h2`` is always forced on the OOB + // connection regardless of this setting. + google.protobuf.Struct transport_socket_match_criteria = 3; +} diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/http_11_proxy/v3/upstream_http_11_connect.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/http_11_proxy/v3/upstream_http_11_connect.proto index 2c9b5333f41..c0134c83374 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/http_11_proxy/v3/upstream_http_11_connect.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/http_11_proxy/v3/upstream_http_11_connect.proto @@ -2,6 +2,7 @@ syntax = "proto3"; package envoy.extensions.transport_sockets.http_11_proxy.v3; +import "envoy/config/core/v3/address.proto"; import "envoy/config/core/v3/base.proto"; import "udpa/annotations/status.proto"; @@ -32,7 +33,14 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // using the key ``envoy.http11_proxy_transport_socket.proxy_address`` and the // proxy address in ``config::core::v3::Address`` format. // +// If the ``default_proxy_address`` is set and proxy address is not found in +// ``typed_filter_metadata``, the default proxy address is used. +// message Http11ProxyUpstreamTransport { // The underlying transport socket being wrapped. Defaults to plaintext (raw_buffer) if unset. config.core.v3.TransportSocket transport_socket = 1; + + // Specifies the default proxy address to use if the proxy address is not present in the + // ``typed_filter_metadata`` of the endpoint. + config.core.v3.Address default_proxy_address = 2; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/tls/v3/common.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/tls/v3/common.proto index 9bc5fb5d029..3a3b753a035 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/tls/v3/common.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/tls/v3/common.proto @@ -57,9 +57,44 @@ message TlsParameters { // // .. attention:: // - // Please refer to `BoringSSL policies `_ + // Please refer to the `BoringSSL FIPS_202205 compliance policy `_ // for details. FIPS_202205 = 0; + + // CNSA2_202603 configures a TLS connection to use: + // + // * Only TLS 1.3, with AES-256-GCM. + // * Only ML-KEM-1024 for key agreement. + // * For handshake signatures, only ECDSA with P-384 and SHA-384, or RSA + // with SHA-384. + // + // Note: this setting aids with compliance with CNSA requirements but does not + // guarantee it. Careful reading of ``draft-becker-cnsa2-tls-profile`` is + // recommended. + // + // .. attention:: + // + // Please refer to the `BoringSSL CNSA2_202603 compliance policy `_ + // for details. + CNSA2_202603 = 1; + + // CNSA1_202603 configures a TLS connection to use: + // * TLS 1.2 or TLS 1.3. + // * For TLS 1.2, only TLS_ECDHE_[ECDSA|RSA]_WITH_AES_256_GCM_SHA384. + // * For TLS 1.3, only AES-256-GCM. + // * ML-KEM-1024 or P-384 for key agreement, preferring ML-KEM-1024 if the + // client supports it. + // * For handshake signatures, only ECDSA with P-384 and SHA-384, or RSA + // with SHA-384. + // + // Note: this setting aids with compliance with CNSA requirements but does not + // guarantee it. Careful reading of RFC 9151 is recommended. + // + // .. attention:: + // + // Please refer to the `BoringSSL CNSA1_202603 compliance policy `_ + // for details. + CNSA1_202603 = 2; } // Minimum TLS protocol version. By default, it's ``TLSv1_2`` for both clients and servers. @@ -369,7 +404,7 @@ message SubjectAltNameMatcher { string oid = 3; } -// [#next-free-field: 18] +// [#next-free-field: 19] message CertificateValidationContext { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.auth.CertificateValidationContext"; @@ -594,4 +629,28 @@ message CertificateValidationContext { // in OpenSSL 1.1.x and newer versions of BoringSSL in that the trust anchor is included. // Trusted issues are specified by setting :ref:`trusted_ca ` google.protobuf.UInt32Value max_verify_depth = 16 [(validate.rules).uint32 = {lte: 100}]; + + // If true, the server does not include the trusted-CA distinguished names in the + // TLS ``CertificateRequest`` message. CAs from :ref:`trusted_ca + // ` + // are still used to validate presented client certificates; only the wire + // advertisement changes. + // + // This is useful when the configured CA set is large enough that the + // ``CertificateRequest`` would exceed client-side TLS record limits, or when + // clients mishandle the CA set in some way. + // + // .. attention:: + // + // When enabled, clients that rely on the advertised CA list to select among + // multiple client certificates may now send no certificate or the wrong one; + // validation will then fail with the standard TLS alert. + // + // This option only affects downstream (server) TLS connections where Envoy sends a + // ``CertificateRequest`` to clients. It has no effect on upstream connections. + // + // Honored by the built-in validator and the SPIFFE validator. Validators that do + // not set a client CA list themselves (e.g., the dynamic-modules validator) are + // unaffected. Defaults to false. + bool suppress_client_ca_list = 18; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/tls/v3/tls.proto b/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/tls/v3/tls.proto index d656c66b5d0..648dd5b5671 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/tls/v3/tls.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/extensions/transport_sockets/tls/v3/tls.proto @@ -73,15 +73,15 @@ message UpstreamTlsContext { // Defaults to 1, setting this to 0 disables session resumption. google.protobuf.UInt32Value max_session_keys = 4; - // Controls enforcement of the ``keyUsage`` extension in peer certificates. If set to ``true``, the handshake will fail if - // the ``keyUsage`` is incompatible with TLS usage. + // Controls enforcement of the ``keyUsage`` extension in peer certificates. If set to ``true``, + // the handshake will fail if the ``keyUsage`` is incompatible with TLS usage. // - // .. note:: - // The default value is ``false`` (i.e., enforcement off). It is expected to change to ``true`` in a future release. + // .. attention:: // - // The ``ssl.was_key_usage_invalid`` in :ref:`listener metrics ` metric will be incremented - // for configurations that would fail if this option were enabled. - google.protobuf.BoolValue enforce_rsa_key_usage = 5; + // This field is deprecated and ignored. Envoy now always enforces the ``keyUsage`` extension + // in peer certificates, making this option unconfigurable. + google.protobuf.BoolValue enforce_rsa_key_usage = 5 + [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; } // [#next-free-field: 12] @@ -297,10 +297,13 @@ message CommonTlsContext { // Custom TLS certificate selector. // - // Select TLS certificate based on TLS client hello. - // If empty, defaults to native TLS certificate selection behavior: - // DNS SANs or Subject Common Name in TLS certificates is extracted as server name pattern to match SNI. - // [#extension-category: envoy.tls.certificate_selectors] + // For the downstream TLS socket, select a TLS certificate based on TLS client hello. If empty, + // defaults to native TLS certificate selection behavior: DNS SANs or Subject Common Name in TLS + // certificates is extracted as server name pattern to match SNI. + // + // For the upstream TLS socket, select a TLS certificate based on TLS server hello and the + // transport socket options. + // [#extension-category: envoy.tls.certificate_selectors,envoy.tls.upstream_certificate_selectors] config.core.v3.TypedExtensionConfig custom_tls_certificate_selector = 16; // Certificate provider for fetching TLS certificates. diff --git a/xds/third_party/envoy/src/main/proto/envoy/service/ext_proc/v3/external_processor.proto b/xds/third_party/envoy/src/main/proto/envoy/service/ext_proc/v3/external_processor.proto index 1c033c08d26..c34e9f51243 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/service/ext_proc/v3/external_processor.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/service/ext_proc/v3/external_processor.proto @@ -6,6 +6,7 @@ import "envoy/config/core/v3/base.proto"; import "envoy/extensions/filters/http/ext_proc/v3/processing_mode.proto"; import "envoy/type/v3/http_status.proto"; +import "google/protobuf/any.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/struct.proto"; @@ -23,37 +24,31 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: External processing service] -// A service that can access and modify HTTP requests and responses -// as part of a filter chain. +// A service that can access and modify HTTP requests and responses as part of a filter chain. // The overall external processing protocol works like this: // // 1. The data plane sends to the service information about the HTTP request. -// 2. The service sends back a ProcessingResponse message that directs -// the data plane to either stop processing, continue without it, or send -// it the next chunk of the message body. -// 3. If so requested, the data plane sends the server the message body in -// chunks, or the entire body at once. In either case, the server may send -// back a ProcessingResponse for each message it receives, or wait for -// a certain amount of body chunks received before streaming back the -// ProcessingResponse messages. -// 4. If so requested, the data plane sends the server the HTTP trailers, -// and the server sends back a ProcessingResponse. -// 5. At this point, request processing is done, and we pick up again -// at step 1 when the data plane receives a response from the upstream -// server. -// 6. At any point above, if the server closes the gRPC stream cleanly, -// then the data plane proceeds without consulting the server. -// 7. At any point above, if the server closes the gRPC stream with an error, -// then the data plane returns a 500 error to the client, unless the filter -// was configured to ignore errors. +// 2. The service sends back a ``ProcessingResponse`` message that directs the data plane to either +// stop processing, continue without it, or send it the next chunk of the message body. +// 3. If so requested, the data plane sends the server the message body in chunks, or the entire +// body at once. In either case, the server may send back a ``ProcessingResponse`` for each +// message it receives, or wait for a certain amount of body chunks to be received before +// streaming back the ``ProcessingResponse`` messages. +// 4. If so requested, the data plane sends the server the HTTP trailers, and the server sends back +// a ``ProcessingResponse``. +// 5. At this point, request processing is done, and we pick up again at step 1 when the data plane +// receives a response from the upstream server. +// 6. At any point above, if the server closes the gRPC stream cleanly, then the data plane +// proceeds without consulting the server. +// 7. At any point above, if the server closes the gRPC stream with an error, then the data plane +// returns a ``500`` error to the client, unless the filter was configured to ignore errors. // -// In other words, the process is a request/response conversation, but -// using a gRPC stream to make it easier for the server to -// maintain state. +// In other words, the process is a request/response conversation, but using a gRPC stream to make +// it easier for the server to maintain state. service ExternalProcessor { // This begins the bidirectional stream that the data plane will use to // give the server control over what the filter does. The actual - // protocol is described by the ProcessingRequest and ProcessingResponse + // protocol is described by the ``ProcessingRequest`` and ``ProcessingResponse`` // messages below. rpc Process(stream ProcessingRequest) returns (stream ProcessingResponse) { } @@ -61,30 +56,90 @@ service ExternalProcessor { // This message specifies the filter protocol configurations which will be sent to the ext_proc // server in a :ref:`ProcessingRequest `. -// If the server does not support these protocol configurations, it may choose to close the gRPC stream. -// If the server supports these protocol configurations, it should respond based on the API specifications. +// If the server does not support these protocol configurations, it may choose to close the gRPC +// stream. If the server supports these protocol configurations, it should respond based on the +// API specifications. message ProtocolConfiguration { - // Specify the filter configuration :ref:`request_body_mode - // ` + // Specifies the filter configuration + // :ref:`request_body_mode `. envoy.extensions.filters.http.ext_proc.v3.ProcessingMode.BodySendMode request_body_mode = 1 [(validate.rules).enum = {defined_only: true}]; - // Specify the filter configuration :ref:`response_body_mode - // ` + // Specifies the filter configuration + // :ref:`response_body_mode `. envoy.extensions.filters.http.ext_proc.v3.ProcessingMode.BodySendMode response_body_mode = 2 [(validate.rules).enum = {defined_only: true}]; - // Specify the filter configuration :ref:`send_body_without_waiting_for_header_response - // ` - // If the client is waiting for a header response from the server, setting ``true`` means the client will send body to the server - // as they arrive. Setting ``false`` means the client will buffer the arrived data and not send it to the server immediately. + // Specifies the filter configuration + // :ref:`send_body_without_waiting_for_header_response `. + // If the client is waiting for a header response from the server, setting to ``true`` means the + // client will send the body to the server as it arrives. Setting to ``false`` means the client + // will buffer the arrived data and not send it to the server immediately. bool send_body_without_waiting_for_header_response = 3; } // This represents the different types of messages that the data plane can send // to an external processing server. -// [#next-free-field: 12] +// [#next-free-field: 14] message ProcessingRequest { + // Initial flow control window sizes for ``FULL_DUPLEX_STREAMED`` and + // ``GRPC`` body send modes. + // + // A sender starts with this amount of flow control window. Whenever + // it sends body data, it must decrement its flow control window by + // the number of bytes that it has sent. When its flow control + // window is less than or equal to the amount of body data it wishes + // to send, it may not send until it receives a window update causing + // its flow control window to be large enough. + // + // However, note that in ``GRPC`` body send mode, whenever the flow + // control window is greater than zero, a sender may send a single + // message, even if the size of that message exceeds the available flow + // control window. At that point, the flow control window will be negative + // and the sender must not send the next message until it becomes positive. + // + // Note that the initial size for the to-sidestream windows are set by + // the sender, not the receiver. This is because each sidestream may be + // routed to a different ext_proc server instance, but there is no + // connection-level handshake to set a default for that server + // instance, so the only alternative here would be to have the + // ext_proc server instance set this on a per-stream basis, which + // would require an additional round-trip and therefore hurt latency. + // This unfortunately means that the ext_proc server instance has a + // bit less control: as soon as it receives these initial values, it can + // immediately send a window update that reduces the window, but it + // must be prepared to handle any data that the sender has already sent. + // The initial sizes for the to-sidestream windows are generally + // expected to be in the range of 32K to 64K. + // + // [#not-implemented-hide:] + message FlowControlInit { + // Downstream-to-sidestream initial window size. + int64 initial_window_downstream_to_sidestream = 1; + + // Sidestream-to-upstream initial window size. + int64 initial_window_sidestream_to_upstream = 2; + + // Upstream-to-sidestream initial window size. + int64 initial_window_upstream_to_sidestream = 3; + + // Sidestream-to-downstream initial window size. + int64 initial_window_sidestream_to_downstream = 4; + } + + // Flow control window update. Values may be positive or negative. The + // sender must immediately add these values to its flow control window, + // which governs how much data can be sent. + // + // [#not-implemented-hide:] + message ClientWindowUpdate { + // Window update for sidestream-to-upstream. + int64 window_increment_sidestream_to_upstream = 1; + + // Window update for sidestream-to-downstream. + int64 window_increment_sidestream_to_downstream = 2; + } + reserved 1; reserved "async_mode"; @@ -93,35 +148,33 @@ message ProcessingRequest { // ones are set for a particular HTTP request/response depend on the // processing mode. oneof request { - option (validate.required) = true; - // Information about the HTTP request headers, as well as peer info and additional // properties. Unless ``observability_mode`` is ``true``, the server must send back a - // HeaderResponse message, an ImmediateResponse message, or close the stream. + // ``HeaderResponse`` message, an ``ImmediateResponse`` message, or close the stream. HttpHeaders request_headers = 2; // Information about the HTTP response headers, as well as peer info and additional // properties. Unless ``observability_mode`` is ``true``, the server must send back a - // HeaderResponse message or close the stream. + // ``HeaderResponse`` message or close the stream. HttpHeaders response_headers = 3; - // A chunk of the HTTP request body. Unless ``observability_mode`` is true, the server must send back - // a BodyResponse message, an ImmediateResponse message, or close the stream. + // A chunk of the HTTP request body. Unless ``observability_mode`` is ``true``, the server must + // send back a ``BodyResponse`` message, an ``ImmediateResponse`` message, or close the stream. HttpBody request_body = 4; - // A chunk of the HTTP response body. Unless ``observability_mode`` is ``true``, the server must send back - // a BodyResponse message or close the stream. + // A chunk of the HTTP response body. Unless ``observability_mode`` is ``true``, the server must + // send back a ``BodyResponse`` message or close the stream. HttpBody response_body = 5; // The HTTP trailers for the request path. Unless ``observability_mode`` is ``true``, the server - // must send back a TrailerResponse message or close the stream. + // must send back a ``TrailerResponse`` message or close the stream. // // This message is only sent if the trailers processing mode is set to ``SEND`` and // the original downstream request has trailers. HttpTrailers request_trailers = 6; // The HTTP trailers for the response path. Unless ``observability_mode`` is ``true``, the server - // must send back a TrailerResponse message or close the stream. + // must send back a ``TrailerResponse`` message or close the stream. // // This message is only sent if the trailers processing mode is set to ``SEND`` and // the original upstream response has trailers. @@ -137,39 +190,75 @@ message ProcessingRequest { // :ref:`attributes ` supported in the data plane. map attributes = 9; - // Specify whether the filter that sent this request is running in :ref:`observability_mode - // ` - // and defaults to false. + // Specifies whether the filter that sent this request is running in + // :ref:`observability_mode `. // - // * A value of ``false`` indicates that the server must respond - // to this message by either sending back a matching ProcessingResponse message, - // or by closing the stream. + // * A value of ``false`` indicates that the server must respond to this message by either + // sending back a matching ``ProcessingResponse`` message, or by closing the stream. // * A value of ``true`` indicates that the server should not respond to this message, as any - // responses will be ignored. However, it may still close the stream to indicate that no more messages - // are needed. + // responses will be ignored. However, it may still close the stream to indicate that no more + // messages are needed. // + // Defaults to ``false``. bool observability_mode = 10; // Specify the filter protocol configurations to be sent to the server. // ``protocol_config`` is only encoded in the first ``ProcessingRequest`` message from the client to the server. ProtocolConfiguration protocol_config = 11; + + // Flow control initialization for ``FULL_DUPLEX_STREAMED`` and + // ``GRPC`` body send modes. + // + // Must be set in the initial message on the stream. Not used in + // subsequent messages. + // + // [#not-implemented-hide:] + FlowControlInit flow_control_init = 12; + + // Flow control updates for ``FULL_DUPLEX_STREAMED`` and ``GRPC`` body + // send modes. + // + // This message may be included in a request message that also + // populates one of the fields in the ``request`` oneof above, or it + // may be sent in a request message that does not set the + // ``request`` oneof. + // + // In ``FULL_DUPLEX_STREAMED`` body send mode, for backward + // compatibility with data planes that do not yet support flow control, + // the data plane must not send a message containing only this field + // (i.e., not setting the ``request`` oneof) unless the ext_proc server + // has sent a window update, thus indicating that it supports flow control. + // + // [#not-implemented-hide:] + ClientWindowUpdate client_window_update = 13; } // This represents the different types of messages the server may send back to the data plane -// when the ``observability_mode`` field in the received ProcessingRequest is set to false. +// when the ``observability_mode`` field in the received ``ProcessingRequest`` is set to ``false``. // // * If the corresponding ``BodySendMode`` in the // :ref:`processing_mode ` -// is not set to ``FULL_DUPLEX_STREAMED``, then for every received ProcessingRequest, -// the server must send back exactly one ProcessingResponse message. +// is not set to ``FULL_DUPLEX_STREAMED``, then for every received ``ProcessingRequest``, +// the server must send back exactly one ``ProcessingResponse`` message. // * If it is set to ``FULL_DUPLEX_STREAMED``, the server must follow the API defined -// for this mode to send the ProcessingResponse messages. -// [#next-free-field: 13] +// for this mode to send the ``ProcessingResponse`` messages. +// [#next-free-field: 15] message ProcessingResponse { + // Flow control window update. Values may be positive or negative. The + // sender must immediately add these values to its flow control window, + // which governs how much data can be sent. + // + // [#not-implemented-hide:] + message ServerWindowUpdate { + // Window update for downstream-to-sidestream. + int64 window_increment_downstream_to_sidestream = 1; + + // Window update for upstream-to-sidestream. + int64 window_increment_upstream_to_sidestream = 2; + } + // The response type that is sent by the server. oneof response { - option (validate.required) = true; - // The server must send back this message in response to a message with the // ``request_headers`` field set. HeadersResponse request_headers = 1; @@ -204,17 +293,19 @@ message ProcessingResponse { ImmediateResponse immediate_response = 7; // The server sends back this message to initiate or continue local response streaming. - // The server must initiate local response streaming with the ``headers_response`` in response to a ProcessingRequest - // with the ``request_headers`` only. - // The server may follow up with multiple messages containing ``body_response``. The server must indicate - // end of stream by setting ``end_of_stream`` to ``true`` in the ``headers_response`` + // The server must initiate local response streaming with the ``headers_response`` in response + // to a ``ProcessingRequest`` with the ``request_headers`` only. + // The server may follow up with multiple messages containing ``body_response``. The server must + // indicate end of stream by setting ``end_of_stream`` to ``true`` in the ``headers_response`` // or ``body_response`` message or by sending a ``trailers_response`` message. - // The client may send a ``request_body`` or ``request_trailers`` to the server depending on configuration. + // The client may send a ``request_body`` or ``request_trailers`` to the server depending on + // configuration. // The streaming local response can only be sent when the ``request_header_mode`` in the filter // :ref:`processing_mode ` - // is set to ``SEND``. The ext_proc server should not send StreamedImmediateResponse if it did not observe request headers, - // as it will result in the race with the upstream server response and reset of the client request. - // Presently only the FULL_DUPLEX_STREAMED or NONE body modes are supported. + // is set to ``SEND``. The ext_proc server should not send ``StreamedImmediateResponse`` if it + // did not observe request headers, as it will result in a race with the upstream server + // response and reset of the client request. + // Presently only the ``FULL_DUPLEX_STREAMED`` or ``NONE`` body modes are supported. StreamedImmediateResponse streamed_immediate_response = 11; } @@ -223,19 +314,37 @@ message ProcessingResponse { // field name(s) of the struct. google.protobuf.Struct dynamic_metadata = 8; - // Override how parts of the HTTP request and response are processed - // for the duration of this particular request/response only. Servers - // may use this to intelligently control how requests are processed - // based on the headers and other metadata that they see. - // This field is only applicable when servers responding to the header requests. - // If it is set in the response to the body or trailer requests, it will be ignored by the data plane. + // Optional typed metadata that will be emitted as dynamic metadata to be consumed by + // following filters. This metadata will be placed in the namespace(s) specified by the + // keys of the map. + // + // Typed dynamic metadata should be preferred over untyped dynamic metadata (``dynamic_metadata``) + // because it is more efficient and more type-safe. + map typed_dynamic_metadata = 13; + + // Override how parts of the HTTP request and response are processed for the duration of this + // particular request/response only. Servers may use this to intelligently control how requests + // are processed based on the headers and other metadata that they see. + // + // This field is applicable when servers are responding to the header requests. If it is set + // in the response to the body or trailer requests, it will be ignored by the data plane. // It is also ignored by the data plane when the ext_proc filter config - // :ref:`allow_mode_override - // ` - // is set to false, or - // :ref:`send_body_without_waiting_for_header_response - // ` - // is set to true. + // :ref:`allow_mode_override ` + // is set to ``false``, or + // :ref:`send_body_without_waiting_for_header_response ` + // is set to ``true``. + // + // The external processing server can override the processing mode by returning a standalone ``mode_override`` + // in the ``ProcessingResponse`` after receiving a ``ProcessingRequest`` for request headers. This standalone + // override must be sent before the request headers response is sent. + // Subsequent messages will adhere to this new mode. + // + // Constraints: + // + // 1. Request Path: A standalone ``mode_override`` only supports transitioning the body processing mode + // from other mode to ``FULL_DUPLEX_STREAMED``, and the trailer mode must be set to ``SEND``. + // 2. Response Path: There are no restrictions on processing mode changes in this case. + // envoy.extensions.filters.http.ext_proc.v3.ProcessingMode mode_override = 9; // [#not-implemented-hide:] @@ -251,70 +360,93 @@ message ProcessingResponse { // client had already sent before it saw the ext_proc stream termination. bool request_drain = 12; - // When ext_proc server receives a request message, in case it needs more - // time to process the message, it sends back a ProcessingResponse message - // with a new timeout value. When the data plane receives this response - // message, it ignores other fields in the response, just stop the original - // timer, which has the timeout value specified in - // :ref:`message_timeout - // ` - // and start a new timer with this ``override_message_timeout`` value and keep the - // data plane ext_proc filter state machine intact. - // Has to be >= 1ms and <= - // :ref:`max_message_timeout ` - // Such message can be sent at most once in a particular data plane ext_proc filter processing state. - // To enable this API, one has to set ``max_message_timeout`` to a number >= 1ms. + // When the ext_proc server receives a request message and needs more time to process it, it + // sends back a ``ProcessingResponse`` message with a new timeout value. When the data plane + // receives this response message, it ignores other fields in the response, stops the original + // timer (which has the timeout value specified in + // :ref:`message_timeout `), + // and starts a new timer with this ``override_message_timeout`` value while keeping the data + // plane ext_proc filter state machine intact. + // + // The value must be >= 1ms and <= + // :ref:`max_message_timeout `. + // Such a message can be sent at most once in a particular data plane ext_proc filter processing + // state. To enable this API, ``max_message_timeout`` must be set to a value >= 1ms. google.protobuf.Duration override_message_timeout = 10; + + // Flow control updates for ``FULL_DUPLEX_STREAMED`` and ``GRPC`` body + // send modes. + // + // This message may be included in a response message that also + // populates one of the fields in the ``response`` oneof above, or it + // may be sent in a response message that does not set the + // ``response`` oneof. + // + // In ``FULL_DUPLEX_STREAMED`` body send mode, for backward + // compatibility with data planes that do not yet support flow control, + // the ext_proc server must not set this field unless the data plane + // sent initial window sizes in its initial message on the stream. + // Conversely, if the data plane did send initial window sizes in its + // initial message on the stream, the ext_proc server must send a + // window update immediately to let the data plane know that it also + // supports flow control. If the ext_proc server is sending a message + // immediately anyway (e.g., for a header or body chunk), it can include + // this field in that same message; otherwise, the ext_proc server must + // send a message containing only this field. + // + // [#not-implemented-hide:] + ServerWindowUpdate server_window_update = 14; } // The following are messages that are sent to the server. -// This message is sent to the external server when the HTTP request and responses +// This message is sent to the external server when the HTTP request and response headers // are first received. message HttpHeaders { - // The HTTP request headers. All header keys will be - // lower-cased, because HTTP header keys are case-insensitive. - // The header value is encoded in the + // The HTTP request headers. All header keys will be lower-cased, because HTTP header keys are + // case-insensitive. The header value is encoded in the // :ref:`raw_value ` field. config.core.v3.HeaderMap headers = 1; // [#not-implemented-hide:] - // This field is deprecated and not implemented. Attributes will be sent in - // the top-level :ref:`attributes ` field. map attributes = 2 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; - // If ``true``, then there is no message body associated with this - // request or response. + // If ``true``, then there is no message body associated with this request or response. bool end_of_stream = 3; } -// This message is sent to the external server when the HTTP request and -// response bodies are received. +// This message is sent to the external server when the HTTP request and response bodies are +// received. message HttpBody { - // The contents of the body in the HTTP request/response. Note that in - // streaming mode multiple ``HttpBody`` messages may be sent. + // The contents of the body in the HTTP request/response. Note that in streaming mode multiple + // ``HttpBody`` messages may be sent. // - // In ``GRPC`` body send mode, a separate ``HttpBody`` message will be - // sent for each message in the gRPC stream. + // In ``GRPC`` body send mode, a separate ``HttpBody`` message will be sent for each message in + // the gRPC stream. bytes body = 1; - // If ``true``, this will be the last ``HttpBody`` message that will be sent and no - // trailers will be sent for the current request/response. + // If ``true``, this will be the last ``HttpBody`` message that will be sent and no trailers + // will be sent for the current request/response. bool end_of_stream = 2; - // This field is used in ``GRPC`` body send mode when ``end_of_stream`` is - // true and ``body`` is empty. Those values would normally indicate an - // empty message on the stream with the end-of-stream bit set. - // However, if the half-close happens after the last message on the - // stream was already sent, then this field will be true to indicate an - // end-of-stream with *no* message (as opposed to an empty message). + // This field is used only in ``GRPC`` body send mode. It is not used in any other body send + // mode. + // + // This field is used only when ``end_of_stream`` is true and ``body`` is empty. + // Normally, in ``GRPC`` body send mode, an empty ``body`` field indicates an empty message on + // the gRPC stream. However, it is possible that the gRPC client sends a half-close without + // actually sending a message on the stream, so we need a way to differentiate between + // an empty message being sent and no message being sent. If this field is true, then it + // indicates that no message has been sent; if it is false, then it indicates that an empty + // message has been sent. + // [#not-implemented-hide:] bool end_of_stream_without_message = 3; - // This field is used in ``GRPC`` body send mode to indicate whether - // the message is compressed. This will never be set to true by gRPC - // but may be set to true by a proxy like Envoy. + // This field is used in ``GRPC`` body send mode to indicate whether the message is compressed. + // This will never be set to ``true`` by gRPC but may be set to ``true`` by a proxy like Envoy. bool grpc_message_compressed = 4; } @@ -352,13 +484,14 @@ message TrailersResponse { HeaderMutation header_mutation = 1; } -// This message is sent by the external server to the data plane after ``HttpHeaders`` -// to initiate local response streaming. The server may follow up with multiple messages containing ``body_response``. -// The server must indicate end of stream by setting ``end_of_stream`` to ``true`` in the ``headers_response`` -// or ``body_response`` message or by sending a ``trailers_response`` message. +// This message is sent by the external server to the data plane after ``HttpHeaders`` to initiate +// local response streaming. The server may follow up with multiple messages containing +// ``body_response``. The server must indicate end of stream by setting ``end_of_stream`` to +// ``true`` in the ``headers_response`` or ``body_response`` message or by sending a +// ``trailers_response`` message. message StreamedImmediateResponse { oneof response { - // Response headers to be sent downstream. The ":status" header must be set. + // Response headers to be sent downstream. The ``:status`` header must be set. HttpHeaders headers_response = 1; // Response body to be sent downstream. @@ -384,7 +517,7 @@ message CommonResponse { // further messages for this request or response even if the processing // mode is configured to do so. // - // When used in response to a request_headers or response_headers message, + // When used in response to a ``request_headers`` or ``response_headers`` message, // this status makes it possible to either completely replace the body // while discarding the original body, or to add a body to a message that // formerly did not have one. @@ -401,23 +534,22 @@ message CommonResponse { ResponseStatus status = 1 [(validate.rules).enum = {defined_only: true}]; // Instructions on how to manipulate the headers. When responding to an - // HttpBody request, header mutations will only take effect if - // the current processing mode for the body is BUFFERED. + // ``HttpBody`` request, header mutations will only take effect if the current processing mode + // for the body is ``BUFFERED``. HeaderMutation header_mutation = 2; - // Replace the body of the last message sent to the remote server on this - // stream. If responding to an HttpBody request, simply replace or clear - // the body chunk that was sent with that request. Body mutations may take - // effect in response either to ``header`` or ``body`` messages. When it is - // in response to ``header`` messages, it only take effect if the + // Replace the body of the last message sent to the remote server on this stream. If responding + // to an ``HttpBody`` request, simply replace or clear the body chunk that was sent with that + // request. Body mutations may take effect in response either to ``header`` or ``body`` messages. + // When it is in response to ``header`` messages, it only takes effect if the // :ref:`status ` - // is set to CONTINUE_AND_REPLACE. + // is set to ``CONTINUE_AND_REPLACE``. BodyMutation body_mutation = 3; // [#not-implemented-hide:] - // Add new trailers to the message. This may be used when responding to either a - // HttpHeaders or HttpBody message, but only if this message is returned - // along with the CONTINUE_AND_REPLACE status. + // Add new trailers to the message. This may be used when responding to either an + // ``HttpHeaders`` or ``HttpBody`` message, but only if this message is returned + // along with the ``CONTINUE_AND_REPLACE`` status. // The header value is encoded in the // :ref:`raw_value ` field. config.core.v3.HeaderMap trailers = 4; @@ -429,34 +561,32 @@ message CommonResponse { bool clear_route_cache = 5; } -// This message causes the filter to attempt to create a locally -// generated response, send it downstream, stop processing -// additional filters, and ignore any additional messages received -// from the remote server for this request or response. If a response -// has already started, then this will either ship the reply directly -// to the downstream codec, or reset the stream. +// This message causes the filter to attempt to create a locally generated response, send it +// downstream, stop processing additional filters, and ignore any additional messages received +// from the remote server for this request or response. If a response has already started, then +// this will either ship the reply directly to the downstream codec, or reset the stream. // [#next-free-field: 6] message ImmediateResponse { // The response code to return. type.v3.HttpStatus status = 1 [(validate.rules).message = {required: true}]; - // Apply changes to the default headers, which will include content-type. + // Apply changes to the default headers, which will include ``content-type``. HeaderMutation headers = 2; // The message body to return with the response which is sent using the - // text/plain content type, or encoded in the grpc-message header. + // ``text/plain`` content type, or encoded in the ``grpc-message`` header. bytes body = 3; // If set, then include a gRPC status trailer. GrpcStatus grpc_status = 4; // A string detailing why this local reply was sent, which may be included - // in log and debug output (e.g. this populates the %RESPONSE_CODE_DETAILS% + // in log and debug output (e.g., this populates the ``%RESPONSE_CODE_DETAILS%`` // command operator field for use in access logging). string details = 5; } -// This message specifies a gRPC status for an ImmediateResponse message. +// This message specifies a gRPC status for an ``ImmediateResponse`` message. message GrpcStatus { // The actual gRPC status. uint32 status = 1; @@ -484,26 +614,24 @@ message StreamedBodyResponse { // a serialized gRPC message to be passed to the upstream/downstream by the data plane. bytes body = 1; - // The server sets this flag to true if it has received a body request with - // :ref:`end_of_stream ` set to true, - // and this is the last chunk of body responses. - // Note that in ``GRPC`` body send mode, this allows the ext_proc - // server to tell the data plane to send a half close after a client - // message, which will result in discarding any other messages sent by - // the client application. + // The server sets this flag to ``true`` if it has received a body request with + // :ref:`end_of_stream ` set to + // ``true``, and this is the last chunk of body responses. + // + // Note that in ``GRPC`` body send mode, this allows the ext_proc server to tell the data plane + // to send a half close after a client message, which will result in discarding any other + // messages sent by the client application. bool end_of_stream = 2; - // This field is used in ``GRPC`` body send mode when ``end_of_stream`` is - // true and ``body`` is empty. Those values would normally indicate an - // empty message on the stream with the end-of-stream bit set. - // However, if the half-close happens after the last message on the - // stream was already sent, then this field will be true to indicate an - // end-of-stream with *no* message (as opposed to an empty message). + // This field is used in ``GRPC`` body send mode when ``end_of_stream`` is ``true`` and ``body`` + // is empty. Those values would normally indicate an empty message on the stream with the + // end-of-stream bit set. However, if the half-close happens after the last message on the stream + // was already sent, then this field will be ``true`` to indicate an end-of-stream with *no* + // message (as opposed to an empty message). bool end_of_stream_without_message = 3; - // This field is used in ``GRPC`` body send mode to indicate whether - // the message is compressed. This will never be set to true by gRPC - // but may be set to true by a proxy like Envoy. + // This field is used in ``GRPC`` body send mode to indicate whether the message is compressed. + // This will never be set to ``true`` by gRPC but may be set to ``true`` by a proxy like Envoy. bool grpc_message_compressed = 4; } @@ -517,11 +645,10 @@ message BodyMutation { // is not set to ``FULL_DUPLEX_STREAMED`` or ``GRPC``. bytes body = 1; - // Clear the corresponding body chunk. - // Should only be used when the corresponding ``BodySendMode`` in the + // Clear the corresponding body chunk. Should only be used when the corresponding + // ``BodySendMode`` in the // :ref:`processing_mode ` // is not set to ``FULL_DUPLEX_STREAMED`` or ``GRPC``. - // Clear the corresponding body chunk. bool clear_body = 2; // Must be used when the corresponding ``BodySendMode`` in the diff --git a/xds/third_party/envoy/src/main/proto/envoy/service/rate_limit_quota/v3/rlqs.proto b/xds/third_party/envoy/src/main/proto/envoy/service/rate_limit_quota/v3/rlqs.proto index b8fa2cd8982..cb65948f62b 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/service/rate_limit_quota/v3/rlqs.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/service/rate_limit_quota/v3/rlqs.proto @@ -6,8 +6,6 @@ import "envoy/type/v3/ratelimit_strategy.proto"; import "google/protobuf/duration.proto"; -import "xds/annotations/v3/status.proto"; - import "udpa/annotations/status.proto"; import "validate/validate.proto"; @@ -16,7 +14,6 @@ option java_outer_classname = "RlqsProto"; option java_multiple_files = true; option go_package = "github.com/envoyproxy/go-control-plane/envoy/service/rate_limit_quota/v3;rate_limit_quotav3"; option (udpa.annotations.file_status).package_version_status = ACTIVE; -option (xds.annotations.v3.file_status).work_in_progress = true; // [#protodoc-title: Rate Limit Quota Service (RLQS)] diff --git a/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/address.proto b/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/address.proto index 8a03a5320af..3cc2241f0b0 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/address.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/type/matcher/v3/address.proto @@ -19,4 +19,10 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // filter state object as an IP. message AddressMatcher { repeated xds.core.v3.CidrRange ranges = 1; + + // If true, the match result will be inverted. Defaults to false. + // + // * If set to false (default), the matcher will return true if the IP matches any of the CIDR ranges. + // * If set to true, the matcher will return true if the IP does NOT match any of the CIDR ranges. + bool invert_match = 2; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/type/v3/http.proto b/xds/third_party/envoy/src/main/proto/envoy/type/v3/http.proto index a1a5a04fc87..c53c2be3ed2 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/type/v3/http.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/type/v3/http.proto @@ -14,11 +14,6 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; enum CodecClientType { HTTP1 = 0; - HTTP2 = 1; - - // [#not-implemented-hide:] QUIC implementation is not production ready yet. Use this enum with - // caution to prevent accidental execution of QUIC code. I.e. `!= HTTP2` is no longer sufficient - // to distinguish HTTP1 and HTTP2 traffic. HTTP3 = 2; } diff --git a/xds/third_party/envoy/src/main/proto/envoy/type/v3/token_bucket.proto b/xds/third_party/envoy/src/main/proto/envoy/type/v3/token_bucket.proto index 157a271efc9..1f91adb2556 100644 --- a/xds/third_party/envoy/src/main/proto/envoy/type/v3/token_bucket.proto +++ b/xds/third_party/envoy/src/main/proto/envoy/type/v3/token_bucket.proto @@ -22,8 +22,9 @@ message TokenBucket { option (udpa.annotations.versioning).previous_message_type = "envoy.type.TokenBucket"; // The maximum tokens that the bucket can hold. This is also the number of tokens that the bucket - // initially contains. - uint32 max_tokens = 1 [(validate.rules).uint32 = {gt: 0}]; + // initially contains. A value of 0 means the bucket will always be empty and all requests will + // be rate limited (i.e., always reject). + uint32 max_tokens = 1 [(validate.rules).uint32 = {gte: 0}]; // The number of tokens added to the bucket during each fill interval. If not specified, defaults // to a single token. From 21fc93c6555fbc98cb9b2262996cb5856d8a2b31 Mon Sep 17 00:00:00 2001 From: Kannan J Date: Tue, 1 Sep 2026 06:26:27 +0000 Subject: [PATCH 2/2] Regenerate ExternalProcessorGrpc from updated envoy protos --- .../ext_proc/v3/ExternalProcessorGrpc.java | 286 ++++++++---------- 1 file changed, 122 insertions(+), 164 deletions(-) diff --git a/xds/src/generated/thirdparty/grpc/io/envoyproxy/envoy/service/ext_proc/v3/ExternalProcessorGrpc.java b/xds/src/generated/thirdparty/grpc/io/envoyproxy/envoy/service/ext_proc/v3/ExternalProcessorGrpc.java index fc3ce3a2723..20064af7844 100644 --- a/xds/src/generated/thirdparty/grpc/io/envoyproxy/envoy/service/ext_proc/v3/ExternalProcessorGrpc.java +++ b/xds/src/generated/thirdparty/grpc/io/envoyproxy/envoy/service/ext_proc/v3/ExternalProcessorGrpc.java @@ -4,31 +4,25 @@ /** * 
- * A service that can access and modify HTTP requests and responses
- * as part of a filter chain.
+ * A service that can access and modify HTTP requests and responses as part of a filter chain.
  * The overall external processing protocol works like this:
  * 1. The data plane sends to the service information about the HTTP request.
- * 2. The service sends back a ProcessingResponse message that directs
- *    the data plane to either stop processing, continue without it, or send
- *    it the next chunk of the message body.
- * 3. If so requested, the data plane sends the server the message body in
- *    chunks, or the entire body at once. In either case, the server may send
- *    back a ProcessingResponse for each message it receives, or wait for
- *    a certain amount of body chunks received before streaming back the
- *    ProcessingResponse messages.
- * 4. If so requested, the data plane sends the server the HTTP trailers,
- *    and the server sends back a ProcessingResponse.
- * 5. At this point, request processing is done, and we pick up again
- *    at step 1 when the data plane receives a response from the upstream
- *    server.
- * 6. At any point above, if the server closes the gRPC stream cleanly,
- *    then the data plane proceeds without consulting the server.
- * 7. At any point above, if the server closes the gRPC stream with an error,
- *    then the data plane returns a 500 error to the client, unless the filter
- *    was configured to ignore errors.
- * In other words, the process is a request/response conversation, but
- * using a gRPC stream to make it easier for the server to
- * maintain state.
+ * 2. The service sends back a ``ProcessingResponse`` message that directs the data plane to either
+ *    stop processing, continue without it, or send it the next chunk of the message body.
+ * 3. If so requested, the data plane sends the server the message body in chunks, or the entire
+ *    body at once. In either case, the server may send back a ``ProcessingResponse`` for each
+ *    message it receives, or wait for a certain amount of body chunks to be received before
+ *    streaming back the ``ProcessingResponse`` messages.
+ * 4. If so requested, the data plane sends the server the HTTP trailers, and the server sends back
+ *    a ``ProcessingResponse``.
+ * 5. At this point, request processing is done, and we pick up again at step 1 when the data plane
+ *    receives a response from the upstream server.
+ * 6. At any point above, if the server closes the gRPC stream cleanly, then the data plane
+ *    proceeds without consulting the server.
+ * 7. At any point above, if the server closes the gRPC stream with an error, then the data plane
+ *    returns a ``500`` error to the client, unless the filter was configured to ignore errors.
+ * In other words, the process is a request/response conversation, but using a gRPC stream to make
+ * it easier for the server to maintain state.
  *
*/ @io.grpc.stub.annotations.GrpcGenerated @@ -131,31 +125,25 @@ public ExternalProcessorFutureStub newStub(io.grpc.Channel channel, io.grpc.Call /** * 
-   * A service that can access and modify HTTP requests and responses
-   * as part of a filter chain.
+   * A service that can access and modify HTTP requests and responses as part of a filter chain.
    * The overall external processing protocol works like this:
    * 1. The data plane sends to the service information about the HTTP request.
-   * 2. The service sends back a ProcessingResponse message that directs
-   *    the data plane to either stop processing, continue without it, or send
-   *    it the next chunk of the message body.
-   * 3. If so requested, the data plane sends the server the message body in
-   *    chunks, or the entire body at once. In either case, the server may send
-   *    back a ProcessingResponse for each message it receives, or wait for
-   *    a certain amount of body chunks received before streaming back the
-   *    ProcessingResponse messages.
-   * 4. If so requested, the data plane sends the server the HTTP trailers,
-   *    and the server sends back a ProcessingResponse.
-   * 5. At this point, request processing is done, and we pick up again
-   *    at step 1 when the data plane receives a response from the upstream
-   *    server.
-   * 6. At any point above, if the server closes the gRPC stream cleanly,
-   *    then the data plane proceeds without consulting the server.
-   * 7. At any point above, if the server closes the gRPC stream with an error,
-   *    then the data plane returns a 500 error to the client, unless the filter
-   *    was configured to ignore errors.
-   * In other words, the process is a request/response conversation, but
-   * using a gRPC stream to make it easier for the server to
-   * maintain state.
+   * 2. The service sends back a ``ProcessingResponse`` message that directs the data plane to either
+   *    stop processing, continue without it, or send it the next chunk of the message body.
+   * 3. If so requested, the data plane sends the server the message body in chunks, or the entire
+   *    body at once. In either case, the server may send back a ``ProcessingResponse`` for each
+   *    message it receives, or wait for a certain amount of body chunks to be received before
+   *    streaming back the ``ProcessingResponse`` messages.
+   * 4. If so requested, the data plane sends the server the HTTP trailers, and the server sends back
+   *    a ``ProcessingResponse``.
+   * 5. At this point, request processing is done, and we pick up again at step 1 when the data plane
+   *    receives a response from the upstream server.
+   * 6. At any point above, if the server closes the gRPC stream cleanly, then the data plane
+   *    proceeds without consulting the server.
+   * 7. At any point above, if the server closes the gRPC stream with an error, then the data plane
+   *    returns a ``500`` error to the client, unless the filter was configured to ignore errors.
+   * In other words, the process is a request/response conversation, but using a gRPC stream to make
+   * it easier for the server to maintain state.
    *
*/ public interface AsyncService { @@ -164,7 +152,7 @@ public interface AsyncService { * 
      * This begins the bidirectional stream that the data plane will use to
      * give the server control over what the filter does. The actual
-     * protocol is described by the ProcessingRequest and ProcessingResponse
+     * protocol is described by the ``ProcessingRequest`` and ``ProcessingResponse``
      * messages below.
      *
*/ @@ -177,31 +165,25 @@ default io.grpc.stub.StreamObserver - * A service that can access and modify HTTP requests and responses - * as part of a filter chain. + * A service that can access and modify HTTP requests and responses as part of a filter chain. * The overall external processing protocol works like this: * 1. The data plane sends to the service information about the HTTP request. - * 2. The service sends back a ProcessingResponse message that directs - * the data plane to either stop processing, continue without it, or send - * it the next chunk of the message body. - * 3. If so requested, the data plane sends the server the message body in - * chunks, or the entire body at once. In either case, the server may send - * back a ProcessingResponse for each message it receives, or wait for - * a certain amount of body chunks received before streaming back the - * ProcessingResponse messages. - * 4. If so requested, the data plane sends the server the HTTP trailers, - * and the server sends back a ProcessingResponse. - * 5. At this point, request processing is done, and we pick up again - * at step 1 when the data plane receives a response from the upstream - * server. - * 6. At any point above, if the server closes the gRPC stream cleanly, - * then the data plane proceeds without consulting the server. - * 7. At any point above, if the server closes the gRPC stream with an error, - * then the data plane returns a 500 error to the client, unless the filter - * was configured to ignore errors. - * In other words, the process is a request/response conversation, but - * using a gRPC stream to make it easier for the server to - * maintain state. + * 2. The service sends back a ``ProcessingResponse`` message that directs the data plane to either + * stop processing, continue without it, or send it the next chunk of the message body. + * 3. If so requested, the data plane sends the server the message body in chunks, or the entire + * body at once. In either case, the server may send back a ``ProcessingResponse`` for each + * message it receives, or wait for a certain amount of body chunks to be received before + * streaming back the ``ProcessingResponse`` messages. + * 4. If so requested, the data plane sends the server the HTTP trailers, and the server sends back + * a ``ProcessingResponse``. + * 5. At this point, request processing is done, and we pick up again at step 1 when the data plane + * receives a response from the upstream server. + * 6. At any point above, if the server closes the gRPC stream cleanly, then the data plane + * proceeds without consulting the server. + * 7. At any point above, if the server closes the gRPC stream with an error, then the data plane + * returns a ``500`` error to the client, unless the filter was configured to ignore errors. + * In other words, the process is a request/response conversation, but using a gRPC stream to make + * it easier for the server to maintain state. * */ public static abstract class ExternalProcessorImplBase @@ -215,31 +197,25 @@ public static abstract class ExternalProcessorImplBase /** * A stub to allow clients to do asynchronous rpc calls to service ExternalProcessor. * 
-   * A service that can access and modify HTTP requests and responses
-   * as part of a filter chain.
+   * A service that can access and modify HTTP requests and responses as part of a filter chain.
    * The overall external processing protocol works like this:
    * 1. The data plane sends to the service information about the HTTP request.
-   * 2. The service sends back a ProcessingResponse message that directs
-   *    the data plane to either stop processing, continue without it, or send
-   *    it the next chunk of the message body.
-   * 3. If so requested, the data plane sends the server the message body in
-   *    chunks, or the entire body at once. In either case, the server may send
-   *    back a ProcessingResponse for each message it receives, or wait for
-   *    a certain amount of body chunks received before streaming back the
-   *    ProcessingResponse messages.
-   * 4. If so requested, the data plane sends the server the HTTP trailers,
-   *    and the server sends back a ProcessingResponse.
-   * 5. At this point, request processing is done, and we pick up again
-   *    at step 1 when the data plane receives a response from the upstream
-   *    server.
-   * 6. At any point above, if the server closes the gRPC stream cleanly,
-   *    then the data plane proceeds without consulting the server.
-   * 7. At any point above, if the server closes the gRPC stream with an error,
-   *    then the data plane returns a 500 error to the client, unless the filter
-   *    was configured to ignore errors.
-   * In other words, the process is a request/response conversation, but
-   * using a gRPC stream to make it easier for the server to
-   * maintain state.
+   * 2. The service sends back a ``ProcessingResponse`` message that directs the data plane to either
+   *    stop processing, continue without it, or send it the next chunk of the message body.
+   * 3. If so requested, the data plane sends the server the message body in chunks, or the entire
+   *    body at once. In either case, the server may send back a ``ProcessingResponse`` for each
+   *    message it receives, or wait for a certain amount of body chunks to be received before
+   *    streaming back the ``ProcessingResponse`` messages.
+   * 4. If so requested, the data plane sends the server the HTTP trailers, and the server sends back
+   *    a ``ProcessingResponse``.
+   * 5. At this point, request processing is done, and we pick up again at step 1 when the data plane
+   *    receives a response from the upstream server.
+   * 6. At any point above, if the server closes the gRPC stream cleanly, then the data plane
+   *    proceeds without consulting the server.
+   * 7. At any point above, if the server closes the gRPC stream with an error, then the data plane
+   *    returns a ``500`` error to the client, unless the filter was configured to ignore errors.
+   * In other words, the process is a request/response conversation, but using a gRPC stream to make
+   * it easier for the server to maintain state.
    *
*/ public static final class ExternalProcessorStub @@ -259,7 +235,7 @@ protected ExternalProcessorStub build( * 
      * This begins the bidirectional stream that the data plane will use to
      * give the server control over what the filter does. The actual
-     * protocol is described by the ProcessingRequest and ProcessingResponse
+     * protocol is described by the ``ProcessingRequest`` and ``ProcessingResponse``
      * messages below.
      *
*/ @@ -273,31 +249,25 @@ public io.grpc.stub.StreamObserver - * A service that can access and modify HTTP requests and responses - * as part of a filter chain. + * A service that can access and modify HTTP requests and responses as part of a filter chain. * The overall external processing protocol works like this: * 1. The data plane sends to the service information about the HTTP request. - * 2. The service sends back a ProcessingResponse message that directs - * the data plane to either stop processing, continue without it, or send - * it the next chunk of the message body. - * 3. If so requested, the data plane sends the server the message body in - * chunks, or the entire body at once. In either case, the server may send - * back a ProcessingResponse for each message it receives, or wait for - * a certain amount of body chunks received before streaming back the - * ProcessingResponse messages. - * 4. If so requested, the data plane sends the server the HTTP trailers, - * and the server sends back a ProcessingResponse. - * 5. At this point, request processing is done, and we pick up again - * at step 1 when the data plane receives a response from the upstream - * server. - * 6. At any point above, if the server closes the gRPC stream cleanly, - * then the data plane proceeds without consulting the server. - * 7. At any point above, if the server closes the gRPC stream with an error, - * then the data plane returns a 500 error to the client, unless the filter - * was configured to ignore errors. - * In other words, the process is a request/response conversation, but - * using a gRPC stream to make it easier for the server to - * maintain state. + * 2. The service sends back a ``ProcessingResponse`` message that directs the data plane to either + * stop processing, continue without it, or send it the next chunk of the message body. + * 3. If so requested, the data plane sends the server the message body in chunks, or the entire + * body at once. In either case, the server may send back a ``ProcessingResponse`` for each + * message it receives, or wait for a certain amount of body chunks to be received before + * streaming back the ``ProcessingResponse`` messages. + * 4. If so requested, the data plane sends the server the HTTP trailers, and the server sends back + * a ``ProcessingResponse``. + * 5. At this point, request processing is done, and we pick up again at step 1 when the data plane + * receives a response from the upstream server. + * 6. At any point above, if the server closes the gRPC stream cleanly, then the data plane + * proceeds without consulting the server. + * 7. At any point above, if the server closes the gRPC stream with an error, then the data plane + * returns a ``500`` error to the client, unless the filter was configured to ignore errors. + * In other words, the process is a request/response conversation, but using a gRPC stream to make + * it easier for the server to maintain state. * */ public static final class ExternalProcessorBlockingV2Stub @@ -317,7 +287,7 @@ protected ExternalProcessorBlockingV2Stub build( * 
      * This begins the bidirectional stream that the data plane will use to
      * give the server control over what the filter does. The actual
-     * protocol is described by the ProcessingRequest and ProcessingResponse
+     * protocol is described by the ``ProcessingRequest`` and ``ProcessingResponse``
      * messages below.
      *
*/ @@ -332,31 +302,25 @@ protected ExternalProcessorBlockingV2Stub build( /** * A stub to allow clients to do limited synchronous rpc calls to service ExternalProcessor. * 
-   * A service that can access and modify HTTP requests and responses
-   * as part of a filter chain.
+   * A service that can access and modify HTTP requests and responses as part of a filter chain.
    * The overall external processing protocol works like this:
    * 1. The data plane sends to the service information about the HTTP request.
-   * 2. The service sends back a ProcessingResponse message that directs
-   *    the data plane to either stop processing, continue without it, or send
-   *    it the next chunk of the message body.
-   * 3. If so requested, the data plane sends the server the message body in
-   *    chunks, or the entire body at once. In either case, the server may send
-   *    back a ProcessingResponse for each message it receives, or wait for
-   *    a certain amount of body chunks received before streaming back the
-   *    ProcessingResponse messages.
-   * 4. If so requested, the data plane sends the server the HTTP trailers,
-   *    and the server sends back a ProcessingResponse.
-   * 5. At this point, request processing is done, and we pick up again
-   *    at step 1 when the data plane receives a response from the upstream
-   *    server.
-   * 6. At any point above, if the server closes the gRPC stream cleanly,
-   *    then the data plane proceeds without consulting the server.
-   * 7. At any point above, if the server closes the gRPC stream with an error,
-   *    then the data plane returns a 500 error to the client, unless the filter
-   *    was configured to ignore errors.
-   * In other words, the process is a request/response conversation, but
-   * using a gRPC stream to make it easier for the server to
-   * maintain state.
+   * 2. The service sends back a ``ProcessingResponse`` message that directs the data plane to either
+   *    stop processing, continue without it, or send it the next chunk of the message body.
+   * 3. If so requested, the data plane sends the server the message body in chunks, or the entire
+   *    body at once. In either case, the server may send back a ``ProcessingResponse`` for each
+   *    message it receives, or wait for a certain amount of body chunks to be received before
+   *    streaming back the ``ProcessingResponse`` messages.
+   * 4. If so requested, the data plane sends the server the HTTP trailers, and the server sends back
+   *    a ``ProcessingResponse``.
+   * 5. At this point, request processing is done, and we pick up again at step 1 when the data plane
+   *    receives a response from the upstream server.
+   * 6. At any point above, if the server closes the gRPC stream cleanly, then the data plane
+   *    proceeds without consulting the server.
+   * 7. At any point above, if the server closes the gRPC stream with an error, then the data plane
+   *    returns a ``500`` error to the client, unless the filter was configured to ignore errors.
+   * In other words, the process is a request/response conversation, but using a gRPC stream to make
+   * it easier for the server to maintain state.
    *
*/ public static final class ExternalProcessorBlockingStub @@ -376,31 +340,25 @@ protected ExternalProcessorBlockingStub build( /** * A stub to allow clients to do ListenableFuture-style rpc calls to service ExternalProcessor. * 
-   * A service that can access and modify HTTP requests and responses
-   * as part of a filter chain.
+   * A service that can access and modify HTTP requests and responses as part of a filter chain.
    * The overall external processing protocol works like this:
    * 1. The data plane sends to the service information about the HTTP request.
-   * 2. The service sends back a ProcessingResponse message that directs
-   *    the data plane to either stop processing, continue without it, or send
-   *    it the next chunk of the message body.
-   * 3. If so requested, the data plane sends the server the message body in
-   *    chunks, or the entire body at once. In either case, the server may send
-   *    back a ProcessingResponse for each message it receives, or wait for
-   *    a certain amount of body chunks received before streaming back the
-   *    ProcessingResponse messages.
-   * 4. If so requested, the data plane sends the server the HTTP trailers,
-   *    and the server sends back a ProcessingResponse.
-   * 5. At this point, request processing is done, and we pick up again
-   *    at step 1 when the data plane receives a response from the upstream
-   *    server.
-   * 6. At any point above, if the server closes the gRPC stream cleanly,
-   *    then the data plane proceeds without consulting the server.
-   * 7. At any point above, if the server closes the gRPC stream with an error,
-   *    then the data plane returns a 500 error to the client, unless the filter
-   *    was configured to ignore errors.
-   * In other words, the process is a request/response conversation, but
-   * using a gRPC stream to make it easier for the server to
-   * maintain state.
+   * 2. The service sends back a ``ProcessingResponse`` message that directs the data plane to either
+   *    stop processing, continue without it, or send it the next chunk of the message body.
+   * 3. If so requested, the data plane sends the server the message body in chunks, or the entire
+   *    body at once. In either case, the server may send back a ``ProcessingResponse`` for each
+   *    message it receives, or wait for a certain amount of body chunks to be received before
+   *    streaming back the ``ProcessingResponse`` messages.
+   * 4. If so requested, the data plane sends the server the HTTP trailers, and the server sends back
+   *    a ``ProcessingResponse``.
+   * 5. At this point, request processing is done, and we pick up again at step 1 when the data plane
+   *    receives a response from the upstream server.
+   * 6. At any point above, if the server closes the gRPC stream cleanly, then the data plane
+   *    proceeds without consulting the server.
+   * 7. At any point above, if the server closes the gRPC stream with an error, then the data plane
+   *    returns a ``500`` error to the client, unless the filter was configured to ignore errors.
+   * In other words, the process is a request/response conversation, but using a gRPC stream to make
+   * it easier for the server to maintain state.
    *
*/ public static final class ExternalProcessorFutureStub