yinxulai / proxysocket

SOCKS5 proxy for NodeJS

proxysocket

proxysocket is a nodejs module for seamlessly making socket connections via a SOCKS5 proxy. Use it in place of a regular net.Socket to easily talk over Tor or an SSH tunnel.

Install

Available on npm for easy install:

npm install proxysocket

You can also download a release manually and extract it as proxysocket has no dependencies.

Usage

Because proxysocket provides the same API as a regular net.Socket object you can use it in many places where sockets and streams are used.

Making a Socket

Create a new socket that will use the proxy:

var proxysocket = require('proxysocket');
var socket = proxysocket.create('localhost', 9050);

The returned object behaves like an ordinary net.Socket object. For example, you can call connect() or listen for events:

socket.connect(80, 'website.com', function () {
	// Connected
});

socket.on('data', function (data) {
	// Receive data
});

Also note if you're using Tor it's fine to pass .onion hosts:

socket.connect(6667, 'p4fsi4ockecnea7l.onion');

Making HTTP Requests

You can use proxysocket.createAgent() to create an object like http.Agent which will make proxy sockets for you when using http.request(). Here is an example:

var proxysocket = require('proxysocket');
var http = require('http');
var agent = proxysocket.createAgent();

http.request({
	host: 'foo.com',
	agent: agent
});

Chaining

It's fine to pass one proxysocket to another:

	var socket1 = proxysocket.create('socks1addr', 9050)
	var socket2 = proxysocket.create('socks2addr', 9050, socket1)

	socket2.connect(80, 'example.com', function () {
		// connected
	})

The resulting chain: socksaddr1:9050 -> socksaddr2:9050 -> example.com

API

proxysocket.create(socksHost, socksPort, socket)

Create a new socket object that uses a SOCKS5 proxy provided.

• socksHost is the host of the proxy. Default is localhost
• socksPort is the port of the proxy. Default is 9050
• socket can be an existing net.Socket object or any object with the same interface (e.g. proxysocket). Default is a new Socket()

proxysocket.createAgent(socksHost, socksPort)

Returns an object like http.Agent which makes new sockets using proxysocket.create() as needed.

socket

The object returned from proxysocket.create() is just like a regular net.Socket. This documentation lists additions to the API.

Note This documentation doesn't list all of the methods, properties, or events of net.Socket, Readable or Writable. See the nodejs API reference for those modules.

socket.socksHost

Get the host address of the proxy. By default this will be localhost.

socket.socksPort

Get the port of the proxy. By default this will be 9050.

socket.realSocket

Get the underlying raw net.Socket connection to the proxy. You don't need to use this and instead should listen on this socket instead.

socket 'socksdata' event

socksdata is emitted whenever underlying data is received from the proxy before the socket is ready for use. This is mainly here for debugging and you should use the data event instead.

Contributing

Please fork and make a pull request if you have anything cool to add. You're also welcome to join the Gitter chat.