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