Skip to content

Commit a40a332

Browse files
docs: enhance the docs on setting filter state (#42665)
## Description Our docs around filter state filter and what does Factory and Object Keys mean are a bit confusing. This PR is trying to make it easy to understand these fields by adding more details and examples. --- **Commit Message:** docs: enhance the docs on setting filter state **Additional Description:** making it easy to understand the filter state object and factory key fields by adding more details and examples. **Risk Level:** Low **Testing:** CI **Docs Changes:** Added **Release Notes:** N/A --------- Signed-off-by: Rohit Agrawal <[email protected]> Mirrored from https://github.com/envoyproxy/envoy @ 210eb6e6c7cc88f5bdfd417f8ce52e5f2363b91a
1 parent 665a2c2 commit a40a332

File tree

1 file changed

+46
-5
lines changed
  • envoy/extensions/filters/common/set_filter_state/v3

1 file changed

+46
-5
lines changed

envoy/extensions/filters/common/set_filter_state/v3/value.proto

Lines changed: 46 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -32,14 +32,55 @@ message FilterStateValue {
3232
oneof key {
3333
option (validate.required) = true;
3434

35-
// Filter state object key. The key is used to lookup the object factory, unless :ref:`factory_key
36-
// <envoy_v3_api_field_extensions.filters.common.set_filter_state.v3.FilterStateValue.factory_key>` is set. See
37-
// :ref:`the well-known filter state keys <well_known_filter_state>` for a list of valid object keys.
35+
// The name under which the filter state object will be stored and can be retrieved.
36+
//
37+
// When using :ref:`well-known filter state keys <well_known_filter_state>` (e.g.,
38+
// ``envoy.network.upstream_server_name``, ``envoy.tcp_proxy.cluster``), the object key serves
39+
// dual purpose where it identifies both where the data is stored and which factory creates the
40+
// object. In this case, :ref:`factory_key
41+
// <envoy_v3_api_field_extensions.filters.common.set_filter_state.v3.FilterStateValue.factory_key>`
42+
// is not needed.
43+
//
44+
// When using a custom key name which is not from the well-known list, you must also specify
45+
// :ref:`factory_key
46+
// <envoy_v3_api_field_extensions.filters.common.set_filter_state.v3.FilterStateValue.factory_key>`
47+
// to indicate which factory should create the object from your value.
48+
//
49+
// Example using a well-known key where ``factory_key`` is not needed:
50+
//
51+
// .. code-block:: yaml
52+
//
53+
// object_key: envoy.tcp_proxy.cluster
54+
// format_string:
55+
// text_format_source:
56+
// inline_string: "my-cluster"
57+
//
58+
// Example using a custom key which requires a ``factory_key``:
59+
//
60+
// .. code-block:: yaml
61+
//
62+
// object_key: my.custom.key
63+
// factory_key: envoy.string
64+
// format_string:
65+
// text_format_source:
66+
// inline_string: "my-value"
67+
//
3868
string object_key = 1 [(validate.rules).string = {min_len: 1}];
3969
}
4070

41-
// Optional filter object factory lookup key. See :ref:`the well-known filter state keys <well_known_filter_state>`
42-
// for a list of valid factory keys.
71+
// Specifies which registered factory should be used to create the filter state object from the
72+
// provided value. This field is required when :ref:`object_key
73+
// <envoy_v3_api_field_extensions.filters.common.set_filter_state.v3.FilterStateValue.object_key>`
74+
// is a custom name not found in the :ref:`well-known filter state keys <well_known_filter_state>`.
75+
//
76+
// Each well-known key has a factory registered with the same name (e.g., the key
77+
// ``envoy.tcp_proxy.cluster`` has a factory also named ``envoy.tcp_proxy.cluster``). For custom keys,
78+
// use one of the following generic factories:
79+
//
80+
// * ``envoy.string``: Creates a generic string object. Use this for arbitrary string values that
81+
// will be accessed via ``StringAccessor``.
82+
//
83+
// If not specified, defaults to the value of ``object_key``.
4384
string factory_key = 6;
4485

4586
oneof value {

0 commit comments

Comments
 (0)