tunnel

What is tunnel?

The tunnel npm package is designed to help create secure and reliable tunneling connections over HTTP. It allows developers to tunnel their HTTP(S) communications through proxy servers, enabling secure and efficient data transfer even in environments with restricted internet access. This package is particularly useful for bypassing network restrictions, securely accessing remote networks, and enhancing privacy.

What are tunnel's main functionalities?

HTTP over HTTP tunneling

This feature allows you to tunnel HTTP requests through an HTTP proxy. It's useful for sending requests from behind a corporate firewall.

const tunnel = require('tunnel');
const tunnelingAgent = tunnel.httpOverHttp({
  proxy: {
    host: 'localhost',
    port: 8080
  }
});
require('http').request({
  host: 'example.com',
  port: 80,
  agent: tunnelingAgent
});

HTTPS over HTTP tunneling

This feature enables HTTPS requests to be tunneled through an HTTP proxy. It's particularly useful for secure communication through a non-secure proxy server.

const tunnel = require('tunnel');
const tunnelingAgent = tunnel.httpsOverHttp({
  proxy: {
    host: 'localhost',
    port: 8080
  }
});
require('https').request({
  host: 'example.com',
  port: 443,
  agent: tunnelingAgent
});

HTTPS over HTTPS tunneling

This feature allows for HTTPS requests to be tunneled through an HTTPS proxy, enhancing security by encrypting both the tunnel and the proxied requests.

const tunnel = require('tunnel');
const tunnelingAgent = tunnel.httpsOverHttps({
  proxy: {
    host: 'localhost',
    port: 8080
  }
});
require('https').request({
  host: 'example.com',
  port: 443,
  agent: tunnelingAgent
});

Other packages similar to tunnel

http-proxy

http-proxy is a full-featured HTTP proxy library that supports websockets. It is designed to help developers easily forward HTTP requests and handle proxying needs. Compared to tunnel, http-proxy offers a broader set of features for proxying but does not focus exclusively on tunneling through proxies.

global-agent

global-agent is a global HTTP/HTTPS proxy agent capable of handling requests across multiple HTTP clients. Unlike tunnel, which is focused on creating tunnel connections, global-agent is designed to configure a global proxy agent for the application, making it easier to manage proxy settings in a centralized manner.

README

node-tunnel - HTTP/HTTPS Agents for tunneling proxies

Example

var tunnel = require('tunnel');

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

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

Installation

$ npm install tunnel

Usages

HTTP over HTTP tunneling

var tunnelingAgent = tunnel.httpOverHttp({
  maxSockets: poolSize, // Defaults to 5

  proxy: { // Proxy settings
    host: proxyHost, // Defaults to 'localhost'
    port: proxyPort, // Defaults to 80
    localAddress: localAddress, // Local interface if necessary

    // Basic authorization for proxy server if necessary
    proxyAuth: 'user:password',

    // Header fields for proxy server if necessary
    headers: {
      'User-Agent': 'Node'
    }
  }
});

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

HTTPS over HTTP tunneling

var tunnelingAgent = tunnel.httpsOverHttp({
  maxSockets: poolSize, // Defaults to 5

  // CA for origin server if necessary
  ca: [ fs.readFileSync('origin-server-ca.pem')],

  // Client certification for origin server if necessary
  key: fs.readFileSync('origin-server-key.pem'),
  cert: fs.readFileSync('origin-server-cert.pem'),

  proxy: { // Proxy settings
    host: proxyHost, // Defaults to 'localhost'
    port: proxyPort, // Defaults to 80
    localAddress: localAddress, // Local interface if necessary

    // Basic authorization for proxy server if necessary
    proxyAuth: 'user:password',

    // Header fields for proxy server if necessary
    headers: {
      'User-Agent': 'Node'
    },
  }
});

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

HTTP over HTTPS tunneling

var tunnelingAgent = tunnel.httpOverHttps({
  maxSockets: poolSize, // Defaults to 5

  proxy: { // Proxy settings
    host: proxyHost, // Defaults to 'localhost'
    port: proxyPort, // Defaults to 443
    localAddress: localAddress, // Local interface if necessary

    // Basic authorization for proxy server if necessary
    proxyAuth: 'user:password',

    // Header fields for proxy server if necessary
    headers: {
      'User-Agent': 'Node'
    },

    // CA for proxy server if necessary
    ca: [ fs.readFileSync('origin-server-ca.pem')],

    // Server name for verification if necessary
    servername: 'example.com',

    // Client certification for proxy server if necessary
    key: fs.readFileSync('origin-server-key.pem'),
    cert: fs.readFileSync('origin-server-cert.pem'),
  }
});

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

HTTPS over HTTPS tunneling

var tunnelingAgent = tunnel.httpsOverHttps({
  maxSockets: poolSize, // Defaults to 5

  // CA for origin server if necessary
  ca: [ fs.readFileSync('origin-server-ca.pem')],

  // Client certification for origin server if necessary
  key: fs.readFileSync('origin-server-key.pem'),
  cert: fs.readFileSync('origin-server-cert.pem'),

  proxy: { // Proxy settings
    host: proxyHost, // Defaults to 'localhost'
    port: proxyPort, // Defaults to 443
    localAddress: localAddress, // Local interface if necessary

    // Basic authorization for proxy server if necessary
    proxyAuth: 'user:password',

    // Header fields for proxy server if necessary
    headers: {
      'User-Agent': 'Node'
    }

    // CA for proxy server if necessary
    ca: [ fs.readFileSync('origin-server-ca.pem')],

    // Server name for verification if necessary
    servername: 'example.com',

    // Client certification for proxy server if necessary
    key: fs.readFileSync('origin-server-key.pem'),
    cert: fs.readFileSync('origin-server-cert.pem'),
  }
});

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