Unified Matcher API

Unified Matcher API

config.common.matcher.v3.Matcher

[config.common.matcher.v3.Matcher proto]

A matcher, which may traverse a matching tree in order to result in a match action. During matching, the tree will be traversed until a match is found, or if no match is found the action specified by the most specific on_no_match will be evaluated. As an on_no_match might result in another matching tree being evaluated, this process might repeat several times until the final OnMatch (or no match) is decided.

Warning

This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the threat model, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points.

{
  "matcher_list": "{...}",
  "matcher_tree": "{...}",
  "on_no_match": "{...}"
}

matcher_list

(config.common.matcher.v3.Matcher.MatcherList) A linear list of matchers to evaluate.

Precisely one of matcher_list, matcher_tree must be set.

matcher_tree

(config.common.matcher.v3.Matcher.MatcherTree) A match tree to evaluate.

Precisely one of matcher_list, matcher_tree must be set.

on_no_match

(config.common.matcher.v3.Matcher.OnMatch) Optional OnMatch to use if the matcher failed. If specified, the OnMatch is used, and the matcher is considered to have matched. If not specified, the matcher is considered not to have matched.

config.common.matcher.v3.Matcher.OnMatch

[config.common.matcher.v3.Matcher.OnMatch proto]

What to do if a match is successful.

{
  "matcher": "{...}",
  "action": "{...}"
}

matcher

(config.common.matcher.v3.Matcher) Nested matcher to evaluate. If the nested matcher does not match and does not specify on_no_match, then this matcher is considered not to have matched, even if a predicate at this level or above returned true.

Precisely one of matcher, action must be set.

action

(config.core.v3.TypedExtensionConfig) Protocol-specific action to take.

Precisely one of matcher, action must be set.

config.common.matcher.v3.Matcher.MatcherList

[config.common.matcher.v3.Matcher.MatcherList proto]

A linear list of field matchers. The field matchers are evaluated in order, and the first match wins.

{
  "matchers": []
}

matchers

(repeated config.common.matcher.v3.Matcher.MatcherList.FieldMatcher, REQUIRED) A list of matchers. First match wins.

config.common.matcher.v3.Matcher.MatcherList.Predicate

[config.common.matcher.v3.Matcher.MatcherList.Predicate proto]

Predicate to determine if a match is successful.

{
  "single_predicate": "{...}",
  "or_matcher": "{...}",
  "and_matcher": "{...}",
  "not_matcher": "{...}"
}

single_predicate

(config.common.matcher.v3.Matcher.MatcherList.Predicate.SinglePredicate) A single predicate to evaluate.

Precisely one of single_predicate, or_matcher, and_matcher, not_matcher must be set.

or_matcher

(config.common.matcher.v3.Matcher.MatcherList.Predicate.PredicateList) A list of predicates to be OR-ed together.

Precisely one of single_predicate, or_matcher, and_matcher, not_matcher must be set.

and_matcher

(config.common.matcher.v3.Matcher.MatcherList.Predicate.PredicateList) A list of predicates to be AND-ed together.

Precisely one of single_predicate, or_matcher, and_matcher, not_matcher must be set.

not_matcher

(config.common.matcher.v3.Matcher.MatcherList.Predicate) The invert of a predicate

Precisely one of single_predicate, or_matcher, and_matcher, not_matcher must be set.

config.common.matcher.v3.Matcher.MatcherList.Predicate.SinglePredicate

[config.common.matcher.v3.Matcher.MatcherList.Predicate.SinglePredicate proto]

Predicate for a single input field.

{
  "input": "{...}",
  "value_match": "{...}",
  "custom_match": "{...}"
}

input

(config.core.v3.TypedExtensionConfig, REQUIRED) Protocol-specific specification of input field to match on.

Tip

This extension category has the following known extensions:

envoy.matching.common_inputs.environment_variable

value_match

(type.matcher.v3.StringMatcher) Built-in string matcher.

Precisely one of value_match, custom_match must be set.

custom_match

(config.core.v3.TypedExtensionConfig) Extension for custom matching logic.

Tip

This extension category has the following known extensions:

Precisely one of value_match, custom_match must be set.

config.common.matcher.v3.Matcher.MatcherList.Predicate.PredicateList

[config.common.matcher.v3.Matcher.MatcherList.Predicate.PredicateList proto]

A list of two or more matchers. Used to allow using a list within a oneof.

{
  "predicate": []
}

predicate

(repeated config.common.matcher.v3.Matcher.MatcherList.Predicate, REQUIRED)

config.common.matcher.v3.Matcher.MatcherList.FieldMatcher

[config.common.matcher.v3.Matcher.MatcherList.FieldMatcher proto]

An individual matcher.

{
  "predicate": "{...}",
  "on_match": "{...}"
}

predicate

(config.common.matcher.v3.Matcher.MatcherList.Predicate, REQUIRED) Determines if the match succeeds.

on_match

(config.common.matcher.v3.Matcher.OnMatch, REQUIRED) What to do if the match succeeds.

config.common.matcher.v3.Matcher.MatcherTree

