Detour

A reverse proxy to untie the knot between frontend and backend developers

Problems

Frontend developers cannot focus on their development because

• Backend deployment is complicated and take up lot of resources on their box
• New features depends on backend API readiness
  • Mocking is okay but changing spec makes mock update time consuming
• Need to tackle CORS issue during tight development schedule

Scenarios

• Decouple frontend and backend development team
  • Join web server and API servers together as if they are from a single server
  • Few frontend developers can use a shared backend server, no need to install database in their own box to run the whole site
  • Don't wait until backend API is ready, mock a response JSON/XML and continue web development
  • Built-in LiveReload server for quick consumption
• Mock changes on big production site
  • Mock as you need, host a smaller staging site without downloading everything from production
  • Support server side includes
• Simple URL rewrite

Install

Run npm install detour-proxy -g to install detour in your box. For every site,

• Create a detour-config.json (sample configuration below)
• Run detour to start the server
  • For custom config path and port, run detour path-to-config-file.json 1337

Sample configuration

{
    "logLevel": "follow",
    "mappings": [{
        "from": "/",
        "to": "html/",
        "skipOn404": true
    }, {
        "from": "/api/",
        "to": "http://api.example.com/"
    }]
}

logLevel could be error, warning, info, skip, forward, follow. Detour use winston.

mappings defines how request could be remapped. Mappings can be overlapping and they are processed from top to bottom (first win will stop other rules).

In the sample configuration, the first mapping will rewrite / (i.e. all requests to the site) to local directory html/. For example, request to /helloworld.html will be served with local file html/helloworld.html, relative to the config file.

skipOn404 indicate that if the requested file is not found, it will skip this mapping and evaluate the next one. Otherwise, detour will return with 404.

You can specify both file path or http:// path to the to argument.

The second mapping will rewrite /api/ to http://api.example.com/. For example, requests to /api/helloworld will be forwarded on behalf to http://api.example.com/helloworld/. Most request headers will be retained. Some are discarded, e.g. accept-encoding.

Currently, we do not add headers (e.g. x-forwarded-for, x-forwarded-proto) to the forwarded request.

Default port

By default, detour use a random port number 7000-7999. To use a custom port number, you can specify it in the command-line. Type detour path-to-config-file.json 1337 to run detour on port 1337 with configuration file path-to-config-file.json.

Default document

For file-based destination, detour adopted index.html as the name of "default document". If the request does not contain a filename (end with slash) and the mapping destination is local file system, detour will add index.html to the request URL.

Server side includes

Detour follow server side includes (or SSI). The SSI path will also be evaluated against the mappings defined in detour-config.json. To aid development, the SSI-ed output will have extra comment <!-- BEGIN SSI /include/topnav.html --> for easier debugging SSI issues.

LiveReload support

Detour built-in LiveReload server. When detour is up, it will watch all mappings that point to local file system. Changes detected will be broadcasted to LiveReload plugin immediately. Instead of using unreliable fs.watch, we use a more reliable approach by crawling every file stats every 2 seconds. We still use fs.watch for auxiliary purpose.

Changelog

• 0.0.25 (2016-04-20): Log LiveReload events
• 0.0.24 (2016-03-30): Use chokidar for file watcher

Issues

If you encounter any issues, please file it on GitHub. To speed up our investigation, please file with a minimal repro steps.

Feature requests

If you want to recommend a feature, please file it on issues or chat with us on Gitter. Please let us know rationale behind your request and we will be more than happy to design and implement the feature for you.