syntax = "proto3";

package envoy.extensions.http.ext_proc.processing_request_modifiers.mapped_attribute_builder.v3;

import "xds/annotations/v3/status.proto";

import "udpa/annotations/status.proto";

option java_package = "io.envoyproxy.envoy.extensions.http.ext_proc.processing_request_modifiers.mapped_attribute_builder.v3";
option java_outer_classname = "MappedAttributeBuilderProto";
option java_multiple_files = true;
option go_package = "github.com/envoyproxy/go-control-plane/envoy/extensions/http/ext_proc/processing_request_modifiers/mapped_attribute_builder/v3;mapped_attribute_builderv3";
option (udpa.annotations.file_status).package_version_status = ACTIVE;
option (xds.annotations.v3.file_status).work_in_progress = true;

// [#protodoc-title: Mapped Attribute Builder for the external processor]
// [#extension: envoy.http.ext_proc.processing_request_modifiers.mapped_attribute_builder]

// Extension to build custom attributes in the :ref:`request
// <envoy_v3_api_msg_service.ext_proc.v3.ProcessingRequest>` based on a configurable mapping. The
// native implementation uses the CEL expression as the key, which is not always desirable. Using this
// extension, one can re-map a CEL expression that references internal filter state into a more
// user-friendly key that decouples the value from the underlying filter implementation.
//
// If a given CEL expression fails to eval, it will not be present in the attributes struct.
//
// If this extension is configured, then the original :ref:`ProcessingRequest
// <envoy_v3_api_msg_service.ext_proc.v3.ProcessingRequest>`'s ``request_attributes`` are ignored,
// and all attributes should be explicitly set via this extension.
//
// An example configuration may look like so:
//
// .. code-block:: yaml
//
//    mapped_request_attributes:
//      "request.path": "request.path"
//      "source.country": "metadata.filter_metadata['com.example.location_filter']['country_code']"
//
// In the above example, the complex filter_metadata expression is evaluated via CEL, and the value
// is stored under the friendlier ``source.country`` key. ``The ProcessingRequest`` would look like:
//
// .. code-block:: text
//
//    attributes {
//      key: "envoy.filters.http.ext_proc"
//      value {
//        fields {
//          key: "request.path"
//          value {
//            string_value: "/profile"
//          }
//        }
//        fields {
//          key: "source.country"
//          value {
//            string_value: "US"
//          }
//        }
//      }
//    }
//
// .. note::
//   Processing request modifiers are currently in alpha.
//
message MappedAttributeBuilder {
  // A map of request attributes to set in the attributes struct.
  // The key is the attribute name, the value is the attribute value,
  // interpretable by CEL. This allows for the re-mapping of attributes, which is not supported
  // by the native attribute building logic.
  map<string, string> mapped_request_attributes = 1;
}
