tap: factor out the TAP filter matcher for later reuse in other filters

CODEOWNERS

@@ -80,6 +80,8 @@ extensions/filters/common/original_src @snowp @klarose
 /*/extensions/filters/common/expr @kyessenov @yangminzhu @lizan
 # webassembly common extension
 /*/extensions/common/wasm @jplevyak @PiotrSikora @lizan
+# common matcher
+/*/extensions/common/matcher @mattklein123 @yangminzhu
 # common crypto extension
 /*/extensions/common/crypto @lizan @PiotrSikora @bdecoste
 /*/extensions/common/proxy_protocol @alyssawilk @wez470

api/BUILD

@@ -130,6 +130,7 @@ proto_library(
         "//envoy/config/accesslog/v3:pkg",
         "//envoy/config/bootstrap/v3:pkg",
         "//envoy/config/cluster/v3:pkg",
+        "//envoy/config/common/matcher/v3:pkg",
         "//envoy/config/core/v3:pkg",
         "//envoy/config/endpoint/v3:pkg",
         "//envoy/config/filter/thrift/router/v2alpha1:pkg",

api/envoy/config/common/matcher/v3/BUILD

@@ -0,0 +1,12 @@
+# DO NOT EDIT. This file is generated by tools/proto_sync.py.
+
+load("@envoy_api//bazel:api_build_system.bzl", "api_proto_package")
+
+licenses(["notice"])  # Apache 2
+
+api_proto_package(
+    deps = [
+        "//envoy/config/route/v3:pkg",
+        "@com_github_cncf_udpa//udpa/annotations:pkg",
+    ],
+)

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

@@ -0,0 +1,100 @@
+syntax = "proto3";
+
+package envoy.config.common.matcher.v3;
+
+import "envoy/config/route/v3/route_components.proto";
+
+import "udpa/annotations/migrate.proto";
+import "udpa/annotations/status.proto";
+import "udpa/annotations/versioning.proto";
+import "validate/validate.proto";
+
+option java_package = "io.envoyproxy.envoy.config.common.matcher.v3";
+option java_outer_classname = "MatcherProto";
+option java_multiple_files = true;
+option (udpa.annotations.file_status).package_version_status = ACTIVE;
+
+// [#protodoc-title: Unified Matcher API]
+
+// Match configuration. This is a recursive structure which allows complex nested match
+// configurations to be built using various logical operators.
+// [#next-free-field: 11]
+message MatchPredicate {
+  // A set of match configurations used for logical operations.
+  message MatchSet {
+    // The list of rules that make up the set.
+    repeated MatchPredicate rules = 1 [(validate.rules).repeated = {min_items: 2}];
+  }
+
+  oneof rule {
+    option (validate.required) = true;
+
+    // A set that describes a logical OR. If any member of the set matches, the match configuration
+    // matches.
+    MatchSet or_match = 1;
+
+    // A set that describes a logical AND. If all members of the set match, the match configuration
+    // matches.
+    MatchSet and_match = 2;
+
+    // A negation match. The match configuration will match if the negated match condition matches.
+    MatchPredicate not_match = 3;
+
+    // The match configuration will always match.
+    bool any_match = 4 [(validate.rules).bool = {const: true}];
+
+    // HTTP request headers match configuration.
+    HttpHeadersMatch http_request_headers_match = 5;
+
+    // HTTP request trailers match configuration.
+    HttpHeadersMatch http_request_trailers_match = 6;
+
+    // HTTP response headers match configuration.
+    HttpHeadersMatch http_response_headers_match = 7;
+
+    // HTTP response trailers match configuration.
+    HttpHeadersMatch http_response_trailers_match = 8;
+
+    // HTTP request generic body match configuration.
+    HttpGenericBodyMatch http_request_generic_body_match = 9;
+
+    // HTTP response generic body match configuration.
+    HttpGenericBodyMatch http_response_generic_body_match = 10;
+  }
+}
+
+// HTTP headers match configuration.
+message HttpHeadersMatch {
+  // HTTP headers to match.
+  repeated route.v3.HeaderMatcher headers = 1;
+}
+
+// HTTP generic body match configuration.
+// List of text strings and hex strings to be located in HTTP body.
+// All specified strings must be found in the HTTP body for positive match.
+// The search may be limited to specified number of bytes from the body start.
+//
+// .. attention::
+//
+//   Searching for patterns in HTTP body is potentially cpu intensive. For each specified pattern, http body is scanned byte by byte to find a match.
+//   If multiple patterns are specified, the process is repeated for each pattern. If location of a pattern is known, ``bytes_limit`` should be specified
+//   to scan only part of the http body.
+message HttpGenericBodyMatch {
+  message GenericTextMatch {
+    oneof rule {
+      option (validate.required) = true;
+
+      // Text string to be located in HTTP body.
+      string string_match = 1;
+
+      // Sequence of bytes to be located in HTTP body.
+      bytes binary_match = 2;
+    }
+  }
+
+  // Limits search to specified number of bytes - default zero (no limit - match entire captured buffer).
+  uint32 bytes_limit = 1;
+
+  // List of patterns to match.
+  repeated GenericTextMatch patterns = 2 [(validate.rules).repeated = {min_items: 1}];
+}

api/envoy/config/tap/v3/BUILD

@@ -6,6 +6,7 @@ licenses(["notice"])  # Apache 2
 
 api_proto_package(
     deps = [
+        "//envoy/config/common/matcher/v3:pkg",
         "//envoy/config/core/v3:pkg",
         "//envoy/config/route/v3:pkg",
         "//envoy/service/tap/v2alpha:pkg",

api/envoy/config/tap/v3/common.proto

@@ -2,6 +2,7 @@ syntax = "proto3";
 
 package envoy.config.tap.v3;
 
+import "envoy/config/common/matcher/v3/matcher.proto";
 import "envoy/config/core/v3/base.proto";
 import "envoy/config/core/v3/grpc_service.proto";
 import "envoy/config/route/v3/route_components.proto";
@@ -28,7 +29,17 @@ message TapConfig {
 
   // The match configuration. If the configuration matches the data source being tapped, a tap will
   // occur, with the result written to the configured output.
-  MatchPredicate match_config = 1 [(validate.rules).message = {required: true}];
+  // Exactly one of :ref:`match <envoy_api_field_config.tap.v3.TapConfig.match>` and
+  // :ref:`match_config <envoy_api_field_config.tap.v3.TapConfig.match_config>` must be set. If both
+  // are set, the :ref:`match <envoy_api_field_config.tap.v3.TapConfig.match>` will be used.
+  MatchPredicate match_config = 1 [deprecated = true];
+
+  // The match configuration. If the configuration matches the data source being tapped, a tap will
+  // occur, with the result written to the configured output.
+  // Exactly one of :ref:`match <envoy_api_field_config.tap.v3.TapConfig.match>` and
+  // :ref:`match_config <envoy_api_field_config.tap.v3.TapConfig.match_config>` must be set. If both
+  // are set, the :ref:`match <envoy_api_field_config.tap.v3.TapConfig.match>` will be used.
+  common.matcher.v3.MatchPredicate match = 4;
 
   // The tap output configuration. If a match configuration matches a data source being tapped,
   // a tap will occur and the data will be written to the configured output.

api/versioning/BUILD

@@ -13,6 +13,7 @@ proto_library(
         "//envoy/config/accesslog/v3:pkg",
         "//envoy/config/bootstrap/v3:pkg",
         "//envoy/config/cluster/v3:pkg",
+        "//envoy/config/common/matcher/v3:pkg",
         "//envoy/config/core/v3:pkg",
         "//envoy/config/endpoint/v3:pkg",
         "//envoy/config/filter/thrift/router/v2alpha1:pkg",

docs/root/api-v3/config/common/common.rst

@@ -5,5 +5,6 @@ Common
   :glob:
   :maxdepth: 2
 
+  matcher/v3/*
   ../../extensions/common/dynamic_forward_proxy/v3/*
   ../../extensions/common/tap/v3/*

docs/root/version_history/current.rst

@@ -69,3 +69,5 @@ Deprecated
 ----------
 * The :ref:`track_timeout_budgets <envoy_v3_api_field_config.cluster.v3.Cluster.track_timeout_budgets>`
   field has been deprecated in favor of `timeout_budgets` part of an :ref:`Optional Configuration <envoy_v3_api_field_config.cluster.v3.Cluster.track_cluster_stats>`.
+* tap: the :ref:`match_config <envoy_v3_api_field_config.tap.v3.TapConfig.match_config>` field has been deprecated in favor of
+  :ref:`match <envoy_v3_api_field_config.tap.v3.TapConfig.match>` field.