Subrequests Express

Usage

On the Express Server

To support subrequests in your express server you only need to add it to your router.

// app.js
const { subrequestsRouterFactory } = require('subrequests-express');

// All your route declarations.
// …
const app = express();

const options = {};
// Add the request aggregator on the '/subrequests' route.
router.use(subrequestsRouterFactory('/subrequests', options, app));

This will add a route in /subrequests that will process blueprints either by GET or POST requests.

Options

Subrequests is very useful when you are making internal requests. Without any options, subrequests will use the hostname in the master request to issue relative requests. A request is considered internal if it has a uri that it's a path instead of a fully qualified URL.

host: The host to use for internal requests. Ex: localhost.
port: The port to use for internal requests. Ex: 3000.

Customize the Response Format

You can provide a subresponse merger plugin by attaching it to the express request object under the subrequestsResponseMerge key. You can do something like:

// app.js
const { subrequestsRouterFactory } = require('subrequests-express');
const JsonResponse = require('subrequests-json-merger');

// All your route declarations.
// …
const app = express();

router.all('/subrequests', (req, res, next) => {
  // Make sure that subrequests-json-merger merges responses using JSON.
  req.subrequestsResponseMerger = JsonResponse;
  next();
});
// Request aggregator.
router.use(subrequestsRouterFactory('/subrequests', {}, app));

Customize the Way Subrequests Are Sent

You can customize the way subrequests are sent. For that you only need to write a requestor. The HttpRequestor and the ExpressRequestor are good examples. You can provide a custom requestor to subrequests-express by attaching your requestor object to req.subrequestsRequestor.

// app.js
const { subrequestsRouterFactory, ExpressRequestor } = require('subrequests-express');
class CustomRequestor extends ExpressRequestor {
  // …
}

// All your route declarations.
// …
const app = express();

router.all('/subrequests', (req, res, next) => {
  // Make sure that subrequests-json-merger merges responses using JSON.
  req.subrequestsRequestor = new CustomRequestor(req);
  next();
});
// Request aggregator.
router.use(subrequestsRouterFactory('/subrequests', {}, app));

Defaults for request

You can override properties of the generated request objects (IncomingMessage) by attaching it to the express request object under the subrequestsOptions.requestOptions key. You can do something like:

// app.js
const { subrequestsRouterFactory } = require('subrequests-express');

// All your route declarations.
// …
const app = express();

router.all('/subrequests', (req, res, next) => {
  // Make sure that subrequests-json-merger merges responses using JSON.
  req.subrequestsResponseMerger = JsonResponse;
  next();
});
// Request aggregator.
router.use(
  (req, res, next) => {
    req.subrequestsOptions = {
      requestOptions: { headers: { 'X-Powered-By': 'Subrequests'} },
    };
    next();
  },
  subrequestsRouterFactory(
    '/subrequests',
    { host: 'localhost', port: 3000 },
    app
  )
);

On the Consumer Application

Use the request aggregator normally under /subrequests or the configured route. See Subrequests for more information on how to use Subrequests.