redirect-rules
Flexible redirect rule engine for connect middleware
Usage
var redirector = ;var rules = from: '/some/url' to: '/another/url' from: path: /\/thing\// to: '/things/{path$1}' from: protocol: 'http' to: 'https://{host}/{url}' from: path: '/workflow' params: complete: true to: '//newdomain.com/welcome' status: 302 from: '/some/url' to: url: '/another/url' status: 302 headers: 'x-redirected-from': '{url}' body: 'Redirecting to {redirectURL}' ;app;
Description
The redirect-rules
middleware is a flexible rules-based engine for redirecting requests. It supports matching
multiple conditions and can easily generate redirect URLs based on conditional match results.
To create the middleware, simply pass a rule object into the module-level function:
var redirector = ;var rule = from: '/url1' to: '/url2' ;app;
To specify multiple redirect rules, pass an Array
; the rules will be tested in order until a match is found:
var redirector = ;var rules = from: '/url1' to: '/url2' from: '/url3' to: '/url4' ;app;
Rules
A rule contains up to three properties:
from
: Conditions for matching a request. See "Matchers" below.to
: The template for the URL to redirect to. See "Redirect URLs" below.status
: The status code to use for the redirect. The default is301
(permanent).to: '/url', status: 302
is synonymous withto: { url: '/url', status: 302 }
.
Matchers
The from
property of rules is an map of matchers to condition values:
hostname: 'some.domain.com' path: '/some/path';
A condition value can be either a string, which is used for exact matches, a RegExp
, or in the case of a map-based
matcher, a map of key/value pairs where the value is a string or regex. For the sake of convenience, if from
is not
a map, it is translated to { url: value }
.
All string-based matches are case-insensitive, so if you need a case-sensitive match, use a regular expression.
In order to easily support JSON-based rules, if a match string is prefixed with regex:
, the condition will treat the
remainder as a regular expression. Sample: "hostname": "regex:/(.*?)\.rootdomain.com/i"
The following matchers are supported:
Matcher | Sample | Description |
---|---|---|
headers |
|
Matches when all specified HTTP headers are present |
hostname |
|
Matches the host HTTP header, minus any port |
method |
|
Matches the HTTP method of the request |
params |
|
Matches when all specified query-string parameters are present |
path |
|
Matches the URL, minus the query string |
port |
|
Matches the port number specified in the host header; if the port is not explicitly present in the header, it will assume the default port number of the protocol |
protocol |
|
Matches the protocol of the request; only http and https are supported at this time |
scheme |
|
Alias for protocol |
url |
|
Matches the path and query string of the URL. This does not include the scheme, hostname, or port |
Redirect URL formatting
The to
property of a rule is a string for formatting the URL to redirect to. It can be a plain URL string or it
can contain variables. The variables can be aspects of the inbound request or condition match results.
If the substitution for a variable is empty, and that would result in an empty path segment, the segment is
automatically omitted. For example, if {foo}
is empty, then /something/{foo}/bar
becomes /something/bar
.
The following variables are supported:
Variable | Description |
---|---|
{headers.<name>} |
The value of an HTTP header |
{host} |
The value of the HTTP host header |
{hostname} |
The value of the HTTP host header, minus the port number |
{method} |
The value of the HTTP method, lower-cased |
{params.<name>} |
The value of a query string parameter |
{path} |
The URL, minus the protocol, hostname, port, and query string |
{port} |
The TCP port number |
{protocol} |
Either http or https |
{query} |
The query string, including the ?; accidental double-?s are automatically corrected |
{scheme} |
Alias for {protocol} |
{url} |
The URL, minus the protocol, hostname, and port |
If a from
condition involved a regular expression containing match groups, then the match groups are available
as variables as well, based on appending $
+ the 1-based group number. For example, given this rule:
from: path: /\/customer\// to: '//crm.mydomain.com/customers?id={path$1}'
.../customer/38239
would be redirected to //crm.mydomain.com/customers?id=38239
.
Additional Response Options
The to
property of a rule may also specify additional headers and a body to go along
with the response. This is done by using an object for the to
value. The following properties are supported:
Property | Description |
---|---|
url |
The url to redirect to. This is equivalent to specifying a `location` header. |
status |
The status code of the response. Defaults to 301. |
headers |
An object of key/value pairs representing additional headers to send in the response |
body |
Content to send in the response body. See "Response Bodies" below. |
Some shortcuts are available.
to: '/url
is the same asto: { url: '/url' }
, which is the same asto: { headers: { location: '/url' } }
.- Setting a
status: 302
property directly on the rule is synonymous withto: { status: 302 }
.
Header values and the body support the same placeholder substitutions available in the to
redirect URL, with an
additional redirectURL
placeholder also being available.
Response Bodies
Some magic is included if you specify a response body for a redirect:
- If the body is a string and starts with '<html ', the
content-type
header will be set totext/html
. - If the body is a string and starts with '<', the
content-type
header will be set toapplication/xml
. - If the body is a string and has neither prefix, the
content-type
header will be set totext/plain
. - If the body is any other type, it will be serialized to JSON, and the
content-type
will beapplication/json
.
If you do not want an automatic content-type
, you should explicitly define a content-type
header in the to
rules.