|
| 1 | +syntax = "proto3"; |
| 2 | + |
| 3 | +package envoy.config.common.matcher.v3; |
| 4 | + |
| 5 | +import "envoy/config/core/v3/extension.proto"; |
| 6 | +import "envoy/config/route/v3/route_components.proto"; |
| 7 | +import "envoy/type/matcher/v3/string.proto"; |
| 8 | + |
| 9 | +import "udpa/annotations/status.proto"; |
| 10 | +import "validate/validate.proto"; |
| 11 | + |
| 12 | +option java_package = "io.envoyproxy.envoy.config.common.matcher.v3"; |
| 13 | +option java_outer_classname = "MatcherProto"; |
| 14 | +option java_multiple_files = true; |
| 15 | +option go_package = "github.com/envoyproxy/go-control-plane/envoy/config/common/matcher/v3;matcherv3"; |
| 16 | +option (udpa.annotations.file_status).package_version_status = ACTIVE; |
| 17 | + |
| 18 | +// [#protodoc-title: Unified Matcher API] |
| 19 | + |
| 20 | +// A matcher, which may traverse a matching tree in order to result in a match action. |
| 21 | +// During matching, the tree will be traversed until a match is found, or if no match |
| 22 | +// is found the action specified by the most specific on_no_match will be evaluated. |
| 23 | +// As an on_no_match might result in another matching tree being evaluated, this process |
| 24 | +// might repeat several times until the final OnMatch (or no match) is decided. |
| 25 | +// |
| 26 | +// .. note:: |
| 27 | +// Please use the syntactically equivalent :ref:`matching API <envoy_v3_api_msg_.xds.type.matcher.v3.Matcher>` |
| 28 | +message Matcher { |
| 29 | + // What to do if a match is successful. |
| 30 | + message OnMatch { |
| 31 | + oneof on_match { |
| 32 | + option (validate.required) = true; |
| 33 | + |
| 34 | + // Nested matcher to evaluate. |
| 35 | + // If the nested matcher does not match and does not specify |
| 36 | + // on_no_match, then this matcher is considered not to have |
| 37 | + // matched, even if a predicate at this level or above returned |
| 38 | + // true. |
| 39 | + Matcher matcher = 1; |
| 40 | + |
| 41 | + // Protocol-specific action to take. |
| 42 | + core.v3.TypedExtensionConfig action = 2; |
| 43 | + } |
| 44 | + |
| 45 | + // If true, the action will be taken but the caller will behave as if no |
| 46 | + // match was found. This applies both to actions directly encoded in the |
| 47 | + // action field and to actions returned from a nested matcher tree in the |
| 48 | + // matcher field. A subsequent matcher on_no_match action will be used |
| 49 | + // instead. |
| 50 | + // |
| 51 | + // This field is not supported in all contexts in which the matcher API is |
| 52 | + // used. If this field is set in a context in which it's not supported, |
| 53 | + // the resource will be rejected. |
| 54 | + bool keep_matching = 3; |
| 55 | + } |
| 56 | + |
| 57 | + // A linear list of field matchers. |
| 58 | + // The field matchers are evaluated in order, and the first match |
| 59 | + // wins. |
| 60 | + message MatcherList { |
| 61 | + // Predicate to determine if a match is successful. |
| 62 | + message Predicate { |
| 63 | + // Predicate for a single input field. |
| 64 | + message SinglePredicate { |
| 65 | + // Protocol-specific specification of input field to match on. |
| 66 | + // [#extension-category: envoy.matching.common_inputs] |
| 67 | + core.v3.TypedExtensionConfig input = 1 [(validate.rules).message = {required: true}]; |
| 68 | + |
| 69 | + oneof matcher { |
| 70 | + option (validate.required) = true; |
| 71 | + |
| 72 | + // Built-in string matcher. |
| 73 | + type.matcher.v3.StringMatcher value_match = 2; |
| 74 | + |
| 75 | + // Extension for custom matching logic. |
| 76 | + // [#extension-category: envoy.matching.input_matchers] |
| 77 | + core.v3.TypedExtensionConfig custom_match = 3; |
| 78 | + } |
| 79 | + } |
| 80 | + |
| 81 | + // A list of two or more matchers. Used to allow using a list within a oneof. |
| 82 | + message PredicateList { |
| 83 | + repeated Predicate predicate = 1 [(validate.rules).repeated = {min_items: 2}]; |
| 84 | + } |
| 85 | + |
| 86 | + oneof match_type { |
| 87 | + option (validate.required) = true; |
| 88 | + |
| 89 | + // A single predicate to evaluate. |
| 90 | + SinglePredicate single_predicate = 1; |
| 91 | + |
| 92 | + // A list of predicates to be OR-ed together. |
| 93 | + PredicateList or_matcher = 2; |
| 94 | + |
| 95 | + // A list of predicates to be AND-ed together. |
| 96 | + PredicateList and_matcher = 3; |
| 97 | + |
| 98 | + // The inverse of a predicate |
| 99 | + Predicate not_matcher = 4; |
| 100 | + } |
| 101 | + } |
| 102 | + |
| 103 | + // An individual matcher. |
| 104 | + message FieldMatcher { |
| 105 | + // Determines if the match succeeds. |
| 106 | + Predicate predicate = 1 [(validate.rules).message = {required: true}]; |
| 107 | + |
| 108 | + // What to do if the match succeeds. |
| 109 | + OnMatch on_match = 2 [(validate.rules).message = {required: true}]; |
| 110 | + } |
| 111 | + |
| 112 | + // A list of matchers. First match wins. |
| 113 | + repeated FieldMatcher matchers = 1 [(validate.rules).repeated = {min_items: 1}]; |
| 114 | + } |
| 115 | + |
| 116 | + message MatcherTree { |
| 117 | + // A map of configured matchers. Used to allow using a map within a oneof. |
| 118 | + message MatchMap { |
| 119 | + map<string, OnMatch> map = 1 [(validate.rules).map = {min_pairs: 1}]; |
| 120 | + } |
| 121 | + |
| 122 | + // Protocol-specific specification of input field to match on. |
| 123 | + core.v3.TypedExtensionConfig input = 1 [(validate.rules).message = {required: true}]; |
| 124 | + |
| 125 | + // Exact or prefix match maps in which to look up the input value. |
| 126 | + // If the lookup succeeds, the match is considered successful, and |
| 127 | + // the corresponding OnMatch is used. |
| 128 | + oneof tree_type { |
| 129 | + option (validate.required) = true; |
| 130 | + |
| 131 | + MatchMap exact_match_map = 2; |
| 132 | + |
| 133 | + // Longest matching prefix wins. |
| 134 | + MatchMap prefix_match_map = 3; |
| 135 | + |
| 136 | + // Extension for custom matching logic. |
| 137 | + core.v3.TypedExtensionConfig custom_match = 4; |
| 138 | + } |
| 139 | + } |
| 140 | + |
| 141 | + oneof matcher_type { |
| 142 | + option (validate.required) = true; |
| 143 | + |
| 144 | + // A linear list of matchers to evaluate. |
| 145 | + MatcherList matcher_list = 1; |
| 146 | + |
| 147 | + // A match tree to evaluate. |
| 148 | + MatcherTree matcher_tree = 2; |
| 149 | + } |
| 150 | + |
| 151 | + // Optional ``OnMatch`` to use if the matcher failed. |
| 152 | + // If specified, the ``OnMatch`` is used, and the matcher is considered |
| 153 | + // to have matched. |
| 154 | + // If not specified, the matcher is considered not to have matched. |
| 155 | + OnMatch on_no_match = 3; |
| 156 | +} |
| 157 | + |
| 158 | +// Match configuration. This is a recursive structure which allows complex nested match |
| 159 | +// configurations to be built using various logical operators. |
| 160 | +// [#next-free-field: 11] |
| 161 | +message MatchPredicate { |
| 162 | + // A set of match configurations used for logical operations. |
| 163 | + message MatchSet { |
| 164 | + // The list of rules that make up the set. |
| 165 | + repeated MatchPredicate rules = 1 [(validate.rules).repeated = {min_items: 2}]; |
| 166 | + } |
| 167 | + |
| 168 | + oneof rule { |
| 169 | + option (validate.required) = true; |
| 170 | + |
| 171 | + // A set that describes a logical OR. If any member of the set matches, the match configuration |
| 172 | + // matches. |
| 173 | + MatchSet or_match = 1; |
| 174 | + |
| 175 | + // A set that describes a logical AND. If all members of the set match, the match configuration |
| 176 | + // matches. |
| 177 | + MatchSet and_match = 2; |
| 178 | + |
| 179 | + // A negation match. The match configuration will match if the negated match condition matches. |
| 180 | + MatchPredicate not_match = 3; |
| 181 | + |
| 182 | + // The match configuration will always match. |
| 183 | + bool any_match = 4 [(validate.rules).bool = {const: true}]; |
| 184 | + |
| 185 | + // HTTP request headers match configuration. |
| 186 | + HttpHeadersMatch http_request_headers_match = 5; |
| 187 | + |
| 188 | + // HTTP request trailers match configuration. |
| 189 | + HttpHeadersMatch http_request_trailers_match = 6; |
| 190 | + |
| 191 | + // HTTP response headers match configuration. |
| 192 | + HttpHeadersMatch http_response_headers_match = 7; |
| 193 | + |
| 194 | + // HTTP response trailers match configuration. |
| 195 | + HttpHeadersMatch http_response_trailers_match = 8; |
| 196 | + |
| 197 | + // HTTP request generic body match configuration. |
| 198 | + HttpGenericBodyMatch http_request_generic_body_match = 9; |
| 199 | + |
| 200 | + // HTTP response generic body match configuration. |
| 201 | + HttpGenericBodyMatch http_response_generic_body_match = 10; |
| 202 | + } |
| 203 | +} |
| 204 | + |
| 205 | +// HTTP headers match configuration. |
| 206 | +message HttpHeadersMatch { |
| 207 | + // HTTP headers to match. |
| 208 | + repeated route.v3.HeaderMatcher headers = 1; |
| 209 | +} |
| 210 | + |
| 211 | +// HTTP generic body match configuration. |
| 212 | +// List of text strings and hex strings to be located in HTTP body. |
| 213 | +// All specified strings must be found in the HTTP body for positive match. |
| 214 | +// The search may be limited to specified number of bytes from the body start. |
| 215 | +// |
| 216 | +// .. attention:: |
| 217 | +// |
| 218 | +// 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. |
| 219 | +// If multiple patterns are specified, the process is repeated for each pattern. If location of a pattern is known, ``bytes_limit`` should be specified |
| 220 | +// to scan only part of the HTTP body. |
| 221 | +message HttpGenericBodyMatch { |
| 222 | + message GenericTextMatch { |
| 223 | + oneof rule { |
| 224 | + option (validate.required) = true; |
| 225 | + |
| 226 | + // Text string to be located in HTTP body. |
| 227 | + string string_match = 1 [(validate.rules).string = {min_len: 1}]; |
| 228 | + |
| 229 | + // Sequence of bytes to be located in HTTP body. |
| 230 | + bytes binary_match = 2 [(validate.rules).bytes = {min_len: 1}]; |
| 231 | + } |
| 232 | + } |
| 233 | + |
| 234 | + // Limits search to specified number of bytes - default zero (no limit - match entire captured buffer). |
| 235 | + uint32 bytes_limit = 1; |
| 236 | + |
| 237 | + // List of patterns to match. |
| 238 | + repeated GenericTextMatch patterns = 2 [(validate.rules).repeated = {min_items: 1}]; |
| 239 | +} |
0 commit comments