// Copyright 2025 Envoy Project Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// 
//     http://www.apache.org/licenses/LICENSE-2.0
// 
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package envoy.extensions.filters.common.set_filter_state.v3;

import "envoy/config/core/v3/substitution_format_string.proto";

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 = "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 filter state value]

// A filter state key and value pair.
// [#next-free-field: 7]
message FilterStateValue {
  enum SharedWithUpstream {
    // Object is not shared with the upstream internal connections.
    NONE = 0;

    // Object is shared with the upstream internal connection.
    ONCE = 1;

    // Object is shared with the upstream internal connection and any internal connection upstream from it.
    TRANSITIVE = 2;
  }

  oneof key {
    option (validate.required) = true;

    // Filter state object key. The key is used to lookup the object factory, unless :ref:`factory_key
    // <envoy_v3_api_field_extensions.filters.common.set_filter_state.v3.FilterStateValue.factory_key>` is set. See
    // :ref:`the well-known filter state keys <well_known_filter_state>` for a list of valid object keys.
    string object_key = 1 [(validate.rules).string = {min_len: 1}];
  }

  // Optional filter object factory lookup key. See :ref:`the well-known filter state keys <well_known_filter_state>`
  // for a list of valid factory keys.
  string factory_key = 6;

  oneof value {
    option (validate.required) = true;

    // Uses the :ref:`format string <config_access_log_format_strings>` to
    // instantiate the filter state object value.
    config.core.v3.SubstitutionFormatString format_string = 2;
  }

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