Allows middlewares to preserve & modify input stream

[botic]

This would enable JSGI middlewares to read the input and reset the input stream to the initial state after. This is needed to add support for X-Hub-Signature like available for the Github and Facebook API. Otherwise someone needs to clone the whole params middleware to avoid that it consumes the input stream before the verification middleware.

[mention-bot]

@botic, thanks for your PR! By analyzing the annotation information on this pull request, we identified @grob and @oberhamsi to be potential reviewers

[botic]

I looked for other solutions for this problem. One would be to directly read into a MemoryStream at the beginning of the JSGI connector and closing the original java.io.InputStream after it. Since a MemoryStream has a position which can be reset to 0, consumers of the body can read the stream and then leave it in the original state.

exports.middleware = function consumingMiddleware(next, app) {
  return function (req) {
    const input = req.input.read();
    req.input.position = 0;

    if (input ...) {
       // process input
    }

    return next(req);
  };
};

Changing it to a MemoryStream instead of a simple Stream might introduces consequences which are not on our radar yet. The simpler solution is like proposed in this PR, which just adds an additional setter method for the input, which will never be used in existing applications.

Since an application can be composed and it never knows which middleware chain might be present, I think we should solve this problem for the upcoming release.