sigs.k8s.io/gateway-api@v1.0.0/geps/gep-726.md

# GEP-726: Add Path Redirects and Rewrites

* Issue: [#726](https://github.com/kubernetes-sigs/gateway-api/issues/726)
* Status: Standard

## TLDR

This GEP proposes adding support for path redirects and rewrites in addition to
host rewrites. This would augment the existing host redirection capabilities.

## Goals

* Implement path redirects.
* Implement the most portable and simple forms of path rewrites.
* Describe how more advanced rewrite and redirect and redirect capabilities
  could be added in the future.

## API

Although many implementations support very advanced rewrite and redirect
capabilities, the following are the most [portable](#portability) concepts that
are not already supported by the Gateway API:

* Path redirects
* Path prefix redirects
* Path prefix rewrites
* Host rewrites

Although regular expression based redirects and rewrites are commonly supported,
there is significantly more variation in both if and how they are implemented.
Given the wide support for this concept, it is important to design the API in a
way that would make it easy to add this capability in the future.

### Path Modifiers

Both redirects and rewrites would share the same `PathModifier` types:

```go
// HTTPPathModifierType defines the type of path redirect.
type HTTPPathModifierType string

const (
  // This type of modifier indicates that the complete path will be replaced by
  // the path redirect value.
  AbsoluteHTTPPathModifier HTTPPathModifierType = "Absolute"

  // This type of modifier indicates that any prefix path matches will be
  // replaced by the substitution value. For example, a path with a prefix match
  // of "/foo" and a ReplacePrefixMatch substitution of "/bar" will have the
  // "/foo" prefix replaced with "/bar" in matching requests.
  PrefixMatchHTTPPathModifier HTTPPathModifierType = "ReplacePrefixMatch"
)

// HTTPPathModifier defines configuration for path modifiers.
type HTTPPathModifier struct {
  // Type defines the type of path modifier.
  //
  // +kubebuilder:validation:Enum=Absolute;ReplacePrefixMatch
  Type HTTPPathModifierType `json:"type"`

  // Substitution defines the HTTP path value to substitute. An empty value ("")
  // indicates that the portion of the path to be changed should be removed from
  // the resulting path. For example, a request to "/foo/bar" with a prefix
  // match of "/foo" would be modified to "/bar".
  //
  // +kubebuilder:validation:MaxLength=1024
  Substitution string `json:"substitution"`
}
```

### Redirects

The existing `RequestRedirect` filter can be expanded to support path redirects.
In the following example, a request to `/foo/abc` would be redirected to
`/bar/abc`.

```yaml
kind: HTTPRoute
apiVersion: gateway.networking.k8s.io/v1alpha2
metadata:
  name: http-filter-1
spec:
  rules:
    - matches:
      - path:
          type: Prefix
          value: /foo
      filters:
      - type: RequestRedirect
        requestRedirect:
          hostname: foo.com
          path:
            type: ReplacePrefixMatch
            value: /bar
```

This would be represented with the following API addition to the existing
HTTPRequestRedirect filter:
```go
// HTTPRequestRedirect defines a filter that redirects a request. At most one of
// these filters may be used on a Route rule. This may not be used on the same
// Route rule as a HTTPRequestRewrite filter.
//
// Support: Extended
type HTTPRequestRedirect struct {
  // Path defines a path redirect.
  //
  // Support: Extended
  //
  // +optional
  Path *HTTPPathModifier `json:"path,omitempty"`
  // ...
}
```

### Rewrites

A new `URLRewrite` filter can be added to support rewrites. In the following
example, a request to `example.com/foo/abc` would be rewritten to
`example.net/bar/abc`.

```yaml
kind: HTTPRoute
apiVersion: gateway.networking.k8s.io/v1alpha2
metadata:
  name: http-filter-1
spec:
  hostnames:
  - example.com
  rules:
    - matches:
      - path:
          type: Prefix
          value: /foo
      filters:
      - type: URLRewrite
        requestRewrite:
          hostname: example.net
          path:
            type: ReplacePrefixMatch
            substitution: /bar
```

This would be represent with the following API additions:
```go
// HTTPURLRewrite defines a filter that modifies a request during forwarding.
// At most one of these filters may be used on a Route rule. This may not be
// used on the same Route rule as a HTTPRequestRedirect filter.
//
// Support: Extended
type HTTPURLRewrite struct {
  // Hostname is the value to be used to replace the Host header value during
  // forwarding.
  //
  // Support: Extended
  //
  // +optional
  // +kubebuilder:validation:MaxLength=255
  Hostname *string `json:"hostname,omitempty"`

  // Path defines a path rewrite.
  //
  // Support: Extended
  //
  // +optional
  Path *HTTPPathModifier `json:"path,omitempty"`
}
```

Note: `RequestRewrite` was originally considered as a name for this filter.
`URLRewrite` was chosen as it more clearly represented the capabilities of the
filter and would not be confused with header or query param modification.

## Portability

When considering what should be possible in the API, it's worth evaluating what
common tooling is capable of. This is by no means a complete list, but this
provides a high level overview of how this is configured across different
implementations.

Although not all of these implementations directly support prefix rewrites or
redirects, the ones that don't include regular expression support which can be
used to implement prefix rewrites and redirects.

Note: This section intentionally excludes the redirect capabilities already
contained in the API.

### Envoy
Envoy supports the following relevant capabilities
([reference](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto)):

* path_redirect (redirect only)
* prefix_rewrite (redirect and forwarding)
* regex_rewrite (redirect and forwarding)
* host_rewrite_literal (forwarding only)
* strip_query (redirect only)

Note that path rewrite relies on the prefix match for the route, there is not
a way to differentiate between the prefix used for matching and rewriting.

### Google Cloud
Google Cloud URL Maps support the following relevant capabilities
([reference](https://cloud.google.com/compute/docs/reference/rest/v1/urlMaps)):

* pathPrefixRewrite (forwarding only)
* hostRewrite (forwarding only)
* pathRedirect (redirect only)
* prefixRedirect (redirect only)
* stripQuery (redirect only)

Note that path rewrite relies on the prefix match for the route, there is not
a way to differentiate between the prefix used for matching and rewriting.

### HAProxy
HAProxy supports the following relevant capabilities
([reference](https://cbonte.github.io/haproxy-dconv/2.5/configuration.html)):

* http-request set-path (advanced path rewrite capabilities)
* http-request replace-path (rewrites entire path)
* http-request replace-pathq (rewrites entire path + query string)
* http-request replace-uri (URI rewrite based on input regex)
* redirect location (advanced redirect capabilities)

### NGINX
The NGINX rewrite module contains the following relevant capabilities
([reference](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html)):

* PCRE regex based rewrites
* Rewrite directive can be used during forwarding or redirects
* Rewrite directive can affect host, path, or both
* Rewrite directive can be chained

## Future Extension
There are two relatively common types of path rewrite/redirect that are not
covered by this proposal:

1. Replace a path prefix separate from the match
2. Replace with a Regular Expression substitution

Both of the following can be represented by adding a new field new types. For
example, this config would result in a request to `/foo/baz` to be rewritten to
`/bar/baz`:

```yaml
filters:
- type: RequestRewrite
  requestRewrite:
    path:
      type: ReplacePrefix
      pattern: /foo
      substitution: /bar
```

Similarly, this config would result in a request to `/foo/bar/baz` being
rewritten to `/foo/other/baz`.
```yaml
filters:
- type: RequestRewrite
  requestRewrite:
    path:
      type: RegularExpression
      pattern: /foo/(.*)/baz
      substitution: other
```

Although both of the above are natural extensions of the API, they are not quite
as broadly supported. For that reason, this GEP proposes omitting these types
from the initial implementation.

## Alternatives

### 1. Generic Path Match Replacement
Instead of the `ReplacePrefixMatch` option proposed above, we could have a
`ReplacePathMatch` option. This would provide significantly more flexibility and
room for growth than prefix replacement.

Unfortunately it would be difficult to represent conformance and support levels.
It also would have limited value. Replacing "Exact" match types would be nearly
identical to the "Absolute" match type, and replacing "RegularExpression" match
types would likely not yield the desired result. In most cases, RegEx rewrites
are implemented separately from RegEx path matching. So a user may want to match
all paths matching one RegEx, but use a separate RegEx + substitution value for
rewrites.

It is theoretically possible that future patch match types could be useful as a
rewrite source, but the common proxies described above seem to be limited to the
rewrite types described above.

### 2. Top Level Rewrite Fields
Although a small difference, we could restructure how the path rewrites and
redirects were configured. One example would be adding top level fields in the
filters for each kind of path rewrite or redirect. That would result in a change
like this:

**Before:**
```yaml
requestRewrite:
  hostname: foo.com
  path:
    type: Prefix
    substitution: /bar
```

**After:**
```yaml
requestRewrite:
  hostname: foo.com
  pathPrefix: /bar
```

Although simpler for the initial use cases, it may become more difficult to
maintain and validate as additional types of rewrites and redirects were added.


## References

Issues:

- [#200: Add support for configurable HTTP redirects](https://github.com/kubernetes-sigs/gateway-api/issues/200)
- [#678: Add support for HTTP rewrites](https://github.com/kubernetes-sigs/gateway-api/issues/678)