towing-hook

Route your Node.js application's TCP connectivity through WebSockets. Built on tcp-over-websockets.

Useful for scenarios where you are unable to make socket connections, eg:

• You are behind a corporate firewall that only allows outbound http(s) traffic

• If you are using StackBlitz, which runs Node.js completely within the browser, and hence does not support socket connections

See an example of this here.

Quickstart

Out-of-the-box, this package will route connections through a tunnel service maintained by the package author. You may wish to set-up your own tunnel service by following the instructions below.

Setting up a self-hosted tunnel service

Use npx to run a tcp-over-websockets tunnel service. This will accept your websocket connection and make a socket connection on your behalf:

$ DEBUG=tcp-over-websockets:* npx -p tcp-over-websockets tcp-over-websockets-server
listening on 8080

As a module hook

# By default, connections go through wss://towing-service.fly.dev.
# This is maintained by the package author.
# If you prefer to use another tunnel service, set this env var:
$ export TOW_TUNNEL=ws://localhost:8080

# You may wish to enable debug logging for the underlying
# tcp-over-websockets dependency by setting this env var
$ export DEBUG=tcp-over-websockets:*

# Use towing-hook without modifying your application
$ node -r towing-hook/register your-application.js

Programmatic use

const { hookToTunnel } = require('towing-hook')

hookToTunnel('ws://localhost:8080')

// Connections are now routed through websockets

How it works

This package glues two dependencies together, mitm.js and tcp-over-websockets.

When invoked, mitm.js will intercept most calls to create connections, in particular net.connect() and tls.connect(). towing-hook will then attach the sockets created by mitm.js to tcp-over-websockets, which will route data from those sockets over a websocket connection.

mitm.js creates mock sockets that behave like raw socket connections, notably for sockets created using tls.connect(). TLS support is hence grafted on using Forge.

Gotchas

Sockets created manually are not intercepted

mitm.js does not intercept connections made with net.Socket#connect() or tls.Socket#connect(), as it does not stub the Socket constructor in the net module. If your application or dependency uses this for connectivity, towing-hook will not route your connection.

ie, the following will not work:

const net = require('net')
const socket = new net.Socket()

socket.connect(22, 'example.org')

but the following will:

const net = require('net')
const socket = net.connect(22, 'example.org')

Track moll/node-mitm#42 for progress on this issue.