redirect-rules

Flexible redirect rule engine for connect middleware

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:

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:

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:

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.