redirect-rules

1.1.1 • Public • Published

redirect-rules

Flexible redirect rule engine for connect middleware

npm version Build Status

Usage

var redirector = require('redirect-rules');
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.use(redirector(rules));

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 = require('redirect-rules');
var rule = { from: '/url1', to: '/url2' };
app.use(redirector(rule));

To specify multiple redirect rules, pass an Array; the rules will be tested in order until a match is found:

var redirector = require('redirect-rules');
var rules = [
    { from: '/url1', to: '/url2' },
    { from: '/url3', to: '/url4' }
];
app.use(redirector(rules));

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 is 301 (permanent). to: '/url', status: 302 is synonymous with to: { 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:

MatcherSampleDescription
headers
from: { headers: { 'user-agent': /Trident/ } }
Matches when all specified HTTP headers are present
hostname
from: { hostname: 'www.mydomain.com' }
Matches the host HTTP header, minus any port
method
from: { method: 'GET' }
Matches the HTTP method of the request
params
from: { params: { locale: /^es-/ } }
Matches when all specified query-string parameters are present
path
from: { path: '/some/path' }
Matches the URL, minus the query string
port
from: { port: 443 }
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
from: { protocol: 'https' }
Matches the protocol of the request; only http and https are supported at this time
scheme
from: { scheme: 'https' }
Alias for protocol
url
from: { url: '/some/url?foo=bar' }
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:

VariableDescription
{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:

PropertyDescription
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 as to: { url: '/url' }, which is the same as to: { headers: { location: '/url' } }.
  • Setting a status: 302 property directly on the rule is synonymous with to: { 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 to text/html.
  • If the body is a string and starts with '<', the content-type header will be set to application/xml.
  • If the body is a string and has neither prefix, the content-type header will be set to text/plain.
  • If the body is any other type, it will be serialized to JSON, and the content-type will be application/json.

If you do not want an automatic content-type, you should explicitly define a content-type header in the to rules.

Package Sidebar

Install

npm i redirect-rules

Weekly Downloads

7

Version

1.1.1

License

MIT

Unpacked Size

21.1 kB

Total Files

35

Last publish

Collaborators

  • jpage