Add StructMatcher and use it in NodeMatcher (#9818)

Signed-off-by: Fuqiang Gao <fuqianggao@google.com>

api/envoy/type/matcher/metadata.proto

@@ -70,6 +70,8 @@ option java_multiple_files = true;
 // enforce access control based on dynamic metadata in a request. See :ref:`Permission
 // <envoy_api_msg_config.rbac.v2.Permission>` and :ref:`Principal
 // <envoy_api_msg_config.rbac.v2.Principal>`.
+
+// [#next-major-version: MetadataMatcher should use StructMatcher]
 message MetadataMatcher {
   // Specifies the segment in a path to retrieve value from Metadata.
   // Note: Currently it's not supported to retrieve a value from a list in Metadata. This means that

api/envoy/type/matcher/node.proto

@@ -2,8 +2,8 @@ syntax = "proto3";
 
 package envoy.type.matcher;
 
-import "envoy/type/matcher/metadata.proto";
 import "envoy/type/matcher/string.proto";
+import "envoy/type/matcher/struct.proto";
 
 option java_package = "io.envoyproxy.envoy.type.matcher";
 option java_outer_classname = "NodeProto";
@@ -18,5 +18,5 @@ message NodeMatcher {
   StringMatcher node_id = 1;
 
   // Specifies match criteria on the node metadata.
-  repeated MetadataMatcher node_metadatas = 2;
+  repeated StructMatcher node_metadatas = 2;
 }

api/envoy/type/matcher/struct.proto

@@ -0,0 +1,82 @@
+syntax = "proto3";
+
+package envoy.type.matcher;
+
+import "envoy/type/matcher/value.proto";
+
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.type.matcher";
+option java_outer_classname = "StructProto";
+option java_multiple_files = true;
+
+// [#protodoc-title: Struct matcher]
+
+// StructMatcher provides a general interface to check if a given value is matched in
+// google.protobuf.Struct. It uses `path` to retrieve the value
+// from the struct and then check if it's matched to the specified value.
+//
+// For example, for the following Struct:
+//
+// .. code-block:: yaml
+//
+//        fields:
+//          a:
+//            struct_value:
+//              fields:
+//                b:
+//                  struct_value:
+//                    fields:
+//                      c:
+//                        string_value: pro
+//                t:
+//                  list_value:
+//                    values:
+//                      - string_value: m
+//                      - string_value: n
+//
+// The following MetadataMatcher is matched as the path [a, b, c] will retrieve a string value "pro"
+// from the Metadata which is matched to the specified prefix match.
+//
+// .. code-block:: yaml
+//
+//    path:
+//    - key: a
+//    - key: b
+//    - key: c
+//    value:
+//      string_match:
+//        prefix: pr
+//
+// The following StructMatcher is matched as the code will match one of the string values in the
+// list at the path [a, t].
+//
+// .. code-block:: yaml
+//
+//    path:
+//    - key: a
+//    - key: t
+//    value:
+//      list_match:
+//        one_of:
+//          string_match:
+//            exact: m
+//
+// An example use of StructMatcher is to match metadata in envoy.v*.core.Node.
+message StructMatcher {
+  // Specifies the segment in a path to retrieve value from Struct.
+  message PathSegment {
+    oneof segment {
+      option (validate.required) = true;
+
+      // If specified, use the key to retrieve the value in a Struct.
+      string key = 1 [(validate.rules).string = {min_bytes: 1}];
+    }
+  }
+
+  // The path to retrieve the Value from the Struct.
+  repeated PathSegment path = 2 [(validate.rules).repeated = {min_items: 1}];
+
+  // The StructMatcher is matched if the value retrieved by path is matched to this value.
+  ValueMatcher value = 3 [(validate.rules).message = {required: true}];
+}

api/envoy/type/matcher/v3/metadata.proto

@@ -72,6 +72,8 @@ option java_multiple_files = true;
 // enforce access control based on dynamic metadata in a request. See :ref:`Permission
 // <envoy_api_msg_config.rbac.v3.Permission>` and :ref:`Principal
 // <envoy_api_msg_config.rbac.v3.Principal>`.
+
+// [#next-major-version: MetadataMatcher should use StructMatcher]
 message MetadataMatcher {
   option (udpa.annotations.versioning).previous_message_type = "envoy.type.matcher.MetadataMatcher";
 

api/envoy/type/matcher/v3/node.proto

@@ -2,8 +2,8 @@ syntax = "proto3";
 
 package envoy.type.matcher.v3;
 
-import "envoy/type/matcher/v3/metadata.proto";
 import "envoy/type/matcher/v3/string.proto";
+import "envoy/type/matcher/v3/struct.proto";
 
 import "udpa/annotations/versioning.proto";
 
@@ -22,5 +22,5 @@ message NodeMatcher {
   StringMatcher node_id = 1;
 
   // Specifies match criteria on the node metadata.
-  repeated MetadataMatcher node_metadatas = 2;
+  repeated StructMatcher node_metadatas = 2;
 }

api/envoy/type/matcher/v3/struct.proto

@@ -0,0 +1,89 @@
+syntax = "proto3";
+
+package envoy.type.matcher.v3;
+
+import "envoy/type/matcher/v3/value.proto";
+
+import "udpa/annotations/versioning.proto";
+
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.type.matcher.v3";
+option java_outer_classname = "StructProto";
+option java_multiple_files = true;
+
+// [#protodoc-title: Struct matcher]
+
+// StructMatcher provides a general interface to check if a given value is matched in
+// google.protobuf.Struct. It uses `path` to retrieve the value
+// from the struct and then check if it's matched to the specified value.
+//
+// For example, for the following Struct:
+//
+// .. code-block:: yaml
+//
+//        fields:
+//          a:
+//            struct_value:
+//              fields:
+//                b:
+//                  struct_value:
+//                    fields:
+//                      c:
+//                        string_value: pro
+//                t:
+//                  list_value:
+//                    values:
+//                      - string_value: m
+//                      - string_value: n
+//
+// The following MetadataMatcher is matched as the path [a, b, c] will retrieve a string value "pro"
+// from the Metadata which is matched to the specified prefix match.
+//
+// .. code-block:: yaml
+//
+//    path:
+//    - key: a
+//    - key: b
+//    - key: c
+//    value:
+//      string_match:
+//        prefix: pr
+//
+// The following StructMatcher is matched as the code will match one of the string values in the
+// list at the path [a, t].
+//
+// .. code-block:: yaml
+//
+//    path:
+//    - key: a
+//    - key: t
+//    value:
+//      list_match:
+//        one_of:
+//          string_match:
+//            exact: m
+//
+// An example use of StructMatcher is to match metadata in envoy.v*.core.Node.
+message StructMatcher {
+  option (udpa.annotations.versioning).previous_message_type = "envoy.type.matcher.StructMatcher";
+
+  // Specifies the segment in a path to retrieve value from Struct.
+  message PathSegment {
+    option (udpa.annotations.versioning).previous_message_type =
+        "envoy.type.matcher.StructMatcher.PathSegment";
+
+    oneof segment {
+      option (validate.required) = true;
+
+      // If specified, use the key to retrieve the value in a Struct.
+      string key = 1 [(validate.rules).string = {min_bytes: 1}];
+    }
+  }
+
+  // The path to retrieve the Value from the Struct.
+  repeated PathSegment path = 2 [(validate.rules).repeated = {min_items: 1}];
+
+  // The StructMatcher is matched if the value retrieved by path is matched to this value.
+  ValueMatcher value = 3 [(validate.rules).message = {required: true}];
+}

docs/root/api-v2/types/types.rst

@@ -17,6 +17,7 @@ Types
   ../type/matcher/number.proto
   ../type/matcher/regex.proto
   ../type/matcher/string.proto
+  ../type/matcher/struct.proto
   ../type/matcher/value.proto
   ../type/metadata/v2/metadata.proto
   ../type/tracing/v2/custom_tag.proto

docs/root/api-v3/types/types.rst

@@ -17,6 +17,7 @@ Types
   ../type/matcher/v3/number.proto
   ../type/matcher/v3/regex.proto
   ../type/matcher/v3/string.proto
+  ../type/matcher/v3/struct.proto
   ../type/matcher/v3/value.proto
   ../type/metadata/v3/metadata.proto
   ../type/tracing/v3/custom_tag.proto