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.
@@ -696,6 +696,27 @@ message RouteAction {
     google.protobuf.BoolValue enabled = 2;
   }
 
+  // Describe how to match the path and rewrite it using a regular expression
+  // and a substitution string.
+  message RegexRewrite {
+    // The regular expression used to find portions of the path (excluding
+    // query parameters) that should be replaced. All matches in the path are
+    // replaced by the substitution string, though anchors in the regular
+    // expression can be used to replace just one occurrence of a pattern.
+    // Capture groups can be used in the pattern to extract portions of the
+    // path, and referenced in the substitution string.
+    type.matcher.RegexMatcher pattern = 1;
+
+    // The string that should be substituted into matching portions of the path.
+    // Capture groups in the pattern can be referenced in this string. Beware,
+    // however, that the syntax for referring to capture groups is defined by
+    // the regular expression engines. Google's `RE2 <https://github.com/google/re2>`_
+    // regular expression engine uses 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;
+  }
+
   reserved 12, 18, 19, 16, 22, 21;
 
   oneof cluster_specifier {
@@ -742,6 +763,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 +790,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``.
+  RegexRewrite 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";
 
@@ -667,6 +667,30 @@ message RouteAction {
     google.protobuf.BoolValue enabled = 2;
   }
 
+  // Describe how to match the path and rewrite it using a regular expression
+  // and a substitution string.
+  message RegexRewrite {
+    option (udpa.annotations.versioning).previous_message_type =
+        "envoy.api.v2.route.RouteAction.RegexRewrite";
+
+    // The regular expression used to find portions of the path (excluding
+    // query parameters) that should be replaced. All matches in the path are
+    // replaced by the substitution string, though anchors in the regular
+    // expression can be used to replace just one occurrence of a pattern.
+    // Capture groups can be used in the pattern to extract portions of the
+    // path, and referenced in the substitution string.
+    type.matcher.v3.RegexMatcher pattern = 1;
+
+    // The string that should be substituted into matching portions of the path.
+    // Capture groups in the pattern can be referenced in this string. Beware,
+    // however, that the syntax for referring to capture groups is defined by
+    // the regular expression engines. Google's `RE2 <https://github.com/google/re2>`_
+    // regular expression engine uses 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;
+  }
+
   reserved 12, 18, 19, 16, 22, 21, 10;
 
   reserved "request_mirror_policy";
@@ -715,6 +739,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 +766,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``.
+  RegexRewrite regex_rewrite = 32;
+
   oneof host_rewrite_specifier {
     // Indicates that during forwarding, the host header will be swapped with
     // this value.

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

@@ -16,6 +16,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.
 * 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
   names is available in the :ref:`deprecated <deprecated>` documentation.