1syntax = "proto3"; 2 3package envoy.type.matcher.v3; 4 5import "google/protobuf/wrappers.proto"; 6 7import "envoy/annotations/deprecation.proto"; 8import "udpa/annotations/status.proto"; 9import "udpa/annotations/versioning.proto"; 10import "validate/validate.proto"; 11 12option java_package = "io.envoyproxy.envoy.type.matcher.v3"; 13option java_outer_classname = "RegexProto"; 14option java_multiple_files = true; 15option go_package = "github.com/envoyproxy/go-control-plane/envoy/type/matcher/v3;matcherv3"; 16option (udpa.annotations.file_status).package_version_status = ACTIVE; 17 18// [#protodoc-title: Regex matcher] 19 20// A regex matcher designed for safety when used with untrusted input. 21message RegexMatcher { 22 option (udpa.annotations.versioning).previous_message_type = "envoy.type.matcher.RegexMatcher"; 23 24 // Google's `RE2 <https://github.com/google/re2>`_ regex engine. The regex string must adhere to 25 // the documented `syntax <https://github.com/google/re2/wiki/Syntax>`_. The engine is designed 26 // to complete execution in linear time as well as limit the amount of memory used. 27 // 28 // Envoy supports program size checking via runtime. The runtime keys ``re2.max_program_size.error_level`` 29 // and ``re2.max_program_size.warn_level`` can be set to integers as the maximum program size or 30 // complexity that a compiled regex can have before an exception is thrown or a warning is 31 // logged, respectively. ``re2.max_program_size.error_level`` defaults to 100, and 32 // ``re2.max_program_size.warn_level`` has no default if unset (will not check/log a warning). 33 // 34 // Envoy emits two stats for tracking the program size of regexes: the histogram ``re2.program_size``, 35 // which records the program size, and the counter ``re2.exceeded_warn_level``, which is incremented 36 // each time the program size exceeds the warn level threshold. 37 message GoogleRE2 { 38 option (udpa.annotations.versioning).previous_message_type = 39 "envoy.type.matcher.RegexMatcher.GoogleRE2"; 40 41 // This field controls the RE2 "program size" which is a rough estimate of how complex a 42 // compiled regex is to evaluate. A regex that has a program size greater than the configured 43 // value will fail to compile. In this case, the configured max program size can be increased 44 // or the regex can be simplified. If not specified, the default is 100. 45 // 46 // This field is deprecated; regexp validation should be performed on the management server 47 // instead of being done by each individual client. 48 // 49 // .. note:: 50 // 51 // Although this field is deprecated, the program size will still be checked against the 52 // global ``re2.max_program_size.error_level`` runtime value. 53 // 54 google.protobuf.UInt32Value max_program_size = 1 55 [deprecated = true, (envoy.annotations.deprecated_at_minor_version) = "3.0"]; 56 } 57 58 oneof engine_type { 59 // Google's RE2 regex engine. 60 GoogleRE2 google_re2 = 1 [ 61 deprecated = true, 62 (validate.rules).message = {required: true}, 63 (envoy.annotations.deprecated_at_minor_version) = "3.0" 64 ]; 65 } 66 67 // The regex match string. The string must be supported by the configured engine. The regex is matched 68 // against the full string, not as a partial match. 69 string regex = 2 [(validate.rules).string = {min_len: 1}]; 70} 71 72// Describes how to match a string and then produce a new string using a regular 73// expression and a substitution string. 74message RegexMatchAndSubstitute { 75 option (udpa.annotations.versioning).previous_message_type = 76 "envoy.type.matcher.RegexMatchAndSubstitute"; 77 78 // The regular expression used to find portions of a string (hereafter called 79 // the "subject string") that should be replaced. When a new string is 80 // produced during the substitution operation, the new string is initially 81 // the same as the subject string, but then all matches in the subject string 82 // are replaced by the substitution string. If replacing all matches isn't 83 // desired, regular expression anchors can be used to ensure a single match, 84 // so as to replace just one occurrence of a pattern. Capture groups can be 85 // used in the pattern to extract portions of the subject string, and then 86 // referenced in the substitution string. 87 RegexMatcher pattern = 1 [(validate.rules).message = {required: true}]; 88 89 // The string that should be substituted into matching portions of the 90 // subject string during a substitution operation to produce a new string. 91 // Capture groups in the pattern can be referenced in the substitution 92 // string. Note, however, that the syntax for referring to capture groups is 93 // defined by the chosen regular expression engine. Google's `RE2 94 // <https://github.com/google/re2>`_ regular expression engine uses a 95 // backslash followed by the capture group number to denote a numbered 96 // capture group. E.g., ``\1`` refers to capture group 1, and ``\2`` refers 97 // to capture group 2. 98 string substitution = 2 99 [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}]; 100} 101