diff --git a/xds/type/matcher/v3/cel.proto b/xds/type/matcher/v3/cel.proto new file mode 100644 index 00000000..55678a46 --- /dev/null +++ b/xds/type/matcher/v3/cel.proto @@ -0,0 +1,60 @@ +syntax = "proto3"; + +package xds.type.matcher.v3; + +import "xds/annotations/v3/status.proto"; +import "xds/type/v3/cel.proto"; + +import "google/protobuf/wrappers.proto"; + +import "validate/validate.proto"; + +option java_package = "com.github.xds.type.matcher.v3"; +option java_outer_classname = "CelMatcherProto"; +option java_multiple_files = true; +option go_package = "github.com/cncf/xds/go/xds/type/matcher/v3"; + +option (xds.annotations.v3.file_status).work_in_progress = true; + +// [#protodoc-title: Common Expression Language (CEL) matchers] + +// Performs a match by evaluating a `Common Expression Language +// `_ (CEL) expression against the standardized set of +// :ref:`HTTP attributes ` specified via ``HttpAttributesCelMatchInput``. +// +// .. attention:: +// +// The match is ``true``, iff the result of the evaluation is a bool AND true. +// In all other cases, the match is ``false``, including but not limited to: non-bool types, +// ``false``, ``null``,`` int(1)``, etc. +// In case CEL expression raises an error, the result of the evaluation is interpreted "no match". +// +// Refer to :ref:`Unified Matcher API ` documentation +// for usage details. +// +// [#comment:TODO(sergiitk): Link HttpAttributesMatchInput + usage example.] +// [#comment:TODO(sergiitk): Add extension category.] +message CelBoolMatcher { + // Either parsed or checked representation of the CEL program. + type.v3.CelExpression expr_match = 1 [(validate.rules).message = {required: true}]; +} + +// Extracts a string by evaluating a `Common Expression Language +// `_ (CEL) expression against the standardized set of +// :ref:`HTTP attributes `. +// +// .. attention:: +// +// Besides CEL evaluation raising an error explicitly, CEL program returning a type other than +// the ``string``, or not returning anything, are considered an error as well. +// +// [#comment:TODO(sergiitk): Add extension category.] +message CelExtractString { + // The CEL expression used to extract a string from the CEL environment. + // the "subject string") that should be replaced. + type.v3.CelExpression expr_extract = 1 [(validate.rules).message = {required: true}]; + + // If CEL expression evaluates to an error, this value is be returned to the caller. + // If not set, the error is propagated to the caller. + google.protobuf.StringValue default_value = 2; +} diff --git a/xds/type/matcher/v3/http_inputs.proto b/xds/type/matcher/v3/http_inputs.proto index 4141eba2..303aa4ff 100644 --- a/xds/type/matcher/v3/http_inputs.proto +++ b/xds/type/matcher/v3/http_inputs.proto @@ -3,7 +3,6 @@ syntax = "proto3"; package xds.type.matcher.v3; import "xds/annotations/v3/status.proto"; -import "xds/type/v3/cel.proto"; import "validate/validate.proto"; @@ -14,38 +13,17 @@ option go_package = "github.com/cncf/xds/go/xds/type/matcher/v3"; option (xds.annotations.v3.file_status).work_in_progress = true; - // [#protodoc-title: Common HTTP Inputs] -// Specifies that matching will be performed on the set of :ref:`HTTP attributes -// ` using `Common Expression Language -// `_ (CEL) expression. -// -// The resulting input is the result of evaluating the CEL program. The result should be one of the -// supported types. Refer to the following table for the supported CEL result types, and known -// compatible matchers. -// -// .. list-table:: -// :widths: 25 75 -// :header-rows: 1 +// Specifies that matching should be performed on the set of :ref:`HTTP attributes +// `. // -// * - CEL result type -// - Compatible Matchers -// * - ``string`` -// - :ref:`StringMatcher ` -// * - ``bool`` -// - TBD +// The attributes will be exposed via `Common Expression Language +// `_ runtime to associated CEL matcher. // // Refer to :ref:`Unified Matcher API ` documentation // for usage details. // -// .. attention:: -// -// In case CEL expression raises an error, the result of the evaluation is interpreted -// short-circuited "no match". Associated Matcher is not evaluated. -// // [#extension: envoy.matching.inputs.http_attributes] message HttpAttributesCelMatchInput { - // CEL expression to evaluate. - type.v3.CelExpression expr = 1 [(validate.rules).message = {required: true}]; }