api: add unified matching API (#13926)

* api: add unified matching API

Signed-off-by: Snow Pettersen <snowp@lyft.com>

Mirrored from https://github.com/envoyproxy/envoy @ de8334227416ebc16a344e3b3abab2998cb34eeb

envoy/config/common/matcher/v3/BUILD

@@ -6,7 +6,9 @@ licenses(["notice"])  # Apache 2
 
 api_proto_package(
     deps = [
+        "//envoy/config/core/v3:pkg",
         "//envoy/config/route/v3:pkg",
+        "//envoy/type/matcher/v3:pkg",
         "@com_github_cncf_udpa//udpa/annotations:pkg",
     ],
 )

envoy/config/common/matcher/v3/matcher.proto

@@ -2,7 +2,9 @@ syntax = "proto3";
 
 package envoy.config.common.matcher.v3;
 
+import "envoy/config/core/v3/extension.proto";
 import "envoy/config/route/v3/route_components.proto";
+import "envoy/type/matcher/v3/value.proto";
 
 import "udpa/annotations/migrate.proto";
 import "udpa/annotations/status.proto";
@@ -16,6 +18,126 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE;
 
 // [#protodoc-title: Unified Matcher API]
 
+// A matcher, which may traverse a matching tree in order to result in a match action.
+// During matching, the tree will be traversed until a match is found, or if no match
+// is found the action specified by the most specific on_no_match will be evaluated.
+// As an on_no_match might result in another matching tree being evaluated, this process
+// might repeat several times until the final OnMatch (or no match) is decided.
+message Matcher {
+  // What to do if a match is successful.
+  message OnMatch {
+    oneof on_match {
+      option (validate.required) = true;
+
+      // Nested matcher to evaluate.
+      // If the nested matcher does not match and does not specify
+      // on_no_match, then this matcher is considered not to have
+      // matched, even if a predicate at this level or above returned
+      // true.
+      Matcher matcher = 1;
+
+      // Protocol-specific action to take.
+      core.v3.TypedExtensionConfig action = 2;
+    }
+  }
+
+  // A linear list of field matchers.
+  // The field matchers are evaluated in order, and the first match
+  // wins.
+  message MatcherList {
+    // Predicate to determine if a match is successful.
+    message Predicate {
+      // Predicate for a single input field.
+      message SinglePredicate {
+        // Protocol-specific specification of input field to match on.
+        core.v3.TypedExtensionConfig input = 1 [(validate.rules).message = {required: true}];
+
+        oneof matcher {
+          option (validate.required) = true;
+
+          // Use existing infrastructure for actually matching the
+          // value.
+          type.matcher.v3.ValueMatcher value_match = 2;
+
+          // Extension for custom matching logic.
+          core.v3.TypedExtensionConfig custom_match = 3;
+        }
+      }
+
+      // A list of two or more matchers. Used to allow using a list within a oneof.
+      message PredicateList {
+        repeated Predicate predicate = 1 [(validate.rules).repeated = {min_items: 2}];
+      }
+
+      oneof match_type {
+        option (validate.required) = true;
+
+        // A single predicate to evaluate.
+        SinglePredicate single_predicate = 1;
+
+        // A list of predicates to be OR-ed together.
+        PredicateList or_matcher = 2;
+
+        // A list of predicates to be AND-ed together.
+        PredicateList and_matcher = 3;
+      }
+    }
+
+    // An individual matcher.
+    message FieldMatcher {
+      // Determines if the match succeeds.
+      Predicate predicate = 1 [(validate.rules).message = {required: true}];
+
+      // What to do if the match succeeds.
+      OnMatch on_match = 2 [(validate.rules).message = {required: true}];
+    }
+
+    // A list of matchers. First match wins.
+    repeated FieldMatcher matchers = 1 [(validate.rules).repeated = {min_items: 1}];
+  }
+
+  message MatcherTree {
+    // A map of configured matchers. Used to allow using a map within a oneof.
+    message MatchMap {
+      map<string, OnMatch> map = 1 [(validate.rules).map = {min_pairs: 1}];
+    }
+
+    // Protocol-specific specification of input field to match on.
+    core.v3.TypedExtensionConfig input = 1 [(validate.rules).message = {required: true}];
+
+    // Exact or prefix match maps in which to look up the input value.
+    // If the lookup succeeds, the match is considered successful, and
+    // the corresponding OnMatch is used.
+    oneof tree_type {
+      option (validate.required) = true;
+
+      MatchMap exact_match_map = 2;
+
+      // Longest matching prefix wins.
+      MatchMap prefix_match_map = 3;
+
+      // Extension for custom matching logic.
+      core.v3.TypedExtensionConfig custom_match = 4;
+    }
+  }
+
+  oneof matcher_type {
+    option (validate.required) = true;
+
+    // A linear list of matchers to evaluate.
+    MatcherList matcher_list = 1;
+
+    // A match tree to evaluate.
+    MatcherTree matcher_tree = 2;
+  }
+
+  // Optional OnMatch to use if the matcher failed.
+  // If specified, the OnMatch is used, and the matcher is considered
+  // to have matched.
+  // If not specified, the matcher is considered not to have matched.
+  OnMatch on_no_match = 3;
+}
+
 // Match configuration. This is a recursive structure which allows complex nested match
 // configurations to be built using various logical operators.
 // [#next-free-field: 11]

envoy/config/common/matcher/v4alpha/BUILD

@@ -7,7 +7,9 @@ licenses(["notice"])  # Apache 2
 api_proto_package(
     deps = [
         "//envoy/config/common/matcher/v3:pkg",
+        "//envoy/config/core/v4alpha:pkg",
         "//envoy/config/route/v4alpha:pkg",
+        "//envoy/type/matcher/v4alpha:pkg",
         "@com_github_cncf_udpa//udpa/annotations:pkg",
     ],
 )

envoy/config/common/matcher/v4alpha/matcher.proto

@@ -2,7 +2,9 @@ syntax = "proto3";
 
 package envoy.config.common.matcher.v4alpha;
 
+import "envoy/config/core/v4alpha/extension.proto";
 import "envoy/config/route/v4alpha/route_components.proto";
+import "envoy/type/matcher/v4alpha/value.proto";
 
 import "udpa/annotations/status.proto";
 import "udpa/annotations/versioning.proto";
@@ -15,6 +17,153 @@ option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSIO
 
 // [#protodoc-title: Unified Matcher API]
 
+// A matcher, which may traverse a matching tree in order to result in a match action.
+// During matching, the tree will be traversed until a match is found, or if no match
+// is found the action specified by the most specific on_no_match will be evaluated.
+// As an on_no_match might result in another matching tree being evaluated, this process
+// might repeat several times until the final OnMatch (or no match) is decided.
+message Matcher {
+  option (udpa.annotations.versioning).previous_message_type =
+      "envoy.config.common.matcher.v3.Matcher";
+
+  // What to do if a match is successful.
+  message OnMatch {
+    option (udpa.annotations.versioning).previous_message_type =
+        "envoy.config.common.matcher.v3.Matcher.OnMatch";
+
+    oneof on_match {
+      option (validate.required) = true;
+
+      // Nested matcher to evaluate.
+      // If the nested matcher does not match and does not specify
+      // on_no_match, then this matcher is considered not to have
+      // matched, even if a predicate at this level or above returned
+      // true.
+      Matcher matcher = 1;
+
+      // Protocol-specific action to take.
+      core.v4alpha.TypedExtensionConfig action = 2;
+    }
+  }
+
+  // A linear list of field matchers.
+  // The field matchers are evaluated in order, and the first match
+  // wins.
+  message MatcherList {
+    option (udpa.annotations.versioning).previous_message_type =
+        "envoy.config.common.matcher.v3.Matcher.MatcherList";
+
+    // Predicate to determine if a match is successful.
+    message Predicate {
+      option (udpa.annotations.versioning).previous_message_type =
+          "envoy.config.common.matcher.v3.Matcher.MatcherList.Predicate";
+
+      // Predicate for a single input field.
+      message SinglePredicate {
+        option (udpa.annotations.versioning).previous_message_type =
+            "envoy.config.common.matcher.v3.Matcher.MatcherList.Predicate.SinglePredicate";
+
+        // Protocol-specific specification of input field to match on.
+        core.v4alpha.TypedExtensionConfig input = 1 [(validate.rules).message = {required: true}];
+
+        oneof matcher {
+          option (validate.required) = true;
+
+          // Use existing infrastructure for actually matching the
+          // value.
+          type.matcher.v4alpha.ValueMatcher value_match = 2;
+
+          // Extension for custom matching logic.
+          core.v4alpha.TypedExtensionConfig custom_match = 3;
+        }
+      }
+
+      // A list of two or more matchers. Used to allow using a list within a oneof.
+      message PredicateList {
+        option (udpa.annotations.versioning).previous_message_type =
+            "envoy.config.common.matcher.v3.Matcher.MatcherList.Predicate.PredicateList";
+
+        repeated Predicate predicate = 1 [(validate.rules).repeated = {min_items: 2}];
+      }
+
+      oneof match_type {
+        option (validate.required) = true;
+
+        // A single predicate to evaluate.
+        SinglePredicate single_predicate = 1;
+
+        // A list of predicates to be OR-ed together.
+        PredicateList or_matcher = 2;
+
+        // A list of predicates to be AND-ed together.
+        PredicateList and_matcher = 3;
+      }
+    }
+
+    // An individual matcher.
+    message FieldMatcher {
+      option (udpa.annotations.versioning).previous_message_type =
+          "envoy.config.common.matcher.v3.Matcher.MatcherList.FieldMatcher";
+
+      // Determines if the match succeeds.
+      Predicate predicate = 1 [(validate.rules).message = {required: true}];
+
+      // What to do if the match succeeds.
+      OnMatch on_match = 2 [(validate.rules).message = {required: true}];
+    }
+
+    // A list of matchers. First match wins.
+    repeated FieldMatcher matchers = 1 [(validate.rules).repeated = {min_items: 1}];
+  }
+
+  message MatcherTree {
+    option (udpa.annotations.versioning).previous_message_type =
+        "envoy.config.common.matcher.v3.Matcher.MatcherTree";
+
+    // A map of configured matchers. Used to allow using a map within a oneof.
+    message MatchMap {
+      option (udpa.annotations.versioning).previous_message_type =
+          "envoy.config.common.matcher.v3.Matcher.MatcherTree.MatchMap";
+
+      map<string, OnMatch> map = 1 [(validate.rules).map = {min_pairs: 1}];
+    }
+
+    // Protocol-specific specification of input field to match on.
+    core.v4alpha.TypedExtensionConfig input = 1 [(validate.rules).message = {required: true}];
+
+    // Exact or prefix match maps in which to look up the input value.
+    // If the lookup succeeds, the match is considered successful, and
+    // the corresponding OnMatch is used.
+    oneof tree_type {
+      option (validate.required) = true;
+
+      MatchMap exact_match_map = 2;
+
+      // Longest matching prefix wins.
+      MatchMap prefix_match_map = 3;
+
+      // Extension for custom matching logic.
+      core.v4alpha.TypedExtensionConfig custom_match = 4;
+    }
+  }
+
+  oneof matcher_type {
+    option (validate.required) = true;
+
+    // A linear list of matchers to evaluate.
+    MatcherList matcher_list = 1;
+
+    // A match tree to evaluate.
+    MatcherTree matcher_tree = 2;
+  }
+
+  // Optional OnMatch to use if the matcher failed.
+  // If specified, the OnMatch is used, and the matcher is considered
+  // to have matched.
+  // If not specified, the matcher is considered not to have matched.
+  OnMatch on_no_match = 3;
+}
+
 // Match configuration. This is a recursive structure which allows complex nested match
 // configurations to be built using various logical operators.
 // [#next-free-field: 11]