Factory for a new proxy with given options. All options are optional.

      var hoxy = require('hoxy');
      var proxy = hoxy.createServer({
        upstreamProxy: 'localhost:9090',
        reverse: 'http://example.com',
        certAuthority: { key, cert },
        tls: { key, cert },
        slow: { rate, latency, up, down }
      });
    

Starts proxy listening on port. Returns itself.

      var hoxy = require('hoxy');
      var proxy = hoxy.createServer().listen(8080);
    

A callback may be provided, to run when the proxy has started listening.

      var hoxy = require('hoxy');
      var port = 8080;
      var proxy = hoxy.createServer().listen(port, function() {
        console.log('The proxy is listening on port ' + port + '.');
      });
    

This method simply passes its arguments to Node's server.listen() method.

Get/set proxy-level slow options. If options is provided, it's a setter.

      proxy.slow({ rate, latency, up, down });
    

If options is not provided, it's a getter.

      var slowOpts = proxy.slow();
    

This is the entry point for intercepting and operating on requests and responses. This first example intercepts all requests.

      proxy.intercept('request', req => console.log(req.url));
    

This is more verbose, but identical to the above.

      proxy.intercept({
        phase: 'request'
      }, function(req, resp, cycle) {
        console.log(req.url);
      });
    

Interceptors

The callback passed to intercept() (AKA the interceptor) receives three arguments (req, resp, cycle) which are instances of classes described below. cycle is also passed as context. Thus:

      proxy.intercept('request', function(req, resp, cycle) {
        console.log(this === cycle) // true
      });
    

Sync versus async interceptors

Hoxy internally runs everything sequentially in series, including interceptors. That happens naturally when your interceptor logic is synchronous. But if it's asynchronous, you must signal that by returning a promise. As long as you do that, Hoxy will wait until the promise resolves and things will flow serially.

      proxy.intercept('request', function(req, resp, cycle) {
        // return a promise from the interceptor
        return getThingA().then(function(thingA) {
          return getThingB(thingA);
        }).then(function(thingB) {
          // do something with "thingB"
        });
      });
    

Future versions of JavaScript will allow async functions. Some transpilers allow you to use this syntax today. These can be used as interceptors, too. Written this way, your logic and your error handling are much cleaner.

      proxy.intercept('request', async function(req, resp, cycle) {
        // this is an async function
        let thingA = await getThingA();
        let thingB = await getThingB(thingA);
        // do something with "thingB"
      });
    

In current versions of io.js, generators can be used as a stand-in for async functions, but with the benefit of being natively-supported, spec-valid ES6 syntax. You must only yield promises from your generator. See co for more details.

      proxy.intercept('request', function*(req, resp, cycle) {
        // this is a generator
        let thingA = yield getThingA();
        let thingB = yield getThingB(thingA);
        // do something with "thingB"
      });
    

Note: Strictly speaking, Hoxy doesn't care whether your interceptor is an async function or a generator. It only cares what kind of thing the return value is:

• Promise: wait for it to resolve, then proceed.
• Iterator: turn it into a promise, wait for it to resolve, then proceed.
• None of the above: proceed immediately.

Options

Options affect how, or if, interceptors get called. Here are a few examples. The following will only intercept GET requests to example.com.

      proxy.intercept({
        phase: 'request',
        method: 'GET',
        hostname: 'example.com'
      }, function(req, resp, cycle) {
        console.log('request made to: '+req.url);
      });
    

The following only intercepts text/html responses. When it does, it exposes the response body as a readable/writable $ variable.

      proxy.intercept({
        phase: 'response',
        mimeType: 'text/html',
        as: '$'
      }, function(req, resp, cycle) {
        resp.$('title')
        .text('all your titles are belong to us');
      });
    

The following only intercepts responses with a declared charset. When it does, it exposes the response body as the string variable.

      proxy.intercept({
        phase: 'response',
        contentType: /charset/i,
        as: 'string'
      }, function(req, resp, cycle) {
        console.log(resp.string);
      });
    

The following only intercepts responses from an /api/users JSON endpoint. When it does, it exposes the response body as the json variable. It uses a URL pattern to match the endpoint URL instead of a regex.

      proxy.intercept({
        phase: 'response',
        fullUrl: 'http://example.com/api/users/:id',
        mimeType: 'application/json',
        as: 'json'
      }, function(req, resp, cycle) {
        console.log(resp.json.email_address);
      });
    

Note: filtering options can be different types.

• string: a loose (==) match.
• regex: regex match of the string-coerced value.
• function: truthiness of return value.

