.. _envoy_v3_api_file_envoy/config/common/matcher/v3/matcher.proto: Unified Matcher API =================== .. _envoy_v3_api_msg_config.common.matcher.v3.Matcher: config.common.matcher.v3.Matcher -------------------------------- :repo:`[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 :ref:`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. .. code-block:: json { "matcher_list": "{...}", "matcher_tree": "{...}", "on_no_match": "{...}" } .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.matcher_list: matcher_list (:ref:`config.common.matcher.v3.Matcher.MatcherList `) A linear list of matchers to evaluate. Precisely one of :ref:`matcher_list `, :ref:`matcher_tree ` must be set. .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.matcher_tree: matcher_tree (:ref:`config.common.matcher.v3.Matcher.MatcherTree `) A match tree to evaluate. Precisely one of :ref:`matcher_list `, :ref:`matcher_tree ` must be set. .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.on_no_match: on_no_match (:ref:`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. .. _envoy_v3_api_msg_config.common.matcher.v3.Matcher.OnMatch: config.common.matcher.v3.Matcher.OnMatch ---------------------------------------- :repo:`[config.common.matcher.v3.Matcher.OnMatch proto] ` What to do if a match is successful. .. code-block:: json { "matcher": "{...}", "action": "{...}" } .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.OnMatch.matcher: matcher (:ref:`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 :ref:`matcher `, :ref:`action ` must be set. .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.OnMatch.action: action (:ref:`config.core.v3.TypedExtensionConfig `) Protocol-specific action to take. Precisely one of :ref:`matcher `, :ref:`action ` must be set. .. _envoy_v3_api_msg_config.common.matcher.v3.Matcher.MatcherList: config.common.matcher.v3.Matcher.MatcherList -------------------------------------------- :repo:`[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. .. code-block:: json { "matchers": [] } .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.MatcherList.matchers: matchers (**repeated** :ref:`config.common.matcher.v3.Matcher.MatcherList.FieldMatcher `, *REQUIRED*) A list of matchers. First match wins. .. _envoy_v3_api_msg_config.common.matcher.v3.Matcher.MatcherList.Predicate: config.common.matcher.v3.Matcher.MatcherList.Predicate ------------------------------------------------------ :repo:`[config.common.matcher.v3.Matcher.MatcherList.Predicate proto] ` Predicate to determine if a match is successful. .. code-block:: json { "single_predicate": "{...}", "or_matcher": "{...}", "and_matcher": "{...}", "not_matcher": "{...}" } .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.MatcherList.Predicate.single_predicate: single_predicate (:ref:`config.common.matcher.v3.Matcher.MatcherList.Predicate.SinglePredicate `) A single predicate to evaluate. Precisely one of :ref:`single_predicate `, :ref:`or_matcher `, :ref:`and_matcher `, :ref:`not_matcher ` must be set. .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.MatcherList.Predicate.or_matcher: or_matcher (:ref:`config.common.matcher.v3.Matcher.MatcherList.Predicate.PredicateList `) A list of predicates to be OR-ed together. Precisely one of :ref:`single_predicate `, :ref:`or_matcher `, :ref:`and_matcher `, :ref:`not_matcher ` must be set. .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.MatcherList.Predicate.and_matcher: and_matcher (:ref:`config.common.matcher.v3.Matcher.MatcherList.Predicate.PredicateList `) A list of predicates to be AND-ed together. Precisely one of :ref:`single_predicate `, :ref:`or_matcher `, :ref:`and_matcher `, :ref:`not_matcher ` must be set. .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.MatcherList.Predicate.not_matcher: not_matcher (:ref:`config.common.matcher.v3.Matcher.MatcherList.Predicate `) The invert of a predicate Precisely one of :ref:`single_predicate `, :ref:`or_matcher `, :ref:`and_matcher `, :ref:`not_matcher ` must be set. .. _envoy_v3_api_msg_config.common.matcher.v3.Matcher.MatcherList.Predicate.SinglePredicate: config.common.matcher.v3.Matcher.MatcherList.Predicate.SinglePredicate ---------------------------------------------------------------------- :repo:`[config.common.matcher.v3.Matcher.MatcherList.Predicate.SinglePredicate proto] ` Predicate for a single input field. .. code-block:: json { "input": "{...}", "value_match": "{...}", "custom_match": "{...}" } .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.MatcherList.Predicate.SinglePredicate.input: input (:ref:`config.core.v3.TypedExtensionConfig `, *REQUIRED*) Protocol-specific specification of input field to match on. .. _extension_category_envoy.matching.common_inputs: .. tip:: This extension category has the following known extensions: - :ref:`envoy.matching.common_inputs.environment_variable ` .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.MatcherList.Predicate.SinglePredicate.value_match: value_match (:ref:`type.matcher.v3.StringMatcher `) Built-in string matcher. Precisely one of :ref:`value_match `, :ref:`custom_match ` must be set. .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.MatcherList.Predicate.SinglePredicate.custom_match: custom_match (:ref:`config.core.v3.TypedExtensionConfig `) Extension for custom matching logic. .. _extension_category_envoy.matching.input_matchers: .. tip:: This extension category has the following known extensions: - :ref:`envoy.matching.input_matchers.consistent_hashing ` - :ref:`envoy.matching.input_matchers.ip ` Precisely one of :ref:`value_match `, :ref:`custom_match ` must be set. .. _envoy_v3_api_msg_config.common.matcher.v3.Matcher.MatcherList.Predicate.PredicateList: config.common.matcher.v3.Matcher.MatcherList.Predicate.PredicateList -------------------------------------------------------------------- :repo:`[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. .. code-block:: json { "predicate": [] } .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.MatcherList.Predicate.PredicateList.predicate: predicate (**repeated** :ref:`config.common.matcher.v3.Matcher.MatcherList.Predicate `, *REQUIRED*) .. _envoy_v3_api_msg_config.common.matcher.v3.Matcher.MatcherList.FieldMatcher: config.common.matcher.v3.Matcher.MatcherList.FieldMatcher --------------------------------------------------------- :repo:`[config.common.matcher.v3.Matcher.MatcherList.FieldMatcher proto] ` An individual matcher. .. code-block:: json { "predicate": "{...}", "on_match": "{...}" } .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.MatcherList.FieldMatcher.predicate: predicate (:ref:`config.common.matcher.v3.Matcher.MatcherList.Predicate `, *REQUIRED*) Determines if the match succeeds. .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.MatcherList.FieldMatcher.on_match: on_match (:ref:`config.common.matcher.v3.Matcher.OnMatch `, *REQUIRED*) What to do if the match succeeds. .. _envoy_v3_api_msg_config.common.matcher.v3.Matcher.MatcherTree: config.common.matcher.v3.Matcher.MatcherTree -------------------------------------------- :repo:`[config.common.matcher.v3.Matcher.MatcherTree proto] ` .. code-block:: json { "input": "{...}", "exact_match_map": "{...}", "prefix_match_map": "{...}", "custom_match": "{...}" } .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.MatcherTree.input: input (:ref:`config.core.v3.TypedExtensionConfig `, *REQUIRED*) Protocol-specific specification of input field to match on. .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.MatcherTree.exact_match_map: exact_match_map (:ref:`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 :ref:`exact_match_map `, :ref:`prefix_match_map `, :ref:`custom_match ` must be set. .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.MatcherTree.prefix_match_map: prefix_match_map (:ref:`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 :ref:`exact_match_map `, :ref:`prefix_match_map `, :ref:`custom_match ` must be set. .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.MatcherTree.custom_match: custom_match (:ref:`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 :ref:`exact_match_map `, :ref:`prefix_match_map `, :ref:`custom_match ` must be set. .. _envoy_v3_api_msg_config.common.matcher.v3.Matcher.MatcherTree.MatchMap: config.common.matcher.v3.Matcher.MatcherTree.MatchMap ----------------------------------------------------- :repo:`[config.common.matcher.v3.Matcher.MatcherTree.MatchMap proto] ` A map of configured matchers. Used to allow using a map within a oneof. .. code-block:: json { "map": "{...}" } .. _envoy_v3_api_field_config.common.matcher.v3.Matcher.MatcherTree.MatchMap.map: map (**repeated** map<`string `_, :ref:`config.common.matcher.v3.Matcher.OnMatch `>) .. _envoy_v3_api_msg_config.common.matcher.v3.MatchPredicate: config.common.matcher.v3.MatchPredicate --------------------------------------- :repo:`[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. .. code-block:: json { "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": "{...}" } .. _envoy_v3_api_field_config.common.matcher.v3.MatchPredicate.or_match: or_match (:ref:`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 :ref:`or_match `, :ref:`and_match `, :ref:`not_match `, :ref:`any_match `, :ref:`http_request_headers_match `, :ref:`http_request_trailers_match `, :ref:`http_response_headers_match `, :ref:`http_response_trailers_match `, :ref:`http_request_generic_body_match `, :ref:`http_response_generic_body_match ` must be set. .. _envoy_v3_api_field_config.common.matcher.v3.MatchPredicate.and_match: and_match (:ref:`config.common.matcher.v3.MatchPredicate.MatchSet `) A set that describes a logical AND. If all members of the set match, the match configuration matches. Precisely one of :ref:`or_match `, :ref:`and_match `, :ref:`not_match `, :ref:`any_match `, :ref:`http_request_headers_match `, :ref:`http_request_trailers_match `, :ref:`http_response_headers_match `, :ref:`http_response_trailers_match `, :ref:`http_request_generic_body_match `, :ref:`http_response_generic_body_match ` must be set. .. _envoy_v3_api_field_config.common.matcher.v3.MatchPredicate.not_match: not_match (:ref:`config.common.matcher.v3.MatchPredicate `) A negation match. The match configuration will match if the negated match condition matches. Precisely one of :ref:`or_match `, :ref:`and_match `, :ref:`not_match `, :ref:`any_match `, :ref:`http_request_headers_match `, :ref:`http_request_trailers_match `, :ref:`http_response_headers_match `, :ref:`http_response_trailers_match `, :ref:`http_request_generic_body_match `, :ref:`http_response_generic_body_match ` must be set. .. _envoy_v3_api_field_config.common.matcher.v3.MatchPredicate.any_match: any_match (`bool `_) The match configuration will always match. Precisely one of :ref:`or_match `, :ref:`and_match `, :ref:`not_match `, :ref:`any_match `, :ref:`http_request_headers_match `, :ref:`http_request_trailers_match `, :ref:`http_response_headers_match `, :ref:`http_response_trailers_match `, :ref:`http_request_generic_body_match `, :ref:`http_response_generic_body_match ` must be set. .. _envoy_v3_api_field_config.common.matcher.v3.MatchPredicate.http_request_headers_match: http_request_headers_match (:ref:`config.common.matcher.v3.HttpHeadersMatch `) HTTP request headers match configuration. Precisely one of :ref:`or_match `, :ref:`and_match `, :ref:`not_match `, :ref:`any_match `, :ref:`http_request_headers_match `, :ref:`http_request_trailers_match `, :ref:`http_response_headers_match `, :ref:`http_response_trailers_match `, :ref:`http_request_generic_body_match `, :ref:`http_response_generic_body_match ` must be set. .. _envoy_v3_api_field_config.common.matcher.v3.MatchPredicate.http_request_trailers_match: http_request_trailers_match (:ref:`config.common.matcher.v3.HttpHeadersMatch `) HTTP request trailers match configuration. Precisely one of :ref:`or_match `, :ref:`and_match `, :ref:`not_match `, :ref:`any_match `, :ref:`http_request_headers_match `, :ref:`http_request_trailers_match `, :ref:`http_response_headers_match `, :ref:`http_response_trailers_match `, :ref:`http_request_generic_body_match `, :ref:`http_response_generic_body_match ` must be set. .. _envoy_v3_api_field_config.common.matcher.v3.MatchPredicate.http_response_headers_match: http_response_headers_match (:ref:`config.common.matcher.v3.HttpHeadersMatch `) HTTP response headers match configuration. Precisely one of :ref:`or_match `, :ref:`and_match `, :ref:`not_match `, :ref:`any_match `, :ref:`http_request_headers_match `, :ref:`http_request_trailers_match `, :ref:`http_response_headers_match `, :ref:`http_response_trailers_match `, :ref:`http_request_generic_body_match `, :ref:`http_response_generic_body_match ` must be set. .. _envoy_v3_api_field_config.common.matcher.v3.MatchPredicate.http_response_trailers_match: http_response_trailers_match (:ref:`config.common.matcher.v3.HttpHeadersMatch `) HTTP response trailers match configuration. Precisely one of :ref:`or_match `, :ref:`and_match `, :ref:`not_match `, :ref:`any_match `, :ref:`http_request_headers_match `, :ref:`http_request_trailers_match `, :ref:`http_response_headers_match `, :ref:`http_response_trailers_match `, :ref:`http_request_generic_body_match `, :ref:`http_response_generic_body_match ` must be set. .. _envoy_v3_api_field_config.common.matcher.v3.MatchPredicate.http_request_generic_body_match: http_request_generic_body_match (:ref:`config.common.matcher.v3.HttpGenericBodyMatch `) HTTP request generic body match configuration. Precisely one of :ref:`or_match `, :ref:`and_match `, :ref:`not_match `, :ref:`any_match `, :ref:`http_request_headers_match `, :ref:`http_request_trailers_match `, :ref:`http_response_headers_match `, :ref:`http_response_trailers_match `, :ref:`http_request_generic_body_match `, :ref:`http_response_generic_body_match ` must be set. .. _envoy_v3_api_field_config.common.matcher.v3.MatchPredicate.http_response_generic_body_match: http_response_generic_body_match (:ref:`config.common.matcher.v3.HttpGenericBodyMatch `) HTTP response generic body match configuration. Precisely one of :ref:`or_match `, :ref:`and_match `, :ref:`not_match `, :ref:`any_match `, :ref:`http_request_headers_match `, :ref:`http_request_trailers_match `, :ref:`http_response_headers_match `, :ref:`http_response_trailers_match `, :ref:`http_request_generic_body_match `, :ref:`http_response_generic_body_match ` must be set. .. _envoy_v3_api_msg_config.common.matcher.v3.MatchPredicate.MatchSet: config.common.matcher.v3.MatchPredicate.MatchSet ------------------------------------------------ :repo:`[config.common.matcher.v3.MatchPredicate.MatchSet proto] ` A set of match configurations used for logical operations. .. code-block:: json { "rules": [] } .. _envoy_v3_api_field_config.common.matcher.v3.MatchPredicate.MatchSet.rules: rules (**repeated** :ref:`config.common.matcher.v3.MatchPredicate `, *REQUIRED*) The list of rules that make up the set. .. _envoy_v3_api_msg_config.common.matcher.v3.HttpHeadersMatch: config.common.matcher.v3.HttpHeadersMatch ----------------------------------------- :repo:`[config.common.matcher.v3.HttpHeadersMatch proto] ` HTTP headers match configuration. .. code-block:: json { "headers": [] } .. _envoy_v3_api_field_config.common.matcher.v3.HttpHeadersMatch.headers: headers (**repeated** :ref:`config.route.v3.HeaderMatcher `) HTTP headers to match. .. _envoy_v3_api_msg_config.common.matcher.v3.HttpGenericBodyMatch: config.common.matcher.v3.HttpGenericBodyMatch --------------------------------------------- :repo:`[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. .. code-block:: json { "bytes_limit": "...", "patterns": [] } .. _envoy_v3_api_field_config.common.matcher.v3.HttpGenericBodyMatch.bytes_limit: bytes_limit (`uint32 `_) Limits search to specified number of bytes - default zero (no limit - match entire captured buffer). .. _envoy_v3_api_field_config.common.matcher.v3.HttpGenericBodyMatch.patterns: patterns (**repeated** :ref:`config.common.matcher.v3.HttpGenericBodyMatch.GenericTextMatch `, *REQUIRED*) List of patterns to match. .. _envoy_v3_api_msg_config.common.matcher.v3.HttpGenericBodyMatch.GenericTextMatch: config.common.matcher.v3.HttpGenericBodyMatch.GenericTextMatch -------------------------------------------------------------- :repo:`[config.common.matcher.v3.HttpGenericBodyMatch.GenericTextMatch proto] ` .. code-block:: json { "string_match": "...", "binary_match": "..." } .. _envoy_v3_api_field_config.common.matcher.v3.HttpGenericBodyMatch.GenericTextMatch.string_match: string_match (`string `_) Text string to be located in HTTP body. Precisely one of :ref:`string_match `, :ref:`binary_match ` must be set. .. _envoy_v3_api_field_config.common.matcher.v3.HttpGenericBodyMatch.GenericTextMatch.binary_match: binary_match (`bytes `_) Sequence of bytes to be located in HTTP body. Precisely one of :ref:`string_match `, :ref:`binary_match ` must be set.