package xds.type.matcher.v3

Get desktop application:
View/edit binary Protocol Buffers messages

Performs a match by evaluating a `Common Expression Language <https://github.com/google/cel-spec>`_ (CEL) expression against the standardized set of :ref:`HTTP attributes <arch_overview_attributes>` specified via ``HttpAttributesCelMatchInput``. .. attention:: The match is ``true``, iff the result of the evaluation is a bool AND true. In all other cases, the match is ``false``, including but not limited to: non-bool types, ``false``, ``null``,`` int(1)``, etc. In case CEL expression raises an error, the result of the evaluation is interpreted "no match". Refer to :ref:`Unified Matcher API <envoy_v3_api_msg_.xds.type.matcher.v3.Matcher>` documentation for usage details. [#comment: envoy.matching.matchers.cel_matcher]

• optional v3.CelExpression expr_match = 1

  Either parsed or checked representation of the CEL program.

• string description = 2

  Free-form description of the CEL AST, e.g. the original expression text, to be used for debugging assistance.

Specifies a set of ranges for matching a double number and the associated match actions.

• repeated DoubleRangeMatcher.RangeMatcher range_matchers = 1

  Match a number by a list of number ranges. If multiple ranges contain the input number, then the first action in this list is taken.

Specifies a list of number ranges and a match action.

Used in: DoubleRangeMatcher

• repeated v3.DoubleRange ranges = 1

  A non-empty set of double ranges.

• optional Matcher.OnMatch on_match = 2

  Match action to apply when the input number is within one of the ranges.

Specifies that matching should be performed on the set of :ref:`HTTP attributes <arch_overview_attributes>`. The attributes will be exposed via `Common Expression Language <https://github.com/google/cel-spec>`_ runtime to associated CEL matcher. Refer to :ref:`Unified Matcher API <envoy_v3_api_msg_.xds.type.matcher.v3.Matcher>` documentation for usage details. [#comment: envoy.matching.inputs.cel_data_input]

(message has no fields)

Matches a specific IP address against a set of possibly overlapping subnets using a trie.

• repeated IPMatcher.IPRangeMatcher range_matchers = 1

  Match IP address by CIDR ranges.

Specifies a list of IP address ranges and a match action.

Used in: IPMatcher

• repeated core.v3.CidrRange ranges = 1

  A non-empty set of CIDR ranges.

• optional Matcher.OnMatch on_match = 2

  Match action to apply when the IP address is within one of the CIDR ranges.

• bool exclusive = 3

  Indicates whether this match option should be considered if there is a more specific matcher. Exclusive matchers are not selected whenever a more specific matcher exists (e.g. matcher with a longer prefix) even when the more specific matcher fails its nested match condition. Non-exclusive matchers are considered if the more specific matcher exists but its nested match condition does not entirely match. Non-exclusive matchers are selected in the order of their specificity first (longest prefix first), then the order of declaration next. For example, consider two range matchers: an exclusive matcher *X* on ``0.0.0.0/0`` and a matcher *Y* on ``192.0.0.0/2`` with a nested match condition *Z*. For the input IP ``192.168.0.1`` matcher *Y* is the most specific. If its nested match condition *Z* does not accept the input, then the less specific matcher *X* does not apply either despite the input being within the range, because matcher *X* is exclusive. The opposite is true if matcher *X* is not marked as exclusive. In that case matcher *X* always matches whenever matcher "*Y* rejects the input.

Specifies a set of ranges for matching an int32 number and the associated match actions.

• repeated Int32RangeMatcher.RangeMatcher range_matchers = 1

  Match a number by a list of number ranges. If multiple ranges contain the input number, then the first action in this list is taken.

Specifies a list of number ranges and a match action.

Used in: Int32RangeMatcher

• repeated v3.Int32Range ranges = 1

  A non-empty set of int32 ranges.

• optional Matcher.OnMatch on_match = 2

  Match action to apply when the input number is within one of the ranges.

Specifies a set of ranges for matching an int64 number and the associated match actions.

• repeated Int64RangeMatcher.RangeMatcher range_matchers = 1

  Match a number by a list of number ranges. If multiple ranges contain the input number, then the first action in this list is taken.

Specifies a list of number ranges and a match action.

Used in: Int64RangeMatcher

• repeated v3.Int64Range ranges = 1

  A non-empty set of int64 ranges.

• optional Matcher.OnMatch on_match = 2

  Match action to apply when the input number is within one of the ranges.

Specifies a list of ways to match a string.

• repeated StringMatcher patterns = 1

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.

Used in: envoy.config.listener.v3.Listener, envoy.config.route.v3.VirtualHost, envoy.extensions.common.matching.v3.ExtensionWithMatcher, envoy.extensions.common.matching.v3.ExtensionWithMatcherPerRoute, envoy.extensions.filters.http.custom_response.v3.CustomResponse, envoy.extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaFilterConfig, envoy.extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaOverride, envoy.extensions.filters.http.rbac.v3.RBAC, envoy.extensions.filters.network.generic_proxy.v3.RouteConfiguration, envoy.extensions.filters.network.generic_proxy.v3.VirtualHost, envoy.extensions.filters.network.rbac.v3.RBAC, envoy.extensions.filters.udp.udp_proxy.v3.UdpProxyConfig, Matcher.OnMatch

• oneof matcher_type

  • Matcher.MatcherList matcher_list = 1

    A linear list of matchers to evaluate.

  • Matcher.MatcherTree matcher_tree = 2

    A match tree to evaluate.

• optional Matcher.OnMatch on_no_match = 3

  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.

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

Used in: Matcher

• repeated MatcherList.FieldMatcher matchers = 1

  A list of matchers. First match wins.

An individual matcher.

Used in: MatcherList

• optional Predicate predicate = 1

  Determines if the match succeeds.

• optional OnMatch on_match = 2

  What to do if the match succeeds.

Predicate to determine if a match is successful.

Used in: FieldMatcher, Predicate.PredicateList

• oneof match_type

  • Predicate.SinglePredicate single_predicate = 1

    A single predicate to evaluate.

  • Predicate.PredicateList or_matcher = 2

    A list of predicates to be OR-ed together.

  • Predicate.PredicateList and_matcher = 3

    A list of predicates to be AND-ed together.

  • Predicate not_matcher = 4

    The invert of a predicate

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

Used in: Predicate

• repeated Predicate predicate = 1

Predicate for a single input field.

Used in: Predicate

• optional core.v3.TypedExtensionConfig input = 1

  Protocol-specific specification of input field to match on. [#extension-category: envoy.matching.common_inputs]

• oneof matcher

  • StringMatcher value_match = 2

    Built-in string matcher.

  • core.v3.TypedExtensionConfig custom_match = 3

    Extension for custom matching logic. [#extension-category: envoy.matching.input_matchers]

Used in: Matcher

• optional core.v3.TypedExtensionConfig input = 1

  Protocol-specific specification of input field to match on.

• oneof tree_type

  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.

  • MatcherTree.MatchMap exact_match_map = 2

  • MatcherTree.MatchMap prefix_match_map = 3

    Longest matching prefix wins.

  • core.v3.TypedExtensionConfig custom_match = 4

    Extension for custom matching logic.

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

Used in: MatcherTree

• map<string, OnMatch> map = 1

What to do if a match is successful.

Used in: DoubleRangeMatcher.RangeMatcher, IPMatcher.IPRangeMatcher, Int32RangeMatcher.RangeMatcher, Int64RangeMatcher.RangeMatcher, Matcher, MatcherList.FieldMatcher, MatcherTree.MatchMap, ServerNameMatcher.DomainMatcher

• oneof on_match

  • Matcher matcher = 1

    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.

  • core.v3.TypedExtensionConfig action = 2

    Protocol-specific action to take.

A regex matcher designed for safety when used with untrusted input.

Used in: StringMatcher

• oneof engine_type

  • RegexMatcher.GoogleRE2 google_re2 = 1

    Google's RE2 regex engine.

• string regex = 2

  The regex match string. The string must be supported by the configured engine.

Google's `RE2 <https://github.com/google/re2>`_ regex engine. The regex string must adhere to the documented `syntax <https://github.com/google/re2/wiki/Syntax>`_. The engine is designed to complete execution in linear time as well as limit the amount of memory used. Envoy supports program size checking via runtime. The runtime keys `re2.max_program_size.error_level` and `re2.max_program_size.warn_level` can be set to integers as the maximum program size or complexity that a compiled regex can have before an exception is thrown or a warning is logged, respectively. `re2.max_program_size.error_level` defaults to 100, and `re2.max_program_size.warn_level` has no default if unset (will not check/log a warning). Envoy emits two stats for tracking the program size of regexes: the histogram `re2.program_size`, which records the program size, and the counter `re2.exceeded_warn_level`, which is incremented each time the program size exceeds the warn level threshold.

Used in: RegexMatcher

(message has no fields)

Matches a fully qualified server name against a set of domain names with optional wildcards.

• repeated ServerNameMatcher.DomainMatcher domain_matchers = 1

  Match a server name by multiple domain matchers. Each domain, exact or wildcard, must appear at most once across all the domain matchers. The server name will be matched against all wildcard domains starting from the longest suffix, i.e. ``www.example.com`` input will be first matched against ``www.example.com``, then ``*.example.com``, then ``*.com``, then ``*``, until the associated matcher action accepts the input. Note that wildcards must be on a dot border, and values like ``*w.example.com`` are invalid.

Specifies a set of exact and wildcard domains and a match action. The wildcard symbol ``*`` must appear at most once as the left-most part of the domain on a dot border. The wildcard matches one or more non-empty domain parts.

Used in: ServerNameMatcher

• repeated string domains = 1

  A non-empty set of domain names with optional wildcards, e.g. ``www.example.com``, ``*.com``, or ``*``.

• optional Matcher.OnMatch on_match = 2

  Match action to apply when the server name matches any of the domain names in the matcher.

Specifies the way to match a string. [#next-free-field: 9]

Used in: ListStringMatcher, Matcher.MatcherList.Predicate.SinglePredicate

• oneof match_pattern

  • string exact = 1

    The input string must match exactly the string specified here. Examples: * *abc* only matches the value *abc*.

  • string prefix = 2

    The input string must have the prefix specified here. Note: empty prefix is not allowed, please use regex instead. Examples: * *abc* matches the value *abc.xyz*

  • string suffix = 3

    The input string must have the suffix specified here. Note: empty prefix is not allowed, please use regex instead. Examples: * *abc* matches the value *xyz.abc*

  • RegexMatcher safe_regex = 5

    The input string must match the regular expression specified here.

  • string contains = 7

    The input string must have the substring specified here. Note: empty contains match is not allowed, please use regex instead. Examples: * *abc* matches the value *xyz.abc.def*

  • core.v3.TypedExtensionConfig custom = 8

    Use an extension as the matcher type. [#extension-category: envoy.string_matcher]

• bool ignore_case = 6

  If true, indicates the exact/prefix/suffix matching should be case insensitive. This has no effect for the safe_regex match. For example, the matcher *data* will match both input string *Data* and *data* if set to true.