README.md

http-rewrite-middleware v0.1.6

This module makes it possible to redirect (rewrite internally or redirect using HTTP codes) User to the specific URL based on RegExp Rules. The designated successor of grunt-connect-rewrite.

Getting Started

• Install the middleware by running:

  npm install http-rewrite-middleware --save

• Include the module:

  var rewriteModule = require('http-rewrite-middleware');

• Define your rules like:

  var rewriteMiddleware = rewriteModule.getMiddleware([
      // Internal rewrite
      {from: '^/index_dev.html$', to: '/src/index.html'},
      // Internal rewrite
      {from: '^/js/(.*)$', to: '/src/js/$1'},
      // 301 Redirect
      {from: '^/old-stuff/(.*)$', to: '/new-cool-stuff/$1', redirect: 'permanent'},
      // 302 Redirect
      {from: '^/stuff/(.*)$', to: '/temporary-stuff/$1', redirect: 'temporary'},
      // Delayed 500ms
      {from: '^/stuff/(.*)$', to: '/temporary-stuff/$1', redirect: 'temporary', delay: 500 },
      // Delayed random 0-5000ms via function
      {from: '^/stuff/(.*)$', to: '/temporary-stuff/$1', redirect: 'temporary', delay: function( req ) {
        return Math.random() * 5000;
      } }
  ]);

• See examples of integration with Connect / Express / Grunt bellow.

Options

Rule's format:

{from: '__from__', to: '__to__'[, redirect: 'permanent'|'temporary', delay: 123]}

Where:

• __from__ - RegExp string to match.
• __to__ - String that replaces matched URL.
• redirect - Optional parameter:
  • When it is omitted then the Rule will be dispatched as an internal rewrite (aka proxified).
  • If the value is set then Browser will receive HTTP Location Header with value of parsed __to__ (permanent value will give HTTP 301, any other value will give HTTP 302).
• delay - Optional parameter:
  • When this is omitted then the Rule will be dispatched immediately
  • If the value is set then the Rule will be dispatched after n milliseconds
  • If the value is a function then the function is executed with the request passed as a parameter

Example of usage with Connect

var connect = require('connect'),
    http = require('http'),
    rewriteModule = require('http-rewrite-middleware');

var app = connect()
    .use(rewriteModule.getMiddleware([
        // ... list of rules here
    ])
    .use(connect.static('public'));

http.createServer(app).listen(3000);

Example of usage with Express

var express = require('express'),
    app = express(),
    rewriteModule = require('http-rewrite-middleware');

app.use(rewriteModule.getMiddleware([
    // ... list of rules here
]);

//...
app.listen(3000);

Example of usage with Grunt (grunt-contrib-connect)

var rewriteModule = require('http-rewrite-middleware');

grunt.initConfig({
    connect: {
        options: {
            port: 9000,
            hostname: 'localhost'
        },
        development: {
            options: {
                middleware: function (connect, options) {
                    var middlewares = [];

                    // RewriteRules support
                    middlewares.push(rewriteModule.getMiddleware([
                        // ... list of rules here
                    ]));

                    if (!Array.isArray(options.base)) {
                        options.base = [options.base];
                    }

                    var directory = options.directory || options.base[options.base.length - 1];
                    options.base.forEach(function (base) {
                        // Serve static files.
                        middlewares.push(connect.static(base));
                    });

                    // Make directory browse-able.
                    middlewares.push(connect.directory(directory));

                    return middlewares;
                }
            }
        }
    }
});

Debugging

In order to debug Rules just add 2nd parameter to the getMiddleware(...) call as getMiddleware(..., {verbose: true}) this will enable logging of matched rules. The message will explain which __from__ rule was matched and what was the result of the rewrite.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code.

Release History

• 2014.02.13 v0.1.5 Fix NPM...
• 2014.01.29 v0.1.3 Add logging support
• 2013.12.17 v0.1.1 Initial Release