Deals with various logging events. This first example listens for error, warn, and debug logging events, and prints them to stderr.

      proxy.log('error warn debug');
    

Or, print logging events to various writable streams.

      proxy.log('error warn debug', process.stderr);
      proxy.log('info', process.stdout);
    

Or, explicitly handle logging events.

      proxy.log('error warn', function(event) {
        console.error(event.level + ': ' + event.message);
        if (event.error) console.error(event.error.stack);
      });
    

Stops proxy receiving requests. Finalizes and/or cleans up any resources the proxy uses internally.

      proxy.close(function(err) { // optional callback
        if (err) {
          throw err;
        }
        console.log('The proxy is no longer accepting new connections.');
      });
    

Protocol of the request.

Destination server hostname, sans port.

Destination server port.

All-caps HTTP method used. Lowercase values are converted to uppercase.

HTTP request header name/value JS object. These are all-lowercase, e.g. accept-encoding.

Root-relative request URL, including query string, like /foo/bar?baz=qux

An object representing querystring params in the URL. For example if the URL is /foo/bar?baz=qux, then this object will look like { baz: 'qux' }.

Request body parsed as JSON. This is only present if you intercept the request as:'json'. Changes made to this object will be seen by the server.

      proxy.intercept({
        phase: 'request',
        method: 'PUT',
        fulUrl: 'http://example.com/users/:id',
        as: 'json'
      }, function(req, resp, cycle) {
        req.json.prefs.subscriptions = 'all';
      });
    

Request body parsed as form-url-encoded params. This will be a key/value POJO. This object will only present if you intercept the request as:'params'. Changes made to this object will be seen by the server.

      proxy.intercept({
        phase: 'request',
        method: 'POST',
        mimeType: 'application/x-www-form-urlencoded',
        as: 'params'
      }, function(req, resp, cycle) {
        console.log(req.params.email);
      });
    

Note, parameters from the URL querystring are not included in this object.

Request body string. This is only present if you intercept the request as:'string'. Overwriting this will overwrite the request body sent to the server.

      proxy.intercept({
        phase: 'request',
        fulUrl: 'http://example.com/users/:id',
        as: 'string'
      }, function(req, resp, cycle) {
        console.log(req.string);
      });
    

Request body binary buffer. This is only present if you intercept the request as:'buffer'. Changes made to this object will be seen by the server.

      proxy.intercept({
        phase: 'request',
        method: 'POST',
        fullUrl: 'http://example.com/images',
        as: 'buffer'
      }, function(req, resp, cycle) {
        // req.buffer contains uploaded image
      });
    

Simulates slowness during request phase. With this method you can set a minimum latency and/or maximum transfer rate. Since these are minimum/maximum, if your native connection is already slower than these values, this method will have no effect.

      // Simulate upload speed of 10,000 bytes per second
      proxy.intercept('request', function(req, resp, cycle) {
        req.slow({rate:10000}); // bytes per second
      });
    

      // Simulate a 500-1000ms delay on every request.
      proxy.intercept('request', function(req, resp, cycle) {
        req.slow({latency:randint(500, 1000)});
      });
    

If url is provided, sets the request's absolute protocol, hostname, port and url. Otherwise it returns the absolute URL of this request. This is mainly a convenience method.

      // Log every request through the proxy.
      proxy.intercept('request', function(req, resp, cycle) {
        console.log(req.fullUrl());
      });
    

Whatever request body gets sent to the server, tee() pipes an identical copy to your writable stream. Your stream is held in memory, and only gets written to if and when the request is sent to the server. In other words, your stream sees whatever the server sees. If the server sees nothing, your stream sees nothing. You can tee() as many times as you want.

      proxy.intercept({
        phase: 'request',
        method: /post|put/i,
        mimeType: 'application/json'
      }, function(req, resp, cycle) {
        req.tee(fs.createWriteStream('./uploaded.json'));
      });
    

HTTP status code being sent to the client.

HTTP response header name/value JS object. Header names are all-lowercase, such as 'content-type'.

Response body parsed as DOM. This object is only present if you intercept the response as:'$'. This is a cheerio object, which provides a jQuery-like API. Changes made to it will be seen by the client.

      proxy.intercept({
        phase: 'response',
        fullUrl: 'http://example.com/page.html',
        as: '$'
      }, function(req, resp, cycle) {
        // change the title of the page
        resp.$('title').text('Fake Title!');
      });
    

Response body parsed as JSON. This is only present if you intercept the response as:'json'. Changes to this object will be seen by the client.

      proxy.intercept({
        phase: 'response',
        method: 'GET',
        fullUrl: 'http://example.com/users/123',
        as: 'json'
      }, function(req, resp, cycle) {
        // arbitrarily manipulate the response json
        resp.json.foo = 'bar';
      });
    

