diff --git a/api/envoy/extensions/filters/common/set_filter_state/v3/rule.proto b/api/envoy/extensions/filters/common/set_filter_state/v3/value.proto similarity index 79% rename from api/envoy/extensions/filters/common/set_filter_state/v3/rule.proto rename to api/envoy/extensions/filters/common/set_filter_state/v3/value.proto index 16fa02f8fa58..81d501033226 100644 --- a/api/envoy/extensions/filters/common/set_filter_state/v3/rule.proto +++ b/api/envoy/extensions/filters/common/set_filter_state/v3/value.proto @@ -8,16 +8,16 @@ import "udpa/annotations/status.proto"; import "validate/validate.proto"; option java_package = "io.envoyproxy.envoy.extensions.filters.common.set_filter_state.v3"; -option java_outer_classname = "RuleProto"; +option java_outer_classname = "ValueProto"; option java_multiple_files = true; option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/filters/common/set_filter_state/v3;set_filter_statev3"; option (udpa.annotations.file_status).package_version_status = ACTIVE; -// [#protodoc-title: Set-Filter-State Update Rule] +// [#protodoc-title: Set-Filter-State filter state value] -// A filter state update rule. +// A filter state key and value pair. // [#next-free-field: 6] -message Rule { +message FilterStateValue { enum SharedWithUpstream { // Object is not shared with the upstream internal connections. NONE = 0; @@ -45,13 +45,16 @@ message Rule { config.core.v3.SubstitutionFormatString format_string = 2; } - // If marked as read-only, the filter state key cannot be overridden by the subsequent updates. + // If marked as read-only, the filter state key value is locked, and cannot + // be overridden by any filter, including this filter. bool read_only = 3; // Configures the object to be shared with the upstream internal connections. See :ref:`internal upstream - // transport ` for more details. + // transport ` for more details on the filter state sharing with + // the internal connections. SharedWithUpstream shared_with_upstream = 4; // Skip the update if the value evaluates to an empty string. + // This option can be used to supply multiple alternatives for the same filter state object key. bool skip_if_empty = 5; } diff --git a/api/envoy/extensions/filters/http/set_filter_state/v3/set_filter_state.proto b/api/envoy/extensions/filters/http/set_filter_state/v3/set_filter_state.proto index 4a1556b2a491..54f1f4c334f2 100644 --- a/api/envoy/extensions/filters/http/set_filter_state/v3/set_filter_state.proto +++ b/api/envoy/extensions/filters/http/set_filter_state/v3/set_filter_state.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package envoy.extensions.filters.http.set_filter_state.v3; -import "envoy/extensions/filters/common/set_filter_state/v3/rule.proto"; +import "envoy/extensions/filters/common/set_filter_state/v3/value.proto"; import "udpa/annotations/status.proto"; @@ -21,6 +21,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#extension: envoy.filters.http.set_filter_state] message Config { - // A sequence of the filter state updates to apply on request headers events. - repeated common.set_filter_state.v3.Rule on_request_headers = 1; + // A sequence of the filter state values to apply in the specified order + // when a new request is received. + repeated common.set_filter_state.v3.FilterStateValue on_request_headers = 1; } diff --git a/api/envoy/extensions/filters/network/set_filter_state/v3/set_filter_state.proto b/api/envoy/extensions/filters/network/set_filter_state/v3/set_filter_state.proto index 022c43fe1be2..084f516e72fe 100644 --- a/api/envoy/extensions/filters/network/set_filter_state/v3/set_filter_state.proto +++ b/api/envoy/extensions/filters/network/set_filter_state/v3/set_filter_state.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package envoy.extensions.filters.network.set_filter_state.v3; -import "envoy/extensions/filters/common/set_filter_state/v3/rule.proto"; +import "envoy/extensions/filters/common/set_filter_state/v3/value.proto"; import "udpa/annotations/status.proto"; @@ -21,6 +21,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#extension: envoy.filters.network.set_filter_state] message Config { - // A sequence of the filter state updates to apply on the new connection events. - repeated common.set_filter_state.v3.Rule on_new_connection = 1; + // A sequence of the filter state values to apply in the specified order + // when a new connection is received. + repeated common.set_filter_state.v3.FilterStateValue on_new_connection = 1; } diff --git a/docs/root/api-v3/common_messages/common_messages.rst b/docs/root/api-v3/common_messages/common_messages.rst index cc4d3dab0f67..6fc045c73e47 100644 --- a/docs/root/api-v3/common_messages/common_messages.rst +++ b/docs/root/api-v3/common_messages/common_messages.rst @@ -38,4 +38,4 @@ Common messages ../config/core/v3/socket_option.proto ../config/core/v3/substitution_format_string.proto ../config/core/v3/udp_socket_config.proto - ../extensions/filters/common/set_filter_state/v3/rule.proto + ../extensions/filters/common/set_filter_state/v3/value.proto diff --git a/docs/root/configuration/http/http_filters/set_filter_state.rst b/docs/root/configuration/http/http_filters/set_filter_state.rst index 515282d63381..52dbe82c5a6a 100644 --- a/docs/root/configuration/http/http_filters/set_filter_state.rst +++ b/docs/root/configuration/http/http_filters/set_filter_state.rst @@ -5,10 +5,16 @@ Set-Filter-State HTTP Filter * This filter should be configured with the type URL ``type.googleapis.com/envoy.extensions.filters.http.set_filter_state.v3.Config``. * :ref:`v3 API reference ` -This filter is configured with rules that update the request filter state using -the request data. The filter state value can then be used for routing, load -balancing decisions, telemetry, etc. See :ref:`the well-known filter state keys -` for the controls used by the other extensions. +This filter is configured with a sequence of values to update the request +filter state using the request data. The filter state value can then be used +for routing, load balancing decisions, telemetry, etc. See :ref:`the well-known +filter state keys ` for the controls used by Envoy +extensions. + +.. warning:: + This filter allows overriding the behavior of other extensions and + significantly and indirectly altering the request processing logic. + Examples -------- diff --git a/docs/root/configuration/listeners/network_filters/set_filter_state.rst b/docs/root/configuration/listeners/network_filters/set_filter_state.rst index da70e5d2d046..0858815fc567 100644 --- a/docs/root/configuration/listeners/network_filters/set_filter_state.rst +++ b/docs/root/configuration/listeners/network_filters/set_filter_state.rst @@ -5,10 +5,16 @@ Set-Filter-State Network Filter * This filter should be configured with the type URL ``type.googleapis.com/envoy.extensions.filters.network.set_filter_state.v3.Config``. * :ref:`v3 API reference ` -This filter is configured with rules that update the connection filter state on -a new connection trigger. The filter state value can then be used for routing, -load balancing decisions, telemetry, etc. See :ref:`the well-known filter state -keys ` for the controls used by the other extensions. +This filter is configured with a sequence of values to update the connection +filter state using the connection data. The filter state value can then be used +for routing, load balancing decisions, telemetry, etc. See :ref:`the well-known +filter state keys ` for the controls used by Envoy +extensions. + +.. warning:: + This filter allows overriding the behavior of other extensions and + significantly and indirectly altering the connection processing logic. + Examples --------