review

Signed-off-by: Kuat Yessenov <[email protected]>

api/envoy/extensions/filters/common/set_filter_state/v3/rule.proto → 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 <config_internal_upstream_transport>` for more details.
+  // transport <config_internal_upstream_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;
 }

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;
 }

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;
 }

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

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 <envoy_v3_api_msg_extensions.filters.http.set_filter_state.v3.Config>`
 
-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
-<well_known_filter_state>` 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 <well_known_filter_state>` 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
 --------

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 <envoy_v3_api_msg_extensions.filters.network.set_filter_state.v3.Config>`
 
-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 <well_known_filter_state>` 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 <well_known_filter_state>` 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
 --------