Unified Matcher API (proto)

.xds.type.matcher.v3.Matcher

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

(.xds.type.matcher.v3.Matcher.MatcherList) A linear list of matchers to evaluate.

Only one of matcher_list, matcher_tree may be set.

matcher_tree

(.xds.type.matcher.v3.Matcher.MatcherTree) A match tree to evaluate.

Only one of matcher_list, matcher_tree may be set.

on_no_match: (.xds.type.matcher.v3.Matcher.OnMatch) Optional OnMatch to use if no matcher above matched (e.g., if there are no matchers specified above, or if none of the matches specified above succeeded). If no matcher above matched and this field is not populated, the match will be considered unsuccessful.

.xds.type.matcher.v3.Matcher.OnMatch

[.xds.type.matcher.v3.Matcher.OnMatch proto]

What to do if a match is successful.

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

matcher

(.xds.type.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

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

Precisely one of matcher, action must be set.

.xds.type.matcher.v3.Matcher.MatcherList

[.xds.type.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 .xds.type.matcher.v3.Matcher.MatcherList.FieldMatcher, REQUIRED) A list of matchers. First match wins.

.xds.type.matcher.v3.Matcher.MatcherList.Predicate

[.xds.type.matcher.v3.Matcher.MatcherList.Predicate proto]

Predicate to determine if a match is successful.

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

single_predicate

(.xds.type.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

(.xds.type.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

(.xds.type.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

(.xds.type.matcher.v3.Matcher.MatcherList.Predicate) The invert of a predicate

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

.xds.type.matcher.v3.Matcher.MatcherList.Predicate.SinglePredicate

[.xds.type.matcher.v3.Matcher.MatcherList.Predicate.SinglePredicate proto]

Predicate for a single input field.

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

input

(.xds.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

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

Precisely one of value_match, custom_match must be set.

custom_match

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

Tip

This extension category has the following known extensions:

The following extensions are available in contrib images only:

envoy.matching.input_matchers.hyperscan

Precisely one of value_match, custom_match must be set.

.xds.type.matcher.v3.Matcher.MatcherList.Predicate.PredicateList

[.xds.type.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 .xds.type.matcher.v3.Matcher.MatcherList.Predicate, REQUIRED)

.xds.type.matcher.v3.Matcher.MatcherList.FieldMatcher

[.xds.type.matcher.v3.Matcher.MatcherList.FieldMatcher proto]

An individual matcher.

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

predicate: (.xds.type.matcher.v3.Matcher.MatcherList.Predicate, REQUIRED) Determines if the match succeeds.

on_match: (.xds.type.matcher.v3.Matcher.OnMatch, REQUIRED) What to do if the match succeeds.

.xds.type.matcher.v3.Matcher.MatcherTree

[.xds.type.matcher.v3.Matcher.MatcherTree proto]

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

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

exact_match_map

(.xds.type.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

(.xds.type.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

(.xds.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.

.xds.type.matcher.v3.Matcher.MatcherTree.MatchMap

[.xds.type.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, .xds.type.matcher.v3.Matcher.OnMatch>)