HTTP Agent for tunneling proxies with persistent sockets

This tunneling agent combines the latest http.Agent with a custom createConnection function that returns the socket of an established tunnel.

Inspired from

• http.Agent on nodejs/node#master
• koichik/node-tunnel

var tunnel = require('persistent-tunnel');

var tunnelingAgent = new tunnel.Agent({
  proxy: {
    host: 'localhost',
    port: 3128
  }
});
tunnelingAgent.createConnection = tunnel.createConnection;

var req = http.request({
  host: 'example.com',
  port: 80,
  agent: tunnelingAgent
});

var tunnel = require('persistent-tunnel');

var tunnelingAgent = new tunnel.Agent({
  keepAlive: true   // create persistent sockets over tunnel
  proxy: {
    host: 'localhost',
    port: 3128
  },
});
tunnelingAgent.createConnection = tunnel.createConnection;

var req = http.request({
  host: 'example.com',
  port: 80,
  agent: tunnelingAgent
});

var tunnel = require('persistent-tunnel');

var tunnelingAgent = new tunnel.Agent({
  keepAlive: true,
  proxy: {
    host: 'localhost',
    port: 3128
    timeout: 2000 // tunnel sockets close after 2s of inactivity
  },
});
tunnelingAgent.createConnection = tunnel.createConnection;

var req = http.request({
  host: 'example.com',
  port: 80,
  agent: tunnelingAgent
});

When keepAlive is set to true, socket pooling / reuse is enabled by the HTTP Agent. In addition to managing the pool, the HTTP Agent calls setKeepAlive() on each pooled socket so that TCP KeepAlive packets are sent over the established connection in small intervals. Any intermediate TCP Load Balancers / Proxies along the tunnel connection should detect the TCP KeepAlive packets and keep the connection alive.

When timeout is set, the connection will get severed if no data has been transfered over the socket for the specified time. TCP KeepAlive packets do not count as data. The timeout setting is useful for making sure that idle sockets will eventually get destroy()'ed and release their resources.

If no timeout value is set, the pooled tunneling sockets will be kept alive forever.

In any case, if a tunnel connection gets dropped for any reason, the underlying socket will emit an error that will result in it being removed from the HTTP Agent pool (and its resources released, too).

• https support
• proxy authorization

If you're having any problem, please raise an issue on GitHub and the Resin.io team will be happy to help.

Licensed under the MIT license.