router: implement new regex_rewrite route action

api/envoy/api/v2/route/route_components.proto

@@ -530,7 +530,7 @@ message CorsPolicy {
   core.RuntimeFractionalPercent shadow_enabled = 10;
 }
 
-// [#next-free-field: 32]
+// [#next-free-field: 33]
 message RouteAction {
   enum ClusterNotFoundResponseCode {
     // HTTP status code - 503 Service Unavailable.
@@ -742,6 +742,10 @@ message RouteAction {
   // place the original path before rewrite into the :ref:`x-envoy-original-path
   // <config_http_filters_router_x-envoy-original-path>` header.
   //
+  // Only one of *prefix_rewrite* or
+  // :ref:`regex_rewrite <envoy_api_field_route.RouteAction.regex_rewrite>`
+  // may be specified.
+  //
   // .. attention::
   //
   //   Pay careful attention to the use of trailing slashes in the
@@ -765,6 +769,36 @@ message RouteAction {
   //   requests to */prefix/etc* will be stripped to */etc*.
   string prefix_rewrite = 5;
 
+  // Indicates that during forwarding, portions of the path that match the
+  // pattern should be rewritten, even allowing the substitution of capture
+  // groups from the pattern into the new path as specified by the rewrite
+  // substitution string. This is useful to allow application paths to be
+  // rewritten in a way that is aware of segments with variable content like
+  // identifiers. The router filter will place the original path as it was
+  // before the rewrite into the :ref:`x-envoy-original-path
+  // <config_http_filters_router_x-envoy-original-path>` header.
+  //
+  // Only one of :ref:`prefix_rewrite <envoy_api_field_route.RouteAction.prefix_rewrite>`
+  // or *regex_rewrite* may be specified.
+  //
+  // Examples using Google's `RE2 <https://github.com/google/re2>`_ engine:
+  //
+  // * The path pattern ``^/service/([^/]+)(/.*)$`` paired with a substitution
+  //   string of ``\2/instance/\1`` would transform ``/service/foo/v1/api``
+  //   into ``/v1/api/instance/foo``.
+  //
+  // * The pattern ``one`` paired with a substitution string of ``two`` would
+  //   transform ``/xxx/one/yyy/one/zzz`` into ``/xxx/two/yyy/two/zzz``.
+  //
+  // * The pattern ``^(.*?)one(.*)$`` paired with a substitution string of
+  //   ``\1two\2`` would replace only the first occurrence of ``one``,
+  //   transforming path ``/xxx/one/yyy/one/zzz`` into ``/xxx/two/yyy/one/zzz``.
+  //
+  // * The pattern ``(?i)/xxx/`` paired with a substitution string of ``/yyy/``
+  //   would do a case-insensitive match and transform path ``/aaa/XxX/bbb`` to
+  //   ``/aaa/yyy/bbb``.
+  type.matcher.RegexMatchAndSubstitute regex_rewrite = 32;
+
   oneof host_rewrite_specifier {
     // Indicates that during forwarding, the host header will be swapped with
     // this value.

api/envoy/config/route/v3/route_components.proto

@@ -491,7 +491,7 @@ message CorsPolicy {
   core.v3.RuntimeFractionalPercent shadow_enabled = 10;
 }
 
-// [#next-free-field: 32]
+// [#next-free-field: 33]
 message RouteAction {
   option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.route.RouteAction";
 
@@ -715,6 +715,10 @@ message RouteAction {
   // place the original path before rewrite into the :ref:`x-envoy-original-path
   // <config_http_filters_router_x-envoy-original-path>` header.
   //
+  // Only one of *prefix_rewrite* or
+  // :ref:`regex_rewrite <envoy_api_field_config.route.v3.RouteAction.regex_rewrite>`
+  // may be specified.
+  //
   // .. attention::
   //
   //   Pay careful attention to the use of trailing slashes in the
@@ -738,6 +742,36 @@ message RouteAction {
   //   requests to */prefix/etc* will be stripped to */etc*.
   string prefix_rewrite = 5;
 
+  // Indicates that during forwarding, portions of the path that match the
+  // pattern should be rewritten, even allowing the substitution of capture
+  // groups from the pattern into the new path as specified by the rewrite
+  // substitution string. This is useful to allow application paths to be
+  // rewritten in a way that is aware of segments with variable content like
+  // identifiers. The router filter will place the original path as it was
+  // before the rewrite into the :ref:`x-envoy-original-path
+  // <config_http_filters_router_x-envoy-original-path>` header.
+  //
+  // Only one of :ref:`prefix_rewrite <envoy_api_field_config.route.v3.RouteAction.prefix_rewrite>`
+  // or *regex_rewrite* may be specified.
+  //
+  // Examples using Google's `RE2 <https://github.com/google/re2>`_ engine:
+  //
+  // * The path pattern ``^/service/([^/]+)(/.*)$`` paired with a substitution
+  //   string of ``\2/instance/\1`` would transform ``/service/foo/v1/api``
+  //   into ``/v1/api/instance/foo``.
+  //
+  // * The pattern ``one`` paired with a substitution string of ``two`` would
+  //   transform ``/xxx/one/yyy/one/zzz`` into ``/xxx/two/yyy/two/zzz``.
+  //
+  // * The pattern ``^(.*?)one(.*)$`` paired with a substitution string of
+  //   ``\1two\2`` would replace only the first occurrence of ``one``,
+  //   transforming path ``/xxx/one/yyy/one/zzz`` into ``/xxx/two/yyy/one/zzz``.
+  //
+  // * The pattern ``(?i)/xxx/`` paired with a substitution string of ``/yyy/``
+  //   would do a case-insensitive match and transform path ``/aaa/XxX/bbb`` to
+  //   ``/aaa/yyy/bbb``.
+  type.matcher.v3.RegexMatchAndSubstitute regex_rewrite = 32;
+
   oneof host_rewrite_specifier {
     // Indicates that during forwarding, the host header will be swapped with
     // this value.

api/envoy/type/matcher/regex.proto

@@ -35,3 +35,29 @@ message RegexMatcher {
   // The regex match string. The string must be supported by the configured engine.
   string regex = 2 [(validate.rules).string = {min_bytes: 1}];
 }
+
+// Describes how to match a string and then produce a new string using a regular
+// expression and a substitution string.
+message RegexMatchAndSubstitute {
+  // The regular expression used to find portions of a string (hereafter called
+  // the "subject string") that should be replaced. When a new string is
+  // produced during the substitution operation, the new string is initially
+  // the same as the subject string, but then all matches in the subject string
+  // are replaced by the substitution string. If replacing all matches isn't
+  // desired, regular expression anchors can be used to ensure a single match,
+  // so as to replace just one occurrence of a pattern. Capture groups can be
+  // used in the pattern to extract portions of the subject string, and then
+  // referenced in the substitution string.
+  RegexMatcher pattern = 1;
+
+  // The string that should be substituted into matching portions of the
+  // subject string during a substitution operation to produce a new string.
+  // Capture groups in the pattern can be referenced in the substitution
+  // string. Note, however, that the syntax for referring to capture groups is
+  // defined by the chosen regular expression engine. Google's `RE2
+  // <https://github.com/google/re2>`_ regular expression engine uses a
+  // backslash followed by the capture group number to denote a numbered
+  // capture group. E.g., ``\1`` refers to capture group 1, and ``\2`` refers
+  // to capture group 2.
+  string substitution = 2;
+}

api/envoy/type/matcher/v3/regex.proto

@@ -42,3 +42,32 @@ message RegexMatcher {
   // The regex match string. The string must be supported by the configured engine.
   string regex = 2 [(validate.rules).string = {min_bytes: 1}];
 }
+
+// Describes how to match a string and then produce a new string using a regular
+// expression and a substitution string.
+message RegexMatchAndSubstitute {
+  option (udpa.annotations.versioning).previous_message_type =
+      "envoy.type.matcher.RegexMatchAndSubstitute";
+
+  // The regular expression used to find portions of a string (hereafter called
+  // the "subject string") that should be replaced. When a new string is
+  // produced during the substitution operation, the new string is initially
+  // the same as the subject string, but then all matches in the subject string
+  // are replaced by the substitution string. If replacing all matches isn't
+  // desired, regular expression anchors can be used to ensure a single match,
+  // so as to replace just one occurrence of a pattern. Capture groups can be
+  // used in the pattern to extract portions of the subject string, and then
+  // referenced in the substitution string.
+  RegexMatcher pattern = 1;
+
+  // The string that should be substituted into matching portions of the
+  // subject string during a substitution operation to produce a new string.
+  // Capture groups in the pattern can be referenced in the substitution
+  // string. Note, however, that the syntax for referring to capture groups is
+  // defined by the chosen regular expression engine. Google's `RE2
+  // <https://github.com/google/re2>`_ regular expression engine uses a
+  // backslash followed by the capture group number to denote a numbered
+  // capture group. E.g., ``\1`` refers to capture group 1, and ``\2`` refers
+  // to capture group 2.
+  string substitution = 2;
+}

docs/root/configuration/http/http_conn_man/headers.rst

@@ -471,7 +471,8 @@ route, virtual host, and/or global route configuration level. See the
 
 No *:-prefixed* pseudo-header may be modified via this mechanism. The *:path*
 and *:authority* headers may instead be modified via mechanisms such as
-:ref:`prefix_rewrite <envoy_api_field_route.RouteAction.prefix_rewrite>` and
+:ref:`prefix_rewrite <envoy_api_field_route.RouteAction.prefix_rewrite>`,
+:ref:`regex_rewrite <envoy_api_field_route.RouteAction.regex_rewrite>`, and
 :ref:`host_rewrite <envoy_api_field_route.RouteAction.host_rewrite>`.
 
 Headers are appended to requests/responses in the following order: weighted cluster level headers,

docs/root/configuration/http/http_filters/router_filter.rst

@@ -341,7 +341,8 @@ responses.
 x-envoy-original-path
 ^^^^^^^^^^^^^^^^^^^^^
 
-If the route utilizes :ref:`prefix_rewrite <envoy_api_field_route.RouteAction.prefix_rewrite>`,
+If the route utilizes :ref:`prefix_rewrite <envoy_api_field_route.RouteAction.prefix_rewrite>`
+or :ref:`regex_rewrite <envoy_api_field_route.RouteAction.regex_rewrite>`,
 Envoy will put the original path header in this header. This can be useful for logging and
 debugging.
 

docs/root/intro/arch_overview/http/http_routing.rst

@@ -30,6 +30,7 @@ request. The router filter supports the following features:
 * :ref:`Automatic host rewriting <envoy_api_field_route.RouteAction.auto_host_rewrite>` based on
   the DNS name of the selected upstream host.
 * :ref:`Prefix rewriting <envoy_api_field_route.RedirectAction.prefix_rewrite>`.
+* :ref:`Path rewriting using a regular expression and capture groups <envoy_api_field_route.RouteAction.regex_rewrite>`.
 * :ref:`Request retries <arch_overview_http_routing_retry>` specified either via HTTP header or via
   route configuration.
 * Request timeout specified either via :ref:`HTTP

docs/root/intro/version_history.rst

@@ -18,6 +18,8 @@ Version history
 * router: added :ref:`auto_san_validation <envoy_api_field_core.UpstreamHttpProtocolOptions.auto_san_validation>` to support overrriding SAN validation to transport socket for new upstream connections based on the downstream HTTP host/authority header.
 * router: added the ability to match a route based on whether a downstream TLS connection certificate has been
   :ref:`validated <envoy_api_field_route.RouteMatch.TlsContextMatchOptions.validated>`.
+* router: added support for :ref:`regex_rewrite
+  <envoy_api_field_route.RouteAction.regex_rewrite>` for path rewriting using regular expressions and capture groups.
 * router: don't ignore :ref:`per_try_timeout <envoy_api_field_route.RetryPolicy.per_try_timeout>` when the :ref:`global route timeout <envoy_api_field_route.RouteAction.timeout>` is disabled.
 * sds: added :ref:`GenericSecret <envoy_api_msg_auth.GenericSecret>` to support secret of generic type.
 * stat sinks: stat sink extensions use the "envoy.stat_sinks" name space. A mapping of extension