resin-io/persistent-tunnel

Name: persistent-tunnel

Owner: Resin.io

Description: HTTP Agent for tunneling proxies with persistent sockets

Created: 2016-02-19 18:53:37.0

Updated: 2017-12-16 12:48:13.0

Pushed: 2016-06-06 17:18:08.0

Homepage:

Size: 27

Language: CoffeeScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

persistent-tunnel

HTTP Agent for tunneling proxies with persistent sockets

Motivation

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

Use cases

Simple tunneling

tunnel = require('persistent-tunnel');

tunnelingAgent = new tunnel.Agent({
oxy: {
host: 'localhost',
port: 3128


elingAgent.createConnection = tunnel.createConnection;

req = http.request({
st: 'example.com',
rt: 80,
ent: tunnelingAgent

Simple tunneling with persistent tunnels

tunnel = require('persistent-tunnel');

tunnelingAgent = new tunnel.Agent({
epAlive: true   // create persistent sockets over tunnel
oxy: {
host: 'localhost',
port: 3128


elingAgent.createConnection = tunnel.createConnection;

req = http.request({
st: 'example.com',
rt: 80,
ent: tunnelingAgent

Simple tunneling with persistent tunnels that expire after a timeout

tunnel = require('persistent-tunnel');

tunnelingAgent = new tunnel.Agent({
epAlive: true,
oxy: {
host: 'localhost',
port: 3128
timeout: 2000 // tunnel sockets close after 2s of inactivity


elingAgent.createConnection = tunnel.createConnection;

req = http.request({
st: 'example.com',
rt: 80,
ent: tunnelingAgent

Configuration

keepAlive setting

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.

timeout setting

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).

TODO

• https support
• proxy authorization

Support

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

License

Licensed under the MIT license.