commandeer

Commandeer

Proxy requests through Connect and capture JSON responses before they are output.

Current Version: 0.3.0
Node Support: 0.10.x, 0.12.x
License: MIT
Build Status:

var commandeer = require('commandeer');
var connect = require('connect');

var app = connect();

app.use(commandeer({
    contentType: 'application/x-commandeer+json',
    dataProperty: 'proxyData',
    target: 'http://localhost:1234'
}));

app.use(function (request, response) {
    response.proxyData.commandeered = true;
    response.end(JSON.stringify(response.proxyData));
});

app.listen(3000);

Install

Install Commandeer with npm:

npm install commandeer

Getting Started

Require in Connect and Commandeer:

var commandeer = require('commandeer');
var connect = require('connect');

Create a Connect application:

var app = connect();

Use the Commandeer middleware in your connect application, configuring it with a few options:

app.use(commandeer({
    contentType: 'application/x-commandeer+json',
    dataProperty: 'proxyData',
    target: 'http://localhost:1234'
}));

Add another middleware after Commandeer to handle any JSON responses that are captured:

app.use(function (request, response) {
    response.proxyData.commandeered = true;
    response.end(JSON.stringify(response.proxyData));
});

Start your Connect application:

app.listen(3000);

Options

contentType (string|array)

Any responses with a matching Content-Type header will not be proxied directly. Instead, the response body will be parsed as JSON and sent to the next middleware in the stack. E.g:

app.use(commandeer({
    contentType: 'application/x-foo'
}));
app.use(function (request, response) {
    // Only responses from with a Content-Type of 'application/x-foo' will reach this middleware
});

If an array of strings is passed in, the response Content-Type will be checked against each of them:

app.use(commandeer({
    contentType: [
        'application/x-foo',
        'application/x-bar'
    ]
}));
app.use(function (request, response) {
    // Only responses from with a Content-Type of 'application/x-foo' or 'application/x-bar' will reach this middleware
});

Defaults to 'application/x-commandeer+json'.

dataProperty (string)

The JSON from captured responses will be stored on this property of the response. This property can be used to access the parsed JSON in the next middleware. E.g:

app.use(commandeer({
    dataProperty: 'foo'
}));
app.use(function (request, response) {
    console.log(response.foo);
});

Defaults to 'proxyData'.

rewriteHostHeader (boolean)

Whether to rewrite the Host header of proxied requests to match the target host. This is required for some back-ends to work properly.

Defaults to true.

target (string)

The proxy target for the application. This should point to your back-end application which can serve both regular responses and proxy data reponses to be captured by Content-Type.

Defaults to 'http://localhost'.

Examples

Commandeer comes with a few example application/backend examples. To run these examples you'll need to install Foreman, or look into the Procfiles for the examples and spin up each process separately.

Basic Example

Simple JSON transform. Commandeerable JSON has a new property added before output.

foreman start -d example/basic

Hogan.js Example

Render the JSON with a templating engine. Commandeerable JSON gets passed into Hogan.js to be rendered as a template.

foreman start -d example/hogan

Contributing

To contribute to Commandeer, clone this repo locally and commit your code on a separate branch.

Please write unit tests for your code, and check that everything works by running the following before opening a pull-request:

make lint test

License

Commandeer is licensed under the MIT license.
Copyright © 2015, Rowan Manning