Response body string. This is only present if you intercept the response as:'string'. Overwriting this will overwrite the response body sent to the client.

      proxy.intercept({
        phase: 'response',
        fullUrl: 'http://example.com/page.html',
        as: 'string'
      }, function(req, resp, cycle) {
        // print page to log
        console.log(resp.string);
      });
    

Response body binary buffer. This is only present if you intercept the response as:'buffer'. Changes made to this object will be seen by the client.

      proxy.intercept({
        phase: 'response',
        fullUrl: 'http://example.com/image.jpg',
        as: 'buffer'
      }, function(req, resp, cycle) {
        // resp.buffer contains a jpg
      });
    

Simulates a slow response. With this method you can set a minimum latency and/or maximum transfer rate. Since these are minimum/maximum, if your native connection is already slower than these values, this method has no effect.

      // Simulate download speed of 100,000 bytes per second
      proxy.intercept('response', function(req, resp, cycle) {
        resp.slow({rate:100000}); // bytes per second
      });
    

      // Simulate a 500-1000ms delay on every response.
      proxy.intercept('response', function(req, resp, cycle) {
        resp.slow({latency:randint(500, 1000)});
      });
    

Whatever response body gets sent to the client, tee() pipes an identical copy to your writable stream. Your stream is held in memory, and only gets written to when the response is sent to the client. In other words, your stream sees whatever the client sees. You can tee() as many times as you want.

      proxy.intercept({
        phase: 'response',
        mimeType: 'image/gif'
      }, function(req, resp, cycle) {
        resp.tee(fs.createWriteStream('./image.gif'));
      });
    

Provisions responses from the local filesystem. Generally, the reason you'd do this is to be able to edit those files locally and test them as if they were live on the remote server. This action populates the response object; see response population for more info. The completion of this action is asynchronous, so serve() returns a promise. Example.

      proxy.intercept({
        phase: 'request',
        fullUrl: 'http://example.com/main.js'
      }, function(req, resp, cycle) {
        return cycle.serve('/Users/gr123/test/main.js');
      });
    

Or the more verbose-but-identical...

      proxy.intercept({
        phase: 'request',
        fullUrl: 'http://example.com/main.js'
      }, function(req, resp, cycle) {
        return cycle.serve({
          path: '/Users/gr123/test/main.js'
        });
      });
    

The returned promise resolves after the response has been populated. There are at least three use cases worth mentioning.

Use case #1: Serve a specific file. First:

      $ curl http://example.com/js/main.js > main.js
    

...then:

      proxy.intercept({
        phase: 'request',
        fullUrl: 'http://example.com/js/main.js'
      }, function(req, resp, cycle) {
        return cycle.serve(__dirname + '/main.js');
      });
    

Use case #2: Serve out of a local docroot. First:

      $ mkdir js
      $ curl http://example.com/js/main.js > js/main.js
      $ curl http://example.com/js/some-lib.js > js/some-lib.js
      $ curl http://example.com/js/other-lib.js > js/other-lib.js
      ...
    

...then:

      proxy.intercept({
        phase: 'request',
        hostname: 'example.com',
        url: /^\/js\/.*/
      }, function(req, resp, cycle) {
        return cycle.serve({
          docroot: __dirname,
          strategy: 'overlay'
        });
      });
    

Use case #3: Serve out of a local docroot. Similar to above, but automatically downloads the files for you, instead of having to curl them as in the above example. You control which files get downloaded locally by the filtering options you provide.

      proxy.intercept({
        phase: 'request',
        hostname: 'example.com',
        url: /^\/js\/.*/
      }, function(req, resp, cycle) {
        return cycle.serve({
          docroot: __dirname,
          strategy: 'mirror'
        });
      });
    

Stores and retrieves data on a cycle instance. This is useful since the same instance is shared across all interceptors for a given request/response cycle, allowing you to share related data across disparate scopes. With two params this method behaves as a setter, with one param as a getter.

      ['request','request-sent','response','response-sent']
      .forEach(function(phase) {
        proxy.intercept(phase, function(req, resp, cycle) {
          cycle.data(phase, Date.now());
        });
      });
      proxy.intercept('response-sent', function(req, resp, cycle) {
        var reqReceived = cycle.data('request');
        var reqSent = cycle.data('request-sent');
        var respReceived = cycle.data('response');
        var respSent = cycle.data('response-sent');
        // now print some profiling data
      });