UriPathRewriteFilter
Rewrite a URL path, using a bidirectional mapping:
-
In the request flow,
fromPath
is mapped totoPath
. -
In the response flow,
toPath
is mapped tofromPath
.
IG overwrites a response header only when all of the following conditions are true:
-
The response includes a header such as
Location
orContent-Location
-
The URI of the response header matches the mapping
-
The value of response header is a relative path or its
scheme://host:port
value matches the base URI.
Usage
{
"name": string,
"type": "UriPathRewriteFilter",
"config": {
"mappings": object,
"failureHandler": Handler reference
}
}
Properties
"mappings"
: object, required-
One or more bidirectional mappings between URL paths. For example mappings, request scenarios, and an example route, refer to Examples.
{ "mappings": { "/fromPath1": "/toPath1", "/fromPath2": "/toPath2", ... } }
Paths are given by a
configuration expression<string>
. Consider the following points when you define paths:-
The incoming URL must start with the mapping path.
-
When more than one mapping applies to a URL, the most specific mapping is used.
-
Duplicate
fromPath
values are removed without warning. -
Trailing slashes
/
are removed from path values. -
If the response includes a
Location
orContent-Location
header with atoPath
in its URL, the response is rewritten withfromPath
.
-
"failureHandler"
: handler reference, optional-
Failure handler to be invoked if an invalid URL is produced when the request path is mapped, or when the response
Location
orContent-Location
header URI path is reverse-mapped.Provide an inline handler declaration, or the name of a handler object defined in the heap. See also Handlers.
Default: HTTP 500
Examples
Valid and invalid mapping examples
The following mapping examples are valid:
-
Single
fromPath
andtoPath
"mappings": { "/fromPath1": "/toPath1", "/fromPath2": "/toPath2" }
-
Expressions in the
fromPath
andtoPath
"mappings": { "/${join(array(`fromPath`, 'path1'), `/`)}": "/${join(array(`toPath`, 'path2'), `/`)}" }
-
Expressions in the
fromPath
andtoPath
that use predefined heap properties"mappings": { "${fromPath}": "${toPath}" }
-
No mappings—the configuration is valid, but has no effect
"mappings": { }
-
Duplicate
toPath
"mappings": { "/fromPath1": "/toPath", "/fromPath2": "/toPath" }
-
Duplicate
fromPath
—the configuration is overwritten without warning"mappings": { "/fromPath": "/toPath1", "/fromPath": "/toPath2" }
The following mapping examples are not valid
-
No
toPath
"mappings": { "/fromPath": "" }
"mappings": { "/fromPath": "${unknown}" }
-
Invalid
toPath
"mappings": { "/fromPath": "${invalidExpression}" }
-
No
fromPath
"mappings": { "": "/toPath" }
"mappings": { "${unknown}": "/toPath" }
-
Invalid
fromPath
"mappings": { "${invalidExpression}": "/toPath" }
Example request scenarios
Description | Mapping | Inbound URI | Rewritten URI |
---|---|---|---|
Basic path |
|
http://example.com/fromPath/remainder |
http://example.com/toPath/remainder |
Root context, where the inbound request URI has a |
|
http://example.com/ |
http://example.com/rootcontext/ |
Root context, where the inbound URI has a |
|
http://example.com/rootcontext/ |
http://example.com/ |
Root context, where the inbound request URI has an empty path |
|
http://example.com |
http://example.com/rootcontext |
Root context, where the rewritten URI has an empty path |
|
http://example.com/rootcontext |
http://example.com |
Root context, with path remainder |
|
http://example.com/remainder |
http://example.com/rootcontext/remainder |
Root context, with path remainder |
|
http://example.com/rootcontext/remainder |
http://example.com/remainder |
Root context, where the trailing |
|
http://example.com/remainder |
http://example.com/rootcontext/remainder |
Path with dot-segments: |
|
http://example.com/fromPath |
http://example.com/toPath1/../toPath2 |
Path with syntax: |
|
http://example.com/fromPath;v=1.1 |
http://example.com/toPath,1.1 |
Path with syntax: |
|
http://example.com/$fromPath |
http://example.com/$toPath |
Path with query parameters |
|
http://example.com/fromPath?param1¶m2=2 |
http://example.com/toPath?param1¶m2=2 |
Path with fragment |
|
http://example.com/fromPath#fragment |
http://example.com/toPath#fragment |
Example route
The example route changes a request URL as follows:
-
The
baseURI
overrides the scheme, host, and port of a request URL. -
The UriPathRewriteFilter remaps the path of a request URL.
Requests to
http://ig.example.com:8080/mylogin
are mapped tohttp://app.example.com:8081/login
.Requests to
http://ig.example.com:8080/welcome
are mapped tohttp://app.example.com:8081/home
.Requests to
http://ig.example.com:8080/other
are mapped tohttp://app.example.com:8081/not-found
, and result in an HTTP 404.Requests to
http://ig.example.com:8080/badurl
are mapped to the invalid URLhttp://app.example.com:8081[
, and invoke the failure handler.
{
"name": "UriPathRewriteFilter",
"baseURI": "http://app.example.com:8081",
"handler": {
"type": "Chain",
"config": {
"filters": [
{
"type": "UriPathRewriteFilter",
"config": {
"mappings": {
"/mylogin": "/login",
"/welcome": "/home",
"/other": "/not-found",
"/badurl": "["
},
"failureHandler": {
"type": "StaticResponseHandler",
"config": {
"status": 500,
"headers": {
"Content-Type": [
"text/plain"
]
},
"entity": "Invalid URL produced"
}
}
}
}
],
"handler": "ClientHandler"
}
}
}