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