Add filter RedirectorV2 (#1116)

easegress-io · Oct 31, 2023 · 378b7e8 · 378b7e8
1 parent 684633f
commit 378b7e8
Show file tree

Hide file tree

Showing 4 changed files with 605 additions and 50 deletions.
diff --git a/docs/07.Reference/7.02.Filters.md b/docs/07.Reference/7.02.Filters.md
@@ -70,9 +70,12 @@
 - [Redirector](#redirector)
   - [Configuration](#configuration-22)
   - [Results](#results-22)
-- [GRPCProxy](#grpcproxy)
+- [RedirectorV2](#redirectorv2)
   - [Configuration](#configuration-23)
   - [Results](#results-23)
+- [GRPCProxy](#grpcproxy)
+  - [Configuration](#configuration-24)
+  - [Results](#results-24)
 - [Common Types](#common-types)
   - [pathadaptor.Spec](#pathadaptorspec)
   - [pathadaptor.RegexpReplace](#pathadaptorregexpreplace)
@@ -983,7 +986,7 @@ HeaderLookup has no results.
 
 ## ResultBuilder
 
-ResultBuilder generates a string, which will be the result of the filter. 
+ResultBuilder generates a string, which will be the result of the filter.
 This filter exists to work with the [`jumpIf` mechanism](7.01.Controllers.md#pipeline) for conditional jumping.
 
 Currently, the result string can only be `result0` - `result9`, this will be
@@ -1139,10 +1142,10 @@ After OIDCAdaptor handled, following OIDC related information can be obtained fr
 
 
 ## OPAFilter
-The [Open Policy Agent (OPA)](https://www.openpolicyagent.org/docs/latest/) is an open source, 
-general-purpose policy engine that unifies policy enforcement across the stack. It provides a 
-high-level declarative language, which can be used to define and enforce policies in 
-Easegress API Gateway. Currently, there are 160+ built-in operators and functions we can use, 
+The [Open Policy Agent (OPA)](https://www.openpolicyagent.org/docs/latest/) is an open source,
+general-purpose policy engine that unifies policy enforcement across the stack. It provides a
+high-level declarative language, which can be used to define and enforce policies in
+Easegress API Gateway. Currently, there are 160+ built-in operators and functions we can use,
 for examples `net.cidr_contains` and `contains`.
 
 ```yaml
@@ -1163,8 +1166,8 @@ filters:
       allow {
          input.request.method == "POST"
          input.request.scheme == "https"
-         contains(input.request.path, "/")               
-         net.cidr_contains("127.0.0.0/24",input.request.realIP)          
+         contains(input.request.path, "/")
+         net.cidr_contains("127.0.0.0/24",input.request.realIP)
       }
 ```
 
@@ -1178,7 +1181,7 @@ The following table lists input request fields that can be used in an OPA policy
 | input.request.raw_query  | string | The current http request raw query                                    | "a=1&b=2&c=3"                        |
 | input.request.query      | map    | The current http request query map                                    | {"a":1,"b":2,"c":3}                  |
 | input.request.headers    | map    | The current http request header map targeted by<br/> includedHeaders  | {"Content-Type":"application/json"}  |
-| input.request.scheme     | string | The current http request scheme                                       | "https"                              | 
+| input.request.scheme     | string | The current http request scheme                                       | "https"                              |
 | input.request.realIP     | string | The current http request client real IP                               | "127.0.0.1"                          |
 | input.request.body       | string | The current http request body string data                             | {"data":"xxx"}                       |
 
@@ -1202,7 +1205,7 @@ The following table lists input request fields that can be used in an OPA policy
 
 The `Redirector` filter is used to do HTTP redirect. `Redirector` matches request url, do replacement, and return response with status code of `3xx` and put new path in response header with key of `Location`.
 
-Here a simple example: 
+Here a simple example:
 ```yaml
 name: demo-pipeline
 kind: Pipeline
@@ -1234,13 +1237,13 @@ filters:
   kind: Redirector
   match: "^/users/([0-9]+)"
   # by default, value of matchPart is uri, supported values: uri, path, full.
-  matchPart: "full" 
+  matchPart: "full"
   replacement: "http://example.com/display?user=$1"
 ```
 
 For request with URL of `https://example.com:8080/apis/v1/user?id=1`, URI part is `/apis/v1/user?id=1`, path part is `/apis/v1/user` and full part is `https://example.com:8080/apis/v1/user?id=1`.
 
-By default, we return status code of `301` "Moved Permanently". To return status code of `302` "Found" or other `3xx`, change `statusCode` in yaml. 
+By default, we return status code of `301` "Moved Permanently". To return status code of `302` "Found" or other `3xx`, change `statusCode` in yaml.
 
 ```yaml
 name: demo-pipeline
@@ -1256,7 +1259,7 @@ filters:
   replacement: "http://example.com/display?user=$1"
 ```
 
-Following are some common used examples: 
+Following are some common used examples:
 1. URI prefix redirect
 ```yaml
 name: demo-pipeline
@@ -1355,13 +1358,96 @@ output: https://example.com/api/user/123
 | ---- | ---- | ----------- | -------- |
 | match | string | Regular expression to match request path. The syntax of the regular expression is [RE2](https://golang.org/s/re2syntax) | Yes |
 | matchPart | string | Parameter to decide which part of url used to do match, supported values: uri, full, path. Default value is uri. | No |
-| replacement | string | Replacement when the match succeeds. Placeholders like `$1`, `$2` can be used to represent the sub-matches in `regexp` | Yes | 
-| statusCode | int | Status code of response. Supported values: 301, 302, 303, 304, 307, 308. Default: 301. | No | 
+| replacement | string | Replacement when the match succeeds. Placeholders like `$1`, `$2` can be used to represent the sub-matches in `regexp` | Yes |
+| statusCode | int | Status code of response. Supported values: 301, 302, 303, 304, 307, 308. Default: 301. | No |
 ### Results
 | Value | Description |
 | ----- | ----------- |
 | redirected | The request has been redirected |
 
+
+## RedirectorV2
+
+The `RedirectorV2` filter provides advanced HTTP redirection capabilities within the Kubernetes API Gateway. It offers fine-grained control over URL components such as scheme, hostname, and path. The specifications are consistent with the [Kubernetes Gateway API's `HTTPRequestRedirectFilter`](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRequestRedirectFilter).
+
+### Configuration
+
+| Name | Type | Description | Required |
+|------|------|-------------|----------|
+| scheme | string | The protocol for the redirected request (e.g., `http` or `https`). | No |
+| hostname | string | The domain name to which the request should be redirected. To specify a port, include it in the hostname (e.g., `example.com:8080`). Note: Explicit port configurations are currently unsupported due to complexities in specification. | No |
+| statusCode | int | The HTTP status code for the redirection response. | Yes |
+| path.type | string | Determines the type of redirection. Supported values: `ReplacePrefixMatch`, `ReplaceFullPath`. | Yes |
+| path.replacePrefixMatch | string | The new prefix for the redirection. Used only with `ReplacePrefixMatch`. | Conditional |
+| path.replaceFullPath | string | The new full path for the redirection. Used only with `ReplaceFullPath`. | Conditional |
+
+### Results
+
+| Value | Description |
+|-------|-------------|
+| redirected | Indicates that the request has been redirected based on the `RedirectorV2` configuration. |
+
+
+Commmon Use-Cases:
+
+1. Replace Prefix:
+
+Substitute a prefix with `/account` and return a `302 Found` status code.
+
+```yaml
+name: demo-pipeline
+kind: Pipeline
+flow:
+- filter: redirectorv2
+filters:
+- name: redirectorv2
+  kind: RedirectorV2
+  pathPrefix: /user
+  path:
+    type: ReplacePrefixMatch
+    replacePrefixMatch: /account
+  statusCode: 302
+```
+
+2. Replace Full Path:
+
+Redirect to an absolute path `/full-path`.
+
+```yaml
+name: demo-pipeline
+kind: Pipeline
+flow:
+- filter: redirectorv2
+filters:
+- name: redirectorv2
+  kind: RedirectorV2
+  path:
+    type: ReplaceFullPath
+    replaceFullPath: /full-path
+  statusCode: 302
+```
+
+3. Domain and Scheme Redirection:
+
+Redirect to a new domain using the HTTPS protocol.
+
+```yaml
+name: demo-pipeline
+kind: Pipeline
+flow:
+- filter: redirectorv2
+filters:
+- name: redirectorv2
+  kind: RedirectorV2
+  scheme: https
+  hostname: newdomain.com
+  pathPrefix: /user
+  path:
+    type: ReplacePrefixMatch
+    replacePrefixMatch: /account
+  statusCode: 302
+```
+
 ## GRPCProxy
 
 The `GRPCProxy` filter is a proxy for gRPC backend service. It supports both unary RPCs and streaming RPCs.
@@ -1389,7 +1475,7 @@ Same as the `Proxy` filter:
 * the servers of a pool can be configured dynamically via service discovery.
 * when there are multiple servers in a pool, the pool can do a load balance between them.
 
-Because gRPC does not support the http `Connect` method, it does not support tunneling mode, 
+Because gRPC does not support the http `Connect` method, it does not support tunneling mode,
 we provide a new [load balancer](#proxyloadbalancespec) `policy.forward` to achieve a similar effect.
 
 Note that each gRPC client establishes a connection with Easegress. However,