[config.common.matcher.v3.Matcher.MatcherTree proto]

{
  "input": "{...}",
  "exact_match_map": "{...}",
  "prefix_match_map": "{...}",
  "custom_match": "{...}"
}

input

(config.core.v3.TypedExtensionConfig, REQUIRED) Protocol-specific specification of input field to match on.

exact_match_map

(config.common.matcher.v3.Matcher.MatcherTree.MatchMap) Exact or prefix match maps in which to look up the input value. If the lookup succeeds, the match is considered successful, and the corresponding OnMatch is used.

Precisely one of exact_match_map, prefix_match_map, custom_match must be set.

prefix_match_map

(config.common.matcher.v3.Matcher.MatcherTree.MatchMap) Longest matching prefix wins.

Exact or prefix match maps in which to look up the input value. If the lookup succeeds, the match is considered successful, and the corresponding OnMatch is used.

Precisely one of exact_match_map, prefix_match_map, custom_match must be set.

custom_match

(config.core.v3.TypedExtensionConfig) Extension for custom matching logic.

Exact or prefix match maps in which to look up the input value. If the lookup succeeds, the match is considered successful, and the corresponding OnMatch is used.

Precisely one of exact_match_map, prefix_match_map, custom_match must be set.

config.common.matcher.v3.Matcher.MatcherTree.MatchMap

[config.common.matcher.v3.Matcher.MatcherTree.MatchMap proto]

A map of configured matchers. Used to allow using a map within a oneof.

{
  "map": "{...}"
}

map

(repeated map<string, config.common.matcher.v3.Matcher.OnMatch>)

config.common.matcher.v3.MatchPredicate

[config.common.matcher.v3.MatchPredicate proto]

Match configuration. This is a recursive structure which allows complex nested match configurations to be built using various logical operators.

{
  "or_match": "{...}",
  "and_match": "{...}",
  "not_match": "{...}",
  "any_match": "...",
  "http_request_headers_match": "{...}",
  "http_request_trailers_match": "{...}",
  "http_response_headers_match": "{...}",
  "http_response_trailers_match": "{...}",
  "http_request_generic_body_match": "{...}",
  "http_response_generic_body_match": "{...}"
}

or_match

(config.common.matcher.v3.MatchPredicate.MatchSet) A set that describes a logical OR. If any member of the set matches, the match configuration matches.

Precisely one of or_match, and_match, not_match, any_match, http_request_headers_match, http_request_trailers_match, http_response_headers_match, http_response_trailers_match, http_request_generic_body_match, http_response_generic_body_match must be set.

and_match

(config.common.matcher.v3.MatchPredicate.MatchSet) A set that describes a logical AND. If all members of the set match, the match configuration matches.

not_match

(config.common.matcher.v3.MatchPredicate) A negation match. The match configuration will match if the negated match condition matches.

any_match

(bool) The match configuration will always match.

http_request_headers_match

(config.common.matcher.v3.HttpHeadersMatch) HTTP request headers match configuration.

http_request_trailers_match

(config.common.matcher.v3.HttpHeadersMatch) HTTP request trailers match configuration.

http_response_headers_match

(config.common.matcher.v3.HttpHeadersMatch) HTTP response headers match configuration.

http_response_trailers_match

(config.common.matcher.v3.HttpHeadersMatch) HTTP response trailers match configuration.

http_request_generic_body_match

(config.common.matcher.v3.HttpGenericBodyMatch) HTTP request generic body match configuration.

http_response_generic_body_match

(config.common.matcher.v3.HttpGenericBodyMatch) HTTP response generic body match configuration.

config.common.matcher.v3.MatchPredicate.MatchSet

[config.common.matcher.v3.MatchPredicate.MatchSet proto]

A set of match configurations used for logical operations.

{
  "rules": []
}

rules

(repeated config.common.matcher.v3.MatchPredicate, REQUIRED) The list of rules that make up the set.

config.common.matcher.v3.HttpHeadersMatch

[config.common.matcher.v3.HttpHeadersMatch proto]

HTTP headers match configuration.

{
  "headers": []
}

headers

(repeated config.route.v3.HeaderMatcher) HTTP headers to match.

config.common.matcher.v3.HttpGenericBodyMatch

[config.common.matcher.v3.HttpGenericBodyMatch proto]

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.

{
  "bytes_limit": "...",
  "patterns": []
}

bytes_limit

(uint32) Limits search to specified number of bytes - default zero (no limit - match entire captured buffer).

patterns

(repeated config.common.matcher.v3.HttpGenericBodyMatch.GenericTextMatch, REQUIRED) List of patterns to match.

config.common.matcher.v3.HttpGenericBodyMatch.GenericTextMatch

[config.common.matcher.v3.HttpGenericBodyMatch.GenericTextMatch proto]

{
  "string_match": "...",
  "binary_match": "..."
}

string_match

(string) Text string to be located in HTTP body.

Precisely one of string_match, binary_match must be set.

binary_match

(bytes) Sequence of bytes to be located in HTTP body.

Precisely one of string_match, binary_match must be set.